ci: scope firecracker backend to integration coverage

fix(db): close SQLite connections explicitly to suppress ResourceWarning on Python 3.13
`sqlite3.Connection.__exit__` only commits/rolls back a transaction — it does not close the connection. Python 3.13 (the Nix env on the KVM runner) emits `ResourceWarning: unclosed database` for every connection GC'd without an explicit close, producing noisy output in the coverage job. Add `DbStore._connection()`, a `contextmanager` that calls `self._connect()`, wraps it in the existing transaction context manager, and closes the connection in a `finally` block. Change all `with self._connect() as conn:` call sites in `db_store.py`, `audit_store.py`, `queue_store.py`, and `orchestrator/registry.py` to `with self._connection() as conn:`. `_connect()` remains as the per-subclass hook (RegistryStore overrides it to set `busy_timeout`); `_connection()` delegates to `self._connect()` so the override is respected.
2026-07-18 21:43:43 +00:00 · 2026-07-18 21:17:22 +00:00 · 2026-07-18 17:02:40 -04:00 · 2026-07-18 16:56:44 -04:00 · 2026-07-18 16:51:31 -04:00 · 2026-07-18 15:27:29 -04:00
31 changed files with 1551 additions and 683 deletions
@@ -24,8 +24,19 @@ jobs:

      - name: Run pylint
        run: |
-          # Run pylint on all Python files in the repo
-          find . -name '*.py' -not -path './.venv/*' -not -path './.git/*' | xargs pylint --fail-under=8.0
+          # Pylint's normal exit code is nonzero for any emitted finding,
+          # regardless of --fail-under. Preserve the full report but enforce
+          # the aggregate score this workflow promises.
+          set +e
+          find . -name '*.py' -not -path './.venv/*' -not -path './.git/*' \
+            | xargs pylint --fail-under=8.0 \
+            | tee /tmp/pylint-output.txt
+          set -e
+          SCORE=$(sed -n \
+            's/^Your code has been rated at \([-0-9.]*\)\/10.*/\1/p' \
+            /tmp/pylint-output.txt | tail -1)
+          test -n "$SCORE"
+          awk -v score="$SCORE" 'BEGIN { exit !(score >= 8.0) }'

      - name: Run pyright
        run: |
@@ -4,16 +4,15 @@
 # dependencies are required to execute it. Tests are split by directory:
 #
 #   tests/unit/         — pure unit tests; always run
-#   tests/integration/  — need a reachable Docker daemon; skip cleanly
-#                         (via tests/_docker.py:skip_unless_docker) when
-#                         Docker isn't available on the runner
+#   tests/integration/  — need a reachable backend; skip cleanly when
+#                         the backend isn't available on the runner
 #   tests/canaries/     — upstream regression canaries; run on a separate
 #                         schedule (see canaries.yml), not here
 #
-# This workflow assumes the Gitea Actions runner exposes the host Docker
-# socket to the job container so `docker` commands inside the job can
-# reach the daemon. If that's not yet configured on the runner the
-# integration tests will skip rather than fail.
+# Integration tests run once per backend in separate jobs. Each job sets
+# BOT_BOTTLE_BACKEND explicitly so the test suite uses the right backend.
+# Backends that aren't available on the runner fail the preflight step
+# rather than silently skipping inside the test output.

 name: test

@@ -23,9 +22,16 @@ on:
      - main
    paths:
      - '**.py'
+      - '.gitea/workflows/**.yml'
+      - 'scripts/**'
+      - 'README.md'
  pull_request:
    paths:
      - '**.py'
+      - '.gitea/workflows/**.yml'
+      - 'scripts/**'
+      - 'README.md'
+  workflow_dispatch:

 jobs:
  unit:
@@ -48,7 +54,7 @@ jobs:
      - name: Report unit coverage
        run: python3 -m coverage report -m

-  integration:
+  integration-docker:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
@@ -65,33 +71,96 @@ jobs:
            echo "docker not on PATH — integration tests will skip"
          fi

-      - name: Run integration tests
+      - name: Run integration tests (docker)
+        env:
+          BOT_BOTTLE_BACKEND: docker
        run: python3 -m unittest discover -t . -s tests/integration -v

-  # Combined unit+integration coverage report (informational). See
-  # docs/decisions/0004-coverage-policy.md.
+  # Integration tests against the Firecracker backend. Runs on a self-hosted
+  # KVM runner (label `kvm`) where /dev/kvm and the TAP/nft pool are available.
  #
-  # The hard diff-coverage gate (changed lines >= 90%) is DEFERRED: the
-  # Firecracker backend's VM/SSH orchestration is covered by the integration
-  # suite, which needs /dev/kvm + the provisioned TAP/nft pool — a
-  # container-based runner skips it and those lines read uncovered, so the
-  # gate can't pass here. Re-enabling it on a self-hosted KVM runner is
-  # tracked separately (see PRD 0069 / #348 and the ci-runner branch).
+  # Restricted to same-repo PRs, push to main, and workflow_dispatch — fork
+  # PRs don't execute untrusted code on the privileged runner.
+  #
+  # Runner prerequisites (provision once; see README "Firecracker on Linux"):
+  # `firecracker` on PATH, `/dev/kvm` accessible, Docker, cached kernel +
+  # static dropbear, and the pool as a persistent systemd unit.
+  integration-firecracker:
+    runs-on: [self-hosted, kvm]
+    if: >-
+      github.event_name == 'push' ||
+      github.event_name == 'workflow_dispatch' ||
+      (github.event_name == 'pull_request' &&
+       github.event.pull_request.head.repo.full_name == github.repository)
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Preflight — Firecracker host is ready
+        run: |
+          command -v firecracker >/dev/null || {
+            echo "firecracker not on PATH — provision the runner (README: Firecracker on Linux)"; exit 1; }
+          test -e /dev/kvm || { echo "/dev/kvm missing — KVM not available on this runner"; exit 1; }
+          # `backend status` exits non-zero unless the TAP pool is up + no
+          # range overlap; it prints the exact `backend setup` fix.
+          python3 cli.py backend status --backend=firecracker
+
+      # No dev-requirements install: the integration suite runs on stdlib
+      # `unittest` (pylint/pyright are lint.yml's concern, not this job's),
+      # and the self-hosted runner's Nix python env has no `pip` module
+      # (`python3 -m pip` → "No module named pip"). Nothing to install.
+      - name: Run integration tests (firecracker)
+        env:
+          BOT_BOTTLE_BACKEND: firecracker
+        run: python3 -m unittest discover -t . -s tests/integration -v
+
+  # Combined unit+integration coverage + the diff-coverage gate (the hard
+  # gate: new/changed lines >= 90%). See docs/decisions/0004-coverage-policy.md.
+  #
+  # This runs on a self-hosted KVM runner (label `kvm`), NOT ubuntu-latest,
+  # because the Firecracker backend's subprocess/VM orchestration
+  # (launch/boot/SSH/isolation-probe) is covered by the integration suite,
+  # and that suite needs `/dev/kvm` + the provisioned TAP/nft pool — which a
+  # container-based runner doesn't have. On such a runner the firecracker
+  # integration test skips and its ~230 orchestration lines read as
+  # uncovered, so the gate can't pass there.
+  #
+  # Restricted to the same events as integration-firecracker (same-repo PRs,
+  # push, workflow_dispatch) for the same security reason.
+  #
+  # See #414 for the planned follow-up: artifact-based coverage combination
+  # (run tests once in their respective jobs, combine .coverage files here).
  coverage:
-    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    runs-on: [self-hosted, kvm]
+    if: >-
+      github.event_name == 'push' ||
+      github.event_name == 'workflow_dispatch' ||
+      (github.event_name == 'pull_request' &&
+       github.event.pull_request.head.repo.full_name == github.repository)
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        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: Install dev requirements
-        run: python3 -m pip install --break-system-packages -r requirements-dev.txt
+      - name: Preflight — Firecracker host is ready
+        run: |
+          command -v firecracker >/dev/null || {
+            echo "firecracker not on PATH — provision the runner (README: Firecracker on Linux)"; exit 1; }
+          test -e /dev/kvm || { echo "/dev/kvm missing — KVM not available on this runner"; exit 1; }
+          # `backend status` exits non-zero unless the TAP pool is up + no
+          # range overlap; it prints the exact `backend setup` fix.
+          python3 cli.py backend status --backend=firecracker

-      - name: Combined coverage report (unit + integration)
+      # No dev-requirements install: `coverage` is already provided by the
+      # self-hosted runner's Nix python env, and that env has no `pip`
+      # module to install into anyway. `scripts/coverage.sh` +
+      # `diff_coverage.py` need only `coverage` (not pylint/pyright).
+      - name: Combined coverage (unit + integration, incl. firecracker)
        run: PYTHON=python3 bash scripts/coverage.sh critical
+
+      - name: Diff-coverage gate (changed lines >= 90%)
+        run: |
+          git fetch --no-tags origin main:refs/remotes/origin/main
+          python3 scripts/diff_coverage.py --base origin/main --min 90
@@ -0,0 +1,17 @@
+name: tracker-policy-issues
+
+on:
+  issues:
+    types: [opened, unlabeled]
+
+jobs:
+  label-issue:
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+    steps:
+      - uses: actions/checkout@v4
+      - name: Ensure the issue has a label
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: python3 scripts/tracker_policy.py label-issue
@@ -0,0 +1,18 @@
+name: tracker-policy-pr
+
+on:
+  pull_request:
+    types: [opened, edited, reopened, synchronized, labeled, unlabeled]
+
+jobs:
+  check-pr:
+    runs-on: ubuntu-latest
+    permissions:
+      issues: read
+      pull-requests: read
+    steps:
+      - uses: actions/checkout@v4
+      - name: Require an unlabeled PR linked to an issue
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: python3 scripts/tracker_policy.py check-pr
@@ -90,6 +90,8 @@ BOT_BOTTLE_BACKEND=firecracker ./cli.py start <agent>

 > **NixOS:** enable `virtualisation.docker`, ensure the KVM module is loaded (`boot.kernelModules = [ "kvm-intel" ];` or `kvm-amd`), and add your user to the `kvm` and `docker` groups. For the network pool, consume the flake module — `imports = [ inputs.bot-bottle.nixosModules.firecracker-netpool ]; services.bot-bottle-firecracker = { enable = true; owner = "you"; };` — then `nixos-rebuild switch` (imperative nft/TAP rules don't survive a rebuild; channel users can `imports = [ <bot-bottle>/nix/firecracker-netpool.nix ]`). `firecracker` isn't in nixpkgs by default as a user binary — install the release binary (pin the version) and put it on `PATH`.

+> **CI:** the coverage gate (`.gitea/workflows/test.yml` → `coverage` job) runs on a self-hosted runner labelled `kvm`, because the Firecracker backend's VM/SSH orchestration is exercised only by the integration suite, which needs `/dev/kvm` + the provisioned pool (a container runner would skip it and read as uncovered). Provision that runner exactly like a normal Firecracker host — `firecracker` on `PATH`, `/dev/kvm`, Docker, the cached guest kernel + static dropbear, and the pool installed as the persistent systemd unit — then register it with the `kvm` label. The unit/lint jobs still run on `ubuntu-latest`.
+
 ```sh
 ./cli.py start <agent>   # builds the image on first run, drops you into claude
 ```
@@ -171,6 +173,15 @@ When an outbound DLP detector matches a token, the route's `dlp.outbound_on_matc

 More examples in `examples/`. Full design lives under `docs/prds/`; the trust-boundary rationale is in `docs/prds/0011-per-file-md-manifest.md`.

+## Tracker policy
+
+Issues are the canonical work items and own all tracker labels; every issue
+must have at least one. Pull requests stay unlabeled and deliberately reference
+an issue with `Closes #…`, `Part of #…`, or another form defined in
+[`ADR 0005`](docs/decisions/0005-issues-own-tracker-metadata.md). Gitea Actions
+enforces the convention for new work from 2026-07-18 onward. Earlier closed
+PRs are grandfathered rather than given artificial retrospective issues.
+
 ## Trademarks

 bot-bottle is an independent project and is not affiliated with, endorsed by, or sponsored by Anthropic, PBC. "Claude" and "Claude Code" are trademarks of Anthropic, PBC; the project name uses "claude" descriptively to indicate that the tool runs Claude Code inside a sandbox.
@@ -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",
@@ -42,7 +42,7 @@ class AuditStore(DbStore):
        super().__init__(db_path or host_db_path(), migrations)

    def write_audit_entry(self, entry: AuditEntry) -> Path:
-        with self._connect() as conn:
+        with self._connection() as conn:
            conn.execute(
                """
                INSERT INTO supervise_audit_entries (
@@ -66,7 +66,7 @@ class AuditStore(DbStore):
    def read_audit_entries(self, component: str, slug: str) -> list[AuditEntry]:
        if not self.db_path.is_file():
            return []
-        with self._connect() as conn:
+        with self._connection() as conn:
            rows = conn.execute(
                """
                SELECT * FROM supervise_audit_entries
@@ -38,6 +38,13 @@ COMMANDS = {
    "supervise": cmd_supervise,
 }

+# Commands that manage host prerequisites (or are otherwise store-free) and
+# must run before — or without — a migrated DB. `backend` provisions/probes
+# the host (TAP pool, /dev/kvm, firecracker) and never opens the store, so
+# gating it on the schema breaks preflight on a fresh CI runner where stdin
+# isn't a TTY and the migration prompt can't be answered.
+NO_MIGRATION_COMMANDS = frozenset({"backend"})
+

 def usage() -> None:
    sys.stderr.write(f"usage: {PROG} <command> [args...]\n\n")
@@ -80,7 +87,7 @@ def main(argv: list[str] | None = None) -> int:
        usage()
        die(f"unknown command: {command}")
    mgr = StoreManager.instance()
-    if not mgr.is_migrated():
+    if command not in NO_MIGRATION_COMMANDS and 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()
@@ -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:
@@ -119,6 +118,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
@@ -180,24 +180,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"})

@@ -219,7 +208,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:
@@ -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",
-]
@@ -3,6 +3,7 @@
 from __future__ import annotations

 import sqlite3
+from contextlib import contextmanager
 from pathlib import Path

 try:
@@ -28,12 +29,21 @@ class DbStore:
        conn.row_factory = sqlite3.Row
        return conn

+    @contextmanager
+    def _connection(self):
+        conn = self._connect()
+        try:
+            with conn:
+                yield conn
+        finally:
+            conn.close()
+
    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:
+            with self._connection() as conn:
                row = conn.execute(
                    "SELECT version FROM schema_versions WHERE module = ?",
                    (self._migrations.schema_key,),
@@ -45,7 +55,7 @@ class DbStore:

    def migrate(self) -> None:
        """Apply any pending migrations and set permissions on the DB file."""
-        with self._connect() as conn:
+        with self._connection() as conn:
            self._migrations.apply(conn)
        self._chmod()

@@ -30,7 +30,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"

@@ -401,7 +400,6 @@ class Egress(ABC):
        )

 __all__ = [
-    "CLAUDE_HOST_CREDENTIAL_TOKEN_REF",
    "CODEX_HOST_CREDENTIAL_TOKEN_REF",
    "EGRESS_HOSTNAME",
    "EGRESS_ROUTES_FILENAME",
@@ -419,18 +419,24 @@ PY
 while IFS=' ' read -r old new ref; do
  [ -z "$ref" ] && continue
  [ "$new" = "$zero" ] && continue
-  if [ "$old" = "$zero" ]; then
-    # New ref: scan only the commits this push introduces — those
-    # reachable from $new but not from any ref the gate already has.
-    # Everything already on the gate arrived via upstream mirror-fetch
-    # or a previously gitleaks-scanned push, so it's already-upstream
-    # or already-scanned; re-scanning it (the old `$new` full-ancestry
-    # range) only resurfaces historical findings and blocks every new
-    # branch. See PRD 0028 / issue #106.
-    log_opts="$new --not --all"
-  else
-    log_opts="$old..$new"
-  fi
+  # Scan only the commits this push introduces — those reachable from
+  # $new but not from any ref the gate already has. Everything already
+  # on the gate arrived via upstream mirror-fetch or a previously
+  # gitleaks-scanned push, so it's already-upstream or already-scanned;
+  # re-scanning it only resurfaces historical fixture findings.
+  #
+  # Applies to both new refs and updates. The old existing-branch range
+  # `$old..$new` walks commits reachable from the new tip but not the
+  # *old branch tip*: on a rebase/force-push onto a freshly-advanced
+  # main that pulls in all of main's new history (incl. the deliberate
+  # sandbox-escape gitleaks fixtures), blocking the push. `--not --all`
+  # excludes anything already on the gate regardless of ancestry, so it
+  # is also correct for non-fast-forward pushes (a rebase can skip
+  # commits off the direct path). Security-equivalent per PRD 0028's
+  # analysis: the bare repo's refs come only from trusted upstream
+  # mirror-fetch or gitleaks-gated pushes.
+  # See PRD 0028 (open question) / issues #106, #346.
+  log_opts="$new --not --all"
  echo "git-gate: gitleaks scanning $ref ($log_opts)" >&2
  if ! gitleaks git --log-opts="$log_opts" --no-banner --redact 1>&2; then
    echo "git-gate: gitleaks rejected push to $ref" >&2
@@ -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/.credentials.json`.
+    `forward_host_credentials` forwards the host Codex auth token into
+    the egress daemon (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(
@@ -167,7 +167,7 @@ class RegistryStore(DbStore):
            metadata=metadata,
            policy=policy,
        )
-        with self._connect() as conn:
+        with self._connection() as conn:
            conn.execute(
                "DELETE FROM orchestrator_bottles "
                "WHERE source_ip = ? AND state = 'active' AND bottle_id != ?",
@@ -193,7 +193,7 @@ class RegistryStore(DbStore):
    def set_policy(self, bottle_id: str, policy: str) -> bool:
        """Update a bottle's policy in place (live reload). Returns True if
        the bottle exists."""
-        with self._connect() as conn:
+        with self._connection() as conn:
            cur = conn.execute(
                "UPDATE orchestrator_bottles SET policy = ? WHERE bottle_id = ?",
                (policy, bottle_id),
@@ -203,7 +203,7 @@ class RegistryStore(DbStore):

    def deregister(self, bottle_id: str) -> bool:
        """Remove a bottle. Returns True if a row was deleted."""
-        with self._connect() as conn:
+        with self._connection() as conn:
            cur = conn.execute(
                "DELETE FROM orchestrator_bottles WHERE bottle_id = ?", (bottle_id,)
            )
@@ -211,7 +211,7 @@ class RegistryStore(DbStore):

    def get(self, bottle_id: str) -> BottleRecord | None:
        """Return the bottle by id, or None if absent."""
-        with self._connect() as conn:
+        with self._connection() as conn:
            row = conn.execute(
                "SELECT * FROM orchestrator_bottles WHERE bottle_id = ?", (bottle_id,)
            ).fetchone()
@@ -219,7 +219,7 @@ class RegistryStore(DbStore):

    def all(self) -> list[BottleRecord]:
        """Every registered bottle, oldest first."""
-        with self._connect() as conn:
+        with self._connection() as conn:
            rows = conn.execute(
                "SELECT * FROM orchestrator_bottles ORDER BY created_at"
            ).fetchall()
@@ -232,7 +232,7 @@ class RegistryStore(DbStore):
        source IP is unspoofable (Firecracker `/31` + nft) and the control
        plane is reachable only by the trusted gateway; pair with the
        identity token (`attribute`) elsewhere."""
-        with self._connect() as conn:
+        with self._connection() as conn:
            rows = conn.execute(
                "SELECT * FROM orchestrator_bottles "
                "WHERE source_ip = ? AND state = 'active'",
@@ -66,7 +66,7 @@ class QueueStore(DbStore):
        super().__init__(resolved, migrations)

    def write_proposal(self, proposal: Proposal) -> Path:
-        with self._connect() as conn:
+        with self._connection() as conn:
            conn.execute(
                """
                INSERT OR REPLACE INTO supervise_proposals (
@@ -89,7 +89,7 @@ class QueueStore(DbStore):
        return self.db_path

    def read_proposal(self, proposal_id: str) -> Proposal:
-        with self._connect() as conn:
+        with self._connection() as conn:
            row = conn.execute(
                """
                SELECT * FROM supervise_proposals
@@ -104,7 +104,7 @@ class QueueStore(DbStore):
    def list_pending_proposals(self) -> list[Proposal]:
        if not self.db_path.is_file():
            return []
-        with self._connect() as conn:
+        with self._connection() as conn:
            rows = conn.execute(
                """
                SELECT p.* FROM supervise_proposals p
@@ -125,7 +125,7 @@ class QueueStore(DbStore):
    def list_all_pending_proposals(self) -> list[Proposal]:
        if not self.db_path.is_file():
            return []
-        with self._connect() as conn:
+        with self._connection() as conn:
            rows = conn.execute(
                """
                SELECT p.* FROM supervise_proposals p
@@ -142,7 +142,7 @@ class QueueStore(DbStore):
        return [self._row_to_proposal(row) for row in rows]

    def write_response(self, response: Response) -> Path:
-        with self._connect() as conn:
+        with self._connection() as conn:
            conn.execute(
                """
                INSERT OR REPLACE INTO supervise_responses (
@@ -161,7 +161,7 @@ class QueueStore(DbStore):
        return self.db_path

    def read_response(self, proposal_id: str) -> Response:
-        with self._connect() as conn:
+        with self._connection() as conn:
            row = conn.execute(
                """
                SELECT * FROM supervise_responses
@@ -176,7 +176,7 @@ class QueueStore(DbStore):
    def archive_proposal(self, proposal_id: str) -> None:
        if not self.db_path.is_file():
            return
-        with self._connect() as conn:
+        with self._connection() as conn:
            conn.execute(
                """
                UPDATE supervise_proposals SET archived = 1
@@ -0,0 +1,57 @@
+# ADR 0005: Keep tracker metadata on issues
+
+- **Status:** Accepted
+- **Date:** 2026-07-18
+- **Deciders:** didericis
+
+## Context
+
+Gitea exposes labels on both issues and pull requests. Applying the same labels
+to both copies planning metadata, creates a synchronization obligation, and
+makes disagreements between the two records possible. At the same time,
+unlabelled objects look accidental unless the repository states which object
+owns the metadata.
+
+The repository already uses issues as work items and PRs as implementations of
+those work items. At this decision's cutoff, all open PRs reference issues, but
+121 of 219 historically merged PRs do not. Manufacturing retrospective issues
+for that history would create records that never participated in planning and
+would make the issue history less truthful.
+
+## Decision
+
+Issues are the canonical tracker records and own labels. Every issue has at
+least one label. An issue opened or left without labels receives
+`Status/Needs Triage` automatically until it is classified.
+
+Pull requests carry no labels. Every new PR deliberately references at least
+one existing issue in its title or description with one of these forms:
+
+- `Closes #123`, `Fixes #123`, or `Resolves #123` when merging completes it.
+- `Part of #123`, `Related to #123`, `Refs #123`, or `References #123` when it
+  contributes without completing it.
+
+Gitea Actions enforces both PR rules as a status check and repairs the empty
+issue-label state. Branch protection makes the PR policy check required.
+
+The policy applies from 2026-07-18 onward. Existing issues may be labelled as
+they are encountered, but closed PRs are grandfathered: no retrospective
+issues or PR labels are created solely to make history conform.
+
+## Consequences
+
+- Classification, priority, and workflow metadata have one source of truth.
+- A PR's issue link is the navigation path to its planning metadata.
+- Multi-PR issues do not require copied or synchronized labels.
+- `Status/Needs Triage` is an intentional fallback, not a final
+  classification.
+- Direct issue creation remains convenient; automation repairs a missing label
+  immediately after creation because Gitea has no native required-label rule.
+- The required check must be configured in branch protection after this
+  workflow lands.
+
+## Links
+
+- Issue #405.
+- `.gitea/workflows/tracker-policy.yml`.
+- `scripts/tracker_policy.py`.
@@ -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/.credentials.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/.credentials.json`
-after `claude login`. 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/.credentials.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": "<access-token>",
-    "refreshToken": "<refresh-token>",
-    "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/.credentials.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.
@@ -6,27 +6,61 @@ general AI-agent sandbox / containment projects — some Claude-specific,
 some agent-agnostic, some hosted SaaS — and contrasts them with
 bot-bottle's design.

-Research conducted 2026-05-11.
+Research conducted 2026-05-11. CubeSandbox added 2026-07-18 (see its
+per-project note and the addendum at the end). Also updated 2026-07-18:
+bot-bottle no longer uses **pipelock** — outbound DLP is now bot-bottle's
+own (deliberately simple) egress scanner (a mitmproxy addon with custom
+detectors, PRD 0017 / 0053), and git-push secret scanning is handled by
+**gitleaks** in the git-gate. "pipelock" below has been replaced with the
+current mechanism; it survives only in older PRDs as history.
+
+Updated again 2026-07-18: six additional tools added (Cleanroom,
+container-use, Docker sbx, Anthropic srt, Microsoft AGT, Open Agent
+Passport); an **Agent-tailored policy** row added to the comparison table;
+a separate Governance layers section added for AGT and OAP. See the
+second addendum at the end.

 ## Summary

-Eight projects surveyed. None duplicate bot-bottle's combination of
-local Docker, declarative JSON manifest, per-agent egress allowlist via
-pipelock, and bottle/agent split. Two clusters stand out:
+Fifteen projects surveyed across two categories: isolation/sandbox tools
+and governance/pre-action authorization layers (the latter don't provide
+VM or container isolation but do per-agent policy enforcement at the
+tool-call level). None duplicate bot-bottle's combination of local
+VM-per-bottle isolation, a declarative per-role manifest, per-agent
+egress allowlist + outbound-content DLP, bottle/agent split, and the
+composable `extends:` policy model. Three clusters stand out:

 - **Closest neighbours** — agent-safehouse and litterbox: local,
  single-user, thin wrappers over an existing OS primitive
  (`sandbox-exec`, Podman + Landlock).
- **Different category** — tilde.run (hosted SaaS), boxlite and
-  microsandbox (microVM libraries for platform builders), endo-familiar
+- **Different category (isolation)** — tilde.run (hosted SaaS), boxlite
+  and microsandbox (microVM libraries for platform builders), CubeSandbox
+  (self-hosted multi-tenant microVM service), endo-familiar
  (capability-security paradigm, no OS isolation).
+- **New: governance/pre-action layers** — Microsoft AGT and Open Agent
+  Passport (OAP): framework-embedded tool-call interceptors with
+  per-agent declarative policy. Closest competitors on agent-tailored
+  policy, but operate at the tool-call level rather than providing
+  network/filesystem isolation; they complement rather than substitute.

-The microVM cluster (matchlock, smolmachines, boxlite, microsandbox) is
-the most relevant for the v2 isolation discussion in
+The microVM cluster (matchlock, smolmachines, boxlite, microsandbox,
+CubeSandbox) is the most relevant for the v2 isolation discussion in
 [`stronger-isolation-alternatives.md`](stronger-isolation-alternatives.md):
 libkrun and Apple's Virtualization.framework have made local microVMs
-ergonomic enough that a `"runtime": "microvm"` option on a bottle is now
-plausible without a heavy stack.
+ergonomic enough that microVMs are **now bot-bottle's default backend**
+(Firecracker on KVM Linux, Apple Container on macOS), with Docker kept
+only as a legacy fallback for CI / hosts without KVM or Apple Container.
+That discussion has since shipped, not just been theorized.
+
+**The one that matters most for positioning is CubeSandbox** — it is the
+first surveyed project to ship bot-bottle's would-be wedge (default-deny
+egress allowlist + full audit logs + in-flight credential custody so keys
+never enter the sandbox) *combined with* per-sandbox microVM isolation,
+open-source under Apache 2.0, with Tencent Cloud behind it and 10.4k
+stars. It's a self-hosted multi-tenant service for platform builders, not
+a single-user declarative tool, so it doesn't collide head-on — but it
+narrows the "nobody else bundles egress custody + credential injection"
+claim that the monetization positioning leans on. See the addendum.

 ## Per-project notes

@@ -155,67 +189,272 @@ plausible without a heavy stack.
  also supported.
 - **Maturity**: Active through April 2026.

+### CubeSandbox *(added 2026-07-18)*
+- **Source**: https://github.com/TencentCloud/CubeSandbox ;
+  HN launch https://news.ycombinator.com/item?id=47863430
+- **License**: Apache 2.0 (~10.4k stars). By Tencent Cloud; described as
+  "battle-tested, production-ready" infra already running in Tencent
+  Cloud. Rust / Go / C.
+- **Isolation**: MicroVMs via RustVMM + KVM — "each sandbox gets its own
+  Guest OS kernel, no Docker shared-kernel escapes." Hardware-level
+  isolation, dedicated kernel per instance.
+- **Locality**: Self-hosted, but **server/cluster-oriented**, not a
+  single-user local CLI. Deploy guides target PVM cloud VMs, bare metal,
+  and dev. A single 96-vCPU host is claimed to run 2,000+ concurrent
+  sandboxes.
+- **Agent integration**: **Drop-in E2B SDK replacement** (single env-var
+  change) — the headline compatibility claim. OpenClaw assistant
+  integration; general LLM-code execution. Aimed at platform builders,
+  not one developer's laptop.
+- **Config**: Programmatic via the E2B-compatible SDK. No declarative
+  manifest.
+- **Network policy**: This is the striking part — **domain allowlists,
+  instant block on unauthorized egress, full audit logs, per-sandbox
+  traffic tokens, policy-routing egress**, enforced by an eBPF-based
+  virtual switch giving kernel-level network isolation. Closest match yet
+  to bot-bottle's own default-deny + per-bottle allowlist egress model.
+- **Credentials**: **Credential vault** — agents call external APIs / LLMs
+  while "keys never enter the sandbox, model context, or logs." Same
+  in-flight-injection idea as matchlock, but productized as a vault.
+- **Performance**: <60ms cold start (claimed 2.5–50× faster than
+  alternatives), <5MB memory per instance; millisecond snapshot rollback
+  is upcoming.
+- **Maturity**: Open-sourced July 2026 off production Tencent Cloud use;
+  most-starred project in this set (~10.4k).
+
+### Cleanroom *(added 2026-07-18)*
+- **Source**: https://github.com/buildkite/cleanroom
+- **License**: Apache 2.0
+- **Isolation**: MicroVM — Firecracker on Linux, Virtualization.framework
+  on macOS. Digest-pinned OCI images.
+- **Locality**: Self-hosted server (CI-oriented).
+- **Agent integration**: Generic process sandbox; CI-first, not a
+  Claude/agent wrapper.
+- **Config**: `cleanroom.yaml` in the repo being sandboxed defines egress
+  rules, resources, and network policy. Cleanroom resolves this from the
+  commit being run.
+- **Network policy**: Default-deny + per-repo hostname allowlist (resolved
+  from DNS answers + destination IP:port). Co-hosted services on the same
+  IP:port are not distinguished. OIDC-backed auth for remote servers.
+- **Credentials**: Host-side only; not injected in-flight but not present
+  in the VM.
+- **Notable**: Policy lives in the *repo being sandboxed*, not in an
+  agent-role definition — closer to per-repo scoping than per-role.
+  Supports Docker-inside-sandbox (`services.docker.required: true`), OIDC
+  authorization, suspend/resume lifecycle.
+- **Maturity**: Active Buildkite product.
+
+### container-use *(added 2026-07-18)*
+- **Source**: https://github.com/dagger/container-use
+- **License**: Apache 2.0
+- **Isolation**: Docker container per agent + git worktree per agent.
+  Containers share the host kernel; stronger than bare host but weaker
+  than microVM.
+- **Locality**: Local.
+- **Agent integration**: MCP stdio server — Claude Code, Cursor, Windsurf.
+  `claude mcp add container-use -- container-use stdio`.
+- **Config**: None for security policy. Environments are provisioned on
+  demand; no allowlist or credential config.
+- **Network policy**: Not addressed.
+- **Notable**: Per-agent git branches (`container-use/<env_name>`);
+  parallel agents without filesystem conflict; real-time log visibility
+  and terminal attach for intervention; git-based review workflow.
+  Oriented toward parallel development safety, not security containment.
+- **Maturity**: Early development, active.
+
+### Docker sbx *(added 2026-07-18)*
+- **Source**: Docker proprietary (`sbx` CLI, separate from `docker`).
+- **License**: Proprietary.
+- **Isolation**: MicroVM (Docker's own implementation) — each session gets
+  its own kernel, Docker daemon inside the VM, and filesystem.
+- **Locality**: Local (macOS and Windows; does not require Docker Desktop).
+- **Agent integration**: Explicit wrapper — Claude Code, Codex, Gemini
+  CLI, Copilot CLI, Kiro. Launches agent inside the VM with
+  `--dangerously-skip-permissions` by default.
+- **Config**: Open / Balanced / Locked Down network presets at launch. No
+  per-role manifest.
+- **Network policy**: Default-deny; preset levels control strictness. TUI
+  dashboard shows a live log of every outbound connection (allowed and
+  blocked) with point-and-click allow/block for hosts.
+- **Credentials**: OS keychain + host-side proxy injection — API keys
+  never enter the VM.
+- **Notable**: Best DX among microVM tools (one command, works like native
+  yolo Claude but inside a VM); branch mode creates a git worktree in
+  `.sbx/`. Network policy is preset-based, not role-declarative.
+- **Maturity**: GA 2026.
+
+### Anthropic srt *(added 2026-07-18)*
+- **Source**: https://github.com/anthropic-experimental/sandbox-runtime
+  (`@anthropic-ai/sandbox-runtime` on npm, `sandbox-runtime` on PyPI)
+- **License**: Apache 2.0 (experimental).
+- **Isolation**: OS-level only — Seatbelt (`sandbox-exec`) on macOS,
+  bubblewrap on Linux, WFP (Windows Filtering Platform) account-fenced on
+  Windows. **No container or VM.** Lowest overhead in the set.
+- **Locality**: Local.
+- **Agent integration**: Claude Code's sandboxed bash tool uses this
+  internally. Can wrap any arbitrary process (`srt <command>`). Cloud
+  Claude Code sessions use full microVMs instead.
+- **Config**: Programmatic per-invocation — allow/deny path lists for
+  filesystem; allow/denylist for network (HTTP proxy + SOCKS5).
+- **Network policy**: Proxy-based filtering (HTTP + SOCKS5); domain
+  allowlist/denylist enforced at proxy layer. Custom proxy supported
+  (e.g. mitmproxy for inspection + audit). Processes that ignore proxy
+  env vars may bypass filtering on some platforms.
+- **Notable**: Cross-platform (macOS/Linux/Windows); wraps any process,
+  not just agents; no role/manifest concept. Annotated as a research
+  preview — APIs may change.
+- **Maturity**: Early research preview.
+
+## Governance / pre-action authorization layers
+
+These two tools don't provide VM or filesystem isolation; they intercept
+tool calls before execution and evaluate them against a per-agent
+declarative policy. They are the closest competitors on **agent-tailored
+policy** and complement isolation sandboxes rather than substituting for
+them.
+
+### Microsoft Agent Governance Toolkit (AGT) *(added 2026-07-18)*
+- **Source**: https://github.com/microsoft/agent-governance-toolkit
+- **License**: MIT (~3.3k stars, open-sourced April 2, 2026).
+- **Isolation**: None (OS/VM). Execution rings (0–3, inspired by CPU
+  privilege levels) control what an agent can do at the framework layer.
+  MCP security gateway treats MCP traffic as an untrusted boundary.
+- **Locality**: Embedded in the agent framework (Python, TypeScript, .NET,
+  Rust, Go; 20+ framework adapters).
+- **Agent integration**: Framework-agnostic. Plugs into Semantic Kernel,
+  AutoGen, and others as a middleware layer.
+- **Config**: YAML policy per agent — tools can be `allowed`, `denied`,
+  `sandboxed`, or routed through an `approval` step. Every action passes
+  through a governance gate checking: agent DID, trust score, risk tier,
+  requested tool, action type, and policy rules.
+- **Network policy**: Not directly — operates at tool-call level.
+- **Credentials**: Per-agent DID (Ed25519 decentralized identifier); agent
+  does not borrow a human's credentials.
+- **Notable**: Dynamic trust score (0–1,000, behavioral decay) —
+  privilege follows observed behaviour, not just provisioning. Covers all
+  10 OWASP Agentic Top 10 risks. Kill switch + SLO monitoring. Sub-ms
+  policy enforcement.
+- **Maturity**: MIT, ~3.3k ⭐, v3.7.0 May 2026.
+
+### Open Agent Passport (OAP) *(added 2026-07-18)*
+- **Source**: https://github.com/aporthq/aport-spec ; spec at
+  https://api.aport.io/spec/spec/oap/oap-spec.md/ ; arXiv 2603.20953
+- **License**: Open specification.
+- **Isolation**: None. Pre-action hook only — intercepts tool calls
+  synchronously before execution, evaluates against a cloud-registry
+  declarative policy, fails closed.
+- **Locality**: Local hook + cloud policy registry.
+- **Agent integration**: Framework-agnostic; hook pattern.
+- **Config**: Declarative policy rules in a cloud registry (evaluated in
+  order; first failing rule denies). Ed25519-signed, hash-chained audit
+  records per decision.
+- **Network policy**: Not directly.
+- **Notable**: 53ms median authorization decision (N=1,000). In an
+  adversarial testbed ($5,000 bounty, 1,151 sessions), social engineering
+  succeeded 74.6% of the time under a permissive policy; under a
+  restrictive OAP policy, 0% success across 879 attempts. Assumes
+  framework runtime is not compromised.
+- **Maturity**: Specification + reference implementation, 2026.
+
 ## Comparison table

-| Axis | bot-bottle | endo-familiar | litterbox | agent-safehouse | matchlock | tilde.run | boxlite | microsandbox | smolmachines |
-|---|---|---|---|---|---|---|---|---|---|
-| Isolation | Docker + internal net + pipelock; gVisor if present | Object-capability (no OS isolation) | Podman + opt. Landlock | macOS `sandbox-exec` | MicroVM (Firecracker / Virt.fw) | Hosted container (unverified) | MicroVM (KVM / Hypervisor.fw) | MicroVM (libkrun) | MicroVM (libkrun / KVM) |
-| Local vs hosted | Local | Local | Local (Linux) | Local (macOS) | Local | Hosted SaaS | Local | Local | Local |
-| Open source | Apache 2.0 | Apache 2.0 | Apache 2.0 | Apache 2.0 | MIT | No | Apache 2.0 | Apache 2.0 | Apache 2.0 |
-| Agent target | Claude Code | Generic (demo) | Generic | Multi-agent wrapper | Generic (+ Claude/OpenAI SDKs) | Claude focus | Generic | Claude + Cursor (MCP/Skills) | Generic (AGENTS.md) |
-| Network policy | Default-deny via pipelock + per-bottle allowlist + DLP | Capability model only | Limited | Not addressed | Default-deny + allowlist + secret-injecting proxy | Default-deny + logging | Per-VM net (unverified) | Not documented | Off by default + allowlist |
-| Parallel agents | Yes (one bottle per agent) | n/a | Not addressed | One at a time | Multiple VMs | Yes (dashboard) | SDK-level | SDK-level | Architectural |
-| Config | JSON manifest (bottles + agents) | Programmatic refs | CLI wizard | Profile files / shell fns | CLI / SDK | DSL + CLI + SDK | SDK | CLI / SDK / MCP | TOML Smolfile |
-| Maturity | Active May 2026 | Research (2022+) | Early (~66 ⭐) | Active (~1.4k ⭐) | Experimental (~574 ⭐) | Private preview | YC, ~4.7k ⭐ | YC, ~6k ⭐, beta | ~3.1k ⭐ |
+*Isolation/sandbox tools only. AGT and OAP are governance layers — see their per-project notes above.*
+
+| Axis | bot-bottle | endo-familiar | litterbox | agent-safehouse | matchlock | tilde.run | boxlite | microsandbox | smolmachines | CubeSandbox | Cleanroom | container-use | Docker sbx | Anthropic srt |
+|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
+| Isolation | MicroVM per bottle default (Firecracker/KVM on Linux, Apple Container on macOS) + own egress DLP scanner; Docker legacy fallback, gVisor there if present | Object-capability (no OS isolation) | Podman + opt. Landlock | macOS `sandbox-exec` | MicroVM (Firecracker / Virt.fw) | Hosted container (unverified) | MicroVM (KVM / Hypervisor.fw) | MicroVM (libkrun) | MicroVM (libkrun / KVM) | MicroVM (RustVMM / KVM) | MicroVM (Firecracker / Virt.fw) | Docker container + git worktree | MicroVM (proprietary) | OS-level (Seatbelt / bubblewrap / WFP) — no container |
+| Local vs hosted | Local | Local | Local (Linux) | Local (macOS) | Local | Hosted SaaS | Local | Local | Local | Self-hosted (server/cluster) | Self-hosted server | Local | Local | Local |
+| Open source | Apache 2.0 | Apache 2.0 | Apache 2.0 | Apache 2.0 | MIT | No | Apache 2.0 | Apache 2.0 | Apache 2.0 | Apache 2.0 | Apache 2.0 | Apache 2.0 | Proprietary | Apache 2.0 (experimental) |
+| Agent target | Claude Code | Generic (demo) | Generic | Multi-agent wrapper | Generic (+ Claude/OpenAI SDKs) | Claude focus | Generic | Claude + Cursor (MCP/Skills) | Generic (AGENTS.md) | E2B-compatible (platform builders) | CI / generic process | Claude Code, Cursor, Windsurf (MCP) | Claude Code, Codex, Gemini CLI, Copilot, Kiro | Claude Code (and any process) |
+| Network policy | Default-deny via own egress scanner + per-bottle allowlist + content DLP + gitleaks on git push | Capability model only | Limited | Not addressed | Default-deny + allowlist + secret-injecting proxy | Default-deny + logging | Per-VM net (unverified) | Not documented | Off by default + allowlist | Default-deny allowlist + instant egress block + audit logs + per-sandbox tokens (eBPF) + credential vault | Default-deny + per-repo host allowlist (cleanroom.yaml) | Not addressed | Default-deny; Open / Balanced / Locked Down presets; live TUI network panel | Proxy-based allowlist/denylist (HTTP + SOCKS5); custom proxy supported |
+| Parallel agents | Yes (one bottle per agent) | n/a | Not addressed | One at a time | Multiple VMs | Yes (dashboard) | SDK-level | SDK-level | Architectural | Yes (2,000+/host claimed) | Yes (server model) | Yes (per-agent containers + worktrees) | Yes | Yes |
+| Long-running posture | Persistent by default (named, supervised) | n/a (demo) | Session (up while in use) | Per-invocation | Ephemeral VM per run | Per-run (versioned) | Ephemeral + snapshot/fork | Ephemeral / on-demand | Named persistent by default | Ephemeral + auto pause/resume | Per-run + suspend/resume | Per-agent container (ephemeral) | Per-session; branch mode creates git worktree in .sbx/ | Per-invocation |
+| DX: run Claude yolo-style | One command → interactive yolo Claude (`start <agent>`, `--dangerously-skip-permissions` default) | n/a (lib demo) | Wizard + build, then run claude inside (Linux only) | One-command wrapper (`safehouse claude --dangerously-skip-permissions`) | CLI: run a cmd in a VM (not a Claude wrapper) | Hosted (`tilde exec`), not local-native | SDK code required (build the run yourself) | CLI/MCP: sandbox-as-a-tool for the agent, not a wrapper around it | SSH into a named machine, run claude there | Stand up a cluster + drive via E2B SDK | CI-oriented, not a Claude wrapper | MCP server: `claude mcp add container-use -- container-use stdio` | One command: `sbx` wraps claude with `--dangerously-skip-permissions` default | Library/wrapper, not a standalone CLI |
+| Config | JSON manifest (bottles + agents) | Programmatic refs | CLI wizard | Profile files / shell fns | CLI / SDK | DSL + CLI + SDK | SDK | CLI / SDK / MCP | TOML Smolfile | E2B-compatible SDK | cleanroom.yaml in repo | None (no policy config) | Preset levels at launch | Programmatic per-invocation (allow/deny lists) |
+| Agent-tailored policy | Yes — bottle/agent split; declarative per-role egress + credentials; composable via `extends:` | Partial — capability model scopes per-agent, but no declarative role manifest | No | Partial — per-agent profile files (Seatbelt); no egress | No | Yes — per-agent DSL RBAC (allow/deny/approve per action/repo/agent) | No | No | No | No — per-sandbox SDK config, not role-scoped | Partial — per-repo cleanroom.yaml, not per-role | No | No — network presets only | No |
+| Maturity | Active July 2026 | Research (2022+) | Early (~66 ⭐) | Active (~1.4k ⭐) | Experimental (~574 ⭐) | Private preview | YC, ~4.7k ⭐ | YC, ~6k ⭐, beta | ~3.1k ⭐ | Tencent, prod, ~10.4k ⭐ | Active (Buildkite product) | Early development | GA 2026 | Early research preview |

 ## What's closest, what's different

 **Closest in design and scope.** agent-safehouse and litterbox sit
 nearest bot-bottle: local, single-user, thin wrappers over an
 existing OS primitive, low-dep. The split is the isolation primitive —
-bot-bottle uses Docker + pipelock egress (plus gVisor where
-available); agent-safehouse uses `sandbox-exec`; litterbox uses Podman +
-Landlock. matchlock and smolmachines are spiritually close on the
-*policy* side (default-deny net, per-host allowlist) but use microVMs
-instead of containers.
+bot-bottle now defaults to a VM per bottle (Firecracker microVM on KVM
+Linux, Apple Container on macOS) with its own DLP-scanning egress proxy,
+keeping Docker only as a legacy fallback; agent-safehouse uses
+`sandbox-exec`; litterbox uses Podman + Landlock. matchlock and
+smolmachines are close on *both* the policy side (default-deny net,
+per-host allowlist) and — now that bot-bottle has moved off
+containers-by-default — the microVM isolation primitive.
+
+**New closest on agent-tailored policy.** Two governance tools are the
+direct competitors on the "coarse-grained sandbox" axis. **tilde.run**
+has had per-agent DSL RBAC since its launch (though it's hosted SaaS).
+**Microsoft AGT** is the most serious new entrant: per-agent DID
+identity, YAML policy that can allow/deny/sandbox/approve individual tool
+calls per agent, and a dynamic behavioural trust score. It operates at
+the framework tool-call layer, not the network layer — so it's
+complementary to bot-bottle's network/filesystem isolation rather than a
+direct substitute, but on the "does this sandbox know what this agent is
+for?" question it is the most complete answer in the field. OAP's
+pre-action hook pattern achieves similar goals with cryptographic audit
+and a 0% adversarial-attack success rate under a restrictive policy.
+
+**New closest on DX.** **Docker sbx** is the first tool in this set that
+matches bot-bottle on the "one command, dangerously-skip-permissions safe
+by default" DX bar, at microVM isolation strength, with host-side
+credential injection. It is proprietary, preset-based (not role-
+declarative), and cloud-agent-specific, but it directly competes on the
+UX proposition. agent-safehouse was the previous DX peer; Docker sbx
+materially raises the bar.
+
+**New closest on repo-scoped policy.** **Cleanroom** (Buildkite) is the
+first tool to combine microVM isolation with a declarative egress policy
+file — though the policy lives in the repo being sandboxed
+(`cleanroom.yaml`), not in an agent-role manifest. That makes it per-
+repo rather than per-role: the same Cleanroom config applies to any
+agent running in that repo. The distinction matters for bot-bottle's
+use case (one developer running multiple agent *roles* with different
+egress footprints), but for CI/CD use cases Cleanroom is a direct
+alternative.

 **Solving a different problem.** tilde.run is hosted SaaS for team /
 production agent pipelines with data-versioned rollback — explicitly
-opposite to bot-bottle's "infrastructure I control" goal. boxlite and
-microsandbox are infrastructure libraries aimed at platform builders
-embedding sandboxes into agent frameworks; they would be a *backend*
-bot-bottle could call, not a competitor to its manifest layer.
-endo-familiar is in a different paradigm entirely: capability passing
-rather than kernel boundaries.
+opposite to bot-bottle's "infrastructure I control" goal. boxlite,
+microsandbox, and CubeSandbox are infrastructure libraries/services aimed
+at platform builders embedding sandboxes into agent frameworks; they
+would be a *backend* bot-bottle could call, not a competitor to its
+manifest layer. endo-familiar is in a different paradigm entirely:
+capability passing rather than kernel boundaries.

 ## Borrowable ideas

 What bot-bottle already has that the survey suggested as
 differentiators:
- Default-deny egress with a per-agent allowlist (pipelock).
+- Default-deny egress with a per-agent allowlist (own egress scanner).
 - DLP scanning of outbound traffic.
 - Bottle / agent split (manifest layer above the isolation primitive).
 - gVisor auto-detection on Linux.

-Ideas worth considering, without abandoning the Python-stdlib-first / local-Docker
-stance:
+Ideas worth considering, without abandoning the Python-stdlib-first /
+local, single-operator stance:

 1. **Per-use SSH key confirmation** (from litterbox). Even with
-   KnownHostKey pinning and pipelock egress, a wrapper SSH agent that
+   KnownHostKey pinning and the egress DLP scanner, a wrapper SSH agent that
   prompts on each key use (e.g. via `osascript` / `notify-send`) would
   catch an agent doing something off-policy with a key it legitimately
   holds. Pure-stdlib, no new deps.
-2. **In-flight secret injection** (from matchlock). Pipelock already
-   does egress allowlisting and DLP; teaching it to *inject* tokens at
+2. **In-flight secret injection** (from matchlock). The egress scanner
+   already does allowlisting and DLP; teaching it to *inject* tokens at
   proxy time so e.g. `GITEA_TOKEN` never appears in the container's
   env would close the "agent reads its own env and exfiltrates" path.
-   Fits the existing pipelock architecture.
-3. **MicroVM backend as an opt-in bottle type** — already on the radar
-   in `stronger-isolation-alternatives.md`. microsandbox, smolmachines,
-   and matchlock all show that libkrun + Apple's
-   Virtualization.framework is ergonomic enough that a
-   `"runtime": "microvm"` field on a bottle is plausible without a heavy
-   stack.
+   Fits the existing egress-proxy architecture.
+3. **MicroVM backend** — ~~on the radar~~ **shipped since this survey.**
+   microVMs are now bot-bottle's default (Firecracker on KVM Linux, Apple
+   Container on macOS); Docker is the legacy fallback. The libkrun / Apple
+   Virtualization.framework ergonomics that microsandbox, smolmachines,
+   and matchlock demonstrated turned out to be enough to make it the
+   default rather than an opt-in.

 Not worth borrowing: the SDK-first programmatic API style of boxlite /
 microsandbox (cuts against the declarative-manifest stance), and the
@@ -230,3 +469,176 @@ hosted-SaaS dashboard model of tilde.run (cuts against the
 - The `superradcompany/microsandbox` URL in the original prompt
  redirects to `microsandbox/microsandbox`; the surveyed project is the
  same.
+- CubeSandbox performance/scale numbers (<60ms cold start, <5MB/instance,
+  2,000+ sandboxes per 96-vCPU host) are the project's own launch claims,
+  not independently verified here.
+
+## Addendum 2026-07-18 — CubeSandbox and the positioning read
+
+CubeSandbox (Tencent Cloud, Apache 2.0, ~10.4k stars, HN launch
+[#47863430](https://news.ycombinator.com/item?id=47863430)) is the first
+project in this survey to combine, in one open-source stack, everything
+bot-bottle treated as its differentiator:
+
+- **Egress custody (connection level)** — default-deny domain allowlist
+  (L7 domain/SNI filtering), instant block on unauthorized egress,
+  per-sandbox traffic tokens, full audit logs of destinations (eBPF
+  virtual switch, "CubeVS"). This matches bot-bottle's egress scanner at
+  the *connection level*, productized — see the one thing it does **not**
+  match, below.
+- **Credential custody** — a vault where keys "never enter the sandbox,
+  model context, or logs." This is the in-flight-injection idea from
+  matchlock, but as a first-class feature, and it's exactly the
+  cross-vendor "egress audit + custody" wedge the monetization
+  positioning treats as the one defensible moat.
+- **Isolation on par with bot-bottle's current default** — a dedicated
+  guest kernel per sandbox (RustVMM/KVM). bot-bottle now defaults to the
+  same class of boundary (Firecracker microVM / Apple Container), so this
+  is parity, not an edge; CubeSandbox's remaining edge is running that
+  per-kernel isolation multi-tenant at scale on one host.
+
+The one axis CubeSandbox does **not** cover — and where bot-bottle stays
+distinctive:
+
+- **Content DLP on *authorized* channels.** CubeSandbox's egress control
+  is connection-level: it decides *whether* a destination is allowed and
+  logs it, and its vault keeps *injected* credentials out of the sandbox
+  entirely. Neither inspects the *payload* of traffic to an allowed
+  destination. So an agent that exfiltrates over a permitted channel —
+  pasting a repo's contents, an agent-derived secret, or PHI into an
+  allowed API/domain — is not caught by CubeSandbox. bot-bottle's own
+  egress DLP scanner does scan that: response + websocket content against
+  the resolved per-flow config, with per-bottle token redaction (see
+  recent egress commits). The vault
+  approach is arguably *stronger* for the specific case of pre-known
+  injected credentials (they can't leak if they were never present), but
+  it is not a substitute for content inspection of everything else.
+
+**Long-running posture — a sharper axis than raw isolation.** E2B and
+CubeSandbox are *ephemeral-per-task* by design; a long-running agent is an
+architected pattern on top, not the default. E2B: 5-minute default
+timeout, continuous runtime tier-capped (~1h Hobby / ~24h Pro), duration
+achieved via **pause/resume** (preserves filesystem + memory + processes;
+reconnect by sandbox ID via `Sandbox.connect()`; resume resets the timeout
+to 5 min; auto-pause via `on_timeout: "pause"`). CubeSandbox mirrors this
+(E2B drop-in) with first-class auto pause/resume and hundred-ms
+checkpoint/fork — and, self-hosted, sets its own timeout policy with no
+vendor tier caps. bot-bottle inverts the model: a bottle is **persistent,
+named, and supervised by default** — long-running *is* the default, not a
+session-management loop over pause/resume. smolmachines is the other
+persistent-by-default project in this set. For anyone building agents that
+run for hours/days, this posture difference matters more than the
+isolation primitive.
+
+**DX — the "run Claude yolo-style" bar.** The reason `claude
+--dangerously-skip-permissions` is so widely used is DX: it's one command
+and the agent just goes. The bottle thesis is to make a *sandboxed* run
+that easy — `start <agent>` builds the image on first run and drops you
+into an interactive Claude session that already has
+`--dangerously-skip-permissions` on by default
+(`contrib/claude/agent_provider.py`), with the sandbox as the guardrail
+instead of per-action prompts. On this axis the field splits cleanly:
+- **Wrappers around the agent** (as-easy-as-native): bot-bottle and
+  **agent-safehouse** (`safehouse claude --dangerously-skip-permissions`).
+  These *are* the run-Claude experience. agent-safehouse is the real DX
+  peer — but it's macOS-only Seatbelt, single-run, and doesn't address
+  network egress; bot-bottle adds VM-grade isolation, egress DLP, and
+  persistent/parallel bottles across macOS + Linux.
+- **Libraries / services** (you build the run yourself): boxlite,
+  microsandbox, CubeSandbox, E2B. These hand you an SDK or a cluster and
+  expect you to wire the agent in — powerful for platform builders,
+  heavyweight for "just run Claude on my laptop." microsandbox's MCP/Skills
+  angle is *sandbox-as-a-tool the agent calls*, which is the inverse of
+  wrapping the agent.
+- **In between:** litterbox (wizard + build, Linux only), smolmachines
+  (SSH into a named machine), matchlock (run a command in a VM).
+
+So DX is a genuine bot-bottle differentiator, and the only project that
+matches it (agent-safehouse) does so with materially weaker isolation and
+no egress story. "As easy as native yolo, but actually sandboxed" is a
+defensible one-liner.
+
+Why it still doesn't collide head-on:
+
+1. **Shape.** CubeSandbox is a *multi-tenant service for platform
+   builders* (drop-in E2B replacement, SDK-driven, 2,000 sandboxes on a
+   box). bot-bottle is a *single-operator, declarative-manifest tool for
+   the infrastructure I run*. Different buyer, different ergonomics — no
+   JSON manifest, no bottle/agent split, no "one command on my laptop."
+2. **Backend, not competitor.** Like boxlite/microsandbox, CubeSandbox is
+   something bot-bottle could sit *on top of* — a `"runtime": "microvm"`
+   or `"runtime": "cubesandbox"` backend under the manifest layer — while
+   keeping the manifest, the bottle/agent split, and the local,
+   single-operator default.
+
+Why it matters anyway:
+
+- The "nobody else bundles connection-level egress allowlist + audit +
+  in-flight credential custody" line is **no longer true for the
+  primitive** — a well-funded, 10k-star open-source project now ships it.
+  But **content DLP on authorized channels is still not matched** (see
+  above), and neither is the *layer above* the primitive (declarative
+  manifest, cross-vendor orchestration, operator UX, the
+  phone-control/dashboard north star). Those two — outbound-payload DLP
+  and the orchestration layer — are where the defensible ground now sits;
+  the connection-level allowlist + vault mechanism, on its own, is no
+  longer differentiating. Revisit the monetization open/paid line with
+  that in mind.
+- Worth a closer look at **how** CubeSandbox does credential injection
+  and per-sandbox egress tokens (eBPF virtual switch vs. bot-bottle's
+  mitmproxy egress proxy) before the next iteration of bot-bottle's
+  in-flight-secret feature — see borrowable idea #2 above.
+
+## Addendum 2026-07-18 (second pass) — agent-tailored policy landscape
+
+The second-pass question was: how novel is bot-bottle's per-agent,
+role-tailored sandbox relative to the expanded field?
+
+**The short answer:** on the isolation + network + role-tailoring
+combination, bot-bottle remains the only tool in this set. On
+role-tailored *policy at the tool-call level*, Microsoft AGT and OAP are
+the most complete answers, but they don't provide isolation; they
+complement rather than substitute.
+
+**The competitive picture by axis:**
+
+- *Agent-tailored egress (declarative, per-role)* — bot-bottle and
+  tilde.run. Cleanroom is per-repo, not per-role. Everyone else is
+  per-session or not addressed.
+- *Agent-tailored tool-call policy (declarative, per-agent identity)* —
+  Microsoft AGT (YAML policy + DID identity + trust score), OAP
+  (declarative policy rules + cryptographic audit). Neither provides
+  network/filesystem isolation.
+- *Composable policy (role overlays)* — bot-bottle (`extends:`). No
+  other tool surveyed supports composable role-policy inheritance.
+- *Isolation + DX (one-command safe yolo)* — bot-bottle and Docker sbx.
+  Docker sbx is proprietary, preset-based, and cloud-agent-specific;
+  it's the first DX-class competitor at microVM isolation strength.
+
+**What the HN "coarse-grained" complaint maps to:** The complaint is
+that a VM isolates the filesystem but doesn't know if the agent
+*should* be sending an email. bot-bottle's bottle/agent split is a
+structural answer to this: the bottle manifest declares exactly what
+the role can reach, and the sandbox enforces it at the network layer.
+Microsoft AGT is the most complete answer at the semantic/tool-call
+layer. The gap both leave open is *intent classification* — knowing
+whether a permitted action is consistent with the agent's actual task.
+See `hn-agent-safety-discourse-july-2026.md` for the blast-radius
+analysis.
+
+**Borrowable from new tools:**
+
+- **Microsoft AGT's trust-score decay** — privilege that reflects
+  observed behaviour rather than static provisioning. Applied to
+  bot-bottle: a bottle that has triggered DLP alerts or supervise holds
+  could auto-downgrade its network preset, or flag the session for
+  closer review. Fits the existing supervise-server architecture.
+- **Docker sbx's live network TUI** — real-time per-session view of
+  allowed and blocked outbound connections with point-and-click
+  allow/block. `cli.py supervise` is the right surface; adding a
+  live-connections panel would directly address the "I can't see what
+  the agent is doing" gap without any backend changes.
+- **OAP's cryptographic audit chain** — Ed25519-signed, hash-chained
+  audit records. Currently bot-bottle logs egress decisions but doesn't
+  chain them. A tamper-evident audit record per session would be useful
+  for the compliance use case the CubeSandbox positioning targets.
@@ -0,0 +1,345 @@
+# HN discourse on agent sandbox safety — June/July 2026
+
+A survey of community opinion and notable security disclosures on Hacker
+News and adjacent sources over June–July 2026. The question: what does
+the current discourse say about whether sandboxes are sufficient for
+agentic AI safety, and where does bot-bottle land against the issues
+being raised?
+
+Research conducted 2026-07-18.
+
+## Summary
+
+The past month marks a turning point in community opinion. Earlier in
+2026, the debate was mostly "which sandbox tool is best?" By June–July,
+a cascade of critical CVEs and novel attack classes has shifted the
+framing to "sandboxes are not enough — what else do you need?" The
+attacks that drove this shift are structurally distinct: most route
+through legitimate, trusted channels (Sentry issues, MCP descriptions,
+README files) rather than exploiting the isolation boundary directly.
+
+bot-bottle's architecture holds up well against the direct-escape class
+(Firecracker/Apple Container default backends, credentials never in the
+agent's env, harness entirely on the host). The remaining gap is prompt
+injection — attacker-controlled data interpreted as model instructions.
+Egress controls and prompt injection defenses are orthogonal: egress
+limits what the agent can *send out*; injection is about what it is
+*told to do*. The two don't substitute for each other. Inside a tightly-
+egressed sandbox a successful injection can't exfiltrate to unknown
+hosts, but it can still corrupt the work product, push malicious commits
+past a secret scanner, or use allowlisted channels for exfiltration.
+Those residual risks are addressed below.
+
+## The sandboxing boom sets the stage
+
+The preceding months generated a wave of sandbox tooling. A March 28
+Ask HN thread
+([#47444917](https://news.ycombinator.com/item?id=47444917)) catalogued
+the explosion: E2B, AIO Sandbox, AgentSphere, Yolobox, Exe.dev,
+AgentFence, DenoSandbox, Capsule (WASM), ERA, Vibekit, Daytona, Modal,
+Nono, and more — all launched within roughly 12 months. A parallel March
+9 thread ([#47185250](https://news.ycombinator.com/item?id=47185250))
+surveyed what developers were actually deploying: "containers or YOLO"
+dominated. The honest community mood was that most teams hadn't solved
+this and were shipping anyway.
+
+## The June–July attack cascade
+
+Six attack patterns broke in quick succession. Together they form the
+argument that the community's framing was wrong: the threat model for
+agents isn't just "code that escapes its container" — it's also prompt
+injection, where attacker-controlled data is interpreted as model
+instructions regardless of whether any isolation boundary was crossed.
+Sections 2–4 below are all the same attack class; the "trusted channel"
+label describes the delivery vector, not a different threat.
+
+### 1. Sandbox escape CVEs (DuneSlide, CVE-2026-39861)
+
+Cato AI Labs disclosed **DuneSlide** (CVE-2026-50548/50549, CVSS 9.8),
+a pair of flaws in Cursor 2.x. CVE-2026-50548 abuses the sandbox's
+`working_directory` parameter to point writes at system files; CVE-26-50549
+exploits a symlink-resolution fallback that fails open. Both start with
+a prompt injection and end in sandbox escape — and Cato's framing was
+blunt: "each CVE defeats a different guardrail; the problem is
+structural, not a string of one-offs."
+
+Claude Code's own sandbox had a similar escape this year:
+**CVE-2026-39861** (symlink flaw). The CurXecute/MCPoison/CVE-2026-26268
+chain from Cursor added a poisoned Slack message, a swap-after-approval
+MCP config, and a Git hook as three more entry points in the same
+attack class.
+
+All patched, but the pattern holds: any application-level sandbox that
+takes attacker-influenced values as path parameters is reachable from a
+prompt injection.
+
+### 2. Prompt injection via MCP data (Agentjacking)
+
+Tenet's "Agentjacking" technique planted a fake bug report in Sentry's
+MCP output. When an agent queries Sentry to fix open issues, the
+malicious event is rendered as structured content visually
+indistinguishable from a real Sentry event, and the agent executes the
+embedded instructions with the developer's full privileges. Hit rate
+across Claude Code and Cursor: **85%**. The route is entirely through a
+legitimately-authorized MCP channel — no isolation boundary is crossed;
+the injection arrives inbound through a channel the sandbox explicitly
+trusts.
+
+The Cloud Security Alliance's summary: treat observability, bug-report,
+and integration data as **untrusted agent input**, not neutral
+development metadata.
+
+### 3. README-embedded prompt injection
+
+A July disclosure showed malicious instructions hidden in `README.md`
+— a file that receives no trust prompt and requires no elevated access.
+When asked point-blank whether the repo held hidden instructions, both
+Claude Sonnet 4.6 and GPT-5.5 said no. A payload written for Sonnet
+4.6 transferred unchanged to Sonnet 5, Opus 4.8, and GPT-5.5. The
+attack surface is every repo an agent is asked to work in.
+
+### 4. Prompt injection via MCP tool descriptions
+
+Microsoft research (June 30) showed that attacker-controlled MCP tool
+description fields can silently redirect agent behavior. The injection
+is embedded in metadata the model reads during tool selection — before
+any sandbox enforcement or egress check runs, and entirely on the
+inbound path that egress controls cannot touch.
+
+### 5. MCP STDIO command injection (10 CVEs)
+
+OX Security disclosed a systemic command injection class in Anthropic's
+MCP protocol, covering 10 CVEs across multiple coding agents. The
+Windsurf case (CVE-2026-30615): processing attacker-controlled HTML
+causes the agent to auto-register a malicious MCP STDIO server and
+execute arbitrary commands with no further user interaction.
+
+### 6. LiteLLM gateway compromise (CVE-2026-40217, CVE-2026-42271)
+
+CVE-2026-40217 exposes LiteLLM's guardrail sandbox via `exec()` with no
+source filtering. CVE-2026-42271 (exploited in the wild, added to CISA's
+KEV catalog) lets callers spawn subprocesses through MCP preview
+endpoints. The threat extends to any agent routed through a compromised
+LiteLLM proxy: the proxy can swap model responses for forged tool calls
+in transit, giving the attacker a reverse shell from the developer's
+machine.
+
+## HN community opinion clusters
+
+**"Move enforcement to the kernel, not the app"** — the Nono Show HN
+([#46849615](https://news.ycombinator.com/item?id=46849615)) and a
+kernel-sandbox thread
+([#47066574](https://news.ycombinator.com/item?id=47066574)) both argued
+that application-layer sandboxes are inherently bypassable by the code
+they're sandboxing. The academic framing, from *Red-Teaming the Agentic
+Red-Team* ([arXiv 2606.24496](https://arxiv.org/pdf/2606.24496)):
+"enforcement should occur at the OS level via the kernel refusing system
+calls that violate policy at runtime — not pre-execution argument
+validation in tool calls."
+
+**"The harness belongs outside the sandbox"** — a May thread
+([#47990675](https://news.ycombinator.com/item?id=47990675)) converged
+on clean architectural separation: harness in one VM, tool execution in
+another. Top comment: "having the harness in one VM, and tool use applied
+to user data in another, is about as safe as you can be at present."
+Several replies described a hypervisor-like policy layer — sitting outside
+both VMs — as the right long-term model.
+
+**"Sandboxes are too coarse-grained"** — a Feb thread
+([#47006445](https://news.ycombinator.com/item?id=47006445)) argued
+that VMs don't answer the real question: knowing whether an agent
+*should* be sending an email or making a transaction. "Everything's just
+in the same big box." This framing picked up traction through June–July
+as the trusted-channel attacks dominated.
+
+**"MCP's trust model is the real problem"** — the month's recurring
+theme. MCP by design gives agents access to authorized external services.
+Once a trusted channel delivers a malicious payload, filesystem sandboxing
+is irrelevant. The community call: treat all MCP tool metadata and return
+values as untrusted input subject to policy validation before ingestion,
+and disable automatic MCP server loading from untrusted repositories.
+
+## How bot-bottle addresses these issues
+
+### What it covers well
+
+**Direct sandbox escape (CVEs, container breakout)**
+
+bot-bottle's default backends are Firecracker microVM (KVM Linux) and
+Apple Container (macOS). Both run the agent in a separate VM with a
+dedicated kernel — the container-escape CVE class (Dirty Pipe, runc
+escapes, DuneSlide's path-parameter abuse) requires escaping a real
+hypervisor boundary, not just a namespace. On the legacy Docker backend,
+gVisor auto-detection provides a userspace syscall barrier for hosts where
+neither KVM nor Apple Container is available.
+
+The bot-bottle process itself runs entirely on the host, outside the VM.
+This is the "harness outside the sandbox" architecture the HN thread
+converged on as best practice. The bottle manifest, egress rules, and
+secrets never enter the agent VM.
+
+**Credential theft on sandbox escape**
+
+Even on a successful VM/container escape, the agent has nothing useful
+to steal. Credentials are injected in-flight by the gateway proxy
+(`auth.scheme` / `auth.token_ref` in the egress route config) — `printenv`
+inside the agent shows proxy URLs only. The git-gate similarly holds the
+upstream SSH credential on the host; the agent pushes through a
+gitleaks-scanned daemon that forwards clean refs upstream. An escaped
+agent gets the host filesystem, not the keys.
+
+**Orphaned-agent credential risk**
+
+bot-bottle is explicitly ephemeral: when the agent exits, `cli.py` tears
+down every gateway and both networks — nothing persists between runs. The
+agent never holds credentials, so there is nothing to orphan.
+
+**MCP config redirection / STDIO auto-registration**
+
+The trust boundary at `$HOME` means bottles live only under
+`~/.bot-bottle/bottles/` — a cloned repo cannot add egress routes or
+redirect env vars to attacker hosts (the design rationale is in
+`docs/prds/0011-per-file-md-manifest.md`). Auto-registering a malicious
+MCP STDIO server from within the agent is still sandboxed by the VM, and
+any outbound calls from that server must pass the egress allowlist and
+outbound DLP scanner.
+
+**Per-agent role tailoring (the "coarse-grained sandbox" complaint)**
+
+The Feb 2026 HN thread that argued "sandboxes are too coarse-grained"
+was pointing at a real gap: a VM isolates the filesystem but doesn't
+know whether an agent *should* be sending email or calling an external
+API. bot-bottle's bottle/agent split is a structural answer at the
+network layer — the bottle manifest declares exactly what each role can
+reach (which hosts, which paths, which HTTP methods), and the egress
+scanner enforces it. A `gitea-dev` bottle that only lists
+`gitea.dideric.is` and `api.anthropic.com` structurally cannot send
+email or reach AWS, not because the model was told not to, but because
+those routes don't exist.
+
+The `extends:` composition model means provider-level policy (the Claude
+auth route) lives in one base bottle and role-specific overlays are
+stacked on top — no duplication, and changing the base propagates to all
+derived roles.
+
+Competitive position on this axis (from `agent-sandbox-landscape.md`):
+
+| Tool | Agent-tailored policy |
+|---|---|
+| **bot-bottle** | Yes — declarative per-role manifest; `extends:` composition; egress + credentials scoped to role |
+| **tilde.run** | Yes — per-agent DSL RBAC (allow/deny/approve per action/repo/agent), but hosted SaaS |
+| **Microsoft AGT** | Yes — YAML policy + per-agent DID + trust score, but tool-call level only (no network isolation) |
+| **OAP** | Yes — declarative pre-action policy + cryptographic audit, but no isolation |
+| **Cleanroom** | Partial — per-repo `cleanroom.yaml`, not per-role |
+| **Docker sbx** | No — network presets only |
+| **Anthropic srt** | No — programmatic per-invocation |
+| **matchlock / smolmachines / microsandbox** | No |
+| **agent-safehouse** | Partial — per-agent Seatbelt profiles; no egress |
+
+Two takeaways: bot-bottle and tilde.run are the only isolation tools
+with declarative role-tailored policy; Microsoft AGT and OAP are the
+closest competitors on role-tailoring but operate at the tool-call layer
+without network/filesystem isolation — complementary, not substitutes.
+
+**Outbound exfiltration (any injection class)**
+
+Whatever triggers the agent — README injection, Agentjacking, MCP
+description poisoning — the final step in most attacks is exfiltration.
+bot-bottle's egress allowlist is default-deny with a per-bottle host
+allowlist; unknown hosts get a hard 403. Outbound DLP scanning
+(`outbound_detectors: [token_patterns, known_secrets]`) catches tokens
+and secrets in outbound bodies; the `supervise` policy (default for
+manifest routes) holds the request for operator approval rather than
+silently blocking it. Together these limit what a successful injection
+can *do* even if it succeeds at the model layer.
+
+**LiteLLM / compromised-proxy attacks**
+
+bot-bottle does not use LiteLLM. The model API route (e.g.
+`api.anthropic.com`) is an auto-injected provider route on the egress
+allowlist; the agent dials the gateway, not the model API directly.
+A compromised third-party proxy is not in the architecture.
+
+### Where it is weaker
+
+**Prompt injection**
+
+Egress controls and prompt injection defenses are orthogonal. Egress
+limits what the agent can *send out* (outbound leg); prompt injection
+is about what attacker-controlled data *tells the agent to do* (inbound
+leg). The two don't substitute for each other and must be treated
+separately.
+
+The inbound DLP scanner (`inbound_detectors: [naive_injection_detection]`)
+is the only runtime defense against injection arriving through allowlisted
+channels — Sentry MCP responses, MCP tool descriptions, README content.
+It is explicitly pattern-matching and will not catch a sufficiently
+crafted payload. There is no semantic / intent-level gate between what
+the model decides and what the agent executes.
+
+**Blast radius within the permitted scope**
+
+Inside a tightly-egressed sandbox a successful injection can't
+exfiltrate to unknown hosts, but it still has real options:
+
+- *Work product corruption.* The agent can modify, delete, or backdoor
+  files in the working directory. This is within its permitted scope;
+  egress controls have nothing to say about it.
+
+- *Malicious commits past the git-gate.* The git-gate scans outbound
+  refs for secrets (gitleaks), not for semantic code intent. A prompt-
+  injected agent can commit subtly malicious code — logic bombs,
+  backdoored auth paths, code that exfiltrates data through the
+  application's own HTTP clients at runtime — that looks clean to a
+  secret scanner.
+
+- *Exfiltration through allowlisted channels.* If an attacker knows or
+  can predict what hosts are in the egress allowlist, those channels are
+  available for exfiltration. A GitHub remote being allowlisted means
+  "push to an attacker-controlled fork" is viable. A logging endpoint
+  being allowlisted means structured data can leave through it. The
+  outbound DLP scanner catches credential tokens and known secrets but
+  not arbitrary business data.
+
+- *Dependency installation within the sandbox.* An agent that runs
+  `npm install` or `pip install` on attacker-specified packages executes
+  code inside the sandbox with the same capabilities the agent has:
+  filesystem access, tool calls, calls to allowlisted hosts. Supply chain
+  injection via package names is in the same injection family, triggered
+  by the same prompt-injection path.
+
+### What would close the remaining gaps
+
+The blast-radius risks above point at two distinct mitigations that
+don't yet exist in bot-bottle:
+
+- *Outbound intent classification.* The egress addon today scans
+  outbound request content for token patterns. What it lacks is
+  awareness of context — it can't distinguish "agent is pushing a
+  legitimate commit" from "agent was injected and is pushing a backdoor."
+  The `supervise` policy is already the right shape for human-in-the-loop
+  review on sensitive outbound actions; extending it with context from
+  the agent's recent tool calls (what files were touched, what was the
+  triggering task) would narrow the gap.
+
+- *Semantic code review on git push.* gitleaks is the wrong tool for
+  catching injected logic. A review step on outbound commits — even a
+  simple diff summary surfaced in `cli.py supervise` before the push is
+  forwarded — would close the malicious-commit path without requiring
+  the agent to be fully trusted.
+
+## Sources
+
+- [Ask HN: The new wave of AI agent sandboxes? (Mar 2026)](https://news.ycombinator.com/item?id=47444917)
+- [OK, let's survey how everybody is sandboxing AI coding agents (Mar 2026)](https://news.ycombinator.com/item?id=47185250)
+- [The agent harness belongs outside the sandbox (May 2026)](https://news.ycombinator.com/item?id=47990675)
+- [Show HN: Nono – Kernel-enforced sandboxing for AI agents (Feb 2026)](https://news.ycombinator.com/item?id=46849615)
+- [Kernel-enforced sandbox for AI agents, MCP and LLM workloads (Feb 2026)](https://news.ycombinator.com/item?id=47066574)
+- [Sandboxes will be left in 2026 (Feb 2026)](https://news.ycombinator.com/item?id=47006445)
+- [Critical Cursor Flaws / DuneSlide – The Hacker News](https://thehackernews.com/2026/07/critical-cursor-flaws-could-let-prompt.html)
+- [Agentjacking Attack – The Hacker News](https://thehackernews.com/2026/06/agentjacking-attack-tricks-ai-coding.html)
+- [Friendly Fire: AI Agents Built to Catch Malicious Code – The Hacker News](https://thehackernews.com/2026/07/friendly-fire-ai-agents-built-to-catch.html)
+- [Microsoft Warns Poisoned MCP Tool Descriptions – The Hacker News](https://thehackernews.com/2026/06/microsoft-warns-poisoned-mcp-tool.html)
+- [MCP STDIO Command Injection Advisory – OX Security](https://www.ox.security/blog/mcp-supply-chain-advisory-rce-vulnerabilities-across-the-ai-ecosystem/)
+- [LiteLLM Vulnerability Chain – The Hacker News](https://thehackernews.com/2026/06/litellm-vulnerability-chain-lets-low.html)
+- [Red-Teaming the Agentic Red-Team (arXiv 2606.24496)](https://arxiv.org/pdf/2606.24496)
@@ -0,0 +1,204 @@
+# Scanning for malicious commits at the git-gate — and whether the semantic layer is a paid feature
+
+A sandboxed agent's most durable way out isn't live exfiltration — it's the
+**artifact it pushes**. Code committed through the git-gate leaves the
+sandbox and runs *later*, in CI or production, with none of the bottle's
+isolation or egress control. gitleaks covers *secrets* on that channel
+(see [`git-gate` pre-receive](../../bot_bottle/git_gate_render.py)); this
+note asks the harder question — can we scan for *malicious code* in
+commits — and the product question the answer raises: is the semantic
+(LLM) layer a decent paid feature on "git egress," alongside a paid
+human-review console for the supervise flow?
+
+## Summary
+
+- **No scanner reliably detects malicious code.** It's undecidable in
+  general and adversarial in practice — a capable agent hides a backdoor
+  from any pattern scanner (and from human reviewers). So the frame is not
+  "detect malice"; it's **raise the cost, cover the common/obvious cases,
+  and put a human on the high-leverage ones.**
+- **Layered, ranked by ROI:** (1) supply-chain / malicious-dependency
+  scanning (Socket, OSV-Scanner, GuardDog) — highest ROI, best git fit;
+  (2) fast heuristic / obfuscation / dangerous-sink scanning
+  (Semgrep-on-diff) — gitleaks-shaped; (3) **risk-based human gating** via
+  the existing supervise plane on high-risk file classes; (4) **LLM
+  semantic diff-review** as a best-effort backstop for novel backdoors.
+- **Architecture:** the git-gate's `pre-receive` is *synchronous* (it
+  blocks the push), so run only fast scanners inline and push heavy
+  analysis (CodeQL, full LLM review) to an **async post-push CI lane** that
+  can't hold the developer hostage.
+- **Monetization verdict: yes — but the paid unit is the *governed
+  git-egress review bundle*, not the raw scanner.** The pre-receive
+  mechanics and the fast OSS scanners stay free (open-core social
+  contract, same as gitleaks). The sell is the control-plane workflow
+  around them: **managed semantic review + a web-console human-review flow
+  + RBAC + audit retention + cross-run policy.** A bare per-push scan is
+  borderline "single-run = free" by our own heuristic, and its detection
+  accuracy is not something to sell on. Sell the *workflow and the
+  governance*, not the detector.
+
+## The threat: temporal escape
+
+This is the one containment fundamentally can't close. bot-bottle's VM
+isolation + egress DLP shrink *live* exfiltration, but the git push
+channel launders a payload past all of it: the agent commits code that
+looks benign at review time and does its work later, outside the
+perimeter — the "blind-XSS"-style temporal escape that both the "3 reasons
+sandboxing won't secure your AI agent" talk and Embroidery's "In sandboxes
+we (shouldn't) trust" call the sharpest gap. gitleaks gates *secrets* on
+this channel; malicious *code* is the uncovered surface, and it's the
+behavioral half of the isolation-vs-behavioral split noted in
+[`agent-sandbox-landscape.md`](agent-sandbox-landscape.md).
+
+## Why it's fundamentally hard
+
+Distinguishing malicious from legitimate code is undecidable in general
+and adversarial in the specific. The underhanded-code contests show humans
+hide backdoors from *human reviewers*; a scanner reduces to regex/dataflow
+heuristics a motivated agent writes around. So "catch malicious commits"
+is the wrong success metric. The right ones: *how much did we raise the
+cost*, *did we cover the common and the obvious*, and *did a human see the
+dangerous changes before they left*.
+
+## Landscape of git-pluggable approaches (ranked by ROI)
+
+1. **Supply-chain / malicious-dependency scanning — highest ROI.** The
+   most likely agent-introduced threat is a malicious or typosquatted
+   *dependency*, not a hand-written backdoor — and it's far more
+   detectable. **Socket** (behavioral analysis of packages: install
+   scripts, obfuscation, unexpected network/fs access, typosquats) is the
+   closest thing to malicious-intent detection that actually works;
+   **OSV-Scanner** (known-bad DB, fast) and **GuardDog** (PyPI/npm
+   heuristics) complement it. Trigger only when a commit changes a
+   lockfile/manifest → block or escalate.
+2. **Fast heuristic / obfuscation / dangerous-sink scanning.** **Semgrep**
+   with a curated ruleset, scanning the *diff* (fast enough for
+   pre-receive). Catches obfuscation (`eval(atob(...))`, base64/hex blobs,
+   minified source), exfil primitives (`curl | sh`, reverse shells,
+   DNS-exfil), and dangerous sinks (`shell=True`, `pickle.loads`, unsafe
+   `yaml.load`, `child_process.exec`). Tune noisy rules to *escalate*, not
+   block.
+3. **Risk-based human gating — the most robust control, already
+   half-built.** The git-gate already escalates `# gitleaks:allow`
+   findings to a supervisor proposal and blocks the push pending approval
+   (`supervise_gitleaks_allow`, [`git_gate_render.py`](../../bot_bottle/git_gate_render.py)).
+   Extend the same flow to **high-risk file classes**: any commit touching
+   CI/build/deploy scripts, auth/crypto code, egress config, or
+   adding/changing dependencies → route to `./cli.py supervise`. This is
+   attribution/policy, not detection, and it's the strongest thing here —
+   a human on exactly the temporal-escape surfaces.
+4. **LLM semantic diff-review — the behavioral backstop.** The only
+   approach with a shot at a novel, benign-looking backdoor: a model
+   reviews the diff for a backdoor / exfiltration / obfuscated payload /
+   dangerous behavior. This is the behavioral-detection thesis applied to
+   the *artifact* (the diff) rather than the agent's reasoning. Real
+   caveats: false positives and negatives, latency/cost, it can be
+   prompt-injected by hostile content *in the diff itself*, and it invites
+   over-trust. Useful, never a guarantee.
+
+**Not for this job:** CodeQL, Trivy, Grype, Bandit. They find *known
+vulns and insecure patterns* (bugs), not deliberate backdoors, and the
+powerful ones (CodeQL taint) need a build + database — too heavy for a
+synchronous gate. They belong in the async CI lane if at all.
+
+## Fit into bot-bottle's git-gate
+
+The `pre-receive` hook today is: gitleaks-scan each ref → escalate
+`# gitleaks:allow` findings to supervise → forward to upstream
+([`git_gate_render.py`](../../bot_bottle/git_gate_render.py)). The
+additions slot in cleanly:
+
+- **Inline (fast), before forward:** a dep-scan phase (on manifest/lockfile
+  change) and a Semgrep-diff phase. Findings block or open a supervise
+  proposal, same shape as gitleaks.
+- **New supervise tool types** alongside the existing
+  `egress-block/allow`, `gitleaks-allow`, `egress-token-allow`
+  ([`supervise_types.py`](../../bot_bottle/supervise_types.py)) — e.g. a
+  `commit-review` proposal for risky-file-class gating and for semantic
+  review. The supervise plane is already the right abstraction; this is
+  another *producer* feeding it, and [`supervise_server.py`](../../bot_bottle/supervise_server.py)
+  (JSON-RPC) is already the console backend.
+- **Async lane (heavy):** full LLM review + any CodeQL run out of band
+  after the push, feeding the same review/audit surface, so the
+  synchronous gate stays fast.
+
+## The product question: paid feature on git egress?
+
+Restating the open-core line bot-bottle runs on: *give away the
+sandbox/runtime, charge for the control plane; single-run/single-node =
+free, cross-run aggregation + central enforcement + identity/fleet = paid;
+the moat is uniform egress audit + secret custody + policy across
+untrusted agents.*
+
+Against that line, the split is clean:
+
+**Free (OSS runtime — the trust funnel):**
+- the `pre-receive` gate mechanics and gitleaks;
+- wiring the OSS scanners (Socket CLI / OSV-Scanner / Semgrep);
+- the CLI supervise flow.
+Keeping the raw scanners free is the same social contract as gitleaks and
+preserves the bottom-up distribution funnel.
+
+**Paid (the governed git-egress bundle — the control plane):**
+- **Managed semantic diff-review** — hosted inference + a curated,
+  maintained malicious-pattern/policy set. This is *capability* (metered),
+  not *insurance* — the thing individuals actually pay for. Position it as
+  **governed code-egress review**, not "we resell inference" (the
+  monetization notes explicitly warn against reselling compute).
+- **The web-console supervise/review flow — the strongest anchor.** Turn
+  the CLI `./cli.py supervise` approval into a real review surface:
+  rendered diff + finding context, approve/reject, **who-approved audit
+  trail, RBAC on approvers, mobile/phone-control** (ties to the
+  dashboard/vault north star). This is "central enforcement +
+  identity/fleet = paid" almost verbatim — and it generalizes across
+  *every* supervise proposal (egress block/allow, gitleaks-allow,
+  commit-review), so it's worth building for the whole plane, with the
+  semantic check as one producer.
+- **Cross-run governance:** fleet-wide policy for what escalates,
+  review-decision history/search/export, and drift alerts.
+
+**Why it fits the moat rather than bolting on:** a git push *is* an egress
+channel. A semantic review + human approval + audit on it extends the
+uniform "egress audit + custody + policy across untrusted agents" wedge to
+**code artifacts** — the same product, applied to the one channel gitleaks
+only half-covers. That's on-moat, not a detour.
+
+**The honest nuance (don't oversell):** a bare per-push LLM scan is
+arguably *free* by the single-run heuristic, and its detection accuracy is
+not defensible to charge for. The paid value is the **governance around
+it** — the console, RBAC, audit retention, cross-run policy — plus the
+managed capability. Sell the *review-and-approve-and-audit workflow*; let
+the detector be explicitly best-effort. And per the monetization
+guardrail, the "anti-corporate" free crowd must not veto these team
+features: the review console + RBAC + audit *are* the monetization.
+
+## Recommendation
+
+1. **Land the free layer first.** Add the dep-scan and Semgrep-diff phases
+   to `pre-receive`, and extend supervise to risky-file-class gating —
+   reuses existing machinery, immediate value, stays OSS.
+2. **Build the supervise web console** over `supervise_server`'s JSON-RPC
+   (already the Phase-1 move in the monetization path). This is the paid
+   anchor and it serves *all* proposal types, not just commit review.
+3. **Add managed semantic diff-review as a paid producer** feeding that
+   console — "governed code-egress review," metered, explicitly
+   best-effort on detection.
+4. **Don't oversell detection.** Market the workflow (review + approve +
+   audit) and the cross-run policy/RBAC, where the value is real and
+   defensible; keep the raw scanners open.
+
+## Sources / references
+
+- [`agent-sandbox-landscape.md`](agent-sandbox-landscape.md) — the
+  egress-DLP gap and isolation-vs-behavioral framing.
+- Git-gate internals: [`git_gate_render.py`](../../bot_bottle/git_gate_render.py),
+  [`supervise_types.py`](../../bot_bottle/supervise_types.py),
+  [`supervise_server.py`](../../bot_bottle/supervise_server.py).
+- External tools: Socket (socket.dev), OSV-Scanner (google/osv-scanner),
+  GuardDog (DataDog/guarddog), Semgrep (semgrep/semgrep).
+- Threat framing: "3 reasons sandboxing won't secure your AI agent"
+  (youtube TsYDazwHJ6U); Embroidery, "In sandboxes we (shouldn't) trust."
+- The authoritative monetization/positioning analysis (the open-core line,
+  the wedge, single-run-free/cross-run-paid) lives in the **separate
+  `bot-bottle-console` repo**, not this one — cited here from memory, not
+  linked.
@@ -27,7 +27,8 @@ echo "== unit ==" >&2
 "$PY" -m coverage run -m unittest discover -t . -s tests/unit

 echo "== integration (skips without Docker) ==" >&2
-"$PY" -m coverage run --append -m unittest discover -t . -s tests/integration
+BOT_BOTTLE_BACKEND=firecracker \
+    "$PY" -m coverage run --append -m unittest discover -t . -s tests/integration

 echo "== combined report ==" >&2
 "$PY" -m coverage report -m
@@ -0,0 +1,135 @@
+#!/usr/bin/env python3
+"""Enforce the repository's issue/PR metadata policy in Gitea Actions."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import urllib.error
+import urllib.request
+from pathlib import Path
+from typing import Any
+
+
+ISSUE_REFERENCE = re.compile(
+    r"(?im)\b(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?|part\s+of|"
+    r"related\s+to|refs?|references)\s+#(\d+)\b"
+)
+TRIAGE_LABEL = "Status/Needs Triage"
+
+
+def deliberate_issue_numbers(title: str, body: str) -> set[int]:
+    """Return same-repository issue numbers referenced intentionally."""
+    return {int(match) for match in ISSUE_REFERENCE.findall(f"{title}\n{body}")}
+
+
+class GiteaApi:
+    """Small API client using the Actions-provided repository token."""
+
+    def __init__(self, api_url: str, repository: str, token: str) -> None:
+        self.base = f"{api_url.rstrip('/')}/repos/{repository}"
+        self.token = token
+
+    def request(self, method: str, path: str, payload: object | None = None) -> Any:
+        data = None if payload is None else json.dumps(payload).encode()
+        request = urllib.request.Request(
+            f"{self.base}{path}",
+            data=data,
+            method=method,
+            headers={
+                "Authorization": f"token {self.token}",
+                "Content-Type": "application/json",
+            },
+        )
+        with urllib.request.urlopen(request, timeout=15) as response:
+            if response.status == 204:
+                return None
+            return json.load(response)
+
+
+def check_pull_request(event: dict[str, Any], api: GiteaApi) -> list[str]:
+    """Return policy violations for a pull_request event."""
+    pull = event["pull_request"]
+    errors: list[str] = []
+    labels = pull.get("labels") or []
+    if labels:
+        errors.append(
+            "PRs must be unlabeled; put tracker metadata on the linked issue "
+            f"(found: {', '.join(label['name'] for label in labels)})."
+        )
+
+    numbers = deliberate_issue_numbers(pull.get("title", ""), pull.get("body", ""))
+    if not numbers:
+        errors.append(
+            "PR must reference an issue with Closes/Fixes/Resolves #N, "
+            "Part of #N, Related to #N, Refs #N, or References #N."
+        )
+        return errors
+
+    real_issues = 0
+    for number in sorted(numbers):
+        try:
+            item = api.request("GET", f"/issues/{number}")
+        except urllib.error.HTTPError as error:
+            if error.code == 404:
+                errors.append(f"Referenced issue #{number} does not exist.")
+                continue
+            raise
+        if item.get("pull_request") is not None:
+            errors.append(f"#{number} is a pull request, not an issue.")
+        else:
+            real_issues += 1
+
+    if not real_issues and not errors:
+        errors.append("PR must reference at least one real issue.")
+    return errors
+
+
+def ensure_issue_label(event: dict[str, Any], api: GiteaApi) -> bool:
+    """Apply the triage label if an issue event leaves the issue unlabeled."""
+    issue = event["issue"]
+    if issue.get("pull_request") is not None or issue.get("labels"):
+        return False
+    labels = api.request("GET", "/labels?limit=100")
+    triage = next((label for label in labels if label["name"] == TRIAGE_LABEL), None)
+    if triage is None:
+        raise RuntimeError(f"repository label {TRIAGE_LABEL!r} does not exist")
+    api.request("POST", f"/issues/{issue['number']}/labels", {"labels": [triage["id"]]})
+    return True
+
+
+def _load_event(path: str) -> dict[str, Any]:
+    return json.loads(Path(path).read_text(encoding="utf-8"))
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("command", choices=("check-pr", "label-issue"))
+    parser.add_argument("--event", default=os.environ.get("GITHUB_EVENT_PATH"))
+    args = parser.parse_args()
+    if not args.event:
+        parser.error("--event or GITHUB_EVENT_PATH is required")
+
+    api = GiteaApi(
+        os.environ["GITHUB_API_URL"],
+        os.environ["GITHUB_REPOSITORY"],
+        os.environ["GITHUB_TOKEN"],
+    )
+    event = _load_event(args.event)
+    if args.command == "check-pr":
+        errors = check_pull_request(event, api)
+        if errors:
+            print("\n".join(f"::error::{error}" for error in errors))
+            return 1
+        print("PR tracker policy passed.")
+        return 0
+
+    changed = ensure_issue_label(event, api)
+    print(f"Applied {TRIAGE_LABEL}." if changed else "Issue already has a label.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
@@ -69,11 +69,12 @@ _DUMMY_HOST_KEY = (

@skip_unless_docker()
@unittest.skipIf(
-    os.environ.get("GITEA_ACTIONS") == "true",
-    "skipped under act_runner: egress_tls_init uses a host bind mount "
-    "the runner container can't see, and the network topology hides "
-    "sibling-gateway visibility — same constraint as the other "
-    "bottle-bringup integration tests",
+    os.environ.get("GITEA_ACTIONS") == "true"
+    and os.environ.get("BOT_BOTTLE_BACKEND") != "firecracker",
+    "skipped under act_runner unless BOT_BOTTLE_BACKEND=firecracker: "
+    "egress_tls_init uses a host bind mount the runner container can't "
+    "see, and the network topology hides sibling-gateway visibility — "
+    "these constraints don't apply on the self-hosted KVM runner",
 )
 class TestSandboxEscape(unittest.TestCase):
    """End-to-end attacks against a real bottle. The bottle stays
@@ -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:
@@ -296,67 +292,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"  # gitleaks:allow
-        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"  # gitleaks:allow
-        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(
@@ -95,5 +95,60 @@ class TestMainDispatch(unittest.TestCase):
            self.assertEqual(130, main(["x"]))


+class TestMigrationGate(unittest.TestCase):
+    """The dispatcher's schema-migration gate (cli/__init__.py)."""
+
+    def setUp(self) -> None:
+        # Force the "schema out of date" branch for every test here.
+        patcher = patch.object(StoreManager, "is_migrated", return_value=False)
+        patcher.start()
+        self.addCleanup(patcher.stop)
+        self.addCleanup(StoreManager.reset)
+
+    def test_store_command_blocks_when_stdin_cannot_confirm(self) -> None:
+        # Non-TTY stdin at EOF (as in CI): the [y/N] prompt reads "" and the
+        # command is refused rather than migrating silently.
+        ran: list[bool] = []
+
+        def handler(_rest: list[str]) -> int:
+            ran.append(True)
+            return 0
+
+        with patch.dict(climod.COMMANDS, {"list": handler}), \
+                patch("sys.stdin", io.StringIO("")), \
+                patch("sys.stderr", io.StringIO()):
+            self.assertEqual(1, main(["list"]))
+        self.assertEqual([], ran, "gated command must not dispatch")
+
+    def test_backend_command_skips_gate(self) -> None:
+        # `backend` provisions/probes the host and never opens the store, so
+        # it must run even on an unmigrated DB with unanswerable stdin.
+        ran: list[bool] = []
+
+        def handler(_rest: list[str]) -> int:
+            ran.append(True)
+            return 0
+
+        with patch.dict(climod.COMMANDS, {"backend": handler}), \
+                patch("sys.stdin", io.StringIO("")), \
+                patch("sys.stderr", io.StringIO()):
+            self.assertEqual(0, main(["backend", "status"]))
+        self.assertEqual([True], ran, "exempt command must dispatch")
+
+    def test_store_command_migrates_on_confirmation(self) -> None:
+        migrated: list[bool] = []
+
+        def handler(_rest: list[str]) -> int:
+            return 0
+
+        with patch.dict(climod.COMMANDS, {"list": handler}), \
+                patch.object(StoreManager, "migrate",
+                             side_effect=lambda: migrated.append(True)), \
+                patch("sys.stdin", io.StringIO("y\n")), \
+                patch("sys.stderr", io.StringIO()):
+            self.assertEqual(0, main(["list"]))
+        self.assertEqual([True], migrated, "confirmed gate must migrate")
+
+
 if __name__ == "__main__":
    unittest.main()
@@ -1,186 +0,0 @@
-"""Unit: host Claude auth extraction."""
-
-from __future__ import annotations
-
-import json
-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: object) -> str:
-    payload: dict[str, object] = {"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"  # gitleaks:allow
-        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},  # gitleaks:allow
-        })
-        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"  # gitleaks:allow
-        # 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"  # gitleaks:allow
-        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"  # gitleaks:allow
-        self._write({
-            "claudeAiOauth": {
-                "accessToken": key,
-                "refreshToken": "sk-ant-ort01-secret",  # gitleaks:allow
-                "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"  # gitleaks:allow
-        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()
@@ -168,16 +168,18 @@ class TestHookRender(unittest.TestCase):
        # Stdin is buffered to a tempfile so both phases can re-read.
        self.assertIn("refs_file=$(mktemp)", hook)

-    def test_new_ref_scan_scoped_to_incoming_commits(self):
-        # A new branch (old=all-zeros) must scan only commits new to the
-        # gate, not the full ancestry — otherwise historical findings
-        # block every new-branch push (PRD 0028 / issue #106).
+    def test_scan_scoped_to_incoming_commits(self):
+        # Every non-delete push scans only commits new to the gate, not
+        # the full ancestry and not the `$old..$new` delta — otherwise
+        # historical fixtures block new-branch pushes (PRD 0028 / #106)
+        # and a rebase/force-push onto an advanced main drags in main's
+        # history incl. the sandbox-escape fixtures (#346).
        hook = git_gate_render_hook()
        self.assertIn('log_opts="$new --not --all"', hook)
-        # The old over-broad full-ancestry range must be gone.
+        # Neither the full-ancestry range nor the ancestry-blind delta
+        # range may survive.
        self.assertNotIn('log_opts="$new"', hook)
-        # Existing-branch delta scan is unchanged.
-        self.assertIn('log_opts="$old..$new"', hook)
+        self.assertNotIn('log_opts="$old..$new"', hook)

    def test_forward_ssh_is_non_interactive_and_bounded(self):
        # No prompt (BatchMode) and a connect timeout, so an unreachable
@@ -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):
@@ -86,22 +86,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:
@@ -0,0 +1,62 @@
+import unittest
+from unittest.mock import Mock
+
+from scripts.tracker_policy import (
+    TRIAGE_LABEL,
+    check_pull_request,
+    deliberate_issue_numbers,
+    ensure_issue_label,
+)
+
+
+class TestDeliberateIssueNumbers(unittest.TestCase):
+    def test_accepts_completing_and_noncompleting_forms(self):
+        self.assertEqual(
+            deliberate_issue_numbers("Fixes #12", "Part of #14; refs #15"),
+            {12, 14, 15},
+        )
+
+    def test_does_not_treat_incidental_number_as_link(self):
+        self.assertEqual(deliberate_issue_numbers("Audit #12", "See PR #14"), set())
+
+
+class TestCheckPullRequest(unittest.TestCase):
+    def test_accepts_unlabelled_pr_linked_to_real_issue(self):
+        api = Mock()
+        api.request.return_value = {"number": 12, "pull_request": None}
+        event = {"pull_request": {"title": "Change", "body": "Part of #12", "labels": []}}
+        self.assertEqual(check_pull_request(event, api), [])
+
+    def test_rejects_labels_and_pr_reference(self):
+        api = Mock()
+        api.request.return_value = {"number": 12, "pull_request": {}}
+        event = {
+            "pull_request": {
+                "title": "Change",
+                "body": "Closes #12",
+                "labels": [{"name": "Kind/Bug"}],
+            }
+        }
+        errors = check_pull_request(event, api)
+        self.assertEqual(len(errors), 2)
+        self.assertIn("unlabeled", errors[0])
+        self.assertIn("not an issue", errors[1])
+
+
+class TestEnsureIssueLabel(unittest.TestCase):
+    def test_adds_triage_label_to_unlabelled_issue(self):
+        api = Mock()
+        api.request.side_effect = [[{"id": 55, "name": TRIAGE_LABEL}], None]
+        event = {"issue": {"number": 405, "labels": [], "pull_request": None}}
+        self.assertTrue(ensure_issue_label(event, api))
+        api.request.assert_any_call("POST", "/issues/405/labels", {"labels": [55]})
+
+    def test_leaves_labelled_issue_unchanged(self):
+        api = Mock()
+        event = {"issue": {"number": 405, "labels": [{"name": "Kind/Documentation"}]}}
+        self.assertFalse(ensure_issue_label(event, api))
+        api.request.assert_not_called()
+
+
+if __name__ == "__main__":
+    unittest.main()
Author	SHA1	Message	Date
didericis-codex	f5fec38ca8	ci: scope firecracker backend to integration coverage test / integration-firecracker (pull_request) Successful in 10s Details test / coverage (pull_request) Has started running Details test / integration-docker (pull_request) Successful in 23s Details test / unit (pull_request) Successful in 36s Details	2026-07-18 21:43:43 +00:00
didericis-claude	e33cccfdde	fix(db): close SQLite connections explicitly to suppress ResourceWarning on Python 3.13 test / integration-firecracker (pull_request) Successful in 9s Details test / integration-docker (pull_request) Successful in 9s Details test / unit (pull_request) Successful in 33s Details lint / lint (push) Successful in 46s Details test / coverage (pull_request) Has been cancelled Details `sqlite3.Connection.__exit__` only commits/rolls back a transaction — it does not close the connection. Python 3.13 (the Nix env on the KVM runner) emits `ResourceWarning: unclosed database` for every connection GC'd without an explicit close, producing noisy output in the coverage job. Add `DbStore._connection()`, a `contextmanager` that calls `self._connect()`, wraps it in the existing transaction context manager, and closes the connection in a `finally` block. Change all `with self._connect() as conn:` call sites in `db_store.py`, `audit_store.py`, `queue_store.py`, and `orchestrator/registry.py` to `with self._connection() as conn:`. `_connect()` remains as the per-subclass hook (RegistryStore overrides it to set `busy_timeout`); `_connection()` delegates to `self._connect()` so the override is respected.	2026-07-18 21:17:22 +00:00
didericis	319cac85b8	ci: drop dev-requirements pip install on the self-hosted KVM runner test / coverage (pull_request) Has started running Details test / integration-firecracker (pull_request) Successful in 12s Details test / integration-docker (pull_request) Successful in 28s Details test / unit (pull_request) Successful in 37s Details The self-hosted runner's Nix python env has no `pip` module, so `python3 -m pip install -r requirements-dev.txt` failed with "No module named pip" in both firecracker jobs. Neither job needs that install: - integration-firecracker runs the stdlib `unittest` suite (no deps); - coverage needs only `coverage`, which the runner's Nix python env already ships (7.12.0) — verified `coverage run`/`coverage json` work. pylint/pyright are lint.yml's concern, not test.yml's. The ubuntu-latest `unit` job keeps its `--break-system-packages` install unchanged. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01S1qRZTJC6qgBsUSjNrBdkX	2026-07-18 17:02:40 -04:00
didericis	774adf30b8	Merge remote-tracking branch 'origin/main' into ci-kvm-runner test / integration-docker (pull_request) Successful in 14s Details test / integration-firecracker (pull_request) Failing after 6s Details test / coverage (pull_request) Failing after 11s Details lint / lint (push) Successful in 50s Details test / unit (pull_request) Successful in 1m36s Details	2026-07-18 16:56:44 -04:00
didericis	5b359fe8d2	fix(git-gate): scan $new --not --all for every push, not $old..$new test / unit (push) Successful in 32s Details test / integration (push) Successful in 31s Details lint / lint (push) Successful in 43s Details Update Quality Badges / update-badges (push) Successful in 38s Details test / coverage (push) Successful in 40s Details The pre-receive hook scanned existing-branch updates with the delta range $old..$new. On a rebase / non-fast-forward force-push onto an advanced main, $old is no longer an ancestor of $new, so $old..$new expands to all of main's new history — including the deliberate sandbox-escape gitleaks fixtures — and the push is rejected on commits that belong to main, not the branch. Unify the range on `$new --not --all` for every non-delete push (this is the deferred open question from PRD 0028, which already applied it to new refs for #106). It scans only the commits the push introduces and is security-equivalent: the bare repo's refs come only from trusted upstream mirror-fetch and gitleaks-gated pushes, so an excluded commit is already-upstream or already-scanned. It is also more correct for non-fast-forward pushes, where $old..$new can skip commits off the direct path. Fixes #421 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01S1qRZTJC6qgBsUSjNrBdkX	2026-07-18 16:51:31 -04:00
didericis	015ff52eda	fix(cli): exempt backend command from DB migration gate test / integration (pull_request) Successful in 8s Details tracker-policy-pr / check-pr (pull_request) Successful in 9s Details test / unit (pull_request) Successful in 31s Details test / coverage (pull_request) Successful in 36s Details test / integration (push) Successful in 12s Details test / unit (push) Successful in 36s Details test / coverage (push) Successful in 39s Details Update Quality Badges / update-badges (push) Successful in 37s Details lint / lint (push) Successful in 2m38s Details `backend setup/status/teardown` manage host prerequisites only and never open the store, but the CLI dispatcher ran the schema-migration gate before every command. On a non-TTY runner the gate's `Migrate now? [y/N]` prompt reads EOF and refuses, so `backend status --backend=firecracker` exits 1 — breaking the Firecracker CI preflight on any host without a pre-migrated DB. Exempt `backend` from the gate; store-touching commands stay gated. Fixes #419 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01S1qRZTJC6qgBsUSjNrBdkX	2026-07-18 15:27:29 -04:00
didericis-claude	4302678f3e	docs(research): expand sandbox landscape with 6 new tools; add agent-tailored policy axis tracker-policy-pr / check-pr (pull_request) Failing after 6s Details Isolation tools added: Cleanroom (Buildkite), container-use (Dagger), Docker sbx, Anthropic srt. Governance/pre-action layers added as a separate section: Microsoft Agent Governance Toolkit (per-agent DID + YAML policy + trust score), Open Agent Passport (declarative policy + cryptographic audit). Comparison table: 14 → 14 columns; new Agent-tailored policy row added. Second addendum covers competitive position on role-tailoring, Docker sbx as new DX-class competitor, and borrowable ideas (trust-score decay, live network TUI, cryptographic audit chain). Discourse note: adds Per-agent role tailoring to "What it covers well" with competitive comparison table across 9 tools.	2026-07-18 19:11:14 +00:00
didericis-claude	5624025b02	ci(test): split integration into per-backend jobs test / integration-docker (pull_request) Successful in 9s Details test / unit (pull_request) Successful in 30s Details lint / lint (push) Successful in 2m24s Details tracker-policy-pr / check-pr (pull_request) Failing after 11s Details test / integration-firecracker (pull_request) Has been cancelled Details test / coverage (pull_request) Has been cancelled Details Add separate `integration-docker` and `integration-firecracker` jobs, each with an explicit BOT_BOTTLE_BACKEND env var, so the backend used is visible in CI output and skipped backends surface as a distinct job rather than silent unittest.skip lines. - integration-docker: ubuntu-latest, BOT_BOTTLE_BACKEND=docker - integration-firecracker: [self-hosted, kvm], BOT_BOTTLE_BACKEND=firecracker, same-repo PRs + push + workflow_dispatch only (untrusted fork PRs do not execute on the privileged KVM runner) - coverage: same same-repo restriction; refs #414 for the planned follow-up that moves coverage to ubuntu-latest via artifact combination Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-07-18 14:46:38 -04:00
didericis-claude	ed38c68b01	test(integration): lift GITEA_ACTIONS skip for Firecracker backend The sandbox-escape test was unconditionally skipped when GITEA_ACTIONS=true, which prevented Firecracker orchestration coverage from being measured even when BOT_BOTTLE_BACKEND=firecracker is set on the KVM runner. Narrow the skip to: GITEA_ACTIONS=true AND BOT_BOTTLE_BACKEND != firecracker. When BOT_BOTTLE_BACKEND=firecracker the test is explicitly opted in to run on the self-hosted KVM runner where the required /dev/kvm + TAP pool exist. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-07-18 14:46:38 -04:00
didericis-claude	df24e5e955	ci(coverage): address review findings from PR #349 - Finding 1: set BOT_BOTTLE_BACKEND=firecracker on the coverage step so the integration suite actually exercises the Firecracker orchestration paths rather than defaulting to Docker - Finding 2: restrict the coverage job to push+workflow_dispatch only; PR-controlled code no longer executes on the privileged KVM runner automatically — maintainers trigger workflow_dispatch for trusted PRs - Finding 3: expand path filters to include workflow files, scripts, and README so changes to CI configuration trigger the workflow itself Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-07-18 14:46:38 -04:00
didericis-claude	ea147edb6f	ci(coverage): install dev requirements on the KVM runner The self-hosted KVM runner is a persistent machine, so --break-system-packages is inappropriate. Use --user instead so coverage (and pyright/pylint for future jobs) land in ~/.local and survive between runs without touching the system Python. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-07-18 14:46:38 -04:00
didericis	2b4382bce9	ci(coverage): run the diff-coverage gate on a self-hosted KVM runner Re-land the coverage gate deferred from #343. The Firecracker VM/SSH orchestration (~230 lines) is only exercised by the integration suite, which needs /dev/kvm + the provisioned TAP/nft pool — a container runner skips it and those lines read uncovered, so the 90% diff gate can't pass on ubuntu-latest. Move the `coverage` job to a self-hosted `kvm` runner with a firecracker-readiness preflight (binary + /dev/kvm + `backend status`) so the integration test actually runs. Unit/lint stay on ubuntu-latest. README documents the runner prerequisites. Depends on a registered self-hosted runner labelled `kvm`; until one is provisioned this gate will not run. See PRD 0069 / #348. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WBMWTEtQdJ4W5UrWuLHCck	2026-07-18 14:46:38 -04:00
didericis-claude	3a6fbad057	ci: split tracker-policy into separate issue and PR workflows tracker-policy-pr / check-pr (pull_request) Successful in 4s Details Gitea Actions reports skipped jobs as a non-success status, which caused label-issue to block PRs even though its if-condition correctly excluded it. Two dedicated workflows eliminate the skipped-job problem entirely. After merge, update the branch-protection required status context from `tracker-policy / check-pr` to `tracker-policy-pr / check-pr`. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-07-18 18:37:44 +00:00
didericis-codex	a800a417d9	ci: enforce pylint score instead of warning exit bits test / integration (pull_request) Successful in 9s Details test / coverage (pull_request) Successful in 39s Details test / unit (pull_request) Successful in 1m22s Details test / integration (push) Successful in 25s Details test / unit (push) Successful in 34s Details lint / lint (push) Successful in 42s Details Update Quality Badges / update-badges (push) Successful in 39s Details test / coverage (push) Successful in 42s Details	2026-07-18 14:18:39 -04:00
didericis-codex	293218035d	ci: enforce canonical issue metadata policy	2026-07-18 14:18:39 -04:00
didericis-claude	727eafe0f9	docs(research): clarify prompt injection framing and blast-radius risks Collapse "trusted-channel data injection" into prompt injection throughout — the trusted channel is a delivery vector, not a distinct attack class. Add explicit inbound/outbound orthogonality framing. Replace the two redundant "weaker" bullets with a single prompt injection section and a new blast-radius breakdown covering work product corruption, malicious commits past gitleaks, exfiltration through allowlisted channels, and dependency-install injection.	2026-07-18 18:13:33 +00:00
didericis-claude	1ec114b6d7	docs(research): survey HN agent safety discourse June-July 2026 Covers the CVE cascade (DuneSlide, CVE-2026-39861, MCP STDIO injection), Agentjacking and README-injection attack classes, community opinion clusters, and a frank assessment of where bot-bottle covers or falls short against each issue.	2026-07-18 18:08:40 +00:00
didericis	aa44feea02	docs(research): note on malicious-commit scanning at the git-gate + paid-feature analysis Adds a research note on whether/how to scan for malicious code (not just secrets) in commits pushed through the git-gate, and whether the semantic (LLM) layer is a defensible paid feature. Verdict: no scanner reliably detects malicious code (undecidable + adversarial), so the frame is raise-cost + cover-the-obvious + human-gate the dangerous. Ranked layers: dependency/supply-chain scanning (Socket/OSV/ GuardDog) > heuristic/obfuscation (Semgrep-on-diff) > risk-based human gating via the existing supervise plane > best-effort LLM diff-review. Fast scanners inline in the synchronous pre-receive; heavy analysis async. Monetization: the paid unit is the governed git-egress review bundle (managed semantic review + web-console human-review flow + RBAC + audit + cross-run policy), not the raw scanner — which stays OSS like gitleaks. Extends the egress audit+custody wedge to code artifacts; the supervise console generalizes across all proposal types (egress, gitleaks, commit review). Sell the workflow, not the detector's accuracy. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YBCHap11yGAKuKfsehNPaD	2026-07-18 07:00:22 -04:00
didericis	f2e2572a40	docs(research): add DX axis — "run Claude yolo-style" — to the sandbox landscape Adds a "DX: run Claude yolo-style" row to the comparison table plus a note framing developer experience as a differentiator. The field splits into wrappers-around-the-agent (bot-bottle, agent-safehouse — one command, the agent just runs, `--dangerously-skip-permissions` on by default with the sandbox as the guardrail) vs libraries/services (boxlite, microsandbox, CubeSandbox, E2B — you wire the agent in via SDK/cluster). agent-safehouse is the only DX peer, but it's macOS-only Seatbelt with no egress story. "As easy as native yolo, but actually sandboxed" is the defensible line. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YBCHap11yGAKuKfsehNPaD	2026-07-18 06:41:26 -04:00
didericis	7069fa225d	docs(research): add long-running posture axis to the sandbox landscape Adds a "Long-running posture" row to the comparison table and an addendum note contrasting the two models: E2B and CubeSandbox are ephemeral-per-task (5-min default timeout, tier-capped continuous runtime, duration via pause/resume + reconnect-by-id), while bot-bottle bottles are persistent, named, and supervised by default. For agents that run for hours/days this posture difference matters more than the isolation primitive. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YBCHap11yGAKuKfsehNPaD	2026-07-18 06:28:26 -04:00
didericis	aa224c4381	docs(research): add CubeSandbox to the sandbox landscape; fix stale bot-bottle self-description Adds CubeSandbox (Tencent Cloud, Apache 2.0, RustVMM/KVM microVM) to the agent-sandbox landscape survey: per-project note, comparison-table column, and a dated addendum on what it means for positioning. CubeSandbox is the first surveyed project to bundle a connection-level egress allowlist + audit + in-flight credential custody, but it does NOT do content DLP on authorized channels — that plus the orchestration layer is where bot-bottle stays distinctive. Also corrects two stale self-descriptions the survey (2026-05-11) baked in and I'd propagated: - Default isolation is now a VM per bottle (Firecracker microVM on KVM Linux, Apple Container on macOS); Docker is only the legacy fallback, per _default_backend_name(). Was described as Docker-by-default. - Outbound DLP is bot-bottle's own mitmproxy egress scanner + gitleaks on git push, not pipelock (removed). All references updated; a note records the change. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YBCHap11yGAKuKfsehNPaD	2026-07-18 06:28:12 -04:00