chore: update quality badges

- Coverage: 84%
- Core coverage: 94%

[skip ci]

.coveragerc

@@ -1,6 +1,10 @@
 [run]
 branch = True
 source = .
+# Store paths relative to the project root so .coverage.* files produced on
+# different runners (ubuntu-latest vs self-hosted KVM) can be combined by the
+# coverage job without a [paths] remapping section.
+relative_files = True
 
 [report]
 # Coverage policy: see docs/decisions/0004-coverage-policy.md.

.gitea/workflows/test.yml

@@ -1,4 +1,5 @@
-# Run the project's test suite on every PR push and on push to main.
+# Run the project's test suite when package or runtime inputs change on a PR
+# or on push to main.
 #
 # The suite uses stdlib `unittest` discovery — no external Python
 # dependencies are required to execute it. Tests are split by directory:
@@ -9,10 +10,12 @@
 #   tests/canaries/     — upstream regression canaries; run on a separate
 #                         schedule (see canaries.yml), not here
 #
-# 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.
+# Each test job runs once under coverage and uploads a small .coverage.*
+# artifact. The `coverage` job combines them — no test reruns, no KVM
+# dependency on that job. For main-branch pushes only, the tested rootfs
+# and matching dropbear are uploaded so `publish-infra` can publish the
+# byte-identical artifact that was tested. PRs avoid the ~194 MB rootfs
+# transfer entirely.
 
 name: test
 
@@ -21,72 +24,37 @@ on:
     branches:
       - main
     paths:
-      - '**.py'
-      - '.gitea/workflows/**.yml'
-      - 'scripts/**'
-      - 'README.md'
-      # Dockerfiles and pyproject.toml are baked into the infra rootfs; a
-      # change here alters what the integration/coverage jobs build locally.
+      - 'bot_bottle/**'
+      - 'tests/**/*.py'
+      - 'cli.py'
+      - 'scripts/coverage.sh'
+      - 'scripts/critical-modules.txt'
+      - 'scripts/diff_coverage.py'
+      - 'scripts/tracker_policy.py'
+      - 'scripts/firecracker-netpool.sh'
       - 'Dockerfile*'
       - 'pyproject.toml'
+      - 'requirements-dev.txt'
+      - '.coveragerc'
+      - '.dockerignore'
   pull_request:
     paths:
-      - '**.py'
-      - '.gitea/workflows/**.yml'
-      - 'scripts/**'
-      - 'README.md'
+      - 'bot_bottle/**'
+      - 'tests/**/*.py'
+      - 'cli.py'
+      - 'scripts/coverage.sh'
+      - 'scripts/critical-modules.txt'
+      - 'scripts/diff_coverage.py'
+      - 'scripts/tracker_policy.py'
+      - 'scripts/firecracker-netpool.sh'
       - 'Dockerfile*'
       - 'pyproject.toml'
+      - 'requirements-dev.txt'
+      - '.coveragerc'
+      - '.dockerignore'
   workflow_dispatch:
 
 jobs:
-  stage-firecracker-inputs:
-    runs-on: [self-hosted, kvm]
-    # Same guard as the other KVM-runner jobs: don't spin the privileged
-    # runner for fork PRs (this only copies a non-secret static binary, but
-    # keep the posture consistent — build-infra/integration/coverage all
-    # depend on it, so gating here gates the whole Firecracker chain).
-    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: Stage the provisioned static dropbear
-        run: |
-          mkdir -p firecracker-inputs
-          cp /var/cache/bot-bottle-fc/dropbear firecracker-inputs/dropbear
-
-      - name: Upload Firecracker build inputs
-        uses: actions/upload-artifact@v3
-        with:
-          name: firecracker-inputs
-          path: firecracker-inputs/
-
-  build-infra:
-    needs: stage-firecracker-inputs
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Download Firecracker build inputs
-        uses: actions/download-artifact@v3
-        with:
-          name: firecracker-inputs
-          path: firecracker-inputs
-
-      - name: Build infra candidate from this checkout
-        env:
-          BOT_BOTTLE_FC_DROPBEAR: ${{ github.workspace }}/firecracker-inputs/dropbear
-        run: python3 -m bot_bottle.backend.firecracker.publish_infra --output infra-candidate
-
-      - name: Upload infra candidate
-        uses: actions/upload-artifact@v3
-        with:
-          name: infra-candidate
-          path: infra-candidate/
-
   unit:
     runs-on: ubuntu-latest
     steps:
@@ -101,12 +69,29 @@ jobs:
       - name: Install dev requirements
         run: python3 -m pip install --break-system-packages -r requirements-dev.txt
 
-      - name: Run unit tests
+      - name: Run unit tests with coverage
+        env:
+          COVERAGE_FILE: ${{ github.workspace }}/.coverage.unit
         run: python3 -m coverage run -m unittest discover -t . -s tests/unit -v
 
       - name: Report unit coverage
+        env:
+          COVERAGE_FILE: ${{ github.workspace }}/.coverage.unit
         run: python3 -m coverage report -m
 
+      # upload-artifact@v3's glob skips dotfiles, so a bare `.coverage.unit`
+      # silently uploads nothing ("No files were found"). Stage it under a
+      # non-dot name; the coverage job renames it back before `coverage
+      # combine`. `cp` also fails loudly if coverage never wrote the file.
+      - name: Stage unit coverage for upload
+        run: cp .coverage.unit coverage-unit.dat
+
+      - name: Upload unit coverage artifact
+        uses: actions/upload-artifact@v3
+        with:
+          name: coverage-unit
+          path: coverage-unit.dat
+
   integration-docker:
     runs-on: ubuntu-latest
     steps:
@@ -115,6 +100,9 @@ jobs:
 
       # No actions/setup-python (see the note in the `unit` job); the
       # container's system Python 3.12 runs the stdlib test suite directly.
+      - name: Install coverage
+        run: python3 -m pip install --break-system-packages coverage
+
       - name: Show environment
         run: |
           python3 --version
@@ -124,10 +112,21 @@ jobs:
             echo "docker not on PATH — integration tests will skip"
           fi
 
-      - name: Run integration tests (docker)
+      - name: Run integration tests (docker) with coverage
         env:
           BOT_BOTTLE_BACKEND: docker
-        run: python3 -m unittest discover -t . -s tests/integration -v
+          COVERAGE_FILE: ${{ github.workspace }}/.coverage.docker
+        run: python3 -m coverage run -m unittest discover -t . -s tests/integration -v
+
+      # Non-dot name so upload-artifact's dotfile-skipping glob picks it up.
+      - name: Stage docker coverage for upload
+        run: cp .coverage.docker coverage-docker.dat
+
+      - name: Upload docker coverage artifact
+        uses: actions/upload-artifact@v3
+        with:
+          name: coverage-docker
+          path: coverage-docker.dat
 
   # 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.
@@ -137,9 +136,16 @@ jobs:
   #
   # Runner prerequisites (provision once; see README "Firecracker on Linux"):
   # `firecracker` on PATH, `/dev/kvm` accessible, cached kernel +
-  # static dropbear, and the pool as a persistent systemd unit.
+  # static dropbear at /var/cache/bot-bottle-fc/dropbear, and the pool as a
+  # persistent systemd unit.
+  #
+  # The infra candidate is built here directly (no artifact download) to
+  # eliminate the ~70 s ubuntu-latest upload + ~83 s combined download that
+  # the old build-infra → integration-firecracker + coverage chain incurred.
+  # For main-branch pushes the tested rootfs and matching dropbear are
+  # uploaded so publish-infra can publish the byte-identical artifact; PRs
+  # skip those uploads entirely.
   integration-firecracker:
-    needs: build-infra
     runs-on: [self-hosted, kvm]
     if: >-
       github.event_name == 'push' ||
@@ -159,49 +165,65 @@ jobs:
           # range overlap; it prints the exact `backend setup` fix.
           python3 cli.py backend status --backend=firecracker
 
-      - name: Download the candidate built from this checkout
-        uses: actions/download-artifact@v3
-        with:
-          name: infra-candidate
-          path: infra-candidate
+      - name: Build infra candidate from this checkout
+        env:
+          BOT_BOTTLE_FC_DROPBEAR: /var/cache/bot-bottle-fc/dropbear
+        run: python3 -m bot_bottle.backend.firecracker.publish_infra --output infra-candidate --reuse-published
 
       - name: Replace the persistent infra VM with the candidate
         run: python3 -c 'from bot_bottle.backend.firecracker import infra_vm; infra_vm.stop()'
 
-      # 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)
+      # 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.
+      - name: Run integration tests (firecracker) with coverage
         env:
           BOT_BOTTLE_BACKEND: firecracker
           BOT_BOTTLE_INFRA_ARTIFACT_DIR: ${{ github.workspace }}/infra-candidate
-        run: python3 -m unittest discover -t . -s tests/integration -v
+          COVERAGE_FILE: ${{ github.workspace }}/.coverage.firecracker
+        run: python3 -m coverage run -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.
+      # Non-dot name so upload-artifact's dotfile-skipping glob picks it up.
+      - name: Stage firecracker coverage for upload
+        run: cp .coverage.firecracker coverage-firecracker.dat
+
+      - name: Upload firecracker coverage artifact
+        uses: actions/upload-artifact@v3
+        with:
+          name: coverage-firecracker
+          path: coverage-firecracker.dat
+
+      # Only upload the large rootfs artifact on main-branch pushes;
+      # PRs avoid the ~194 MB transfer. publish-infra only runs on main
+      # and downloads these to publish the byte-identical tested rootfs.
+      - name: Upload tested rootfs (main branch only)
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        uses: actions/upload-artifact@v3
+        with:
+          name: infra-candidate
+          path: infra-candidate/
+
+      - name: Upload dropbear for publish verification (main branch only)
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        uses: actions/upload-artifact@v3
+        with:
+          name: firecracker-inputs
+          path: /var/cache/bot-bottle-fc/dropbear
+
+  # Combined coverage gate: aggregates .coverage.* artifacts uploaded by each
+  # test job, then runs the diff-coverage gate (new/changed lines >= 90%).
   #
-  # 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.
+  # Runs on ubuntu-latest — no KVM needed, no test reruns. Coverage files use
+  # relative_files = True (.coveragerc) so they combine cleanly across runners.
+  # Each test job sets COVERAGE_FILE to an absolute path so coverage.py writes
+  # to a known location that upload-artifact can find regardless of runner env.
   #
-  # 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).
-  #
-  # build-infra creates one candidate from the checkout. This job boots that
-  # same candidate after integration-firecracker has exercised it; the main
-  # push path publishes the identical bytes only after every required job.
+  # Restricted to the same events as integration-firecracker: it depends on
+  # that job's coverage artifact and skips for fork PRs alongside it.
   coverage:
-    needs: [build-infra, integration-firecracker]
+    needs: [unit, integration-docker, integration-firecracker]
     timeout-minutes: 15
-    runs-on: [self-hosted, kvm]
+    runs-on: ubuntu-latest
     if: >-
       github.event_name == 'push' ||
       github.event_name == 'workflow_dispatch' ||
@@ -213,29 +235,37 @@ jobs:
         with:
           fetch-depth: 0
 
-      - 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: Install coverage
+        run: python3 -m pip install --break-system-packages coverage
 
-      - name: Download the candidate already exercised by integration
+      - name: Download unit coverage artifact
         uses: actions/download-artifact@v3
         with:
-          name: infra-candidate
-          path: infra-candidate
+          name: coverage-unit
+          path: ${{ github.workspace }}
+
+      - name: Download docker coverage artifact
+        uses: actions/download-artifact@v3
+        with:
+          name: coverage-docker
+          path: ${{ github.workspace }}
+
+      - name: Download firecracker coverage artifact
+        uses: actions/download-artifact@v3
+        with:
+          name: coverage-firecracker
+          path: ${{ github.workspace }}
+
+      # Rename the non-dot upload names back to the .coverage.* files that
+      # `coverage combine` discovers (see the staging steps in each test job).
+      - name: Reassemble coverage data files
+        run: |
+          mv coverage-unit.dat .coverage.unit
+          mv coverage-docker.dat .coverage.docker
+          mv coverage-firecracker.dat .coverage.firecracker
 
-      # 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)
-        env:
-          BOT_BOTTLE_CI_INFRA_ARTIFACT_DIR: ${{ github.workspace }}/infra-candidate
-        run: PYTHON=python3 bash scripts/coverage.sh critical
+        run: PYTHON=python3 bash scripts/coverage.sh aggregate critical
 
       - name: Diff-coverage gate (changed lines >= 90%)
         run: |
@@ -243,14 +273,14 @@ jobs:
           python3 scripts/diff_coverage.py --base origin/main --min 90
 
   publish-infra:
-    needs: [stage-firecracker-inputs, build-infra, unit, integration-docker, integration-firecracker, coverage]
+    needs: [unit, integration-docker, integration-firecracker, coverage]
     runs-on: ubuntu-latest
     if: github.event_name == 'push' && github.ref == 'refs/heads/main'
     steps:
       - name: Checkout the tested revision
         uses: actions/checkout@v4
 
-      - name: Download the tested candidate
+      - name: Download the tested rootfs
         uses: actions/download-artifact@v3
         with:
           name: infra-candidate
@@ -258,9 +288,10 @@ jobs:
 
       # publish_infra re-derives the version from the checkout to confirm the
       # bundle matches before uploading, and the version hashes the dropbear
-      # bytes. Stage the SAME dropbear build-infra used, or the recheck
-      # computes a "<missing>"-dropbear version and rejects the candidate.
-      - name: Download the staged dropbear (matches build-infra's version)
+      # bytes. Download the SAME dropbear integration-firecracker used, or
+      # the recheck computes a "<missing>"-dropbear version and rejects the
+      # candidate.
+      - name: Download the staged dropbear (matches build's version)
         uses: actions/download-artifact@v3
         with:
           name: firecracker-inputs

.gitea/workflows/update-badges.yml

@@ -14,11 +14,14 @@ on:
 jobs:
   update-badges:
     runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
     steps:
       - uses: actions/checkout@v3
         with:
           fetch-depth: 0
-          token: ${{ secrets.GITHUB_TOKEN }}
+          token: ${{ secrets.BADGE_PUSH_TOKEN }}
 
       # No actions/setup-python: the runner image ships Python 3.12 and older
       # act_runner engines mishandle setup-python's PATH. Install into the

README.md

@@ -5,7 +5,7 @@
 # bot-bottle
 
 [![test](https://gitea.dideric.is/didericis/bot-bottle/actions/workflows/test.yml/badge.svg?branch=main)](https://gitea.dideric.is/didericis/bot-bottle/actions?workflow=test.yml)
-[![coverage](https://img.shields.io/badge/coverage-81%25-brightgreen)](https://coverage.readthedocs.io/)
+[![coverage](https://img.shields.io/badge/coverage-84%25-brightgreen)](https://coverage.readthedocs.io/)
 [![core coverage](https://img.shields.io/badge/core%20coverage-94%25-brightgreen)](https://gitea.dideric.is/didericis/bot-bottle/src/branch/main/docs/decisions/0004-coverage-policy.md)
 
 **Problem:** Developer wants to run a coding agent without supervision, but they don't want a prompt injected or misbehaving agent wrecking their environment or exfiltrating sensitive data.
@@ -75,6 +75,88 @@ On compatible macOS hosts, the default backend requires Apple's `container` CLI
 
 Use `BOT_BOTTLE_BACKEND=docker ./cli.py start <agent>` on hosts where neither Apple Container nor KVM is available and Docker is the desired backend.
 
+### Containers inside a bottle
+
+A bottle may set `nested_containers: true`. On the macOS backend this starts a
+guest-local, rootless **podman** service after the bottle is registered and
+exposes its Docker-compatible API socket, so the agent still runs `docker` and
+`docker compose`. Nothing is mounted from the host: Docker Desktop's socket
+stays out of the bottle and the guest gains no outer VM capabilities. Backends
+that cannot do this (`docker`, `firecracker`) reject the flag rather than
+silently ignore it.
+
+Rootless Docker was tried first and does not work here at all: Apple
+Container's capability bounding set omits `CAP_SYS_ADMIN`, which the kernel
+requires to write a multi-range `uid_map`. See
+[`docs/research/rootless-docker-in-apple-container-spike.md`](docs/research/rootless-docker-in-apple-container-spike.md).
+
+The tradeoff to understand before enabling it: podman avoids that requirement
+by falling back to a single-UID mapping, so nested containers provide **no
+isolation from the agent itself** — `root` inside a nested container is the
+agent user outside it. Nested containers are a build/test convenience, not a
+security boundary. The bottle remains the boundary.
+
+Pulling images goes through the bottle's egress proxy like every other
+request, so each registry needs a route — **and so does the CDN it redirects
+layer blobs to**, which is a different host. Without the CDN route the pull
+authenticates, fetches the manifest, then 403s partway through.
+
+Docker Hub and GHCR additionally need `preserve_auth: true`: their token dance
+uses a client-fetched per-scope bearer token that the proxy would otherwise
+strip. Turn DLP off on every registry and CDN route — the bodies are
+compressed layer blobs that no detector can read, and buffering them is what
+triggers the shared-proxy OOM in #455.
+
+```yaml
+nested_containers: true
+egress:
+  routes:
+    # Docker Hub: registry, token endpoint, blob CDN.
+    - host: registry-1.docker.io
+      preserve_auth: true
+      dlp: { outbound_detectors: false, inbound_detectors: false }
+    - host: auth.docker.io
+      preserve_auth: true
+      dlp: { outbound_detectors: false, inbound_detectors: false }
+    - host: production.cloudfront.docker.com
+      dlp: { outbound_detectors: false, inbound_detectors: false }
+    # GHCR: registry + blob CDN.
+    - host: ghcr.io
+      preserve_auth: true
+      dlp: { outbound_detectors: false, inbound_detectors: false }
+    - host: pkg-containers.githubusercontent.com
+      dlp: { outbound_detectors: false, inbound_detectors: false }
+    # quay.io: registry + blob CDNs. No preserve_auth needed for public pulls.
+    - host: quay.io
+      dlp: { outbound_detectors: false, inbound_detectors: false }
+    - host: cdn01.quay.io
+      dlp: { outbound_detectors: false, inbound_detectors: false }
+    - host: cdn02.quay.io
+      dlp: { outbound_detectors: false, inbound_detectors: false }
+    - host: cdn03.quay.io
+      dlp: { outbound_detectors: false, inbound_detectors: false }
+```
+
+`mcr.microsoft.com` and `registry.k8s.io` follow the same shape and also
+redirect blobs elsewhere (`*.data.mcr.microsoft.com` and
+`us-*-docker.pkg.dev` respectively); route whichever host the 403 names.
+
+Inside a nested container the same allowlist applies: an allowlisted host
+returns 200 and anything else gets a 403 straight from the proxy. The
+gateway's CA bundle and proxy settings are wired in automatically, so
+`docker run … curl https://…` works with no extra flags — no `--add-host`,
+`-e`, or `-v`.
+
+Two things worth knowing when testing that:
+
+- Public DNS inside a nested container fails **by design**. Everything
+  egresses through the proxy, so `nslookup` failing is expected and is not
+  evidence of a problem.
+- Alpine's BusyBox `wget` drops the connection after the proxy's TLS
+  interception and reports `error getting response`, even though the proxy
+  logs the decrypted request and returns a response. Use `curl` to test
+  egress; BusyBox `wget` will lie to you.
+
 ### Firecracker on Linux
 
 On Linux, a KVM-capable host defaults to the Firecracker backend. It needs:
@@ -123,14 +205,14 @@ git:
 egress:
   routes:
     - host: gitea.dideric.is
-      auth:
-        scheme: token        # Bearer | token
-        token_ref: BOT_BOTTLE_GITEA_TOKEN
-      matches:               # optional — restrict to specific paths/methods/headers
-        - paths:
-            - {type: prefix, value: /api/v1/}
-          methods: [GET, POST, PATCH, DELETE]
-      dlp:                   # optional — per-route detector overrides (default: all on)
+      inspect:
+        auth:
+          scheme: token        # Bearer | token
+          token_ref: BOT_BOTTLE_GITEA_TOKEN
+        matches:               # optional — restrict to specific paths/methods/headers
+          - paths:
+              - {type: prefix, value: /api/v1/}
+            methods: [GET, POST, PATCH, DELETE]
         outbound_detectors: [token_patterns, known_secrets]
         inbound_detectors: false   # disable response scanning for this host
 ---

bot_bottle/agent_provider.py

@@ -45,6 +45,10 @@ 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",
@@ -257,7 +261,28 @@ class AgentProvider(ABC):
         Default: Debian/node — writes the git-gate insteadOf gitconfig
         and sets user.name/email as node. Workspace copy runs through
         BottleBackend.provision_workspace against the running bottle."""
-        from .log import info
+        from .log import die, info
+
+        # Firecracker exports image rootfs files through an unprivileged host
+        # tar extraction, so image-time ownership of XDG directories is not
+        # preserved.  Git consults ~/.config/git even when the actual config
+        # is ~/.gitconfig; an unreadable directory there can prevent the
+        # git-gate insteadOf rules below from taking effect.  Repair this at
+        # runtime, after every backend's copy/export path has completed.
+        git_xdg_dir = f"{plan.guest_home}/.config/git"
+        repair = bottle.exec(
+            f"chown node:node {shlex.quote(plan.guest_home)} && "
+            f"chmod 755 {shlex.quote(plan.guest_home)} && "
+            f"mkdir -p {shlex.quote(git_xdg_dir)} && "
+            f"chown -R node:node {shlex.quote(f'{plan.guest_home}/.config')} && "
+            f"chmod -R u+rwX,go+rX {shlex.quote(f'{plan.guest_home}/.config')}",
+            user="root",
+        )
+        if repair.returncode != 0:
+            die(
+                "git provisioning: could not make the runtime Git config "
+                f"directory readable: {(repair.stderr or repair.stdout).strip()}"
+            )
 
         manifest_bottle = plan.manifest.bottle
         if manifest_bottle.git:
@@ -280,11 +305,27 @@ class AgentProvider(ABC):
                 f"{len(manifest_bottle.git)} insteadOf rule(s)"
             )
             bottle.cp_in(str(config_file), guest_gitconfig)
-            bottle.exec(
+            permissions = bottle.exec(
                 f"chown node:node {shlex.quote(guest_gitconfig)} && "
                 f"chmod 644 {shlex.quote(guest_gitconfig)}",
                 user="root",
             )
+            if permissions.returncode != 0:
+                die(
+                    "git provisioning: could not set ownership on "
+                    f"{guest_gitconfig}: "
+                    f"{(permissions.stderr or permissions.stdout).strip()}"
+                )
+            configured = bottle.exec(
+                "git config --global --get-regexp '^url\\..*\\.insteadof$'",
+                user="node",
+            )
+            if configured.returncode != 0:
+                die(
+                    "git provisioning: the runtime user cannot read the "
+                    f"git-gate insteadOf rules from {guest_gitconfig}: "
+                    f"{(configured.stderr or configured.stdout).strip()}"
+                )
 
         gu = manifest_bottle.git_user
         if not gu.is_empty():

bot_bottle/backend/__init__.py

@@ -37,10 +37,10 @@ import os
 import shlex
 import sys
 from abc import ABC, abstractmethod
-from contextlib import AbstractContextManager
+from contextlib import AbstractContextManager, contextmanager
 from dataclasses import dataclass
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, Generic, Sequence, TypeVar
+from typing import TYPE_CHECKING, Any, Generator, Generic, Sequence, TypeVar
 
 from ..agent_provider import AgentProvisionPlan, get_provider, build_agent_provision_plan
 from ..egress import EgressPlan
@@ -83,6 +83,9 @@ class BottleSpec:
     # True when launched via --headless (no TTY, no interactive prompts).
     # The git-gate host-key preflight uses this to error rather than prompt.
     headless: bool = False
+    # Image startup policy. "fresh" preserves the normal build path;
+    # "cached" reuses the current local image/artifact without rebuilding.
+    image_policy: str = "fresh"
 
 
 @dataclass(frozen=True)
@@ -278,6 +281,18 @@ PlanT = TypeVar("PlanT", bound=BottlePlan)
 CleanupT = TypeVar("CleanupT", bound=BottleCleanupPlan)
 
 
+@dataclass(frozen=True)
+class BottleImages:
+    """Resolved image references (or artifact paths) for a bottle launch.
+
+    For Docker/macOS-container backends, `agent` and `sidecar` are string
+    image refs. For the smolmachines backend they are Path objects pointing
+    to pre-built `.smolmachine` artifacts."""
+
+    agent: str | Path
+    sidecar: str | Path = ""
+
+
 class BottleBackend(ABC, Generic[PlanT, CleanupT]):
     """Abstract base for selectable bottle backends. Concrete subclasses
     (e.g. DockerBottleBackend) own their own prepare/launch impls.
@@ -287,6 +302,11 @@ class BottleBackend(ABC, Generic[PlanT, CleanupT]):
 
     name: str
 
+    # Whether this backend can run a container engine *inside* the bottle.
+    # Backends that cannot must reject `nested_containers: true` rather than
+    # reach for a host daemon socket (issue #392).
+    supports_nested_containers: bool = False
+
     def prepare(self, spec: BottleSpec, stage_dir: Path) -> PlanT:
         """Template method: run cross-backend host-side validation, then
         delegate to the subclass's `_resolve_plan` for the
@@ -300,12 +320,16 @@ class BottleBackend(ABC, Generic[PlanT, CleanupT]):
             prepare_egress,
             prepare_git_gate,
             prepare_supervise,
+            reject_nested_containers,
             resolve_manifest_dockerfile,
             write_launch_metadata,
         )
 
         manifest = self._validate(spec)
 
+        if not self.supports_nested_containers:
+            reject_nested_containers(self.name, manifest)
+
         self._preflight()
 
         from ..git_gate_host_key import preflight_host_keys
@@ -437,9 +461,27 @@ class BottleBackend(ABC, Generic[PlanT, CleanupT]):
         prompt file, Dockerfile path, and guest home all live on
         `agent_provision_plan` — the source of truth."""
 
+    def prelaunch_checks(self, plan: PlanT) -> None:
+        """Raise StaleImageError if any cached image used by this plan is stale.
+        No-op default; backends override to call the shared check_stale*
+        helpers on their image/artifact timestamps. Called by the CLI before
+        launch so the operator can be prompted outside the launch context."""
+
+    @contextmanager
+    def launch(self, plan: PlanT) -> Generator[Bottle, None, None]:
+        """Template: build or load images, then delegate to _launch_impl."""
+        images = self._build_or_load_images(plan)
+        with self._launch_impl(plan, images) as bottle:
+            yield bottle
+
     @abstractmethod
-    def launch(self, plan: PlanT) -> AbstractContextManager[Bottle]:
-        """Build/run the bottle and yield a handle; tear down on exit."""
+    def _build_or_load_images(self, plan: PlanT) -> BottleImages:
+        """Return the agent and sidecar image references (or artifact paths)
+        for this plan, building fresh images when the policy requires it."""
+
+    @abstractmethod
+    def _launch_impl(self, plan: PlanT, images: BottleImages) -> AbstractContextManager[Bottle]:
+        """Bring up the bottle using pre-resolved images; yield a handle; tear down on exit."""
 
     def provision(self, plan: PlanT, bottle: "Bottle") -> str | None:
         """Copy host-side files (CA cert, prompt, skills, .git) into

bot_bottle/backend/consolidated_util.py

@@ -7,10 +7,13 @@ imports it rather than re-implementing it.
 
 from __future__ import annotations
 
+import dataclasses
+
 from ..egress import EgressPlan
 from ..git_gate import GitGatePlan
-from ..orchestrator.client import OrchestratorClient
+from ..orchestrator.client import OrchestratorClient, RegisteredBottle
 from ..orchestrator.registration import registration_inputs
+from ..orchestrator.secret_store import new_env_var_secret
 from .docker.gateway_provision import GatewayTransport, deprovision_git_gate, provision_git_gate
 
 
@@ -23,21 +26,27 @@ def provision_bottle(
     *,
     image_ref: str = "",
     tokens: dict[str, str] | None = None,
-):
+    env_var_secret: str | None = None,
+) -> RegisteredBottle:
     """Register the bottle and provision its git-gate state. Rolls back the
-    registration if provisioning fails so no orphan is left. Returns the
-    `RegisteredBottle` from the orchestrator."""
+    registration if provisioning fails so no orphan is left.
+
+    Generates a fresh ENV_VAR_SECRET, passes it to the orchestrator so it can
+    encrypt the token values at rest, and stamps the secret onto the returned
+    ``RegisteredBottle`` so callers can inject it into the agent container's
+    environment."""
     inputs = registration_inputs(egress_plan)
+    env_var_secret = env_var_secret or new_env_var_secret()
     reg = client.register_bottle(
         source_ip, image_ref=image_ref, policy=inputs.policy,
-        metadata=inputs.metadata, tokens=tokens,
+        metadata=inputs.metadata, tokens=tokens, env_var_secret=env_var_secret,
     )
     try:
         provision_git_gate(transport, reg.bottle_id, git_gate_plan)
     except Exception:
         client.teardown_bottle(reg.bottle_id)
         raise
-    return reg
+    return dataclasses.replace(reg, env_var_secret=env_var_secret)
 
 
 def teardown_consolidated(
@@ -45,10 +54,15 @@ def teardown_consolidated(
     transport: GatewayTransport,
     *,
     orchestrator_url: str,
+    timeout: float | None = None,
 ) -> None:
     """Deregister the bottle and remove its git-gate state. Both steps are
     idempotent so this is safe from a cleanup trap."""
-    OrchestratorClient(orchestrator_url).teardown_bottle(bottle_id)
+    from ..orchestrator.config_store import DEFAULT_TEARDOWN_TIMEOUT_SECONDS
+    OrchestratorClient(
+        orchestrator_url,
+        timeout=timeout if timeout is not None else DEFAULT_TEARDOWN_TIMEOUT_SECONDS,
+    ).teardown_bottle(bottle_id)
     deprovision_git_gate(transport, bottle_id)
 
 

bot_bottle/backend/docker/backend.py

@@ -31,7 +31,7 @@ from ...env import ResolvedEnv
 from ...git_gate import GitGatePlan
 from ...supervise import SupervisePlan
 from ...manifest import Manifest
-from .. import ActiveAgent, BottleBackend, BottleSpec
+from .. import ActiveAgent, BottleBackend, BottleImages, BottleSpec
 from . import cleanup as _cleanup
 from . import enumerate as _enumerate
 from . import launch as _launch
@@ -100,9 +100,15 @@ class DockerBottleBackend(BottleBackend["DockerBottlePlan", "DockerBottleCleanup
             stage_dir=stage_dir,
         )
 
+    def prelaunch_checks(self, plan: DockerBottlePlan) -> None:
+        _launch.stale_checks(plan)
+
+    def _build_or_load_images(self, plan: DockerBottlePlan) -> BottleImages:
+        return _launch.build_or_load_images(plan)
+
     @contextmanager
-    def launch(self, plan: DockerBottlePlan) -> Generator[DockerBottle, None, None]:
-        with _launch.launch(plan, provision=self.provision) as bottle:
+    def _launch_impl(self, plan: DockerBottlePlan, images: BottleImages) -> Generator[DockerBottle, None, None]:
+        with _launch.launch(plan, images, provision=self.provision) as bottle:
             yield bottle
 
     def ensure_orchestrator(self) -> str:

bot_bottle/backend/docker/bottle_plan.py

@@ -39,6 +39,10 @@ class DockerBottlePlan(BottlePlan):
     # (egress proxy credentials, git-gate/supervise headers); set by launch
     # from the orchestrator registration. Empty pre-registration.
     identity_token: str = ""
+    # Encryption key for the agent's stored egress secrets; injected into the
+    # agent container as ENV_VAR_SECRET via the compose subprocess env (bare
+    # name — value never written to the compose file). Empty pre-registration.
+    env_var_secret: str = ""
 
     @property
     def container_name(self) -> str:

bot_bottle/backend/docker/consolidated_compose.py

@@ -17,6 +17,7 @@ from __future__ import annotations
 from typing import Any
 
 from ...egress import egress_agent_env_entries
+from ...orchestrator.secret_store import ENV_VAR_SECRET_NAME
 from ..util import AGENT_CA_BUNDLE, AGENT_CA_PATH
 from .bottle_plan import DockerBottlePlan
 from .egress import EGRESS_PORT
@@ -58,6 +59,10 @@ def consolidated_agent_compose(
     # the secret value never lands on argv or in the compose file.
     for name in sorted(plan.forwarded_env.keys()):
         env.append(name)
+    # ENV_VAR_SECRET: bare name so the value comes from the compose subprocess
+    # env (set in launch.py) and is never written to the compose file on disk.
+    if getattr(plan, "env_var_secret", ""):
+        env.append(ENV_VAR_SECRET_NAME)
     env.extend(egress_agent_env_entries(plan.egress_plan))
 
     service: dict[str, Any] = {

bot_bottle/backend/docker/consolidated_launch.py

@@ -15,12 +15,15 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 
+from ... import log
 from ...docker_cmd import run_docker
 from ...egress import EgressPlan
 from ...git_gate import GitGatePlan
 from ...orchestrator.client import OrchestratorClient
 from ...orchestrator.gateway import GATEWAY_NETWORK
 from ...orchestrator.lifecycle import INFRA_NAME, OrchestratorService
+from ...orchestrator.secret_store import ENV_VAR_SECRET_NAME
+from ...orchestrator.reprovision import reprovision_bottles
 from ..consolidated_util import provision_bottle
 from ..consolidated_util import teardown_consolidated as _teardown_util
 from .gateway_provision import DockerGatewayTransport
@@ -41,6 +44,7 @@ class LaunchContext:
     network: str            # the shared gateway network to attach to
     gateway_ip: str         # the gateway's address — the agent's proxy target
     orchestrator_url: str
+    env_var_secret: str = ""  # encryption key injected into the agent's env
 
 
 def _network_cidr(network: str) -> str:
@@ -85,6 +89,55 @@ def _network_container_ips(network: str) -> list[str]:
     return ips
 
 
+def _reprovision_running_bottles(
+    orchestrator_url: str,
+    network: str = GATEWAY_NETWORK,
+    infra_name: str = INFRA_NAME,
+) -> None:
+    """Re-inject egress tokens for any registered bottles that lost their
+    in-memory tokens (e.g., after an infra container restart).
+
+    For each registered bottle whose source IP maps to a live container on the
+    gateway network, reads ENV_VAR_SECRET via ``docker exec … printenv`` and
+    calls ``POST /bottles/<id>/reprovision_gateway``. Idempotent — a no-op
+    when the orchestrator already has all tokens loaded. Best-effort: a single
+    container exec failure never blocks a new bottle launch."""
+    client = OrchestratorClient(orchestrator_url)
+    # Build {source_ip: container_name} from live containers on the gateway
+    # network, excluding the infra container itself.
+    try:
+        proc = run_docker([
+            "docker", "network", "inspect",
+            "--format", "{{range .Containers}}{{.Name}} {{.IPv4Address}}\n{{end}}",
+            network,
+        ])
+    except OSError as exc:
+        log.info(f"egress token reprovision skipped: {exc}")
+        return
+    ip_to_container: dict[str, str] = {}
+    for line in proc.stdout.splitlines():
+        parts = line.strip().split()
+        if len(parts) >= 2 and parts[0] != infra_name:
+            ip = parts[1].split("/", 1)[0]
+            if ip:
+                ip_to_container[ip] = parts[0]
+
+    secrets_by_ip: dict[str, str] = {}
+    for source_ip, container_name in ip_to_container.items():
+        proc = run_docker(
+            ["docker", "exec", container_name, "printenv", ENV_VAR_SECRET_NAME]
+        )
+        if proc.returncode == 0 and proc.stdout.strip():
+            secrets_by_ip[source_ip] = proc.stdout.strip()
+
+    reprovisioned = reprovision_bottles(client, secrets_by_ip)
+    if reprovisioned:
+        log.info(
+            "reprovisioned egress tokens",
+            context={"count": reprovisioned},
+        )
+
+
 def launch_consolidated(
     egress_plan: EgressPlan,
     git_gate_plan: GitGatePlan,
@@ -96,9 +149,14 @@ def launch_consolidated(
     network: str = GATEWAY_NETWORK,
 ) -> LaunchContext:
     """Ensure the infra container is up, allocate + register the bottle, and
-    provision its git-gate state. Returns the agent's attach context."""
+    provision its git-gate state. Returns the agent's attach context.
+
+    Also reprovisiones egress tokens for any already-running bottles that lost
+    their in-memory credentials (e.g. after an infra container restart), so
+    they regain egress access before the new bottle is registered."""
     service = service or OrchestratorService()
     url = service.ensure_running()
+    _reprovision_running_bottles(url, network=network, infra_name=infra_name)
     client = OrchestratorClient(url)
 
     cidr = _network_cidr(network)
@@ -117,15 +175,17 @@ def launch_consolidated(
         network=network,
         gateway_ip=gateway_ip,
         orchestrator_url=url,
+        env_var_secret=reg.env_var_secret,
     )
 
 
 def teardown_consolidated(
     bottle_id: str, *, orchestrator_url: str, infra_name: str = INFRA_NAME,
+    timeout: float | None = None,
 ) -> None:
     """Deregister the bottle and remove its git-gate state. Idempotent."""
     _teardown_util(bottle_id, DockerGatewayTransport(infra_name),
-                   orchestrator_url=orchestrator_url)
+                   orchestrator_url=orchestrator_url, timeout=timeout)
 
 
 __all__ = [

bot_bottle/backend/docker/launch.py

@@ -42,7 +42,9 @@ from ...git_gate import (
     provision_git_gate_dynamic_keys,
     revoke_git_gate_provisioned_keys,
 )
-from ...log import info, warn
+from ...image_cache import check_stale
+from ...log import die, info, warn
+from .. import BottleImages
 from . import util as docker_mod
 from .bottle import DockerBottle
 from .bottle_plan import DockerBottlePlan
@@ -62,6 +64,7 @@ from .compose import (
     write_compose_file,
 )
 from .consolidated_compose import consolidated_agent_compose
+from ...orchestrator.config_store import resolve_teardown_timeout
 from .consolidated_launch import launch_consolidated, teardown_consolidated
 from ...orchestrator.gateway import DockerGateway
 
@@ -70,16 +73,47 @@ from ...orchestrator.gateway import DockerGateway
 _REPO_DIR = str(Path(__file__).resolve().parent.parent.parent.parent)
 
 
+def build_or_load_images(plan: DockerBottlePlan) -> BottleImages:
+    """Resolve the agent image ref for this plan.
+
+    Returns the committed snapshot if one exists, the cached image when the
+    policy is 'cached', or builds a fresh image and returns that."""
+    committed = read_committed_image(plan.slug)
+    if committed and docker_mod.image_exists(committed):
+        info(f"using committed image {committed!r}")
+        return BottleImages(agent=committed)
+    if plan.spec.image_policy == "cached":
+        if not docker_mod.image_exists(plan.image):
+            die(
+                f"cached agent image {plan.image!r} not found; "
+                "run without --cached-images to build it"
+            )
+        info(f"using cached agent image {plan.image!r}")
+        return BottleImages(agent=plan.image)
+    docker_mod.build_image(plan.image, _REPO_DIR, dockerfile=plan.dockerfile_path)
+    docker_mod.verify_agent_image(
+        plan.image, runtime_for(plan.agent_provider_template).smoke_test,
+    )
+    return BottleImages(agent=plan.image)
+
+
 @contextmanager
 def launch(
     plan: DockerBottlePlan,
+    images: BottleImages,
     *,
     provision: Callable[[DockerBottlePlan, "DockerBottle"], str | None],
 ) -> Generator[DockerBottle, None, None]:
-    """Build, launch, and provision a Docker bottle via compose.
-    Teardown on exit."""
+    """Launch and provision a Docker bottle via compose. Teardown on exit."""
     stack = ExitStack()
 
+    # Stamp the resolved agent image ref into the plan so compose rendering
+    # picks up the right image (may be a committed snapshot or cached ref).
+    plan = dataclasses.replace(
+        plan,
+        agent_provision=dataclasses.replace(plan.agent_provision, image=str(images.agent)),
+    )
+
     _bottle_for_revoke = plan.manifest.bottle
     _git_gate_dir_for_revoke = git_gate_state_dir(plan.slug)
 
@@ -96,25 +130,6 @@ def launch(
         )
 
     try:
-        # Step 1: agent image. Use a committed snapshot when one exists
-        # and is present in the local daemon; otherwise build from the
-        # Dockerfile. (The gateway image is built by the orchestrator.)
-        committed = read_committed_image(plan.slug)
-        if committed and docker_mod.image_exists(committed):
-            info(f"using committed image {committed!r}")
-            plan = dataclasses.replace(
-                plan,
-                agent_provision=dataclasses.replace(plan.agent_provision, image=committed),
-            )
-        else:
-            docker_mod.build_image(
-                plan.image, _REPO_DIR,
-                dockerfile=plan.dockerfile_path,
-            )
-            docker_mod.verify_agent_image(
-                plan.image, runtime_for(plan.agent_provider_template).smoke_test,
-            )
-
         # Step 2: mint the git-gate dynamic (gitea) deploy keys, if any, before
         # provisioning the bottle's repos into the shared gateway.
         git_gate_plan = plan.git_gate_plan
@@ -133,11 +148,14 @@ def launch(
         token_values = egress_resolve_token_values(
             plan.egress_plan.token_env_map, effective_env,
         )
+        teardown_timeout = resolve_teardown_timeout()
         ctx = launch_consolidated(
             plan.egress_plan, git_gate_plan, image_ref=plan.image, tokens=token_values,
         )
         stack.callback(
-            teardown_consolidated, ctx.bottle_id, orchestrator_url=ctx.orchestrator_url,
+            teardown_consolidated, ctx.bottle_id,
+            orchestrator_url=ctx.orchestrator_url,
+            timeout=teardown_timeout,
         )
 
         # Step 4: install the SHARED gateway CA into the agent (replaces the
@@ -168,6 +186,7 @@ def launch(
             agent_git_gate_url=git_gate_url,
             agent_supervise_url=supervise_url,
             identity_token=ctx.identity_token,
+            env_var_secret=ctx.env_var_secret,
         )
 
         # Step 5: render + up the agent-only compose, pinned on the shared
@@ -180,7 +199,12 @@ def launch(
         project = compose_project_name(plan.slug)
         # Forwarded vars (OAuth token, host interpolations) flow through the
         # subprocess env as bare names so values never land in the file.
+        # ENV_VAR_SECRET follows the same pattern: bare name in the compose
+        # spec, value only in the subprocess env so it is never written to disk.
         compose_env: dict[str, str] = {**os.environ, **plan.forwarded_env}
+        if plan.env_var_secret:
+            from ...orchestrator.secret_store import ENV_VAR_SECRET_NAME
+            compose_env[ENV_VAR_SECRET_NAME] = plan.env_var_secret
         info(
             f"docker compose up -d  (project {project}, agent on shared "
             f"gateway {ctx.gateway_ip}, ip {ctx.source_ip})"
@@ -207,3 +231,21 @@ def launch(
         yield bottle
     finally:
         teardown()
+
+
+def stale_checks(plan: DockerBottlePlan) -> None:
+    """Raise StaleImageError if a cached image is older than the configured
+    threshold. Only runs when image_policy is 'cached'. Called by the backend
+    class's _image_stale_checks before _launch_impl starts any resources."""
+    if plan.spec.image_policy != "cached":
+        return
+    committed = read_committed_image(plan.slug)
+    if committed and docker_mod.image_exists(committed):
+        ts = docker_mod.image_created_at(committed)
+        if ts is not None:
+            check_stale(f"agent image {committed!r}", ts)
+        return
+    if docker_mod.image_exists(plan.image):
+        ts = docker_mod.image_created_at(plan.image)
+        if ts is not None:
+            check_stale(f"agent image {plan.image!r}", ts)

bot_bottle/backend/docker/util.py

@@ -5,6 +5,7 @@ existence, and building images."""
 from __future__ import annotations
 
 import os
+from datetime import datetime, timezone
 import re
 import shutil
 import subprocess
@@ -197,3 +198,46 @@ def commit_container(container_name: str, image_tag: str) -> None:
             f"{(result.stderr or '').strip() or '<no stderr>'}"
         )
     info(f"committed {container_name!r} → {image_tag!r}")
+
+
+def image_created_at(ref: str) -> datetime | None:
+    """Return Docker's image Created timestamp as an aware UTC datetime, or
+    None when the field is absent or unparseable. Callers should skip the
+    stale check when None is returned."""
+    r = subprocess.run(
+        ["docker", "image", "inspect", "--format", "{{.Created}}", ref],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if r.returncode != 0:
+        die(
+            f"docker image inspect for {ref!r} failed: "
+            f"{(r.stderr or '').strip() or '<no stderr>'}"
+        )
+    raw = r.stdout.strip()
+    if not raw:
+        return None
+    try:
+        return _parse_docker_timestamp(raw)
+    except ValueError:
+        return None
+
+
+def _parse_docker_timestamp(raw: str) -> datetime:
+    text = raw.strip()
+    if text.endswith("Z"):
+        text = text[:-1] + "+00:00"
+    dot = text.find(".")
+    if dot != -1:
+        tz_plus = text.find("+", dot)
+        tz_minus = text.find("-", dot)
+        tz_candidates = [pos for pos in (tz_plus, tz_minus) if pos != -1]
+        if tz_candidates:
+            tz_pos = min(tz_candidates)
+            frac = text[dot + 1:tz_pos]
+            text = text[:dot + 1] + frac[:6].ljust(6, "0") + text[tz_pos:]
+    dt = datetime.fromisoformat(text)
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=timezone.utc)
+    return dt.astimezone(timezone.utc)

bot_bottle/backend/firecracker/backend.py

@@ -18,7 +18,7 @@ from ...env import ResolvedEnv
 from ...git_gate import GitGatePlan
 from ...manifest import Manifest
 from ...supervise import SupervisePlan
-from .. import ActiveAgent, BottleBackend, BottleSpec
+from .. import ActiveAgent, BottleBackend, BottleImages, BottleSpec
 from . import cleanup as _cleanup
 from . import enumerate as _enumerate
 from . import launch as _launch
@@ -92,11 +92,18 @@ class FirecrackerBottleBackend(
             stage_dir=stage_dir,
         )
 
+    def _build_or_load_images(self, plan: FirecrackerBottlePlan) -> BottleImages:
+        return BottleImages(agent=_launch.build_or_load_agent_base(plan))
+
+    def prelaunch_checks(self, plan: FirecrackerBottlePlan) -> None:
+        _launch.stale_checks(plan)
+
     @contextmanager
-    def launch(
-        self, plan: FirecrackerBottlePlan
+    def _launch_impl(
+        self, plan: FirecrackerBottlePlan, images: BottleImages,
     ) -> Generator[FirecrackerBottle, None, None]:
-        with _launch.launch(plan, provision=self.provision) as bottle:
+        assert isinstance(images.agent, Path)
+        with _launch.launch(plan, images.agent, provision=self.provision) as bottle:
             yield bottle
 
     def prepare_cleanup(self) -> FirecrackerBottleCleanupPlan:

bot_bottle/backend/firecracker/bottle_plan.py

@@ -22,6 +22,9 @@ class FirecrackerBottlePlan(BottlePlan):
     # (egress proxy credentials, git-gate/supervise headers); set by launch
     # from the orchestrator registration. Empty pre-registration.
     identity_token: str = ""
+    # Applied to every agent SSH exec and mirrored into /run inside the VM so
+    # the host can recover it after the infra VM restarts.
+    env_var_secret: str = ""
 
     @property
     def container_name(self) -> str:

bot_bottle/backend/firecracker/cleanup.py

@@ -1,8 +1,23 @@
 """Cleanup for the Firecracker backend.
 
-Orphans are: firecracker VMM processes whose config lives under our run
-dir, and the per-bottle run dirs. TAP slots free themselves (the flock
-drops when the launcher exits), so there is nothing to reclaim there.
+Reaps *orphans* only — resources with no live VM behind them:
+
+  * orphan run dirs: a per-bottle run dir (holding the ~1G rootfs.ext4)
+    whose firecracker process has exited. These leak when a launch is
+    hard-killed before its teardown runs (host OOM/crash, a cancelled CI
+    job, `kill -9`); the clean-exit path already removes its own dir in
+    launch.py.
+  * orphan VM pids: a firecracker process whose run dir is already gone
+    — a VMM left lingering after its dir was removed.
+
+A run dir with a *live* firecracker process is a running bottle and is
+left strictly alone: it is neither killed nor removed. (The backend's
+`enumerate_active` registry is still a stub — #354 — so a live process
+is the only reliable "this bottle is in use" signal we have. Once the
+registry lands, registry-orphaned-but-running VMs can be reaped too.)
+
+TAP slots free themselves (the flock drops when the launcher exits), so
+there is nothing to reclaim there.
 """
 
 from __future__ import annotations
@@ -22,38 +37,79 @@ def _run_root() -> Path:
     return util.cache_dir() / "run"
 
 
-def _orphan_vm_pids() -> list[int]:
-    """firecracker processes whose --config-file is under our run dir."""
-    run_root = str(_run_root())
+def _run_dir_of(cmd: str, run_root: Path) -> Path | None:
+    """The bottle run dir a firecracker cmdline belongs to, or None.
+
+    A bottle VM is launched with `--config-file <run_root>/<slug>/config.json`,
+    so the run dir is the config file's parent when it sits directly under
+    the run root. Anything else (a builder VM, the infra VM elsewhere) is
+    not ours to reap here.
+    """
+    toks = cmd.split()
+    for i, tok in enumerate(toks):
+        if tok == "--config-file" and i + 1 < len(toks):
+            parent = Path(toks[i + 1]).parent
+            if parent.parent == run_root:
+                return parent
+    return None
+
+
+def _scan_processes(run_root: Path) -> tuple[set[str], list[int]]:
+    """Inspect running firecracker VMs under ``run_root``.
+
+    Returns ``(live_run_dirs, orphan_pids)``:
+      * ``live_run_dirs`` — run dirs backed by a running VM (never reaped);
+      * ``orphan_pids`` — firecracker pids whose run dir no longer exists
+        (a lingering VMM to kill).
+    """
     result = subprocess.run(
         ["pgrep", "-a", "firecracker"],
         capture_output=True, text=True, check=False,
     )
     if result.returncode != 0:
-        return []
-    pids: list[int] = []
+        return set(), []
+    live: set[str] = set()
+    orphan_pids: list[int] = []
     for line in result.stdout.splitlines():
         parts = line.split(None, 1)
-        if len(parts) != 2 or run_root not in parts[1]:
+        if len(parts) != 2:
             continue
         try:
-            pids.append(int(parts[0]))
+            pid = int(parts[0])
         except ValueError:
             continue
-    return pids
+        run_dir = _run_dir_of(parts[1], run_root)
+        if run_dir is None:
+            continue
+        if run_dir.is_dir():
+            live.add(str(run_dir))
+        else:
+            orphan_pids.append(pid)
+    return live, orphan_pids
 
 
-def _run_dirs() -> list[str]:
-    run_root = _run_root()
+def live_run_dirs() -> tuple[Path, ...]:
+    """Run directories backed by currently running agent microVMs."""
+    live, _ = _scan_processes(_run_root())
+    return tuple(Path(path) for path in sorted(live))
+
+
+def _orphan_run_dirs(run_root: Path, live: set[str]) -> list[str]:
+    """Run dirs with no live VM behind them — the leaked ones to remove."""
     if not run_root.is_dir():
         return []
-    return sorted(str(p) for p in run_root.iterdir() if p.is_dir())
+    return sorted(
+        str(p) for p in run_root.iterdir()
+        if p.is_dir() and str(p) not in live
+    )
 
 
 def prepare_cleanup() -> FirecrackerBottleCleanupPlan:
+    run_root = _run_root()
+    live, orphan_pids = _scan_processes(run_root)
     return FirecrackerBottleCleanupPlan(
-        vm_pids=tuple(_orphan_vm_pids()),
-        run_dirs=tuple(_run_dirs()),
+        vm_pids=tuple(orphan_pids),
+        run_dirs=tuple(_orphan_run_dirs(run_root, live)),
     )
 
 

bot_bottle/backend/firecracker/consolidated_launch.py

@@ -25,16 +25,27 @@ The TAP slot allocation, rootfs build, and VM boot are the caller's job.
 
 from __future__ import annotations
 
+import json
+import subprocess
 from dataclasses import dataclass
+from pathlib import Path
 
 from ...egress import EgressPlan
 from ...git_gate import GitGatePlan
-from ...orchestrator.client import OrchestratorClient
+from ...log import info
+from ...orchestrator.client import OrchestratorClient, OrchestratorClientError
 from ...orchestrator.lifecycle import (
     OrchestratorStartError,  # re-exported so callers can catch it
 )
-from ..consolidated_util import provision_bottle, teardown_consolidated as _teardown_util
-from . import infra_vm
+from ...orchestrator.reprovision import reprovision_bottles
+from ...orchestrator.secret_store import ENV_VAR_SECRET_NAME
+from ..consolidated_util import (
+    provision_bottle,
+    teardown_consolidated as _teardown_util,
+)
+from . import cleanup, infra_vm, util
+
+_ENV_VAR_SECRET_PATH = "/run/bot-bottle/env-var-secret"
 
 
 class ConsolidatedLaunchError(RuntimeError):
@@ -50,6 +61,55 @@ class LaunchContext:
     source_ip: str          # the VM's guest IP — the attribution key
     gateway_ca_pem: str     # the shared gateway CA the provisioner installs
     orchestrator_url: str
+    env_var_secret: str = ""  # encryption key injected into the agent's env
+
+
+def _guest_ip_from_config(config_path: Path) -> str:
+    """Read the kernel's configured guest IP from a Firecracker config."""
+    try:
+        config = json.loads(config_path.read_text())
+        args = config["boot-source"]["boot_args"]
+        ip_arg = next(part for part in args.split() if part.startswith("ip="))
+        return ip_arg.removeprefix("ip=").split(":", 1)[0]
+    except (OSError, ValueError, KeyError, TypeError, StopIteration):
+        return ""
+
+
+def persist_env_var_secret(private_key: Path, guest_ip: str, secret: str) -> None:
+    """Mirror the exec-time key into guest tmpfs for restart recovery."""
+    proc = subprocess.run(
+        util.ssh_base_argv(private_key, guest_ip)
+        + [f"umask 077; mkdir -p /run/bot-bottle; cat > {_ENV_VAR_SECRET_PATH}"],
+        input=secret, capture_output=True, text=True, check=False,
+    )
+    if proc.returncode != 0:
+        raise ConsolidatedLaunchError(
+            f"failed to persist {ENV_VAR_SECRET_NAME} in agent VM: "
+            f"{proc.stderr.strip() or '<no stderr>'}"
+        )
+
+
+def _reprovision_running_bottles(client: OrchestratorClient) -> None:
+    """Read keys from live agent VMs and restore the restarted gateway."""
+    try:
+        secrets_by_ip: dict[str, str] = {}
+        for run_dir in cleanup.live_run_dirs():
+            guest_ip = _guest_ip_from_config(run_dir / "config.json")
+            private_key = run_dir / "bottle_id_ed25519"
+            if not guest_ip or not private_key.is_file():
+                continue
+            proc = subprocess.run(
+                util.ssh_base_argv(private_key, guest_ip)
+                + [f"cat {_ENV_VAR_SECRET_PATH}"],
+                capture_output=True, text=True, check=False,
+            )
+            if proc.returncode == 0 and proc.stdout.strip():
+                secrets_by_ip[guest_ip] = proc.stdout.strip()
+        count = reprovision_bottles(client, secrets_by_ip)
+        if count:
+            info(f"reprovisioned egress tokens for {count} Firecracker bottle(s)")
+    except (OSError, OrchestratorClientError) as exc:
+        info(f"egress token reprovision skipped: {exc}")
 
 
 def launch_consolidated(
@@ -66,6 +126,7 @@ def launch_consolidated(
     infra = infra_vm.ensure_running()
     url = infra.control_plane_url
     client = OrchestratorClient(url)
+    _reprovision_running_bottles(client)
 
     transport = infra_vm.gateway_transport()
     reg = provision_bottle(
@@ -80,15 +141,19 @@ def launch_consolidated(
         source_ip=guest_ip,
         gateway_ca_pem=infra.gateway_ca_pem(),
         orchestrator_url=url,
+        env_var_secret=reg.env_var_secret,
     )
 
 
-def teardown_consolidated(bottle_id: str, *, orchestrator_url: str) -> None:
+def teardown_consolidated(
+    bottle_id: str, *, orchestrator_url: str, timeout: float | None = None,
+) -> None:
     """Deregister the bottle and remove its git-gate state from the gateway
     VM. Both steps are idempotent so this is safe from a cleanup trap. Does
     NOT stop the infra VM — it's a persistent per-host singleton shared by
     every bottle."""
-    _teardown_util(bottle_id, infra_vm.gateway_transport(), orchestrator_url=orchestrator_url)
+    _teardown_util(bottle_id, infra_vm.gateway_transport(),
+                   orchestrator_url=orchestrator_url, timeout=timeout)
 
 
 __all__ = [

bot_bottle/backend/firecracker/freezer.py

@@ -5,7 +5,7 @@ backend — we stream the guest root filesystem out over the control
 channel (SSH here). Unlike the other backends this needs no Docker: the
 tar *is* the resumable artifact. `resume` extracts it and rebuilds a
 fresh per-bottle ext4 with `mke2fs -d` (see `util.build_committed_rootfs_dir`
-and `launch._build_agent_base`). The bottle keeps running after the
+and `launch.build_or_load_agent_base`). The bottle keeps running after the
 snapshot.
 """
 

bot_bottle/backend/firecracker/image_builder.py

@@ -58,6 +58,12 @@ def _rootfs_digest(dockerfile: Path) -> str:
     return h.hexdigest()[:16]
 
 
+def cached_agent_rootfs_dir(dockerfile: Path) -> Path | None:
+    """Return the ready cached rootfs for ``dockerfile``, if one exists."""
+    base = util.cache_dir() / "rootfs" / f"agent-{_rootfs_digest(dockerfile)}"
+    return base if (base / ".bb-ready").is_file() else None
+
+
 def build_agent_rootfs_dir(
     dockerfile: Path, *, image_tag: str, smoke_test: tuple[str, ...] = (),
 ) -> Path:
@@ -72,7 +78,7 @@ def build_agent_rootfs_dir(
     silent-failure image at build time rather than at first agent use."""
     digest = _rootfs_digest(dockerfile)
     base = util.cache_dir() / "rootfs" / f"agent-{digest}"
-    if (base / ".bb-ready").is_file():
+    if cached_agent_rootfs_dir(dockerfile) is not None:
         info(f"using cached agent rootfs {base.name}")
         return base
 

bot_bottle/backend/firecracker/infra_vm.py

@@ -33,6 +33,7 @@ from pathlib import Path
 from typing import Generator
 
 from ...log import die, info
+from .. import util as backend_util
 from ..docker import util as docker_mod
 from ..docker.gateway_provision import GatewayProvisionError
 from . import firecracker_vm, infra_artifact, netpool, util
@@ -93,19 +94,18 @@ class InfraVm:
         """The gateway's mitmproxy CA (PEM) that agents install to trust its
         TLS interception. Generated a moment after boot, so this polls over
         SSH until it appears (mirrors DockerGateway.ca_cert_pem)."""
-        deadline = time.monotonic() + timeout
-        while True:
+        def _fetch() -> str | None:
             proc = subprocess.run(
                 util.ssh_base_argv(self.private_key, self.guest_ip)
                 + [f"cat {_GATEWAY_CA_PATH}"],
                 capture_output=True, text=True, timeout=15, check=False,
             )
-            if proc.returncode == 0 and "BEGIN CERTIFICATE" in proc.stdout:
-                return proc.stdout
-            if time.monotonic() >= deadline:
-                die(f"gateway CA not available after {timeout:g}s: "
-                    f"{proc.stderr.strip() or 'empty'}")
-            time.sleep(_HEALTH_POLL_SECONDS)
+            ok = proc.returncode == 0 and "BEGIN CERTIFICATE" in proc.stdout
+            return proc.stdout if ok else None
+        try:
+            return backend_util.poll_ca_cert(_fetch, timeout=timeout)
+        except TimeoutError as exc:
+            die(str(exc))
 
 
 def ensure_built() -> None:

bot_bottle/backend/firecracker/launch.py

@@ -26,6 +26,7 @@ from __future__ import annotations
 
 import dataclasses
 import os
+import shutil
 from contextlib import ExitStack, contextmanager
 from pathlib import Path
 from typing import Callable, Generator
@@ -45,15 +46,19 @@ from ...git_gate import (
     provision_git_gate_dynamic_keys,
     revoke_git_gate_provisioned_keys,
 )
-from ...log import info, warn
+from ...image_cache import check_stale_path
+from ...log import die, info, warn
 from ...supervise import SUPERVISE_PORT
 from ..docker.egress import EGRESS_PORT
 from ..util import AGENT_CA_BUNDLE, AGENT_CA_PATH
 from . import firecracker_vm, image_builder, isolation_probe, netpool, util
 from .bottle import FirecrackerBottle
 from .bottle_plan import FirecrackerBottlePlan
+from ...orchestrator.config_store import resolve_teardown_timeout
+from ...orchestrator.secret_store import ENV_VAR_SECRET_NAME
 from .consolidated_launch import (
     launch_consolidated,
+    persist_env_var_secret,
     teardown_consolidated,
 )
 
@@ -64,6 +69,7 @@ _GIT_HTTP_PORT = 9420
 @contextmanager
 def launch(
     plan: FirecrackerBottlePlan,
+    agent_base: Path,
     *,
     provision: Callable[[FirecrackerBottlePlan, "FirecrackerBottle"], str | None],
 ) -> Generator[FirecrackerBottle, None, None]:
@@ -85,11 +91,9 @@ def launch(
             raise teardown_exc
 
     try:
-        # Step 1: agent rootfs. Built from the Dockerfile inside a Firecracker
-        # builder VM (buildah, no host docker); a committed snapshot is reused
-        # when present. Returns the base dir the per-bottle ext4 is made from.
-        plan, agent_base = _build_agent_base(plan)
-
+        # Step 1 (rootfs resolution/build) runs in BottleBackend.launch before
+        # this context starts resources. ``agent_base`` is the selected cache,
+        # fresh build, or committed snapshot.
         # Step 2: mint the git-gate dynamic (gitea) deploy keys, if any.
         git_gate_plan = plan.git_gate_plan
         if git_gate_plan.upstreams:
@@ -112,6 +116,7 @@ def launch(
         token_values = egress_resolve_token_values(
             plan.egress_plan.token_env_map, effective_env,
         )
+        teardown_timeout = resolve_teardown_timeout()
         ctx = launch_consolidated(
             plan.egress_plan, git_gate_plan,
             guest_ip=slot.guest_ip,
@@ -121,6 +126,7 @@ def launch(
         stack.callback(
             teardown_consolidated, ctx.bottle_id,
             orchestrator_url=ctx.orchestrator_url,
+            timeout=teardown_timeout,
         )
 
         # Step 5: install the SHARED gateway CA (replaces the per-bottle CA).
@@ -149,6 +155,7 @@ def launch(
             git_gate_plan=git_gate_plan,
             egress_plan=egress_plan,
             identity_token=ctx.identity_token,
+            env_var_secret=ctx.env_var_secret,
             # Deliver the identity token as egress proxy credentials — clients
             # honor `HTTPS_PROXY=http://id:token@gw` without app changes; the
             # gateway reads Proxy-Authorization, validates the (source_ip,
@@ -164,6 +171,10 @@ def launch(
         # Step 6: build the per-bottle rootfs + SSH key, then boot.
         run_dir = util.cache_dir() / "run" / plan.slug
         run_dir.mkdir(parents=True, exist_ok=True)
+        # Remove the run dir on teardown so the per-bottle rootfs.ext4 (~1G)
+        # doesn't leak. Registered before vm.terminate below so it runs *after*
+        # it (ExitStack is LIFO): the VM is gone before we rm its rootfs.
+        stack.callback(lambda: shutil.rmtree(run_dir, ignore_errors=True))
         rootfs = run_dir / "rootfs.ext4"
         util.build_rootfs_ext4(agent_base, rootfs)
         private_key, pubkey = util.generate_keypair(run_dir)
@@ -179,6 +190,7 @@ def launch(
         )
         stack.callback(vm.terminate)
         firecracker_vm.wait_for_ssh(vm, private_key)
+        persist_env_var_secret(private_key, slot.guest_ip, ctx.env_var_secret)
 
         # Authoritative fail-closed egress-boundary check, before the agent
         # runs: prove the VM cannot reach the host directly.
@@ -206,9 +218,7 @@ def launch(
         teardown()
 
 
-def _build_agent_base(
-    plan: FirecrackerBottlePlan,
-) -> tuple[FirecrackerBottlePlan, Path]:
+def build_or_load_agent_base(plan: FirecrackerBottlePlan) -> Path:
     """Produce the agent's base rootfs dir. Primary path: build the Dockerfile
     inside a Firecracker builder VM (buildah, no host docker), smoke-testing
     the image before export. A committed snapshot (freeze/migrate) is resumed
@@ -217,13 +227,36 @@ def _build_agent_base(
     committed_tar = committed_rootfs_path(plan.slug)
     if committed and committed_tar.is_file():
         info(f"resuming from committed rootfs {committed_tar}")
-        return plan, util.build_committed_rootfs_dir(committed_tar)
-    base = image_builder.build_agent_rootfs_dir(
-        Path(plan.dockerfile_path),
+        return util.build_committed_rootfs_dir(committed_tar)
+    dockerfile = Path(plan.dockerfile_path)
+    if plan.spec.image_policy == "cached":
+        cached = image_builder.cached_agent_rootfs_dir(dockerfile)
+        if cached is None:
+            die(
+                f"cached agent rootfs for {plan.image!r} not found; "
+                "run without --cached-images to build it"
+            )
+        info(f"using cached agent rootfs {cached.name}")
+        return cached
+    return image_builder.build_agent_rootfs_dir(
+        dockerfile,
         image_tag=plan.image,
         smoke_test=runtime_for(plan.agent_provider_template).smoke_test,
     )
-    return plan, base
+
+
+def stale_checks(plan: FirecrackerBottlePlan) -> None:
+    """Raise when the cached rootfs selected by this plan is stale."""
+    if plan.spec.image_policy != "cached":
+        return
+    committed = read_committed_image(plan.slug)
+    committed_tar = committed_rootfs_path(plan.slug)
+    if committed and committed_tar.is_file():
+        check_stale_path(f"agent rootfs {committed_tar}", committed_tar)
+        return
+    cached = image_builder.cached_agent_rootfs_dir(Path(plan.dockerfile_path))
+    if cached is not None:
+        check_stale_path(f"agent rootfs {cached}", cached / ".bb-ready")
 
 
 # --- agent guest env -------------------------------------------------
@@ -239,6 +272,11 @@ def _agent_guest_env(plan: FirecrackerBottlePlan, host_ip: str) -> dict[str, str
         "HTTPS_PROXY": proxy_url, "HTTP_PROXY": proxy_url,
         "https_proxy": proxy_url, "http_proxy": proxy_url,
         "NO_PROXY": no_proxy, "no_proxy": no_proxy,
+        # Rootfs export can leave Git's implicit XDG paths unreadable even
+        # after the runtime repair. Bypass that discovery and name the
+        # provisioned global config explicitly so insteadOf can never fall
+        # through to the credential-bearing upstream URL.
+        "GIT_CONFIG_GLOBAL": f"{plan.guest_home}/.gitconfig",
         "NODE_EXTRA_CA_CERTS": AGENT_CA_PATH,
         "SSL_CERT_FILE": AGENT_CA_BUNDLE,
         "REQUESTS_CA_BUNDLE": AGENT_CA_BUNDLE,
@@ -247,6 +285,8 @@ def _agent_guest_env(plan: FirecrackerBottlePlan, host_ip: str) -> dict[str, str
         env["GIT_GATE_URL"] = plan.agent_git_gate_url
     if plan.agent_supervise_url:
         env["MCP_SUPERVISE_URL"] = plan.agent_supervise_url
+    if plan.env_var_secret:
+        env[ENV_VAR_SECRET_NAME] = plan.env_var_secret
     for entry in egress_agent_env_entries(plan.egress_plan):
         key, _, value = entry.partition("=")
         env[key] = value

bot_bottle/backend/firecracker/publish_infra.py

@@ -131,6 +131,29 @@ def build_artifact(out_dir: Path) -> tuple[str, Path, Path]:
     return version, gz, sha
 
 
+def _try_download_published(out_dir: Path) -> tuple[str, Path, Path] | None:
+    """If this version's artifact is already in the registry, download the gz
+    and sha to out_dir and return (version, gz_path, sha_path). Returns None
+    when not yet published."""
+    version = infra_artifact.infra_artifact_version(infra_vm._infra_init())
+    sha_url = infra_artifact.artifact_url(version, "rootfs.ext4.gz.sha256")
+    try:
+        with urllib.request.urlopen(infra_artifact._open(sha_url)):
+            pass
+    except urllib.error.HTTPError as e:
+        if e.code == 404:
+            return None
+        raise SystemExit(f"registry check failed (HTTP {e.code}): {sha_url}")
+    except urllib.error.URLError as e:
+        raise SystemExit(f"registry unreachable: {sha_url} ({e.reason})")
+    print(f"infra rootfs {version} already published — downloading instead of building")
+    gz = out_dir / "rootfs.ext4.gz"
+    sha = out_dir / "rootfs.ext4.gz.sha256"
+    infra_artifact._download(infra_artifact.artifact_url(version, "rootfs.ext4.gz"), gz)
+    infra_artifact._download(infra_artifact.artifact_url(version, "rootfs.ext4.gz.sha256"), sha)
+    return version, gz, sha
+
+
 def _publish_bundle(root: Path, token: str) -> str:
     version_file = root / "version.txt"
     # Guard the read so a missing version.txt is a clean error, not a raw
@@ -187,6 +210,8 @@ def main(argv: list[str] | None = None) -> int:
                       help="build a candidate bundle in DIR without publishing")
     mode.add_argument("--publish-dir", type=Path,
                       help="publish an already-built and tested candidate bundle")
+    parser.add_argument("--reuse-published", action="store_true",
+                        help="with --output: download from registry if already published instead of building")
     args = parser.parse_args(argv)
 
     _, _, token = infra_artifact._config()
@@ -197,6 +222,14 @@ def main(argv: list[str] | None = None) -> int:
 
     if args.output is not None:
         args.output.mkdir(parents=True, exist_ok=True)
+        reused = None
+        if args.reuse_published:
+            reused = _try_download_published(args.output)
+        if reused is not None:
+            version, _, _ = reused
+            (args.output / "version.txt").write_text(version + "\n", encoding="utf-8")
+            print(f"reused published infra rootfs candidate {version}")
+            return 0
         version, _gz, _sha = build_artifact(args.output)
         (args.output / "version.txt").write_text(version + "\n", encoding="utf-8")
         print(f"built infra rootfs candidate {version}")

bot_bottle/backend/firecracker/util.py

@@ -373,6 +373,12 @@ mount -o remount,rw / 2>/dev/null
 # scratch dirs there — git worktrees, build temp, `git init /tmp/...`, etc.
 mkdir -p /tmp && chmod 1777 /tmp
 
+# Rootfs export also maps the image's original owners to the unprivileged
+# host build uid. That uid is not guaranteed to be node's uid in the guest;
+# restore the home-directory boundary before any SSH provisioning runs.
+chown node:node /home/node 2>/dev/null || true
+chmod 755 /home/node 2>/dev/null || true
+
 # Install the per-bottle SSH pubkey from the kernel cmdline.
 KEY=$(sed -n 's/.*bb_pubkey=\([^ ]*\).*/\1/p' /proc/cmdline | base64 -d 2>/dev/null)
 if [ -n "$KEY" ]; then
@@ -393,6 +399,9 @@ fi
 chown -R 0:0 /root 2>/dev/null || true
 
 mkdir -p /etc/dropbear /run
+# Keep restart-recovery key material memory-backed, separate from both the
+# agent rootfs and the infra VM's persistent registry volume.
+mount -t tmpfs -o mode=0755 tmpfs /run 2>/dev/null || true
 # -R: generate host keys on demand. -E: log auth failures to stderr,
 # captured in the host-side console.log for debugging.
 /bb-dropbear -R -E -p 22 &

bot_bottle/backend/macos_container/backend.py

@@ -12,7 +12,7 @@ from ...env import ResolvedEnv
 from ...git_gate import GitGatePlan
 from ...supervise import SupervisePlan
 from ...manifest import Manifest
-from .. import ActiveAgent, BottleBackend, BottleSpec
+from .. import ActiveAgent, BottleBackend, BottleImages, BottleSpec
 from . import cleanup as _cleanup
 from . import enumerate as _enumerate
 from . import launch as _launch
@@ -31,6 +31,7 @@ class MacosContainerBottleBackend(
     `--backend=macos-container`."""
 
     name = "macos-container"
+    supports_nested_containers = True
 
     @classmethod
     def is_available(cls) -> bool:
@@ -82,11 +83,17 @@ class MacosContainerBottleBackend(
             stage_dir=stage_dir,
         )
 
+    def prelaunch_checks(self, plan: MacosContainerBottlePlan) -> None:
+        _launch.stale_checks(plan)
+
+    def _build_or_load_images(self, plan: MacosContainerBottlePlan) -> BottleImages:
+        return _launch.build_or_load_images(plan)
+
     @contextmanager
-    def launch(
-        self, plan: MacosContainerBottlePlan
+    def _launch_impl(
+        self, plan: MacosContainerBottlePlan, images: BottleImages
     ) -> Generator[MacosContainerBottle, None, None]:
-        with _launch.launch(plan, provision=self.provision) as bottle:
+        with _launch.launch(plan, images, provision=self.provision) as bottle:
             yield bottle
 
     def ensure_orchestrator(self) -> str:

bot_bottle/backend/macos_container/bottle.py

@@ -68,9 +68,14 @@ class MacosContainerBottle(Bottle):
         # reaches the agent (PRD 0070): registration mints it *after* the
         # container exists — its source IP is the registration key and Apple
         # Container assigns that by DHCP — so it cannot be in the run-time env
-        # the way docker's compose spec does it. `container exec --env` wins
-        # over the run-time value, so the token-bearing proxy URL set here
-        # supersedes the token-less one baked in at launch.
+        # the way docker's compose spec does it.
+        #
+        # `container exec --env` does NOT override a run-time value — it
+        # appends, leaving duplicate entries in the agent's `environ` whose
+        # resolution is runtime-specific (Node last-wins, Rust first-wins). So
+        # nothing here may rely on superseding: the proxy vars are supplied
+        # *only* at exec time and are deliberately absent from the run-time
+        # env. See `launch._agent_env_entries`.
         self._exec_env = dict(exec_env or {})
         self._closed = False
 

bot_bottle/backend/macos_container/bottle_plan.py

@@ -20,6 +20,12 @@ class MacosContainerBottlePlan(BottlePlan):
     # bottle is registered. See launch.py's stamp for why it lives here and not
     # only in the exec-time proxy env.
     identity_token: str = ""
+    # Guest-local container engine (issue #392). Gates the derived image, the
+    # device-mode relaxation, and the resident podman service.
+    nested_containers: bool = False
+    # Generated before `container run` so it becomes part of the container's
+    # configured environment and can be read back after an infra restart.
+    env_var_secret: str = ""
 
     @property
     def container_name(self) -> str:

bot_bottle/backend/macos_container/consolidated_launch.py

@@ -36,8 +36,16 @@ from dataclasses import dataclass
 
 from ...egress import EgressPlan
 from ...git_gate import GitGatePlan
-from ...orchestrator.client import OrchestratorClient
-from ..consolidated_util import provision_bottle, teardown_consolidated as _teardown_util
+from ...log import info
+from ...orchestrator.client import OrchestratorClient, OrchestratorClientError
+from ...orchestrator.reprovision import reprovision_bottles
+from ...orchestrator.secret_store import ENV_VAR_SECRET_NAME
+from ..consolidated_util import (
+    provision_bottle,
+    teardown_consolidated as _teardown_util,
+)
+from . import util as container_mod
+from .enumerate import CONTAINER_NAME_PREFIX, EnumerationError, enumerate_active
 from .gateway import GATEWAY_NETWORK
 from .gateway_provision import AppleGatewayTransport
 from .infra import MacosInfraService, OrchestratorStartError
@@ -69,6 +77,7 @@ class LaunchContext:
     gateway_ip: str
     network: str
     orchestrator_url: str
+    env_var_secret: str = ""  # encryption key injected into the agent's env
 
 
 def ensure_gateway(
@@ -80,12 +89,61 @@ def ensure_gateway(
     needs `gateway_ip` at run time."""
     service = service or MacosInfraService()
     infra = service.ensure_running()
-    return GatewayEndpoint(
+    endpoint = GatewayEndpoint(
         orchestrator_url=infra.control_plane_url,
         gateway_ip=infra.gateway_ip,
         gateway_ca_pem=service.ca_cert_pem(),
         network=service.network,
     )
+    _reprovision_running_bottles(endpoint)
+    return endpoint
+
+
+def _reprovision_running_bottles(endpoint: GatewayEndpoint) -> None:
+    """Recover keys from live Apple containers and restore gateway tokens."""
+    try:
+        secrets_by_ip: dict[str, str] = {}
+        for agent in enumerate_active():
+            name = f"{CONTAINER_NAME_PREFIX}{agent.slug}"
+            source_ip = container_mod.inspect_container_network_ip(name, endpoint.network)
+            if not source_ip:
+                continue
+            secret = container_mod.read_container_env(name, ENV_VAR_SECRET_NAME)
+            if secret:
+                secrets_by_ip[source_ip] = secret
+        count = reprovision_bottles(
+            OrchestratorClient(endpoint.orchestrator_url), secrets_by_ip,
+        )
+        if count:
+            info(f"reprovisioned egress tokens for {count} macOS bottle(s)")
+    except (OrchestratorClientError, EnumerationError, OSError) as exc:
+        info(f"egress token reprovision skipped: {exc}")
+
+
+def live_source_ips(network: str) -> list[str]:
+    """Every running agent container's address on `network`.
+
+    The reconciliation input: the orchestrator lives inside the infra
+    container and cannot enumerate the host's containers, so the host has to
+    tell it which bottles are actually up. Containers that have not been
+    assigned an address yet contribute nothing — the reap's grace window, not
+    this list, is what protects an in-flight launch.
+
+    Raises `EnumerationError` when the live set cannot be determined
+    authoritatively: either the container listing fails or any individual
+    inspect fails. Callers must skip reconciliation in that case to avoid
+    unregistering healthy bottles."""
+    ips: list[str] = []
+    for agent in enumerate_active():
+        name = f"{CONTAINER_NAME_PREFIX}{agent.slug}"
+        ip = container_mod.inspect_container_network_ip(name, network)
+        if ip is None:
+            raise EnumerationError(
+                f"container inspect {name!r} failed; live set is not authoritative"
+            )
+        if ip:
+            ips.append(ip)
+    return ips
 
 
 def register_agent(
@@ -96,15 +154,27 @@ def register_agent(
     endpoint: GatewayEndpoint,
     image_ref: str = "",
     tokens: dict[str, str] | None = None,
+    env_var_secret: str | None = None,
 ) -> LaunchContext:
     """Register the (already running) agent by its address and provision its
     git-gate state into the gateway. `source_ip` must be read from the live
     container — it is the attribution key the gateway resolves policy by.
     Raises on failure; the caller tears down."""
     client = OrchestratorClient(endpoint.orchestrator_url)
+    # Self-heal before registering: a launcher that died hard (SIGKILL, closed
+    # terminal, host sleep) never ran its teardown callback, leaving an active
+    # row with no container. vmnet recycles addresses, so such a row can
+    # collide with this bottle's — and `by_source_ip` fail-closes on ambiguity,
+    # which would resolve no policy at all and deny every host. Best-effort: a
+    # reconciliation failure must not block an otherwise-fine launch.
+    try:
+        client.reconcile(live_source_ips(endpoint.network))
+    except (OrchestratorClientError, EnumerationError) as e:
+        info(f"registry reconciliation skipped: {e}")
     reg = provision_bottle(
         client, source_ip, egress_plan, git_gate_plan, AppleGatewayTransport(),
         image_ref=image_ref, tokens=tokens,
+        env_var_secret=env_var_secret,
     )
     return LaunchContext(
         bottle_id=reg.bottle_id,
@@ -113,20 +183,25 @@ def register_agent(
         gateway_ip=endpoint.gateway_ip,
         network=endpoint.network,
         orchestrator_url=endpoint.orchestrator_url,
+        env_var_secret=reg.env_var_secret,
     )
 
 
-def teardown_consolidated(bottle_id: str, *, orchestrator_url: str) -> None:
+def teardown_consolidated(
+    bottle_id: str, *, orchestrator_url: str, timeout: float | None = None,
+) -> None:
     """Deregister the bottle and remove its git-gate state from the gateway.
     Both steps are idempotent so this is safe from a cleanup trap. Does NOT
     stop the gateway — it's a persistent per-host singleton."""
-    _teardown_util(bottle_id, AppleGatewayTransport(), orchestrator_url=orchestrator_url)
+    _teardown_util(bottle_id, AppleGatewayTransport(),
+                   orchestrator_url=orchestrator_url, timeout=timeout)
 
 
 __all__ = [
     "GatewayEndpoint",
     "LaunchContext",
     "ensure_gateway",
+    "live_source_ips",
     "register_agent",
     "teardown_consolidated",
     "ConsolidatedLaunchError",

bot_bottle/backend/macos_container/enumerate.py

@@ -8,13 +8,21 @@ from ...bottle_state import read_metadata
 from .. import ActiveAgent
 from .infra import INFRA_NAME
 
-_PREFIX = "bot-bottle-"
+# The name every agent container carries: `bot-bottle-<slug>`. Exported
+# because callers that act on a running bottle (gateway-host rewrites,
+# registry reconciliation) have to map an enumerated slug back to a
+# container name.
+CONTAINER_NAME_PREFIX = "bot-bottle-"
 # The shared per-host infra container carries the same prefix as agent
 # containers but is infrastructure, not a bottle — one control plane + gateway
 # serves every agent, so listing it as an agent would invent one per host.
 _INFRA_NAMES = frozenset({INFRA_NAME})
 
 
+class EnumerationError(RuntimeError):
+    """container list failed; the resulting live set is not authoritative."""
+
+
 def enumerate_active() -> list[ActiveAgent]:
     result = subprocess.run(
         ["container", "list", "--quiet"],
@@ -23,12 +31,15 @@ def enumerate_active() -> list[ActiveAgent]:
         check=False,
     )
     if result.returncode != 0:
-        return []
+        raise EnumerationError(
+            f"container list failed: "
+            f"{(result.stderr or '').strip() or '<no stderr>'}"
+        )
     out: list[ActiveAgent] = []
     for name in sorted(line.strip() for line in result.stdout.splitlines()):
-        if not name.startswith(_PREFIX) or name in _INFRA_NAMES:
+        if not name.startswith(CONTAINER_NAME_PREFIX) or name in _INFRA_NAMES:
             continue
-        slug = name[len(_PREFIX):]
+        slug = name[len(CONTAINER_NAME_PREFIX):]
         metadata = read_metadata(slug)
         out.append(ActiveAgent(
             backend_name="macos-container",

bot_bottle/backend/macos_container/gateway_hosts.py

@@ -0,0 +1,96 @@
+"""Stable gateway name for macOS agents, via each bottle's `/etc/hosts`.
+
+The shared gateway's address is assigned by vmnet's DHCP and changes whenever
+the infra container is recreated — a source-hash bump, an image upgrade, a
+crash. Every agent-facing URL (egress proxy, git-http, supervise) embeds that
+address, and the proxy URL reaches the agent as **process environment** at
+`container exec` time. A running process's `environ` cannot be rewritten from
+outside, so a moved gateway used to strand every running bottle permanently:
+not degraded, unreachable, until the bottle was relaunched and its session
+thrown away.
+
+So the agent never learns the address. It is given a stable *name*
+(`GATEWAY_HOSTNAME`) in every URL, resolved through its own `/etc/hosts`.
+Unlike `environ`, that is a file — it can be rewritten inside a container that
+is already running, so a gateway that comes back at a new address is picked up
+by live bottles instead of orphaning them.
+
+Apple Container 1.0 offers no container-name DNS on a user network (the only
+nameserver an agent sees is vmnet's, which does not know container names) and
+`container run` has no `--add-host`, so the entry is written by exec after the
+container starts.
+
+Writing it needs root, and the agent runs as `node`: the agent therefore
+cannot repoint its own gateway name, while the host (which drives `container
+exec --user root`) can. That asymmetry is deliberate — keep it.
+"""
+
+from __future__ import annotations
+
+from ...log import warn
+from . import util as container_mod
+from .enumerate import CONTAINER_NAME_PREFIX, enumerate_active
+
+# The name every agent-facing gateway URL uses. Must not collide with a real
+# DNS name the agent might resolve; it is bottle-local by construction.
+GATEWAY_HOSTNAME = "bot-bottle-gateway"
+
+# Marker so the rewrite is idempotent and only ever touches our own line —
+# the rest of /etc/hosts (localhost, the container's own name) is preserved.
+_MARKER = "# bot-bottle gateway"
+
+
+def _rewrite_script(gateway_ip: str) -> str:
+    """A shell one-liner that replaces our managed line in `/etc/hosts`.
+
+    Rewrites in place via a temp file + `cat` rather than `mv`, so the file
+    keeps its original inode, ownership, and mode — a bind-mounted or
+    pre-created `/etc/hosts` must not be replaced by a root-owned 0644 copy
+    that the runtime then refuses to update.
+    """
+    return (
+        "set -e; "
+        f"grep -v '{_MARKER}' /etc/hosts > /tmp/.bb-hosts || true; "
+        f"printf '%s %s %s\\n' '{gateway_ip}' '{GATEWAY_HOSTNAME}' "
+        f"'{_MARKER}' >> /tmp/.bb-hosts; "
+        "cat /tmp/.bb-hosts > /etc/hosts; "
+        "rm -f /tmp/.bb-hosts"
+    )
+
+
+def set_gateway_host(container_name: str, gateway_ip: str) -> None:
+    """Point `GATEWAY_HOSTNAME` at `gateway_ip` inside one running container.
+
+    Must run before the agent is exec'd: the agent's proxy URL names the
+    gateway, so the entry has to exist for its first connection. Idempotent —
+    re-running with the same address is a no-op in effect.
+    """
+    container_mod.exec_container_as_root(
+        container_name, ["sh", "-c", _rewrite_script(gateway_ip)],
+    )
+
+
+def refresh_gateway_host(gateway_ip: str) -> list[str]:
+    """Re-point every running bottle at the current gateway address.
+
+    Called once the shared gateway is known to be up, so a bottle stranded by
+    an earlier gateway restart re-attaches instead of needing a relaunch.
+    Returns the containers updated.
+
+    Best-effort per bottle: one container that refuses the write (already
+    exiting, say) must not stop the others from being repaired, and must not
+    fail the launch that triggered the sweep.
+    """
+    updated: list[str] = []
+    for agent in enumerate_active():
+        name = f"{CONTAINER_NAME_PREFIX}{agent.slug}"
+        try:
+            set_gateway_host(name, gateway_ip)
+            updated.append(name)
+        # One bad bottle must not stop the sweep, so this is deliberately broad.
+        except Exception as e:  # noqa: BLE001  # pylint: disable=broad-exception-caught
+            warn(f"could not re-point {name} at the gateway: {e}")
+    return updated
+
+
+__all__ = ["GATEWAY_HOSTNAME", "set_gateway_host", "refresh_gateway_host"]

bot_bottle/backend/macos_container/infra.py

@@ -41,7 +41,7 @@ from dataclasses import dataclass
 from pathlib import Path
 
 from ... import log
-from ...orchestrator.gateway import GATEWAY_CA_CERT
+from ...orchestrator.gateway import GATEWAY_CA_CERT, MITMPROXY_HOME
 from ...orchestrator.lifecycle import (
     DEFAULT_PORT,
     DEFAULT_STARTUP_TIMEOUT_SECONDS,
@@ -52,7 +52,9 @@ from ...paths import (
     CONTROL_PLANE_TOKEN_ENV,
     HOST_DB_FILENAME,
     host_control_plane_token,
+    host_gateway_ca_dir,
 )
+from .. import util as backend_util
 from . import util as container_mod
 from .gateway import (
     DEFAULT_CA_TIMEOUT_SECONDS,
@@ -217,6 +219,14 @@ class MacosInfraService:
             # Container-only DB volume: one kernel writes bot-bottle.db, never
             # shared with the host or another guest.
             "--volume", f"{self._db_volume}:{_DB_ROOT_IN_CONTAINER}",
+            # The DB needs a container-only ext4 volume for coherent SQLite
+            # locking, but the CA has no such constraint. Keep it in the host
+            # app-data root so infra-container recreation and Apple Container
+            # volume pruning cannot silently rotate every bottle's trust
+            # anchor (issue #450).
+            "--mount",
+            container_mod.bind_mount_spec(
+                str(host_gateway_ca_dir()), MITMPROXY_HOME),
             # Bind-mount the control-plane source (read-only); a code change
             # takes effect on relaunch with no image rebuild.
             "--mount",
@@ -260,21 +270,19 @@ class MacosInfraService:
 
     def ca_cert_pem(self, *, timeout: float = DEFAULT_CA_TIMEOUT_SECONDS) -> str:
         """The gateway's mitmproxy CA (PEM) agents install to trust its TLS
-        interception. Read out of the container (the CA lives on a
-        container-internal path, not a host mount); polls because mitmproxy
-        writes it a beat after start."""
-        deadline = time.monotonic() + timeout
-        while True:
+        interception. Read through the container path backed by the persistent
+        host CA directory; polls because mitmproxy writes it a beat after
+        start."""
+        def _fetch() -> str | None:
             result = container_mod.run_container_argv(
                 ["container", "exec", self._name, "cat", GATEWAY_CA_CERT])
-            if result.returncode == 0 and result.stdout.strip():
-                return result.stdout
-            if time.monotonic() >= deadline:
-                raise GatewayError(
-                    f"gateway CA not available in {self._name} after {timeout:g}s: "
-                    f"{(result.stderr or '').strip() or 'empty'}"
-                )
-            time.sleep(_CA_POLL_SECONDS)
+            return result.stdout if result.returncode == 0 and result.stdout.strip() else None
+        try:
+            return backend_util.poll_ca_cert(_fetch, timeout=timeout)
+        except TimeoutError as exc:
+            raise GatewayError(
+                f"gateway CA not available in {self._name} after {timeout:g}s"
+            ) from exc
 
     def stop(self) -> None:
         """Remove the infra container (idempotent). The DB volume persists."""

bot_bottle/backend/macos_container/launch.py

@@ -53,13 +53,23 @@ from ...git_gate import (
     revoke_git_gate_provisioned_keys,
 )
 from ...git_http_backend import DEFAULT_PORT as _GIT_HTTP_PORT
+from ...image_cache import check_stale
 from ...log import die, info, warn
+from .. import BottleImages
 from ...supervise import SUPERVISE_PORT
 from ..docker.egress import EGRESS_PORT
 from ..util import AGENT_CA_BUNDLE, AGENT_CA_PATH
 from . import util as container_mod
 from .bottle import MacosContainerBottle
+from .gateway_hosts import (
+    GATEWAY_HOSTNAME,
+    refresh_gateway_host,
+    set_gateway_host,
+)
+from . import nested_containers as nested_containers_mod
 from .bottle_plan import MacosContainerBottlePlan
+from ...orchestrator.config_store import resolve_teardown_timeout
+from ...orchestrator.secret_store import ENV_VAR_SECRET_NAME, new_env_var_secret
 from .consolidated_launch import (
     GatewayEndpoint,
     ensure_gateway,
@@ -71,18 +81,69 @@ _REPO_DIR = str(Path(__file__).resolve().parent.parent.parent.parent)
 _AGENT_SLEEP_SECONDS = "2147483647"
 
 
+def build_or_load_images(plan: MacosContainerBottlePlan) -> BottleImages:
+    """Resolve the agent image ref for this plan. The gateway's own image is
+    built by `ensure_gateway` — it belongs to the shared singleton."""
+    return BottleImages(agent=_layer_nested_containers(plan, _agent_image(plan)))
+
+
+def _agent_image(plan: MacosContainerBottlePlan) -> str:
+    committed = read_committed_image(plan.slug)
+    if committed and container_mod.image_exists(committed):
+        info(f"using committed image {committed!r}")
+        return committed
+    if plan.spec.image_policy == "cached":
+        if not container_mod.image_exists(plan.image):
+            die(
+                f"cached agent image {plan.image!r} not found; "
+                "run without --cached-images to build it"
+            )
+        info(f"using cached agent image {plan.image!r}")
+        return plan.image
+    container_mod.build_image(plan.image, _REPO_DIR, dockerfile=plan.dockerfile_path)
+    return plan.image
+
+
+def _layer_nested_containers(
+    plan: MacosContainerBottlePlan, agent_image: str,
+) -> str:
+    """Add the guest-local container tooling on top of the agent image.
+
+    A separate derived tag, not the provider Dockerfile, so bottles that never
+    ask for nested containers carry none of its weight.
+    """
+    if not plan.nested_containers:
+        return agent_image
+    derived = f"{agent_image}{nested_containers_mod.IMAGE_SUFFIX}"
+    if plan.spec.image_policy == "cached":
+        if not container_mod.image_exists(derived):
+            die(
+                f"cached nested-container image {derived!r} not found; "
+                "run without --cached-images to build it"
+            )
+        info(f"using cached nested-container image {derived!r}")
+        return derived
+    return nested_containers_mod.build_image(agent_image, container_mod.build_image)
+
+
 @contextmanager
 def launch(
     plan: MacosContainerBottlePlan,
+    images: BottleImages,
     *,
     provision: Callable[[MacosContainerBottlePlan, "MacosContainerBottle"], str | None],
 ) -> Generator[MacosContainerBottle, None, None]:
-    """Build, run, register, provision, and yield an Apple Container bottle on
-    the shared per-host gateway."""
+    """Run, register, provision, and yield an Apple Container bottle on the
+    shared per-host gateway."""
     stack = ExitStack()
     bottle_for_revoke = plan.manifest.bottle
     git_gate_dir_for_revoke = git_gate_state_dir(plan.slug)
 
+    plan = dataclasses.replace(
+        plan,
+        agent_provision=dataclasses.replace(plan.agent_provision, image=str(images.agent)),
+    )
+
     def teardown() -> None:
         teardown_exc: BaseException | None = None
         try:
@@ -95,17 +156,21 @@ def launch(
             raise teardown_exc
 
     try:
-        plan = _build_images(plan)
-
         # Step 1: the per-host singletons. Must precede the agent run — its
         # proxy env needs the gateway's address at `container run` time.
         endpoint = ensure_gateway()
+        # The gateway's address may have changed since these bottles launched
+        # (any infra recreate re-runs DHCP). They name the gateway rather than
+        # address it, so re-pointing /etc/hosts re-attaches them in place
+        # instead of leaving them stranded until relaunch.
+        refresh_gateway_host(endpoint.gateway_ip)
 
         # Step 2: mint this bottle's deploy keys, then point it at the SHARED
         # gateway's CA + git-http/supervise ports.
         plan = _provision_git_gate_keys(plan)
         plan = _install_gateway_ca(plan, endpoint)
         plan = _stamp_agent_urls(plan, endpoint)
+        plan = dataclasses.replace(plan, env_var_secret=new_env_var_secret())
 
         # Step 3: run the agent. It has no identity token yet — registration
         # needs the address this run assigns.
@@ -117,6 +182,9 @@ def launch(
         # attribution key; `--cap-drop CAP_NET_RAW` at run is what makes it
         # unforgeable. Poll: `container run --detach` can return before vmnet's
         # DHCP has assigned the address.
+        # Resolve the gateway name before anything execs: every agent-facing
+        # URL uses it, so the entry must exist for the first connection.
+        set_gateway_host(plan.container_name, endpoint.gateway_ip)
         source_ip = container_mod.wait_container_ipv4_on_network(
             plan.container_name, endpoint.network,
         )
@@ -129,6 +197,7 @@ def launch(
         token_values = egress_resolve_token_values(
             plan.egress_plan.token_env_map, effective_env,
         )
+        teardown_timeout = resolve_teardown_timeout()
         ctx = register_agent(
             plan.egress_plan,
             plan.git_gate_plan,
@@ -136,10 +205,12 @@ def launch(
             endpoint=endpoint,
             image_ref=plan.image,
             tokens=token_values,
+            env_var_secret=plan.env_var_secret,
         )
         stack.callback(
             teardown_consolidated, ctx.bottle_id,
             orchestrator_url=ctx.orchestrator_url,
+            timeout=teardown_timeout,
         )
         info(
             f"agent {plan.container_name} registered "
@@ -155,6 +226,10 @@ def launch(
         # token above, so — unlike the run-time env — the plan CAN carry it.
         plan = dataclasses.replace(plan, identity_token=ctx.identity_token)
 
+        exec_env = {
+            **_identity_proxy_env(endpoint, ctx.identity_token),
+            **nested_containers_mod.guest_env(plan.nested_containers),
+        }
         bottle = MacosContainerBottle(
             plan.container_name,
             teardown,
@@ -168,31 +243,38 @@ def launch(
             ),
             terminal_color=plan.spec.color,
             agent_workdir=plan.workspace_plan.workdir,
-            exec_env=_identity_proxy_env(endpoint, ctx.identity_token),
+            exec_env=exec_env,
         )
         bottle.prompt_path = provision(plan, bottle)
 
+        if plan.nested_containers:
+            nested_containers_mod.prepare_guest_devices(
+                plan.container_name, container_mod.exec_container_as_root,
+            )
+            nested_containers_mod.start(bottle)
+
         yield bottle
     finally:
         teardown()
 
 
-def _build_images(plan: MacosContainerBottlePlan) -> MacosContainerBottlePlan:
-    """Build the agent image. The gateway's own image is built by
-    `ensure_gateway` — it belongs to the shared singleton, not to a bottle."""
+
+def stale_checks(plan: MacosContainerBottlePlan) -> None:
+    """Raise StaleImageError if a cached image is older than the configured
+    threshold. Only runs when image_policy is 'cached'. Called by the backend
+    class's _image_stale_checks before _launch_impl starts any resources."""
+    if plan.spec.image_policy != "cached":
+        return
     committed = read_committed_image(plan.slug)
     if committed and container_mod.image_exists(committed):
-        info(f"using committed image {committed!r}")
-        return dataclasses.replace(
-            plan,
-            agent_provision=dataclasses.replace(
-                plan.agent_provision, image=committed,
-            ),
-        )
-    container_mod.build_image(
-        plan.image, _REPO_DIR, dockerfile=plan.dockerfile_path,
-    )
-    return plan
+        ts = container_mod.image_created_at(committed)
+        if ts is not None:
+            check_stale(f"agent image {committed!r}", ts)
+        return
+    if container_mod.image_exists(plan.image):
+        ts = container_mod.image_created_at(plan.image)
+        if ts is not None:
+            check_stale(f"agent image {plan.image!r}", ts)
 
 
 def _provision_git_gate_keys(
@@ -231,13 +313,20 @@ def _stamp_agent_urls(
 ) -> MacosContainerBottlePlan:
     """Point the agent's git-gate insteadOf rewrites + supervise MCP at the
     shared gateway's ports. Both bypass the egress proxy (NO_PROXY covers the
-    gateway address)."""
+    gateway name).
+
+    Addressed by `GATEWAY_HOSTNAME`, never by IP: these URLs are baked into
+    the agent's gitconfig and MCP config at provision time, so an address here
+    would strand the bottle the moment the gateway moved. The name is resolved
+    per connection through `/etc/hosts`, which stays rewritable while the
+    bottle runs."""
+    del endpoint  # addressed by name; the address reaches the bottle via /etc/hosts
     git_gate_url = (
-        f"http://{endpoint.gateway_ip}:{_GIT_HTTP_PORT}"
+        f"http://{GATEWAY_HOSTNAME}:{_GIT_HTTP_PORT}"
         if plan.git_gate_plan.upstreams else ""
     )
     supervise_url = (
-        f"http://{endpoint.gateway_ip}:{SUPERVISE_PORT}/"
+        f"http://{GATEWAY_HOSTNAME}:{SUPERVISE_PORT}/"
         if plan.supervise_plan is not None else ""
     )
     return dataclasses.replace(
@@ -247,30 +336,43 @@ def _stamp_agent_urls(
     )
 
 
-def _proxy_url(gateway_ip: str, identity_token: str = "") -> str:
+def _proxy_url(identity_token: str = "") -> str:
     """The agent's egress proxy URL. The identity token rides as proxy
     credentials — the gateway reads Proxy-Authorization, resolves the
     (source_ip, token) pair against the control plane, and strips it before
-    upstream. Without a valid pair `/resolve` denies the request (#366)."""
+    upstream. Without a valid pair `/resolve` denies the request (#366).
+
+    Names the gateway rather than addressing it: this URL reaches the agent as
+    process environment, which cannot be rewritten once the agent is running,
+    so an address baked here is unfixable if the gateway moves."""
     cred = f"bottle:{identity_token}@" if identity_token else ""
-    return f"http://{cred}{gateway_ip}:{EGRESS_PORT}"
+    return f"http://{cred}{GATEWAY_HOSTNAME}:{EGRESS_PORT}"
 
 
-def _no_proxy(gateway_ip: str) -> str:
+def _no_proxy() -> str:
     # git-http + supervise live on the gateway and must NOT go through the
-    # egress proxy — the agent reaches them directly by its address.
-    return f"localhost,127.0.0.1,{gateway_ip}"
+    # egress proxy — the agent reaches them directly by name. Deliberately
+    # address-free: NO_PROXY is baked into the run-time env and is therefore
+    # just as unfixable as the proxy URL if the gateway moves.
+    return f"localhost,127.0.0.1,{GATEWAY_HOSTNAME}"
 
 
 def _identity_proxy_env(
     endpoint: GatewayEndpoint, identity_token: str,
 ) -> dict[str, str]:
-    """The token-bearing proxy env applied at `container exec`. It supersedes
-    the token-less run-time value (exec `--env` wins), which is the only way to
-    get the token in: it does not exist until after the container runs."""
+    """The token-bearing proxy env applied at `container exec` — the only way
+    to get the token in, since it does not exist until after the container
+    runs (registration keys on the DHCP-assigned address).
+
+    This is the *sole* source of `*_PROXY` for the agent. It deliberately does
+    not rely on overriding a run-time value: `container exec --env` appends
+    rather than replaces, so a run-time `HTTPS_PROXY` would survive alongside
+    this one and first-wins runtimes would read the wrong entry. See
+    `_agent_env_entries`."""
     if not identity_token:
         return {}
-    url = _proxy_url(endpoint.gateway_ip, identity_token)
+    del endpoint  # the gateway is named, not addressed
+    url = _proxy_url(identity_token)
     return {
         "HTTPS_PROXY": url, "HTTP_PROXY": url,
         "https_proxy": url, "http_proxy": url,
@@ -317,16 +419,23 @@ def _agent_run_argv(
 def _agent_env_entries(
     plan: MacosContainerBottlePlan, endpoint: GatewayEndpoint,
 ) -> tuple[str, ...]:
-    # Token-less at run time — the token does not exist yet (see
-    # `_identity_proxy_env`). Anything egressing before the exec-time override
-    # is denied by `/resolve`, which is the safe direction.
-    proxy_url = _proxy_url(endpoint.gateway_ip)
-    no_proxy = _no_proxy(endpoint.gateway_ip)
+    # No `*_PROXY` here on purpose. The token-bearing URL is applied at
+    # `container exec` (`_identity_proxy_env`), and Apple's `container exec
+    # --env` **appends** to the run-time environment rather than replacing it:
+    # setting a token-less value here leaves two `HTTPS_PROXY` entries in the
+    # agent's `environ`, token-less first. Which one a runtime reads is then
+    # pure luck — Node takes the last (and worked), Rust's `std::env::var`
+    # takes the first, so Codex proxied without its identity token and
+    # `/resolve` fail-closed on every request.
+    #
+    # A token-less proxy URL has no legitimate consumer anyway: the init
+    # process is `sleep` and everything that egresses arrives via exec. Its
+    # only value was a tidy 403 for unattributed callers, which is not worth
+    # silently dropping attribution for. Without it a process that egresses
+    # before the exec-time env still fails closed — the agent network is
+    # host-only, so there is no route off it except the gateway.
+    no_proxy = _no_proxy()
     env = [
-        f"HTTPS_PROXY={proxy_url}",
-        f"HTTP_PROXY={proxy_url}",
-        f"https_proxy={proxy_url}",
-        f"http_proxy={proxy_url}",
         f"NO_PROXY={no_proxy}",
         f"no_proxy={no_proxy}",
         f"NODE_EXTRA_CA_CERTS={AGENT_CA_PATH}",
@@ -337,6 +446,8 @@ def _agent_env_entries(
         env.append(f"GIT_GATE_URL={plan.agent_git_gate_url}")
     if plan.agent_supervise_url:
         env.append(f"MCP_SUPERVISE_URL={plan.agent_supervise_url}")
+    if getattr(plan, "env_var_secret", ""):
+        env.append(f"{ENV_VAR_SECRET_NAME}={plan.env_var_secret}")
     for name, value in sorted(plan.agent_provision.guest_env.items()):
         env.append(f"{name}={value}")
     # Forwarded vars: bare name → inherits from the `container run` process env

bot_bottle/backend/macos_container/nested-containers-init.sh

@@ -0,0 +1,210 @@
+#!/bin/sh
+set -eu
+
+uid="$(id -u)"
+if [ "$uid" -eq 0 ]; then
+    echo "refusing to run the guest container engine as root" >&2
+    exit 1
+fi
+
+# Every piece of podman 5's networking stack is checked here, because each
+# one fails at a different and misleading layer if it is absent: no pasta and
+# nothing starts at all; no nft and netavark cannot build the bridge every
+# compose file expects; no aardvark-dns and DNS inside nested containers fails
+# while everything else looks healthy.
+for command in podman docker fuse-overlayfs pasta nft slirp4netns; do
+    command -v "$command" >/dev/null 2>&1 || {
+        echo "missing nested-container prerequisite: $command" >&2
+        exit 1
+    }
+done
+
+# The inverse of the rootless-Docker check, and the whole point of the podman
+# variant: a subordinate range would push podman onto newuidmap, which cannot
+# write a multi-range uid_map without CAP_SYS_ADMIN in this guest.  An empty
+# range keeps it on the single-UID self-mapping an unprivileged process may
+# write itself.
+if grep -q "^$(id -un):" /etc/subuid 2>/dev/null; then
+    echo "unexpected subordinate UID range for $(id -un): podman would" >&2
+    echo "require CAP_SYS_ADMIN via newuidmap in this guest" >&2
+    exit 1
+fi
+
+for device in /dev/fuse /dev/net/tun; do
+    [ -r "$device" ] && [ -w "$device" ] || {
+        echo "device $device is not readable/writable by $(id -un)" >&2
+        exit 1
+    }
+done
+
+# Short by necessity, not by accident: conmon's attach socket lives under
+# this directory and must fit in a 108-byte sun_path. See nested_containers.py.
+# Must stay in step with AGENT_CA_BUNDLE in bot_bottle/backend/util.py; a unit
+# test pins the two together.
+CA_BUNDLE="/etc/ssl/certs/ca-certificates.crt"
+[ -r "$CA_BUNDLE" ] || {
+    echo "gateway CA bundle $CA_BUNDLE is missing or unreadable" >&2
+    exit 1
+}
+
+# The proxy URL the agent inherits names `bot-bottle-gateway`, which resolves
+# only through this bottle's /etc/hosts. A nested container gets its own hosts
+# file, so it cannot resolve the name and dies at "Could not resolve proxy".
+#
+# podman's containers.conf `hosts_file` would fix that, except the
+# Docker-compatible API ignores it — it only takes effect for native
+# `podman run`, and the agent types `docker`. So the name is resolved *here*
+# and the address, not the name, goes into the proxy URL the nested container
+# receives. Verified on macOS 26 / podman 5.4.2: with the address in place,
+# https://quay.io returns 200 and a non-allowlisted host still gets 403, so
+# the egress boundary applies inside nested containers too.
+GATEWAY_NAME="bot-bottle-gateway"
+gateway_ip="$(
+    awk -v name="$GATEWAY_NAME" '$2 == name { print $1; exit }' /etc/hosts
+)"
+[ -n "$gateway_ip" ] || {
+    echo "no /etc/hosts entry for $GATEWAY_NAME; the gateway address is" >&2
+    echo "needed so nested containers can reach the egress proxy" >&2
+    exit 1
+}
+
+export XDG_RUNTIME_DIR="${XDG_RUNTIME_DIR:-/tmp/bbp}"
+config="$HOME/.config/containers"
+mkdir -p "$XDG_RUNTIME_DIR" "$config"
+chmod 700 "$XDG_RUNTIME_DIR"
+
+# ignore_chown_errors is required, not incidental: with a single-UID mapping
+# there is no second UID for image layers to be chowned to, so layers that
+# record other owners would otherwise fail to extract.
+cat > "$config/storage.conf" <<'CONF'
+[storage]
+driver="overlay"
+[storage.options.overlay]
+mount_program="/usr/bin/fuse-overlayfs"
+ignore_chown_errors="true"
+CONF
+
+# No cgroup delegation reaches this guest, so asking podman to manage cgroups
+# fails; events_logger=file avoids the journald socket that is equally absent.
+#
+# The rest of this config is what lets a nested container reach the network:
+#
+#   hosts_file   only takes effect for native `podman run` — the
+#                Docker-compatible API ignores it, and the agent types
+#                `docker`. Kept anyway because it costs nothing and makes
+#                podman-native use behave; the compat path is covered by the
+#                address-bearing proxy URL below.
+#   volumes/env  the gateway TLS-intercepts, so a container that does not
+#                trust the bottle's CA bundle gets "unable to get local issuer
+#                certificate". Mounting the bundle read-only and pointing the
+#                usual env vars at it covers curl, wget, python, and node
+#                without distro-specific trust commands.
+#
+# The proxy URL carries the bottle's identity token. podman already forwards
+# that same URL into every nested container from the agent's own environment,
+# so writing it to a 0600 file inside this disposable VM hands it to nobody
+# new. It is never echoed.
+CA_BUNDLE="$CA_BUNDLE" GATEWAY_NAME="$GATEWAY_NAME" GATEWAY_IP="$gateway_ip" \
+CONTAINERS_CONF="$config/containers.conf" python3 - <<'PY'
+import os
+from pathlib import Path
+
+ca = os.environ["CA_BUNDLE"]
+name = os.environ["GATEWAY_NAME"]
+ip = os.environ["GATEWAY_IP"]
+
+entries = [
+    f"SSL_CERT_FILE={ca}",
+    f"CURL_CA_BUNDLE={ca}",
+    f"REQUESTS_CA_BUNDLE={ca}",
+    f"NODE_EXTRA_CA_CERTS={ca}",
+]
+# The gateway name resolves only through the bottle's /etc/hosts, which a
+# nested container does not inherit, so hand it the address instead.
+for var in ("HTTP_PROXY", "HTTPS_PROXY", "http_proxy", "https_proxy"):
+    value = os.environ.get(var)
+    if value:
+        entries.append(f"{var}={value.replace(name, ip)}")
+# NO_PROXY keeps the name: it is matched against what a client asks for, and
+# code inside a nested container still says "bot-bottle-gateway".
+for var in ("NO_PROXY", "no_proxy"):
+    value = os.environ.get(var)
+    if value:
+        entries.append(f"{var}={value}")
+
+path = Path(os.environ["CONTAINERS_CONF"])
+path.write_text("\n".join([
+    "[containers]",
+    'cgroups="disabled"',
+    # podman copies the host's proxy vars into every container by default,
+    # and that copy *wins* over the env below — putting the unresolvable
+    # gateway name back. Turn it off so the address-bearing URLs stand.
+    "http_proxy=false",
+    'hosts_file="/etc/hosts"',
+    f'volumes=["{ca}:{ca}:ro"]',
+    "env=[",
+    *[f'  "{entry}",' for entry in entries],
+    "]",
+    "[engine]",
+    'cgroup_manager="cgroupfs"',
+    'events_logger="file"',
+    "",
+]), encoding="utf-8")
+path.chmod(0o600)
+PY
+
+# Registry pulls egress through the bottle's proxy like everything else. The
+# token-bearing proxy URL is already in the agent's environment; persisting it
+# inside this disposable VM does not broaden its authority.
+#
+# This file is also what the Docker CLI copies into every container it starts,
+# and being client-side it beats anything the podman service does — it is why
+# containers.conf `env`, `http_proxy=false`, and the service's own environment
+# all failed to change what a nested container saw. The address goes in here
+# for the same reason it goes everywhere else: `bot-bottle-gateway` resolves
+# in the bottle, never inside a nested container.
+GATEWAY_NAME="$GATEWAY_NAME" GATEWAY_IP="$gateway_ip" python3 - <<'PY'
+import json
+import os
+from pathlib import Path
+
+name = os.environ["GATEWAY_NAME"]
+ip = os.environ["GATEWAY_IP"]
+
+proxy = os.environ.get("HTTPS_PROXY") or os.environ.get("https_proxy", "")
+# NO_PROXY keeps the name: it is matched against what a client asks for, and
+# code inside a nested container still says "bot-bottle-gateway".
+no_proxy = os.environ.get("NO_PROXY") or os.environ.get("no_proxy", "")
+config = {"proxies": {"default": {
+    "httpProxy": proxy.replace(name, ip),
+    "httpsProxy": proxy.replace(name, ip),
+    "noProxy": no_proxy,
+}}}
+path = Path.home() / ".docker" / "config.json"
+path.parent.mkdir(parents=True, exist_ok=True)
+path.write_text(json.dumps(config), encoding="utf-8")
+path.chmod(0o600)
+PY
+
+if docker info >/dev/null 2>&1; then
+    exit 0
+fi
+
+# Belt to the ~/.docker/config.json braces above, which is what actually
+# decides this for `docker run`. The service environment is what podman falls
+# back to for anything the CLI does not stamp — its own registry pulls, and
+# containers created through the API by something other than the Docker CLI.
+# Cheap, and it keeps the address consistent across both paths.
+#
+# Assigned via parameter expansion, never echoed: these carry the bottle's
+# identity token.
+for var in HTTP_PROXY HTTPS_PROXY http_proxy https_proxy; do
+    eval "value=\${$var:-}"
+    [ -n "$value" ] || continue
+    eval "export $var=\"\${value%%$GATEWAY_NAME*}$gateway_ip\${value#*$GATEWAY_NAME}\""
+done
+
+log=/tmp/bot-bottle-nested-containers.log
+nohup podman system service --time=0 \
+    "unix://$XDG_RUNTIME_DIR/podman.sock" \
+    >"$log" 2>&1 </dev/null &

bot_bottle/backend/macos_container/nested_containers.py

@@ -0,0 +1,161 @@
+"""Guest-local container engine for Apple-container bottles (issue #392).
+
+The service and every nested container remain inside the existing per-bottle
+VM.  This module refuses to compensate for missing prerequisites with outer
+capabilities, a privileged container, or a host Docker socket.
+
+Podman is used rather than rootless Docker for one specific reason: Apple
+Container's capability bounding set omits `CAP_SYS_ADMIN`, which the kernel
+requires to write a multi-range `uid_map` via `newuidmap`.  Rootless Docker
+has no path that avoids that write.  Podman does — with no subordinate UID
+range configured it falls back to a single-UID self-mapping, which an
+unprivileged process may write itself.  See
+`docs/research/rootless-docker-in-apple-container-spike.md`.
+
+That fallback is why `build_image` *removes* the agent user's `/etc/subuid`
+and `/etc/subgid` entries instead of adding them: their presence is precisely
+what would send podman down the `newuidmap` path that cannot work here.
+
+The agent still talks to `docker` and `docker compose`; those speak to
+podman's Docker-compatible API socket, so nothing in the agent's habits
+changes.
+"""
+
+from __future__ import annotations
+
+import shlex
+import shutil
+import tempfile
+import time
+from pathlib import Path
+from typing import Callable
+
+from ...log import die, info
+
+_INIT = "/usr/local/libexec/bot-bottle/nested-containers-init"
+# Deliberately cryptic and short. podman derives conmon's attach socket as
+# `$XDG_RUNTIME_DIR/libpod/tmp/socket/<64-hex-id>/attach`, and a Unix socket
+# path may not exceed 108 bytes (`sun_path`). The descriptive
+# `/tmp/bot-bottle-podman-run` produced a 116-byte path — over the limit, so
+# attach would have broken as soon as anything got far enough to attach. Do
+# not lengthen this for readability; it buys 8 bytes of headroom.
+_RUNTIME_DIR = "/tmp/bbp"
+_SOCKET = f"{_RUNTIME_DIR}/podman.sock"
+_LOG = "/tmp/bot-bottle-nested-containers.log"
+IMAGE_SUFFIX = "-nested-containers"
+READY_RETRIES = 30
+
+# Apple Container creates both device nodes 0600 root:root, so the agent user
+# cannot open them: /dev/fuse blocks the fuse-overlayfs storage driver and
+# /dev/net/tun blocks slirp4netns, which rootless podman uses for the default
+# bridge network that stock compose files expect.  Relaxing the modes needs no
+# capability the bottle does not already hold — unlike CAP_SYS_ADMIN, which is
+# what killed the rootless-Docker approach.
+_GUEST_DEVICES = ("/dev/fuse", "/dev/net/tun")
+
+
+def build_image(
+    base_image: str,
+    build: Callable[..., None],
+) -> str:
+    """Layer the nested-container tooling onto an already-built agent image.
+
+    Podman and its networking stack live here rather than in the base agent
+    images so that bottles without the flag pay no image-size cost.
+
+    # TODO(#394): replace this hand-rolled Dockerfile with a docker-layer
+    # abstraction once that infrastructure exists.
+    """
+    image = f"{base_image}{IMAGE_SUFFIX}"
+    init_script = Path(__file__).with_name("nested-containers-init.sh")
+    with tempfile.TemporaryDirectory(prefix="bot-bottle-nested-containers.") as tmp:
+        context = Path(tmp)
+        shutil.copy2(init_script, context / "nested-containers-init.sh")
+        (context / "Dockerfile").write_text(
+            "FROM docker:28-cli AS docker_cli\n"
+            f"FROM {base_image}\n"
+            "USER root\n"
+            "COPY --from=docker_cli /usr/local/bin/docker /usr/local/bin/docker\n"
+            "COPY --from=docker_cli /usr/local/libexec/docker/cli-plugins/"
+            "docker-compose /usr/local/libexec/docker/cli-plugins/docker-compose\n"
+            "RUN apt-get update \\\n"
+            # podman 5's networking stack, installed explicitly because
+            # --no-install-recommends omits it and each missing piece fails
+            # at a different, misleading layer:
+            #   podman       -> moved here from the base agent images so that
+            #                   bottles without nested_containers pay no cost
+            #   passt        -> `pasta`, the default rootless netns helper
+            #                   (podman 4 used slirp4netns); without it
+            #                   nothing starts: "could not find pasta"
+            #   nftables     -> `nft`, which netavark shells out to for the
+            #                   bridge network every compose file expects
+            #   aardvark-dns -> name resolution *inside* nested containers;
+            #                   without it DNS fails while everything else
+            #                   looks healthy
+            # slirp4netns stays as the documented fallback for pasta.
+            " && apt-get install -y --no-install-recommends "
+            "aardvark-dns fuse-overlayfs netavark nftables passt podman "
+            "slirp4netns uidmap \\\n"
+            " && rm -rf /var/lib/apt/lists/* \\\n"
+            # Deliberate: an empty subordinate range keeps podman on the
+            # single-UID mapping that needs no CAP_SYS_ADMIN.  Adding ranges
+            # here would reintroduce the newuidmap failure this design exists
+            # to route around.
+            " && sed -i '/^node:/d' /etc/subuid /etc/subgid\n"
+            "COPY nested-containers-init.sh "
+            "/usr/local/libexec/bot-bottle/nested-containers-init\n"
+            "RUN chmod 0755 /usr/local/libexec/bot-bottle/nested-containers-init\n"
+            "USER node\n",
+            encoding="utf-8",
+        )
+        build(image, str(context), dockerfile=str(context / "Dockerfile"))
+    return image
+
+
+def guest_env(enabled: bool) -> dict[str, str]:
+    """Environment consumed by the Docker CLI inside an enabled bottle."""
+    if not enabled:
+        return {}
+    return {
+        "DOCKER_HOST": f"unix://{_SOCKET}",
+        "XDG_RUNTIME_DIR": _RUNTIME_DIR,
+    }
+
+
+def prepare_guest_devices(container_name: str, exec_as_root: Callable[..., None]) -> None:
+    """Make /dev/fuse and /dev/net/tun openable by the agent user.
+
+    Runs as root inside the bottle because the agent must not be able to
+    re-mode device nodes itself.  No outer capability is involved.
+    """
+    exec_as_root(
+        container_name,
+        ["sh", "-c", f"chmod 0666 {' '.join(_GUEST_DEVICES)}"],
+    )
+
+
+def start(bottle: object) -> None:
+    """Start and verify the unprivileged service through the bottle exec API."""
+    info("starting guest-local container engine")
+    result = bottle.exec(shlex.quote(_INIT))  # type: ignore[attr-defined]
+    if result.returncode != 0:
+        detail = (result.stderr or result.stdout or "").strip()
+        die(f"nested-container bootstrap failed: {detail or '<no output>'}")
+
+    for _ in range(READY_RETRIES):
+        result = bottle.exec("docker info >/dev/null 2>&1")  # type: ignore[attr-defined]
+        if result.returncode == 0:
+            info("guest-local container engine is ready")
+            return
+        time.sleep(0.2)
+
+    logs = bottle.exec(  # type: ignore[attr-defined]
+        f"tail -n 80 {_LOG} 2>/dev/null || true"
+    )
+    die(
+        "guest-local container engine did not become ready without additional "
+        f"outer privileges:\n{(logs.stdout or logs.stderr or '<no log>').strip()}"
+    )
+
+
+__all__ = ["build_image", "guest_env", "prepare_guest_devices", "start"]

bot_bottle/backend/macos_container/resolve_plan.py

@@ -44,4 +44,5 @@ def resolve_plan(
         egress_plan=egress_plan,
         supervise_plan=supervise_plan,
         agent_provision=agent_provision_plan,
+        nested_containers=manifest.bottle.nested_containers,
     )

bot_bottle/backend/macos_container/util.py

@@ -10,6 +10,7 @@ import shutil
 import subprocess
 import tempfile
 import time
+from datetime import datetime, timezone
 from typing import Iterable
 
 from ...log import die, info
@@ -360,6 +361,27 @@ def exec_container(name: str, argv: list[str]) -> None:
         )
 
 
+def read_container_env(name: str, env_name: str) -> str:
+    """Read one configured env value from a running container, or ``""``."""
+    result = _run_container_op([_CONTAINER, "exec", name, "printenv", env_name])
+    return result.stdout.strip() if result.returncode == 0 else ""
+
+
+def exec_container_as_root(name: str, argv: list[str]) -> None:
+    """`exec_container`, but as uid 0 inside the container.
+
+    For host-driven maintenance the agent itself must not be able to perform —
+    rewriting `/etc/hosts` to point the gateway name at an address. The agent
+    runs as `node`, so it cannot repoint its own gateway; the host can.
+    """
+    result = _run_container_op([_CONTAINER, "exec", "--user", "root", name, *argv])
+    if result.returncode != 0:
+        die(
+            f"container exec (root) in {name} failed: "
+            f"{(result.stderr or '').strip() or '<no stderr>'}"
+        )
+
+
 def _run_container_op(cmd: list[str]) -> subprocess.CompletedProcess[str]:
     result = subprocess.run(
         cmd,
@@ -557,6 +579,41 @@ def try_container_ipv4_on_network(name: str, network: str) -> str:
     return ""
 
 
+def inspect_container_network_ip(name: str, network: str) -> str | None:
+    """IP of `name` on `network`, distinguishing inspect failure from "not yet".
+
+    Returns:
+      - the IP string when the container has one on `network`
+      - "" when inspect succeeds but no address is assigned yet (in-flight DHCP)
+      - None when the inspect command itself fails (authoritative list impossible)
+    """
+    result = subprocess.run(
+        [_CONTAINER, "inspect", name],
+        capture_output=True, text=True, check=False,
+    )
+    if result.returncode != 0:
+        return None
+    try:
+        data = json.loads(result.stdout or "[]")
+    except json.JSONDecodeError:
+        return None
+    if isinstance(data, list):
+        data = data[0] if data else {}
+    if not isinstance(data, dict):
+        return None
+    status = data.get("status")
+    networks = status.get("networks") if isinstance(status, dict) else None
+    if not isinstance(networks, list):
+        return ""
+    for entry in networks:
+        if not isinstance(entry, dict) or entry.get("network") != network:
+            continue
+        raw = entry.get("ipv4Address")
+        if isinstance(raw, str) and raw:
+            return raw.split("/", 1)[0]
+    return ""
+
+
 def wait_container_ipv4_on_network(
     name: str, network: str, *, timeout: float = 15.0, poll: float = 0.25,
 ) -> str:
@@ -611,6 +668,39 @@ def image_id(ref: str) -> str:
     raise AssertionError("unreachable")
 
 
+def image_created_at(ref: str) -> datetime | None:
+    """Return the image creation timestamp as an aware UTC datetime, or None
+    when the field is absent or unparseable (e.g. FROM-scratch images, images
+    pulled from registries that omit the field). Callers should skip the stale
+    check when None is returned rather than treating it as an error."""
+    result = subprocess.run(
+        [_CONTAINER, "image", "inspect", ref],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if result.returncode != 0:
+        die(
+            f"container image inspect for {ref!r} failed: "
+            f"{(result.stderr or '').strip() or '<no stderr>'}"
+        )
+    try:
+        data = json.loads(result.stdout or "{}")
+    except json.JSONDecodeError as exc:
+        die(f"container image inspect for {ref!r} returned malformed JSON: {exc}")
+    if isinstance(data, list) and data:
+        data = data[0]
+    if isinstance(data, dict):
+        value = data.get("created") or data.get("Created")
+        if isinstance(value, str) and value:
+            try:
+                ts = value.rstrip("Z")
+                return datetime.fromisoformat(ts).replace(tzinfo=timezone.utc)
+            except ValueError:
+                pass
+    return None
+
+
 def save(ref: str, output: str) -> None:
     subprocess.run([_CONTAINER, "image", "save", ref, "-o", output], check=True)
 

bot_bottle/backend/resolve_common.py

@@ -26,6 +26,7 @@ from ..bottle_state import (
 )
 from ..egress import Egress, EgressPlan
 from ..git_gate import GitGate, GitGatePlan
+from ..log import die
 from ..manifest import Manifest, ManifestBottle
 from ..supervise import Supervise, SupervisePlan
 from . import BottleSpec
@@ -112,6 +113,22 @@ def merge_provision_env_vars(provision: AgentProvisionPlan) -> AgentProvisionPla
     return replace(provision, guest_env=merged)
 
 
+def reject_nested_containers(backend: str, manifest: Manifest) -> None:
+    """Fail loudly when a backend cannot honor `nested_containers: true`.
+
+    Silently ignoring it would hand the agent a bottle where `docker` is not
+    there — and the only sound alternatives on these backends (a host daemon
+    socket, a privileged container) are exactly what issue #392 rules out.
+    """
+    if not manifest.bottle.nested_containers:
+        return
+    die(
+        f"nested_containers is not supported on the {backend} backend. "
+        "Only macos-container runs a guest-local container engine today; "
+        "mounting the host Docker socket is not an option bot-bottle offers."
+    )
+
+
 def resolve_manifest_dockerfile(path_value: str, spec: BottleSpec) -> str:
     """Resolve a manifest-supplied dockerfile path relative to user_cwd."""
     path = Path(os.path.expanduser(path_value))
@@ -122,6 +139,7 @@ def resolve_manifest_dockerfile(path_value: str, spec: BottleSpec) -> str:
 
 __all__ = [
     "merge_provision_env_vars",
+    "reject_nested_containers",
     "mint_slug",
     "prepare_agent_state_dir",
     "prepare_egress",

bot_bottle/backend/util.py

@@ -7,6 +7,8 @@ from __future__ import annotations
 import hashlib
 import os
 import ssl
+import time
+from collections.abc import Callable
 from pathlib import Path
 from typing import TYPE_CHECKING
 
@@ -15,6 +17,24 @@ from ..log import die, info
 if TYPE_CHECKING:
     from ..egress import EgressPlan
 
+_CA_POLL_INTERVAL = 0.5
+
+
+def poll_ca_cert(fetch: Callable[[], str | None], *, timeout: float) -> str:
+    """Poll `fetch` until it returns a non-empty PEM string or `timeout` expires.
+
+    `fetch` should return the PEM on success and `None` (or empty string) when
+    the cert is not yet available. Raises `TimeoutError` if the cert never
+    appears within `timeout` seconds."""
+    deadline = time.monotonic() + timeout
+    while True:
+        result = fetch()
+        if result:
+            return result
+        if time.monotonic() >= deadline:
+            raise TimeoutError(f"CA cert not available after {timeout:g}s")
+        time.sleep(_CA_POLL_INTERVAL)
+
 
 # Debian-family CA layout, shared by every backend (all guest images
 # are Debian-family). AGENT_CA_PATH is the source path that

bot_bottle/cli/__init__.py

@@ -114,7 +114,3 @@ def main(argv: list[str] | None = None) -> int:
         return e.code if isinstance(e.code, int) else 1
     except KeyboardInterrupt:
         return 130
-
-
-if __name__ == "__main__":
-    sys.exit(main())

bot_bottle/cli/__main__.py

@@ -0,0 +1,15 @@
+"""Entry point for `python -m bot_bottle.cli`.
+
+`cli.py` at the repo root is the usual way in; this makes the package
+runnable too, so the CLI works from an installed copy where there is no
+`cli.py` on disk to point at.
+"""
+
+from __future__ import annotations
+
+import sys
+
+from . import main
+
+if __name__ == "__main__":
+    sys.exit(main())

bot_bottle/cli/login.py

@@ -18,10 +18,12 @@ import json
 import os
 import socket
 import sys
+import tempfile
 import time
 import urllib.error
 import urllib.request
 from pathlib import Path
+from typing import Any
 
 from ..paths import bot_bottle_root
 
@@ -48,7 +50,7 @@ def _flag(argv: list[str], name: str) -> str | None:
     return None
 
 
-def _post(url: str, payload: dict) -> dict:
+def _post(url: str, payload: dict[str, Any]) -> dict[str, Any]:
     data = json.dumps(payload).encode()
     req = urllib.request.Request(
         url, data=data, headers={"Content-Type": "application/json"}
@@ -57,7 +59,7 @@ def _post(url: str, payload: dict) -> dict:
         return json.loads(resp.read())
 
 
-def _get(url: str) -> tuple[int, dict]:
+def _get(url: str) -> tuple[int, dict[str, Any]]:
     req = urllib.request.Request(url)
     try:
         with urllib.request.urlopen(req, timeout=10) as resp:
@@ -71,7 +73,7 @@ def _save_credentials(
 ) -> Path:
     path = bot_bottle_root() / "console.json"
     path.parent.mkdir(parents=True, exist_ok=True)
-    path.write_text(
+    content = (
         json.dumps(
             {
                 "url": console_url,
@@ -83,7 +85,19 @@ def _save_credentials(
         )
         + "\n"
     )
-    path.chmod(0o600)
+    fd, tmp_path_str = tempfile.mkstemp(dir=path.parent, prefix=".console-")
+    tmp = Path(tmp_path_str)
+    try:
+        tmp.chmod(0o600)
+        with os.fdopen(fd, "w") as f:
+            f.write(content)
+        os.replace(tmp, path)
+    except OSError:
+        try:
+            tmp.unlink()
+        except OSError:
+            pass
+        raise
     return path
 
 
@@ -104,17 +118,18 @@ def cmd_login(argv: list[str]) -> int:
 
     try:
         resp = _post(f"{console_url}/api/v1/hosts/authorize", {"label": label})
-    except Exception as exc:
+    except (OSError, ValueError) as exc:
         sys.stderr.write(f"bb login: failed to start authorization: {exc}\n")
         return 1
 
     device_code = resp["device_code"]
     user_code = resp["user_code"]
     expires_in = resp.get("expires_in", 300)
+    poll_sleep = max(1, min(int(resp.get("poll_interval", _POLL_SLEEP)), 60))
 
     sys.stderr.write(
         f"\nOpen this URL in your browser to authorize this host:\n\n"
-        f"  {console_url}/authorize?code={user_code}\n\n"
+        f"  {console_url}/hosts/authorize?code={user_code}\n\n"
         f"Waiting for approval"
     )
 
@@ -122,13 +137,13 @@ def cmd_login(argv: list[str]) -> int:
     while time.monotonic() < deadline:
         sys.stderr.write(".")
         sys.stderr.flush()
-        time.sleep(_POLL_SLEEP)
+        time.sleep(poll_sleep)
 
         try:
             code, result = _get(
                 f"{console_url}/api/v1/hosts/authorize/{device_code}"
             )
-        except Exception:
+        except (OSError, ValueError):
             continue
 
         if code == 410:

bot_bottle/cli/start.py

@@ -35,6 +35,7 @@ from ..bottle_state import (
     is_preserved,
     mark_preserved,
 )
+from ..image_cache import StaleImageError
 from ..log import info, die
 from ..manifest import Manifest, ManifestIndex
 from ._common import PROG, USER_CWD, read_tty_line
@@ -64,6 +65,14 @@ def cmd_start(argv: list[str]) -> int:
             "skip all prompts. For orchestrators, CI, and webhooks."
         ),
     )
+    parser.add_argument(
+        "--cached-images",
+        action="store_true",
+        help=(
+            "quickstart with existing local agent and sidecar images; "
+            "only valid with --headless"
+        ),
+    )
     parser.add_argument(
         "--bottle",
         action="append",
@@ -96,6 +105,8 @@ def cmd_start(argv: list[str]) -> int:
         help="agent name defined in bot-bottle.json (omit to pick interactively)",
     )
     args = parser.parse_args(argv)
+    if args.cached_images and not args.headless:
+        die("--cached-images is only supported with --headless")
 
     dry_run = args.dry_run or os.environ.get("BOT_BOTTLE_DRY_RUN") == "1"
     if args.no_cache or os.environ.get("BOT_BOTTLE_NO_CACHE") == "1":
@@ -147,6 +158,10 @@ def cmd_start(argv: list[str]) -> int:
     label, color = tui.name_color_modal(default_label=agent_name)
     label, color = _resolve_unique_label(label, color)
 
+    image_policy = _select_image_policy()
+    if image_policy is None:
+        return 0
+
     spec = BottleSpec(
         manifest=manifest,
         agent_name=agent_name,
@@ -155,6 +170,7 @@ def cmd_start(argv: list[str]) -> int:
         label=label,
         color=color,
         bottle_names=bottle_names,
+        image_policy=image_policy,
     )
     return _launch_bottle(
         spec,
@@ -213,6 +229,7 @@ def _start_headless(
         color=args.color or "",
         bottle_names=bottle_names,
         headless=True,
+        image_policy="cached" if args.cached_images else "fresh",
     )
     return _launch_bottle(
         spec,
@@ -395,6 +412,13 @@ def _text_prompt_yes() -> bool:
     return reply in ("y", "Y", "yes", "YES")
 
 
+def _select_image_policy() -> str | None:
+    return tui.filter_select(
+        ["fresh", "cached"],
+        title="Select image startup mode",
+    )
+
+
 def _text_render_preflight():
     def _render(plan: DockerBottlePlan, backend_name: str) -> None:
         print(file=sys.stderr)
@@ -500,6 +524,8 @@ def _manifest_to_yaml(manifest: Manifest) -> str:
                 lines.append(f"          scheme: {r.AuthScheme}")
 
     lines.append(f"  supervise: {'true' if bottle.supervise else 'false'}")
+    if bottle.nested_containers:
+        lines.append("  nested_containers: true")
 
     return "\n".join(lines)
 
@@ -537,6 +563,15 @@ def _launch_bottle(
             return 0
 
         backend = get_bottle_backend(backend_name)
+        try:
+            backend.prelaunch_checks(plan)
+        except StaleImageError as exc:
+            if assume_yes:
+                die(str(exc))
+            sys.stderr.write(f"bot-bottle: {exc}\nLaunch anyway? [y/N] ")
+            sys.stderr.flush()
+            if read_tty_line() not in ("y", "Y", "yes", "YES"):
+                return 0
         with backend.launch(plan) as bottle:
             agent_provider_template = getattr(plan, "agent_provider_template", "claude")
             extra_args: tuple[str, ...] = ()
@@ -555,10 +590,6 @@ def _launch_bottle(
                 f"session ended (exit {exit_code}); "
                 f"container {bottle.name} will be removed"
             )
-            # While the container is still alive: always snapshot the
-            # transcript and — if the agent exited non-zero — mark
-            # the state for preservation. This picks up crashes /
-            # Ctrl-Cs / OOM kills before cleanup removes the state dir.
             if agent_provider_template == "claude":
                 capture_claude_session_state(identity, exit_code)
         return 0

bot_bottle/config_store.py

@@ -0,0 +1,71 @@
+"""SQLite-backed bot-bottle configuration store."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+try:
+    from .db_store import DbStore
+    from .migrations import TableMigrations
+    from .paths import host_db_path
+except ImportError:
+    from db_store import DbStore  # type: ignore[import-not-found]  # pylint: disable=import-error,no-name-in-module
+    from migrations import TableMigrations  # type: ignore[import-not-found]  # pylint: disable=import-error,no-name-in-module
+    from paths import host_db_path  # type: ignore[import-not-found]  # pylint: disable=import-error,no-name-in-module
+
+
+DEFAULT_CACHED_IMAGE_STALE_WARNING_DAYS = 1
+
+
+class ConfigStore(DbStore):
+    """SQLite configuration for host-side bot-bottle settings."""
+
+    def __init__(self, db_path: Path | None = None) -> None:
+        migrations = TableMigrations("config_store", [
+            # v1 — host-side bot-bottle settings
+            """
+            CREATE TABLE IF NOT EXISTS bot_bottle_config (
+                id INTEGER PRIMARY KEY CHECK (id = 1),
+                cached_image_stale_warning_days INTEGER NOT NULL DEFAULT 1
+            )
+            """,
+        ])
+        super().__init__(db_path or host_db_path(), migrations)
+
+    def cached_image_stale_warning_days(self) -> int:
+        if not self.db_path.is_file():
+            return DEFAULT_CACHED_IMAGE_STALE_WARNING_DAYS
+        with self._connect() as conn:
+            row = conn.execute(
+                """
+                SELECT cached_image_stale_warning_days
+                FROM bot_bottle_config
+                WHERE id = 1
+                """,
+            ).fetchone()
+        if row is None:
+            return DEFAULT_CACHED_IMAGE_STALE_WARNING_DAYS
+        try:
+            return int(row["cached_image_stale_warning_days"])
+        except (TypeError, ValueError):
+            return DEFAULT_CACHED_IMAGE_STALE_WARNING_DAYS
+
+    def set_cached_image_stale_warning_days(self, days: int) -> Path:
+        with self._connect() as conn:
+            conn.execute(
+                """
+                INSERT INTO bot_bottle_config (id, cached_image_stale_warning_days)
+                VALUES (1, ?)
+                ON CONFLICT(id) DO UPDATE SET
+                    cached_image_stale_warning_days = excluded.cached_image_stale_warning_days
+                """,
+                (days,),
+            )
+        self._chmod()
+        return self.db_path
+
+
+__all__ = [
+    "DEFAULT_CACHED_IMAGE_STALE_WARNING_DAYS",
+    "ConfigStore",
+]

bot_bottle/contrib/claude/Dockerfile

@@ -10,7 +10,7 @@
 
 # Current Node LTS; slim variant keeps the image small while still
 # providing apt-get for any future additions.
-FROM node:22-slim
+FROM node:22-trixie-slim
 
 # Install runtime system deps. claude-code shells out to git for several
 # features (status checks, commits, PR creation) — without git in the
@@ -21,7 +21,14 @@ FROM node:22-slim
 # to it) works against egress's bumped TLS without the agent needing
 # local DNS.
 RUN apt-get update \
-  && apt-get install -y --no-install-recommends git ca-certificates curl ripgrep iproute2 dnsutils \
+  && apt-get install -y --no-install-recommends \
+  git \
+  ca-certificates \
+  curl \
+  openssh-client \
+  ripgrep \
+  iproute2 \
+  dnsutils \
   && rm -rf /var/lib/apt/lists/*
 
 # App-specific deps. Python isn't required by claude-code itself
@@ -39,6 +46,11 @@ RUN apt-get update \
 RUN npm install -g --no-fund --no-audit @anthropic-ai/claude-code@2.1.172 \
   && npm cache clean --force
 
+# Git reads both ~/.gitconfig and ~/.config/git/config. Keep its XDG config
+# path traversable by the non-root runtime user so permission errors do not
+# suppress bot-bottle's git-gate insteadOf rules.
+RUN install -d -o node -g node -m 755 /home/node/.config /home/node/.config/git
+
 # Run as a non-root user. The node image already provides a `node` user
 # (uid 1000) with a home directory, which is where claude-code will write
 # its session state.

bot_bottle/contrib/claude/agent_provider.py

@@ -23,8 +23,9 @@ from ...agent_provider import (
     provider_startup_args,
 )
 from ...backend.docker import util as docker_mod
-from ...egress import EgressRoute
+from ...egress import CLAUDE_HOST_CREDENTIAL_TOKEN_REF, EgressRoute
 from ...log import die, info, warn
+from .claude_auth import claude_host_access_token
 
 
 if TYPE_CHECKING:
@@ -118,7 +119,6 @@ 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,13 +180,24 @@ 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 else "",
-            token_ref=auth_token,
+            auth_scheme="Bearer" if (auth_token or forward_host_credentials) else "",
+            token_ref=cred_token_ref,
         ),)
         hidden_env_names: frozenset[str] = frozenset()
-        if auth_token:
+        if auth_token or forward_host_credentials:
             env_vars["CLAUDE_CODE_OAUTH_TOKEN"] = "egress-placeholder"
             hidden_env_names = frozenset({"CLAUDE_CODE_OAUTH_TOKEN"})
 
@@ -208,6 +219,7 @@ class ClaudeAgentProvider(AgentProvider):
             files=tuple(files),
             egress_routes=egress_routes,
             hidden_env_names=hidden_env_names,
+            provisioned_env=provisioned_env,
         )
 
     def provision_skills(self, plan: "BottlePlan", bottle: "Bottle") -> None:

bot_bottle/contrib/claude/claude_auth.py

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

bot_bottle/contrib/codex/Dockerfile

@@ -3,10 +3,16 @@
 # Mirrors the default Claude image shape: Node LTS, git/network tooling,
 # non-root node user, and the provider CLI installed for that user.
 
-FROM node:22-slim
+FROM node:22-trixie-slim
 
 RUN apt-get update \
-  && apt-get install -y --no-install-recommends git ca-certificates curl procps ripgrep \
+  && apt-get install -y --no-install-recommends \
+  git \
+  ca-certificates \
+  curl \
+  openssh-client \
+  procps \
+  ripgrep \
   && rm -rf /var/lib/apt/lists/*
 
 # App-specific deps. Python isn't required by codex itself
@@ -17,6 +23,8 @@ RUN apt-get update \
   && apt-get install -y --no-install-recommends python3 python3-pip python3-venv \
   && rm -rf /var/lib/apt/lists/*
 
+RUN install -d -o node -g node -m 755 /home/node/.config /home/node/.config/git
+
 USER node
 WORKDIR /home/node
 

bot_bottle/contrib/pi/Dockerfile

@@ -2,7 +2,7 @@
 #
 # Node LTS, git/network tooling, and the Pi coding-agent CLI installed globally.
 
-FROM node:22-slim
+FROM node:22-trixie-slim
 
 RUN apt-get update \
   && apt-get install -y --no-install-recommends \
@@ -10,6 +10,7 @@ RUN apt-get update \
   ca-certificates \
   curl \
   fd-find \
+  openssh-client \
   ripgrep \
   && ln -s /usr/bin/fdfind /usr/local/bin/fd \
   && rm -rf /var/lib/apt/lists/*
@@ -21,7 +22,8 @@ RUN apt-get update \
 RUN npm install -g --ignore-scripts --no-fund --no-audit @earendil-works/pi-coding-agent \
   && npm cache clean --force
 
-RUN mkdir -p /home/node/.pi/agent \
+RUN install -d -o node -g node -m 755 /home/node/.config /home/node/.config/git \
+  && mkdir -p /home/node/.pi/agent \
   /home/node/.pi/context-mode/sessions \
   /tmp/pi-subagents-uid-1000 \
   && chown -R node:node /home/node/.pi /tmp \

bot_bottle/egress.py

@@ -30,6 +30,7 @@ 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"
 
@@ -145,6 +146,8 @@ def egress_manifest_routes(
             outbound_detectors=r.OutboundDetectors,
             inbound_detectors=r.InboundDetectors,
             outbound_on_match=r.OutboundOnMatch,
+            preserve_auth=r.PreserveAuth,
+            inspect=r.Inspect,
         ))
     return tuple(out)
 
@@ -224,9 +227,13 @@ def _yaml_str_escape(s: str) -> str:
 
 def _route_to_yaml_fields(r: Route) -> dict[str, object]:
     fields: dict[str, object] = {"host": r.host}
+    if not r.inspect:
+        fields["inspect"] = False
+        return fields
+    inspect: dict[str, object] = {}
     if r.auth_scheme and r.token_env:
-        fields["auth_scheme"] = r.auth_scheme
-        fields["token_env"] = r.token_env
+        inspect["auth_scheme"] = r.auth_scheme
+        inspect["token_env"] = r.token_env
     if r.matches:
         matches_data: list[dict[str, object]] = []
         for entry in r.matches:
@@ -250,28 +257,30 @@ def _route_to_yaml_fields(r: Route) -> dict[str, object]:
                     headers_data.append(hd)
                 entry_data["headers"] = headers_data
             matches_data.append(entry_data)
-        fields["matches"] = matches_data
+        inspect["matches"] = matches_data
     if r.git_fetch:
-        fields["git"] = {"fetch": True}
+        inspect["git"] = {"fetch": True}
+    if r.preserve_auth:
+        inspect["preserve_auth"] = True
     if (
         r.outbound_detectors is not None
         or r.inbound_detectors is not None
         or r.outbound_on_match
     ):
-        dlp: dict[str, object] = {}
         if r.outbound_detectors is not None:
-            dlp["outbound_detectors"] = (
+            inspect["outbound_detectors"] = (
                 False if not r.outbound_detectors
                 else list(r.outbound_detectors)
             )
         if r.inbound_detectors is not None:
-            dlp["inbound_detectors"] = (
+            inspect["inbound_detectors"] = (
                 False if not r.inbound_detectors
                 else list(r.inbound_detectors)
             )
         if r.outbound_on_match:
-            dlp["outbound_on_match"] = r.outbound_on_match
-        fields["dlp"] = dlp
+            inspect["outbound_on_match"] = r.outbound_on_match
+    if inspect:
+        fields["inspect"] = inspect
     return fields
 
 
@@ -279,30 +288,30 @@ def _render_match_entry(entry: dict[str, object]) -> list[str]:
     lines: list[str] = []
     first_key = True
     if "paths" in entry:
-        lines.append("      - paths:")
+        lines.append("        - paths:")
         first_key = False
         for pd in entry["paths"]:  # type: ignore[union-attr]
             pd_dict: dict[str, str] = pd  # type: ignore[assignment]
             if "type" in pd_dict:
-                lines.append(f'          - type: "{_yaml_str_escape(pd_dict["type"])}"')
-                lines.append(f'            value: "{_yaml_str_escape(pd_dict["value"])}"')
+                lines.append(f'            - type: "{_yaml_str_escape(pd_dict["type"])}"')
+                lines.append(f'              value: "{_yaml_str_escape(pd_dict["value"])}"')
             else:
-                lines.append(f'          - value: "{_yaml_str_escape(pd_dict["value"])}"')
+                lines.append(f'            - value: "{_yaml_str_escape(pd_dict["value"])}"')
     if "methods" in entry:
         methods_str = ", ".join(f'"{_yaml_str_escape(m)}"' for m in entry["methods"])  # type: ignore[union-attr]
-        prefix = "      - " if first_key else "        "
+        prefix = "        - " if first_key else "          "
         lines.append(f'{prefix}methods: [{methods_str}]')
         first_key = False
     if "headers" in entry:
-        prefix = "      - " if first_key else "        "
+        prefix = "        - " if first_key else "          "
         lines.append(f"{prefix}headers:")
         first_key = False
         for hd in entry["headers"]:  # type: ignore[union-attr]
             hd_dict: dict[str, str] = hd  # type: ignore[assignment]
-            lines.append(f'          - name: "{_yaml_str_escape(hd_dict["name"])}"')
-            lines.append(f'            value: "{_yaml_str_escape(hd_dict["value"])}"')
+            lines.append(f'            - name: "{_yaml_str_escape(hd_dict["name"])}"')
+            lines.append(f'              value: "{_yaml_str_escape(hd_dict["value"])}"')
     if first_key:
-        lines.append("      - {}")
+        lines.append("        - {}")
     return lines
 
 
@@ -321,22 +330,30 @@ def egress_render_routes(
     for r in routes:
         f = _route_to_yaml_fields(r)
         lines.append(f'  - host: "{_yaml_str_escape(str(f["host"]))}"')
-        if "auth_scheme" in f:
-            lines.append(f'    auth_scheme: "{_yaml_str_escape(str(f["auth_scheme"]))}"')
-            lines.append(f'    token_env: "{_yaml_str_escape(str(f["token_env"]))}"')
-        if "matches" in f:
-            lines.append("    matches:")
-            for entry in f["matches"]:  # type: ignore[union-attr]
+        if f.get("inspect") is False:
+            lines.append("    inspect: false")
+            continue
+        inspect: dict[str, object] = f.get("inspect", {})  # type: ignore[assignment]
+        if not inspect:
+            continue
+        lines.append("    inspect:")
+        if "auth_scheme" in inspect:
+            lines.append(f'      auth_scheme: "{_yaml_str_escape(str(inspect["auth_scheme"]))}"')
+            lines.append(f'      token_env: "{_yaml_str_escape(str(inspect["token_env"]))}"')
+        if "matches" in inspect:
+            lines.append("      matches:")
+            for entry in inspect["matches"]:  # type: ignore[union-attr]
                 lines.extend(_render_match_entry(entry))  # type: ignore[arg-type]
-        if "git" in f:
-            git_dict: dict[str, object] = f["git"]  # type: ignore
-            lines.append("    git:")
+        if "git" in inspect:
+            git_dict: dict[str, object] = inspect["git"]  # type: ignore
+            lines.append("      git:")
             if git_dict.get("fetch") is True:
-                lines.append("      fetch: true")
-        if "dlp" in f:
-            dlp_dict: dict[str, object] = f["dlp"]  # type: ignore
-            lines.append("    dlp:")
-            for dk, dv in dlp_dict.items():
+                lines.append("        fetch: true")
+        if inspect.get("preserve_auth") is True:
+            lines.append("      preserve_auth: true")
+        for dk in ("outbound_detectors", "inbound_detectors", "outbound_on_match"):
+            if dk in inspect:
+                dv = inspect[dk]
                 if dv is False:
                     lines.append(f"      {dk}: false")
                 elif isinstance(dv, list):
@@ -400,6 +417,7 @@ class Egress(ABC):
         )
 
 __all__ = [
+    "CLAUDE_HOST_CREDENTIAL_TOKEN_REF",
     "CODEX_HOST_CREDENTIAL_TOKEN_REF",
     "EGRESS_HOSTNAME",
     "EGRESS_ROUTES_FILENAME",

bot_bottle/egress_addon.py

@@ -97,10 +97,11 @@ class EgressAddon:
     # comes from the orchestrator's /resolve (PRD 0070); there is no static
     # per-bottle routes file, SIGHUP reload, or single-tenant fallback.
     _resolver: "PolicyResolver"
-    # Class default so __new__-built addons have it (real runs get a fresh
-    # per-instance dict in __init__; only http_connect mutates it, which the
-    # request-flow tests don't exercise).
+    # Class defaults so __new__-built addons have them (real runs get fresh
+    # per-instance collections in __init__; only http_connect mutates them,
+    # which request-flow tests don't exercise unless they call http_connect).
     _conn_tokens: "dict[str, str]" = {}
+    _passthrough_conns: "set[str]" = set()
 
     def __init__(self) -> None:
         # Resolver-only: the gateway is always multi-tenant, resolving each
@@ -125,6 +126,10 @@ class EgressAddon:
         # `Proxy-Authorization` (HTTPS tunnels don't repeat it on the bumped
         # inner requests). Keyed by client_conn.id; cleared on disconnect.
         self._conn_tokens: dict[str, str] = {}
+        # Connections whose route carries `inspect: false` — mitmproxy tunnels
+        # these without TLS interception so the client sees the server's real
+        # cert. Keyed by client_conn.id; cleared on disconnect.
+        self._passthrough_conns: set[str] = set()
         self._token_allow_timeout = _token_allow_timeout_from_env(os.environ)
 
     @staticmethod
@@ -305,25 +310,68 @@ class EgressAddon:
     def http_connect(self, flow: http.HTTPFlow) -> None:
         """Capture the identity token from an HTTPS tunnel's CONNECT (the inner
         bumped requests won't carry `Proxy-Authorization`), keyed by client
-        connection, and strip it so it never reaches upstream."""
+        connection, and strip it so it never reaches upstream.
+
+        For `inspect: false` routes, also resolve the policy here to make the
+        allowlist decision before the TLS handshake: the tunnel is either
+        blocked immediately or marked for passthrough in `_passthrough_conns`
+        so `tls_clienthello` skips interception."""
         token = _token_from_proxy_auth(
             flow.request.headers.get("Proxy-Authorization", ""))
         flow.request.headers.pop("Proxy-Authorization", None)
         conn = flow.client_conn
-        if conn is not None and getattr(conn, "id", ""):
-            self._conn_tokens[conn.id] = token
+        conn_id = getattr(conn, "id", "") if conn is not None else ""
+        if conn_id:
+            self._conn_tokens[conn_id] = token
+
+        # Resolve the policy here for all HTTPS connections and stash it so
+        # request() reuses it without a second orchestrator round-trip.  For
+        # passthrough hosts we also make the allowlist decision now because
+        # inner requests never reach request() after the TLS bypass.
+        client_ip = conn.peername[0] if conn is not None and conn.peername else ""
+        config, slug, env = resolve_client_context(self._resolver, client_ip, token)
+        self._stash_flow_ctx(flow, config, slug, env)
+        host = flow.request.pretty_host
+        route = match_route(config.routes, host)
+        if route is not None and not route.inspect:
+            decision = decide(config.routes, host, "/", env, deny_reason=config.deny_reason)
+            if decision.action == "block":
+                flow.response = http.Response.make(
+                    403,
+                    decision.reason.encode("utf-8"),
+                    {"Content-Type": "text/plain; charset=utf-8"},
+                )
+                return
+            if conn_id:
+                self._passthrough_conns.add(conn_id)
+
+    def tls_clienthello(self, client_hello: typing.Any) -> None:
+        """Skip TLS interception for `inspect: false` routes so the client sees
+        the server's real certificate rather than the MITM CA's leaf."""
+        conn_id = getattr(client_hello.context.client, "id", "")
+        if conn_id in self._passthrough_conns:
+            client_hello.ignore_connection = True
 
     def client_disconnected(self, client: typing.Any) -> None:
-        """Drop the per-connection token when the client goes away."""
-        self._conn_tokens.pop(getattr(client, "id", ""), None)
+        """Drop the per-connection token and passthrough flag when the client
+        goes away."""
+        conn_id = getattr(client, "id", "")
+        self._conn_tokens.pop(conn_id, None)
+        self._passthrough_conns.discard(conn_id)
 
     async def request(self, flow: http.HTTPFlow) -> None:
         request_path, _, query = flow.request.path.partition("?")
 
-        config, slug, env = self._resolve_flow(flow)
-        # Stash for the response / websocket hooks so their DLP scans reuse this
-        # bottle's resolved policy (one /resolve per flow — see _flow_ctx).
-        self._stash_flow_ctx(flow, config, slug, env)
+        # Reuse the context stashed by http_connect for HTTPS flows (one
+        # orchestrator round-trip per connection). Plain-HTTP flows have no
+        # prior CONNECT stash, so resolve now and stash for response/websocket.
+        meta = getattr(flow, "metadata", None)
+        if isinstance(meta, dict) and _FLOW_CTX_KEY in meta:
+            config, slug, env = meta[_FLOW_CTX_KEY]
+            self._request_token(flow)  # strip identity headers; token already resolved
+        else:
+            config, slug, env = self._resolve_flow(flow)
+            self._stash_flow_ctx(flow, config, slug, env)
 
         # Introspection ("_egress.local/allowlist") reports the calling bottle's
         # own resolved routes — served after resolution so it reflects this
@@ -335,8 +383,10 @@ class EgressAddon:
         # DLP outbound scan BEFORE stripping auth — catches tokens the
         # agent tried to smuggle in any header, path, query param, or body.
         # Hostname is included to catch DNS-tunnelling exfiltration attempts.
+        # `inspect: false` routes skip scanning entirely (TLS is also not
+        # intercepted for HTTPS, so this branch only fires for plain HTTP).
         route = match_route(config.routes, flow.request.pretty_host)
-        if route is not None:
+        if route is not None and route.inspect:
             if not await self._handle_outbound_dlp(flow, route, slug, env):
                 return
             # The redact policy may have rewritten the request line; recompute
@@ -367,7 +417,10 @@ class EgressAddon:
 
         # Strip agent-set Authorization after DLP scan so smuggled tokens
         # are caught above; the route may inject gateway-owned auth below.
-        flow.request.headers.pop("authorization", None)
+        # Routes with preserve_auth=True pass the header through as-is so the
+        # agent's own credentials (e.g. registry bearer tokens) reach the upstream.
+        if route is None or not route.preserve_auth:
+            flow.request.headers.pop("authorization", None)
 
         # Build headers mapping for match evaluation
         req_headers = {k.lower(): v for k, v in flow.request.headers.items()}
@@ -379,6 +432,7 @@ class EgressAddon:
             env,
             request_method=flow.request.method,
             request_headers=req_headers,
+            deny_reason=config.deny_reason,
         )
 
         if decision.action == "block":
@@ -602,7 +656,7 @@ class EgressAddon:
         bottle's resolved config (`request()` stashed it — see `_flow_ctx`)."""
         config, _slug, env = self._flow_ctx(flow)
         route = match_route(config.routes, flow.request.pretty_host)
-        if route is None:
+        if route is None or not route.inspect:
             return
         if flow.response is None:
             return
@@ -648,7 +702,7 @@ class EgressAddon:
             return
         config, slug, env = self._flow_ctx(flow)
         route = match_route(config.routes, flow.request.pretty_host)
-        if route is None:
+        if route is None or not route.inspect:
             return
         message = flow.websocket.messages[-1]  # type: ignore[union-attr]
         content = message.content.decode("utf-8", errors="replace")

bot_bottle/egress_addon_core.py

@@ -28,7 +28,7 @@ from .egress_dlp_config import (
     ON_MATCH_SUPERVISE,
     OUTBOUND_DETECTOR_NAMES,
     OUTBOUND_ON_MATCH_VALUES,
-    parse_dlp_block,
+    parse_inspect_block,
 )
 
 
@@ -78,6 +78,9 @@ class Route:
     inbound_detectors: tuple[str, ...] | None = None
     # "" means unset → DEFAULT_OUTBOUND_ON_MATCH. See OUTBOUND_ON_MATCH_VALUES.
     outbound_on_match: str = ""
+    preserve_auth: bool = False
+    # False tunnels HTTPS without TLS interception or HTTP-level controls.
+    inspect: bool = True
 
 
 LOG_OFF = 0    # no logging
@@ -89,6 +92,14 @@ LOG_FULL = 2    # log block/warn events + full request and response bodies
 class Config:
     routes: tuple[Route, ...]
     log: int = LOG_OFF
+    # Why this Config is a deny-all, when it is one for a reason *other* than
+    # the bottle's own policy genuinely not listing the host. A deny-all is
+    # indistinguishable from "policy loaded, host not allowed" at the decision
+    # point — both are simply "no matching route" — so without this the
+    # operator sees `host X is not in the allowlist` and goes hunting for a
+    # missing route that was never the problem. Empty for a normally-parsed
+    # policy; `decide` prefers it over the allowlist wording when set.
+    deny_reason: str = ""
 
 
 @dataclass(frozen=True)
@@ -250,10 +261,31 @@ def _parse_one(idx: int, raw: object) -> Route:
     host: object = raw_dict.get("host")
     if not isinstance(host, str) or not host:
         raise ValueError(f"{label}: 'host' must be a non-empty string")
+    legacy_flat = "inspect" not in raw_dict
+    inspect_raw = raw_dict.get("inspect", {})
+    if inspect_raw is False:
+        inspect = False
+        settings: dict[str, object] = {}
+    elif isinstance(inspect_raw, dict):
+        inspect = True
+        settings = (
+            {k: v for k, v in raw_dict.items() if k != "host"}
+            if legacy_flat
+            else typing.cast(dict[str, object], inspect_raw)
+        )
+        legacy_dlp = settings.pop("dlp", None)
+        if isinstance(legacy_dlp, dict):
+            settings.update(typing.cast(dict[str, object], legacy_dlp))
+        elif legacy_dlp is not None:
+            raise ValueError(
+                f"{label} ({host}): legacy 'dlp' must be an object"
+            )
+    else:
+        raise ValueError(f"{label} ({host}): 'inspect' must be false or an object")
 
     # matches
     matches: tuple[MatchEntry, ...] = ()
-    matches_raw = raw_dict.get("matches")
+    matches_raw = settings.get("matches")
     if matches_raw is not None:
         if not isinstance(matches_raw, list):
             raise ValueError(f"{label} ({host}): 'matches' must be a list")
@@ -263,8 +295,8 @@ def _parse_one(idx: int, raw: object) -> Route:
         )
 
     # auth (unchanged wire format)
-    auth_scheme: object = raw_dict.get("auth_scheme", "")
-    token_env: object = raw_dict.get("token_env", "")
+    auth_scheme: object = settings.get("auth_scheme", "")
+    token_env: object = settings.get("token_env", "")
     if not isinstance(auth_scheme, str):
         raise ValueError(f"{label} ({host}): 'auth_scheme' must be a string")
     if not isinstance(token_env, str):
@@ -278,7 +310,7 @@ def _parse_one(idx: int, raw: object) -> Route:
 
     # git-over-HTTPS policy
     git_fetch = False
-    git_raw = raw_dict.get("git")
+    git_raw = settings.get("git")
     if git_raw is not None:
         if not isinstance(git_raw, dict):
             raise ValueError(f"{label} ({host}): 'git' must be an object")
@@ -296,15 +328,30 @@ def _parse_one(idx: int, raw: object) -> Route:
                 )
 
     # dlp detectors
-    outbound_detectors, inbound_detectors, outbound_on_match = parse_dlp_block(
-        idx, host, raw_dict,
+    outbound_detectors, inbound_detectors, outbound_on_match = parse_inspect_block(
+        idx, host, settings,
     )
 
+    preserve_auth_raw = settings.get("preserve_auth", False)
+    if preserve_auth_raw is not True and preserve_auth_raw is not False:
+        raise ValueError(
+            f"{label} ({host}): 'preserve_auth' must be a boolean"
+        )
+    preserve_auth: bool = preserve_auth_raw
+
+    for k in settings:
+        if k not in (
+            "matches", "auth_scheme", "token_env", "git", "preserve_auth",
+            "outbound_detectors", "inbound_detectors", "outbound_on_match",
+        ):
+            raise ValueError(
+                f"{label} ({host}): inspect has unknown key {k!r}"
+            )
     for k in raw_dict:
-        if k not in ("host", "matches", "auth_scheme", "token_env", "dlp", "git"):
+        if not legacy_flat and k not in ("host", "inspect"):
             raise ValueError(
                 f"{label} ({host}): unknown key {k!r}; accepted keys "
-                f"are 'host', 'matches', 'auth_scheme', 'token_env', 'dlp', 'git'"
+                f"are 'host' and 'inspect'"
             )
 
     return Route(
@@ -316,6 +363,8 @@ def _parse_one(idx: int, raw: object) -> Route:
         outbound_detectors=outbound_detectors,
         inbound_detectors=inbound_detectors,
         outbound_on_match=outbound_on_match,
+        preserve_auth=preserve_auth,
+        inspect=inspect,
     )
 
 
@@ -352,22 +401,27 @@ def route_to_yaml_dict(r: Route) -> dict[str, object]:
     proposal without translation. Fields that are empty/default are
     omitted so the agent doesn't copy irrelevant keys."""
     d: dict[str, object] = {"host": r.host}
+    if not r.inspect:
+        d["inspect"] = False
+        return d
+    inspected: dict[str, object] = {}
     if r.auth_scheme:
-        d["auth_scheme"] = r.auth_scheme
-        d["token_env"] = r.token_env
+        inspected["auth_scheme"] = r.auth_scheme
+        inspected["token_env"] = r.token_env
     if r.matches:
-        d["matches"] = [_match_entry_to_dict(m) for m in r.matches]
+        inspected["matches"] = [_match_entry_to_dict(m) for m in r.matches]
     if r.git_fetch:
-        d["git"] = {"fetch": True}
-    dlp: dict[str, object] = {}
+        inspected["git"] = {"fetch": True}
     if r.outbound_detectors is not None:
-        dlp["outbound_detectors"] = list(r.outbound_detectors)
+        inspected["outbound_detectors"] = list(r.outbound_detectors)
     if r.inbound_detectors is not None:
-        dlp["inbound_detectors"] = list(r.inbound_detectors)
+        inspected["inbound_detectors"] = list(r.inbound_detectors)
     if r.outbound_on_match:
-        dlp["outbound_on_match"] = r.outbound_on_match
-    if dlp:
-        d["dlp"] = dlp
+        inspected["outbound_on_match"] = r.outbound_on_match
+    if r.preserve_auth:
+        inspected["preserve_auth"] = True
+    if inspected:
+        d["inspect"] = inspected
     return d
 
 
@@ -405,16 +459,40 @@ class PolicyResolverLike(typing.Protocol):
         ...
 
 
+# Deny-all explanations. Each names the *actual* failure so an operator isn't
+# sent looking for a missing egress route when the bottle never had a policy
+# to begin with — the failure mode that made a bricked registration read like
+# a misconfigured allowlist.
+DENY_UNATTRIBUTED = (
+    "egress: this request was not attributed to any bottle, so no egress "
+    "policy applies and every host is denied. Either the bottle's registry "
+    "row is missing/ambiguous (torn down, or another bottle claimed its "
+    "source IP), or the request carried no matching identity token — check "
+    "that the caller's proxy URL includes it. This is not an allowlist problem."
+)
+DENY_UNPARSEABLE = (
+    "egress: this bottle's egress policy could not be parsed, so it is being "
+    "treated as deny-all. Fix the bottle's egress.routes; every host is denied "
+    "until it loads."
+)
+DENY_RESOLVER_ERROR = (
+    "egress: the orchestrator could not be reached to resolve this bottle's "
+    "egress policy, so every host is denied (fail-closed). Check that the "
+    "control plane is up; this is not an allowlist problem."
+)
+
+
 def _config_from_policy(policy: "str | None") -> "Config":
     """Parse a resolved policy blob into a Config, fail-closed: None / empty /
     unparseable all become a deny-all Config (no routes → every request
-    blocked)."""
+    blocked). Each deny-all carries the reason it is one, so the block message
+    names the real fault instead of blaming the allowlist."""
     if not policy:
-        return Config(routes=())  # unattributed or empty → deny-all
+        return Config(routes=(), deny_reason=DENY_UNATTRIBUTED)
     try:
         return load_config(policy)
     except ValueError:
-        return Config(routes=())  # unparseable policy → deny
+        return Config(routes=(), deny_reason=DENY_UNPARSEABLE)
 
 
 def resolve_client_config(
@@ -428,7 +506,7 @@ def resolve_client_config(
     try:
         policy = resolver.resolve(client_ip, identity_token)
     except Exception:  # noqa: BLE001  # pylint: disable=broad-exception-caught
-        return Config(routes=())  # orchestrator unreachable/errored → deny
+        return Config(routes=(), deny_reason=DENY_RESOLVER_ERROR)
     return _config_from_policy(policy)
 
 
@@ -457,7 +535,7 @@ def resolve_client_context(
             client_ip, identity_token,
         )
     except Exception:  # noqa: BLE001  # pylint: disable=broad-exception-caught
-        return Config(routes=()), "", {}  # orchestrator unreachable/errored → deny
+        return Config(routes=(), deny_reason=DENY_RESOLVER_ERROR), "", {}
     return _config_from_policy(policy), (bottle_id or ""), tokens
 
 
@@ -572,12 +650,16 @@ def decide(
     *,
     request_method: str = "GET",
     request_headers: typing.Mapping[str, str] | None = None,
+    deny_reason: str = "",
 ) -> Decision:
+    """`deny_reason` is `Config.deny_reason`: when the deny-all came from a
+    missing/unparseable policy rather than the bottle's own allowlist, report
+    that instead of implying a route is merely absent."""
     route = match_route(routes, request_host)
     if route is None:
         return Decision(
             action="block",
-            reason=(
+            reason=deny_reason or (
                 f"egress: host {request_host!r} is not in the "
                 f"bottle's egress.routes allowlist. Declare a "
                 f"route for it or remove the request."
@@ -711,6 +793,8 @@ def scan_outbound(
     safe_tokens: typing.AbstractSet[str] | None = None,
     crlf_text: str | None = None,
 ) -> ScanResult | None:
+    if not route.inspect:
+        return None
     # Lazy import to avoid circular deps and keep dlp_detectors optional
     # at import time (the gateway copies it flat alongside this file).
     try:
@@ -808,6 +892,8 @@ def scan_inbound(
     route: Route,
     body: str | bytes,
 ) -> ScanResult | None:
+    if not route.inspect:
+        return None
     try:
         from dlp_detectors import scan_naive_injection  # type: ignore[import-not-found]
     except ImportError:  # pragma: no cover - host-side path
@@ -835,7 +921,7 @@ __all__ = [
     "DEFAULT_OUTBOUND_ON_MATCH",
     "OUTBOUND_DETECTOR_NAMES",
     "INBOUND_DETECTOR_NAMES",
-    "parse_dlp_block",
+    "parse_inspect_block",
     "Config",
     "Decision",
     "HeaderMatch",
@@ -852,6 +938,9 @@ __all__ = [
     "is_git_push_request",
     "is_git_fetch_request",
     "load_config",
+    "DENY_UNATTRIBUTED",
+    "DENY_UNPARSEABLE",
+    "DENY_RESOLVER_ERROR",
     "resolve_client_config",
     "resolve_client_context",
     "PolicyResolverLike",

bot_bottle/egress_dlp_config.py

@@ -1,6 +1,6 @@
-"""DLP detector-config parsing for egress routes (PRD 0053, PRD 0062).
+"""Inspection and DLP configuration parsing for egress routes.
 
-A route's optional `dlp:` block names which outbound/inbound detectors run
+A route's optional `inspect:` object names which outbound/inbound detectors run
 and what the proxy does when an outbound detector matches a token
 (`outbound_on_match`). This module owns parsing and validating that block,
 kept apart from the request-time scan/decision flow in `egress_addon_core`
@@ -26,20 +26,14 @@ OUTBOUND_ON_MATCH_VALUES = (ON_MATCH_BLOCK, ON_MATCH_REDACT, ON_MATCH_SUPERVISE)
 DEFAULT_OUTBOUND_ON_MATCH = ON_MATCH_SUPERVISE
 
 
-def parse_dlp_block(
+def parse_inspect_block(
     idx: int,
     host: str,
-    raw_dict: dict[str, object],
+    inspect: dict[str, object],
 ) -> tuple[tuple[str, ...] | None, tuple[str, ...] | None, str]:
-    """Parse the optional `dlp` block on a route, returning
-    (outbound_detectors, inbound_detectors, outbound_on_match)."""
-    dlp_raw = raw_dict.get("dlp")
-    if dlp_raw is None:
-        return None, None, ""
+    """Parse DLP settings from an inspected route."""
     label = f"route[{idx}] ({host})"
-    if not isinstance(dlp_raw, dict):
-        raise ValueError(f"{label}: 'dlp' must be an object")
-    dlp = typing.cast(dict[str, object], dlp_raw)
+    dlp = inspect
 
     def _parse_detector_field(
         field: str,
@@ -52,18 +46,18 @@ def parse_dlp_block(
             return ()
         if not isinstance(val, list):
             raise ValueError(
-                f"{label}: dlp.{field} must be false, a list, or omitted"
+                f"{label}: inspect.{field} must be false, a list, or omitted"
             )
         items = typing.cast(list[object], val)
         names: list[str] = []
         for j, item in enumerate(items):
             if not isinstance(item, str):
                 raise ValueError(
-                    f"{label}: dlp.{field}[{j}] must be a string"
+                    f"{label}: inspect.{field}[{j}] must be a string"
                 )
             if item not in valid_names:
                 raise ValueError(
-                    f"{label}: dlp.{field}[{j}] {item!r} is not a valid "
+                    f"{label}: inspect.{field}[{j}] {item!r} is not a valid "
                     f"detector name; valid names: {', '.join(sorted(valid_names))}"
                 )
             names.append(item)
@@ -77,16 +71,9 @@ def parse_dlp_block(
     if on_match_raw is not None:
         if not isinstance(on_match_raw, str) or on_match_raw not in OUTBOUND_ON_MATCH_VALUES:
             raise ValueError(
-                f"{label}: dlp.outbound_on_match must be one of "
+                f"{label}: inspect.outbound_on_match must be one of "
                 f"{', '.join(OUTBOUND_ON_MATCH_VALUES)} (got {on_match_raw!r})"
             )
         on_match = on_match_raw
 
-    for k in dlp:
-        if k not in ("outbound_detectors", "inbound_detectors", "outbound_on_match"):
-            raise ValueError(
-                f"{label}: dlp has unknown key {k!r}; accepted keys "
-                f"are 'outbound_detectors', 'inbound_detectors', "
-                f"'outbound_on_match'"
-            )
     return outbound, inbound, on_match

bot_bottle/image_cache.py

@@ -0,0 +1,42 @@
+"""Shared helpers for cached-image quickstart stale checks."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from pathlib import Path
+
+try:
+    from .config_store import ConfigStore
+except ImportError:
+    from config_store import ConfigStore  # type: ignore[import-not-found]  # pylint: disable=import-error,no-name-in-module
+
+
+class StaleImageError(Exception):
+    """Raised when a cached image or artifact exceeds the configured staleness
+    threshold. Callers can catch this to prompt interactively; headless paths
+    let it propagate as a fatal error."""
+
+
+def check_stale(label: str, created_at: datetime) -> None:
+    """Raise StaleImageError if `created_at` is older than the configured
+    stale-warning threshold. Negative threshold disables the check."""
+    threshold_days = ConfigStore().cached_image_stale_warning_days()
+    if threshold_days < 0:
+        return
+    now = datetime.now(timezone.utc)
+    created = created_at.astimezone(timezone.utc)
+    age = now - created
+    if age.total_seconds() <= threshold_days * 86400:
+        return
+    raise StaleImageError(
+        f"cached {label} is {age.days} day(s) old; "
+        "quickstart does not verify it matches the current Dockerfile/context"
+    )
+
+
+def check_stale_path(label: str, path: Path) -> None:
+    """Raise StaleImageError if `path`'s mtime exceeds the staleness threshold."""
+    check_stale(label, datetime.fromtimestamp(path.stat().st_mtime, tz=timezone.utc))
+
+
+__all__ = ["StaleImageError", "check_stale", "check_stale_path"]

bot_bottle/manifest.py

@@ -20,6 +20,7 @@ Bottle schema (frontmatter):
   egress: { routes: [ <egress-route>, ... ] }
     # route keys: host, matches, auth, role, dlp
   supervise:    <bool>                          # optional (default true)
+  nested_containers: <bool>                     # optional (default false)
 
 Agent schema (frontmatter):
   bottle:        <bottle-name>          # required

bot_bottle/manifest_agent.py

@@ -25,8 +25,9 @@ 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 Codex auth token into
-    the egress daemon (Codex only).
+    `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`.
     """
 
     template: str = "claude"
@@ -92,10 +93,15 @@ class ManifestAgentProvider:
                 f"is only supported for built-in templates "
                 f"({', '.join(sorted(PROVIDER_TEMPLATES))})"
             )
-        if forward_host_credentials and template != "codex":
+        if forward_host_credentials and template not in {"codex", "claude"}:
             raise ManifestError(
                 f"bottle '{bottle_name}' agent_provider.forward_host_credentials "
-                "is currently only supported for template 'codex'"
+                "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"
             )
         settings = _parse_provider_settings(bottle_name, template, d.get("settings"))
         return cls(

bot_bottle/manifest_bottle.py

@@ -44,6 +44,15 @@ class ManifestBottle:
     # daemon that exposes egress MCP tools to the agent. Set
     # `supervise: false` to skip the gateway.
     supervise: bool = True
+    # Guest-local container engine (issue #392). Not a host-daemon grant:
+    # backends implement it inside the bottle or reject it. Gated because it
+    # costs image weight, a resident service, and relaxed guest device modes
+    # that the majority of bottles never need.
+    nested_containers: bool = False
+    # Source fields retained across extends/runtime composition. Boolean
+    # defaults otherwise erase the distinction between "omitted" and an
+    # explicitly declared value (especially False).
+    declared_fields: frozenset[str] = frozenset()
 
     @classmethod
     def from_dict(cls, name: str, raw: object) -> "ManifestBottle":
@@ -123,7 +132,16 @@ class ManifestBottle:
                 f"(was {type(supervise_raw).__name__})"
             )
 
+        nested_raw = d.get("nested_containers", False)
+        if not isinstance(nested_raw, bool):
+            raise ManifestError(
+                f"bottle '{name}' nested_containers must be a boolean "
+                f"(was {type(nested_raw).__name__})"
+            )
+
         return cls(
             env=env, agent_provider=agent_provider, git=git,
             git_user=git_user, egress=egress, supervise=supervise_raw,
+            nested_containers=nested_raw,
+            declared_fields=frozenset(d),
         )

bot_bottle/manifest_egress.py

@@ -71,6 +71,8 @@ class ManifestEgressRoute:
     OutboundDetectors: tuple[str, ...] | None = None
     InboundDetectors: tuple[str, ...] | None = None
     OutboundOnMatch: str = ""
+    PreserveAuth: bool = False
+    Inspect: bool = True
 
     @classmethod
     def from_dict(cls, bottle_name: str, idx: int, raw: object) -> "ManifestEgressRoute":
@@ -80,9 +82,17 @@ class ManifestEgressRoute:
         if not isinstance(host, str) or not host:
             raise ManifestError(f"{label} missing required string field 'host'")
 
+        inspect_raw = d.get("inspect", {})
+        if inspect_raw is False:
+            inspect = False
+            inspect_d: dict[str, object] = {}
+        else:
+            inspect = True
+            inspect_d = as_json_object(inspect_raw, f"{label} inspect")
+
         # --- matches ---
         matches: tuple[ManifestMatchEntry, ...] = ()
-        matches_raw = d.get("matches")
+        matches_raw = inspect_d.get("matches")
         if matches_raw is not None:
             if not isinstance(matches_raw, list):
                 raise ManifestError(
@@ -100,9 +110,9 @@ class ManifestEgressRoute:
         # --- auth ---
         auth_scheme = ""
         token_ref = ""
-        if "auth" in d:
-            auth_raw = d.get("auth")
-            auth_d = as_json_object(auth_raw, f"{label} auth")
+        if "auth" in inspect_d:
+            auth_raw = inspect_d.get("auth")
+            auth_d = as_json_object(auth_raw, f"{label} inspect.auth")
             if not auth_d:
                 raise ManifestError(
                     f"{label} auth is empty ({{}}); omit the 'auth' key "
@@ -162,19 +172,19 @@ class ManifestEgressRoute:
                 f"the 'role' field is reserved for future use"
             )
 
-        # --- dlp ---
+        # --- DLP settings (inspection-only) ---
         outbound_detectors: tuple[str, ...] | None = None
         inbound_detectors: tuple[str, ...] | None = None
         outbound_on_match = ""
-        if "dlp" in d:
-            outbound_detectors, inbound_detectors, outbound_on_match = _parse_dlp_block(
-                label, d.get("dlp"),
+        if inspect:
+            outbound_detectors, inbound_detectors, outbound_on_match = _parse_inspect_block(
+                label, inspect_d,
             )
 
         # --- git-over-HTTPS policy ---
         git_fetch = False
-        if "git" in d:
-            git_d = as_json_object(d.get("git"), f"{label} git")
+        if "git" in inspect_d:
+            git_d = as_json_object(inspect_d.get("git"), f"{label} inspect.git")
             raw_fetch = git_d.get("fetch", False)
             if isinstance(raw_fetch, bool):
                 git_fetch = raw_fetch
@@ -190,11 +200,33 @@ class ManifestEgressRoute:
                         f"only 'fetch' is accepted"
                     )
 
+        # --- preserve_auth ---
+        preserve_auth = False
+        if "preserve_auth" in inspect_d:
+            raw_preserve_auth = inspect_d.get("preserve_auth")
+            if not isinstance(raw_preserve_auth, bool):
+                raise ManifestError(
+                    f"{label} preserve_auth must be a boolean "
+                    f"(was {type(raw_preserve_auth).__name__})"
+                )
+            preserve_auth = raw_preserve_auth
+
+        for k in inspect_d:
+            if k not in (
+                "matches", "auth", "git", "preserve_auth",
+                "outbound_detectors", "inbound_detectors", "outbound_on_match",
+            ):
+                raise ManifestError(
+                    f"{label} inspect has unknown key {k!r}; accepted keys are "
+                    f"'matches', 'auth', 'git', 'preserve_auth', "
+                    f"'outbound_detectors', 'inbound_detectors', "
+                    f"'outbound_on_match'"
+                )
         for k in d:
-            if k not in ("host", "matches", "auth", "role", "dlp", "git"):
+            if k not in ("host", "role", "inspect"):
                 raise ManifestError(
                     f"{label} has unknown key {k!r}; accepted keys are "
-                    f"'host', 'matches', 'auth', 'role', 'dlp', 'git'"
+                    f"'host', 'role', and 'inspect'"
                 )
 
         return cls(
@@ -207,6 +239,8 @@ class ManifestEgressRoute:
             OutboundDetectors=outbound_detectors,
             InboundDetectors=inbound_detectors,
             OutboundOnMatch=outbound_on_match,
+            PreserveAuth=preserve_auth,
+            Inspect=inspect,
         )
 
 
@@ -326,12 +360,13 @@ def _parse_header_match(
     return ManifestHeaderMatch(Name=name, Value=value, Type=htype)
 
 
-def _parse_dlp_block(
+def _parse_inspect_block(
     route_label: str,
-    raw: object,
+    inspect: dict[str, object],
 ) -> tuple[tuple[str, ...] | None, tuple[str, ...] | None, str]:
-    label = f"{route_label} dlp"
-    d = as_json_object(raw, label)
+    """Parse DLP settings from an inspected route."""
+    label = f"{route_label} inspect"
+    d = inspect
 
     def _parse_field(
         field: str,
@@ -374,13 +409,6 @@ def _parse_dlp_block(
             )
         on_match = on_match_raw
 
-    for k in d:
-        if k not in ("outbound_detectors", "inbound_detectors", "outbound_on_match"):
-            raise ManifestError(
-                f"{label} has unknown key {k!r}; accepted keys are "
-                f"'outbound_detectors', 'inbound_detectors', "
-                f"'outbound_on_match'"
-            )
     return outbound, inbound, on_match
 
 

bot_bottle/manifest_extends.py

@@ -8,6 +8,17 @@ from .manifest_git import ManifestGitUser, parse_git_gate_config
 from .manifest_util import ManifestError, as_json_object
 
 
+def _overlay_declared_bool(
+    base: ManifestBottle,
+    override: ManifestBottle,
+    field: str,
+) -> bool:
+    """Overlay a defaulted boolean only when override declared it."""
+    value = getattr(override if field in override.declared_fields else base, field)
+    assert isinstance(value, bool)
+    return value
+
+
 def merge_bottles_runtime(bottles: "list[ManifestBottle]") -> "ManifestBottle":
     """Merge an ordered list of pre-resolved ManifestBottle objects.
 
@@ -15,7 +26,13 @@ def merge_bottles_runtime(bottles: "list[ManifestBottle]") -> "ManifestBottle":
     the same field-merge rules as the file-based extends machinery:
       env: dict merge, later wins; git_user: per-field overlay, later
       wins on non-empty; git (repos): union by name, later wins; egress
-      routes: concatenate; agent_provider, supervise: later replaces.
+      routes: concatenate; agent_provider, supervise, nested_containers:
+      later replaces (presence-aware).
+
+    Defaulted booleans use presence-aware replacement: if the later bottle
+    was loaded from a source that explicitly declared the key, its value
+    wins (so an explicit `false` can override an earlier `true`). If the
+    later bottle never mentioned the key, the earlier value is preserved.
     """
     if not bottles:
         raise ValueError("merge_bottles_runtime requires at least one bottle")
@@ -53,7 +70,11 @@ def _merge_two_bottles_runtime(base: "ManifestBottle", override: "ManifestBottle
         git=merged_git,
         git_user=merged_git_user,
         egress=merged_egress,
-        supervise=override.supervise,
+        supervise=_overlay_declared_bool(base, override, "supervise"),
+        nested_containers=_overlay_declared_bool(
+            base, override, "nested_containers"
+        ),
+        declared_fields=base.declared_fields | override.declared_fields,
     )
 
 
@@ -205,7 +226,11 @@ def _fold_two_bottles(
         git=merged_git,
         git_user=merged_git_user,
         egress=merged_egress,
-        supervise=later.supervise,
+        supervise=_overlay_declared_bool(earlier, later, "supervise"),
+        nested_containers=_overlay_declared_bool(
+            earlier, later, "nested_containers"
+        ),
+        declared_fields=earlier.declared_fields | later.declared_fields,
     ), merged_repos_raw
 
 
@@ -263,8 +288,9 @@ def _merge_bottles(
         if "agent_provider" in child_raw
         else parent.agent_provider
     )
-    merged_supervise = (
-        child.supervise if "supervise" in child_raw else parent.supervise
+    merged_supervise = _overlay_declared_bool(parent, child, "supervise")
+    merged_nested_containers = _overlay_declared_bool(
+        parent, child, "nested_containers"
     )
     validate_egress_routes(name, merged_egress.routes)
 
@@ -275,6 +301,8 @@ def _merge_bottles(
         git_user=merged_git_user,
         egress=merged_egress,
         supervise=merged_supervise,
+        nested_containers=merged_nested_containers,
+        declared_fields=parent.declared_fields | child.declared_fields,
     )
 
 

bot_bottle/manifest_schema.py

@@ -16,7 +16,10 @@ _FILENAME_RX = re.compile(r"^[a-z][a-z0-9-]*$")
 # sets dies with a "did you mean" pointer: typos should not silently
 # ghost into an empty config.
 BOTTLE_KEYS = frozenset(
-    {"env", "extends", "agent_provider", "git-gate", "egress", "supervise"}
+    {
+        "env", "extends", "agent_provider", "git-gate", "egress",
+        "supervise", "nested_containers",
+    }
 )
 AGENT_KEYS_REQUIRED: frozenset[str] = frozenset()
 AGENT_KEYS_OPTIONAL = frozenset({"bottle", "skills", "git-gate"})

bot_bottle/orchestrator/client.py

@@ -15,6 +15,7 @@ from __future__ import annotations
 import json
 import urllib.error
 import urllib.request
+from collections.abc import Iterable
 from dataclasses import dataclass
 
 from ..paths import host_control_plane_token
@@ -40,10 +41,13 @@ class OrchestratorClientError(RuntimeError):
 @dataclass(frozen=True)
 class RegisteredBottle:
     """What `POST /bottles` returns: the minted bottle id and the per-bottle
-    identity token the agent presents for app-layer attribution."""
+    identity token the agent presents for app-layer attribution. `env_var_secret`
+    is set by the caller (not from the server response) and carries the
+    encryption key so it can be injected into the agent container's env."""
 
     bottle_id: str
     identity_token: str
+    env_var_secret: str = ""
 
 
 class OrchestratorClient:
@@ -119,17 +123,21 @@ class OrchestratorClient:
         metadata: str = "",
         policy: str = "",
         tokens: dict[str, str] | None = None,
+        env_var_secret: str = "",
     ) -> RegisteredBottle:
         """Register a bottle and broker its launch (`POST /bottles`). `tokens`
         are the per-bottle egress auth values (env_name -> value) the
-        orchestrator holds in memory for the gateway to inject. Returns the
-        minted id + identity token."""
+        orchestrator holds in memory for the gateway to inject. When
+        *env_var_secret* is provided, the orchestrator also encrypts the token
+        values and stores them in ``bottled_agent_secrets`` for restart
+        recovery. Returns the minted id + identity token."""
         payload = self._ok("POST", "/bottles", {
             "source_ip": source_ip,
             "image_ref": image_ref,
             "metadata": metadata,
             "policy": policy,
             "tokens": tokens or {},
+            "env_var_secret": env_var_secret,
         })
         bottle_id = payload.get("bottle_id")
         token = payload.get("identity_token")
@@ -137,6 +145,24 @@ class OrchestratorClient:
             raise OrchestratorClientError("register: response missing bottle_id/identity_token")
         return RegisteredBottle(bottle_id=bottle_id, identity_token=token)
 
+    def reprovision_gateway(self, bottle_id: str, env_var_secret: str) -> bool:
+        """Re-inject a bottle's egress tokens from its ENV_VAR_SECRET
+        (`POST /bottles/<id>/reprovision_gateway`). Returns True when the
+        orchestrator successfully decrypted and restored the tokens, False
+        when it had no stored secrets for this bottle (404)."""
+        status, _ = self._request(
+            "POST",
+            f"/bottles/{bottle_id}/reprovision_gateway",
+            {"env_var_secret": env_var_secret},
+        )
+        if status == 404:
+            return False
+        if not 200 <= status < 300:
+            raise OrchestratorClientError(
+                f"reprovision_gateway {bottle_id}: HTTP {status}"
+            )
+        return True
+
     def teardown_bottle(self, bottle_id: str) -> bool:
         """Tear a bottle down (`DELETE /bottles/<id>`). False if the
         orchestrator didn't know it (404) — idempotent for cleanup paths."""
@@ -147,6 +173,20 @@ class OrchestratorClient:
             raise OrchestratorClientError(f"teardown {bottle_id}: HTTP {status}")
         return True
 
+    def reconcile(
+        self, live_source_ips: Iterable[str], *, grace_seconds: float | None = None,
+    ) -> list[str]:
+        """Drop registry rows for bottles that are no longer running
+        (`POST /reconcile`), returning the reaped bottle ids. `live_source_ips`
+        is the caller's enumeration of its live bottles — the orchestrator
+        can't see the backend from inside the infra container."""
+        body: dict[str, object] = {"live_source_ips": list(live_source_ips)}
+        if grace_seconds is not None:
+            body["grace_seconds"] = grace_seconds
+        payload = self._ok("POST", "/reconcile", body)
+        reaped = payload.get("reaped")
+        return [r for r in reaped if isinstance(r, str)] if isinstance(reaped, list) else []
+
     def set_policy(self, bottle_id: str, policy: str) -> bool:
         """Live-reload a bottle's policy (`PUT /bottles/<id>/policy`). False on
         404 (unknown bottle)."""

bot_bottle/orchestrator/config_store.py

@@ -0,0 +1,107 @@
+"""Per-host orchestrator configuration store (settings in bot-bottle.db).
+
+Co-tenants the shared `bot-bottle.db` via the `DbStore` framework.  Settings
+are readable by the host launch path directly (no HTTP round-trip to the
+orchestrator), so they take effect even before the orchestrator is reachable.
+"""
+
+from __future__ import annotations
+
+import os
+import sqlite3
+from pathlib import Path
+
+from ..db_store import DbStore
+from ..migrations import TableMigrations
+from ..paths import host_db_path
+
+TEARDOWN_TIMEOUT_ENV = "BOT_BOTTLE_ORCHESTRATOR_TEARDOWN_TIMEOUT_SECONDS"
+DEFAULT_TEARDOWN_TIMEOUT_SECONDS = 30.0
+
+_MIGRATIONS = TableMigrations(
+    "orchestrator_config",
+    [
+        """
+        CREATE TABLE IF NOT EXISTS orchestrator_config (
+            id                       INTEGER PRIMARY KEY CHECK (id = 1),
+            teardown_timeout_seconds REAL
+        )
+        """,
+    ],
+)
+
+
+class OrchestratorConfigStore(DbStore):
+    """Orchestrator settings in the shared host DB."""
+
+    def __init__(self, db_path: Path | None = None) -> None:
+        super().__init__(db_path or host_db_path(), _MIGRATIONS)
+
+    def _connect(self) -> sqlite3.Connection:
+        conn = super()._connect()
+        conn.execute("PRAGMA busy_timeout=5000")
+        return conn
+
+    def get_teardown_timeout_seconds(self) -> float | None:
+        """Return the configured teardown timeout, or None if not set."""
+        try:
+            with self._connection() as conn:
+                row = conn.execute(
+                    "SELECT teardown_timeout_seconds FROM orchestrator_config WHERE id = 1"
+                ).fetchone()
+        except sqlite3.OperationalError:
+            return None
+        return row["teardown_timeout_seconds"] if row else None
+
+    def set_teardown_timeout_seconds(self, value: float) -> None:
+        """Persist the teardown timeout."""
+        with self._connection() as conn:
+            conn.execute(
+                "INSERT OR REPLACE INTO orchestrator_config"
+                " (id, teardown_timeout_seconds) VALUES (1, ?)",
+                (value,),
+            )
+        self._chmod()
+
+    def delete_teardown_timeout_seconds(self) -> bool:
+        """Clear the stored teardown timeout. Returns True if a value existed."""
+        with self._connection() as conn:
+            cur = conn.execute(
+                "UPDATE orchestrator_config SET teardown_timeout_seconds = NULL"
+                " WHERE id = 1 AND teardown_timeout_seconds IS NOT NULL"
+            )
+        return cur.rowcount > 0
+
+
+def resolve_teardown_timeout(db_path: Path | None = None) -> float:
+    """Return the teardown timeout to use, in priority order:
+
+    1. ``BOT_BOTTLE_ORCHESTRATOR_TEARDOWN_TIMEOUT_SECONDS`` env var
+    2. ``teardown_timeout_seconds`` in the orchestrator config DB
+    3. ``DEFAULT_TEARDOWN_TIMEOUT_SECONDS`` (30 s)
+    """
+    raw = os.environ.get(TEARDOWN_TIMEOUT_ENV, "").strip()
+    if raw:
+        try:
+            value = float(raw)
+            if value > 0:
+                return value
+        except ValueError:
+            pass
+
+    store = OrchestratorConfigStore(db_path)
+    if not store.is_migrated():
+        store.migrate()
+    db_value = store.get_teardown_timeout_seconds()
+    if db_value is not None and db_value > 0:
+        return db_value
+
+    return DEFAULT_TEARDOWN_TIMEOUT_SECONDS
+
+
+__all__ = [
+    "OrchestratorConfigStore",
+    "resolve_teardown_timeout",
+    "TEARDOWN_TIMEOUT_ENV",
+    "DEFAULT_TEARDOWN_TIMEOUT_SECONDS",
+]

bot_bottle/orchestrator/control_plane.py

@@ -9,10 +9,17 @@ vsock / unix-socket portability caveats):
     GET    /bottles                   -> 200 {"bottles": [ <redacted record>, ...]}
     POST   /bottles                   -> 201 {"bottle_id","identity_token"}  (launch)
                                          body: {"source_ip", ["image_ref"],
-                                                ["metadata"], ["policy"]}
+                                                ["metadata"], ["policy"],
+                                                ["tokens"], ["env_var_secret"]}
     PUT    /bottles/<bottle_id>/policy -> 200 {"updated": true} | 404  (live reload)
                                          body: {"policy"}
+    POST   /bottles/<bottle_id>/reprovision_gateway
+                                      -> 200 {"reprovisioned": true} | 404
+                                         body: {"env_var_secret"}
     DELETE /bottles/<bottle_id>        -> 200 {"torn_down": true} | 404  (teardown)
+    POST   /reconcile                 -> 200 {"reaped": [bottle_id, ...]}
+                                         body: {"live_source_ips": [...],
+                                                ["grace_seconds"]}
     POST   /attribute                 -> 200 {"bottle_id"} | 403
     POST   /resolve                   -> 200 {"bottle_id","policy"} | 403
                                          body: {"source_ip","identity_token"}
@@ -113,12 +120,14 @@ def dispatch(  # pylint: disable=too-many-return-statements,too-many-branches
         tokens = {
             k: v for k, v in raw_tokens.items() if isinstance(k, str) and isinstance(v, str)
         } if isinstance(raw_tokens, dict) else {}
+        env_var_secret = data.get("env_var_secret", "")
         rec = orch.launch_bottle(
             source_ip,
             image_ref=image_ref if isinstance(image_ref, str) else "",
             metadata=metadata if isinstance(metadata, str) else "",
             policy=policy if isinstance(policy, str) else "",
             tokens=tokens,
+            env_var_secret=env_var_secret if isinstance(env_var_secret, str) else "",
         )
         return 201, {"bottle_id": rec.bottle_id, "identity_token": rec.identity_token}
 
@@ -135,12 +144,50 @@ def dispatch(  # pylint: disable=too-many-return-statements,too-many-branches
             return 200, {"updated": True}
         return 404, {"error": "no such bottle"}
 
+    if (
+        method == "POST"
+        and route.startswith("/bottles/")
+        and route.endswith("/reprovision_gateway")
+    ):
+        bottle_id = route[len("/bottles/") : -len("/reprovision_gateway")]
+        try:
+            data = _parse_json_object(body)
+        except ValueError as e:
+            return 400, {"error": f"invalid JSON: {e}"}
+        env_var_secret = data.get("env_var_secret")
+        if not isinstance(env_var_secret, str) or not env_var_secret:
+            return 400, {"error": "env_var_secret (string) is required"}
+        if orch.reprovision_from_secret(bottle_id, env_var_secret):
+            return 200, {"reprovisioned": True}
+        return 404, {"error": "no stored secrets for this bottle"}
+
     if method == "DELETE" and route.startswith("/bottles/"):
         bottle_id = route[len("/bottles/"):]
         if orch.teardown_bottle(bottle_id):
             return 200, {"torn_down": True}
         return 404, {"error": "no such bottle"}
 
+    if method == "POST" and route == "/reconcile":
+        # Host-driven self-heal: the caller enumerates its live bottles (only
+        # the host can see the backend) and the orchestrator drops rows for
+        # every other active bottle. Trusted-caller only — an agent that could
+        # reach this would be able to unregister its neighbours.
+        try:
+            data = _parse_json_object(body)
+        except ValueError as e:
+            return 400, {"error": f"invalid JSON: {e}"}
+        raw_ips = data.get("live_source_ips")
+        if not isinstance(raw_ips, list):
+            return 400, {"error": "live_source_ips (list of strings) is required"}
+        live = [ip for ip in raw_ips if isinstance(ip, str) and ip]
+        grace = data.get("grace_seconds")
+        kwargs = (
+            {"grace_seconds": float(grace)}
+            if isinstance(grace, (int, float)) and not isinstance(grace, bool)
+            else {}
+        )
+        return 200, {"reaped": orch.reconcile(live, **kwargs)}
+
     if method == "POST" and route == "/attribute":
         try:
             data = _parse_json_object(body)

bot_bottle/orchestrator/gateway.py

@@ -27,6 +27,7 @@ from ..paths import (
     CONTROL_PLANE_TOKEN_ENV,
     host_control_plane_token,
     host_db_path,
+    host_gateway_ca_dir,
 )
 from ..supervise import DB_PATH_IN_CONTAINER
 
@@ -48,14 +49,23 @@ GATEWAY_LABEL = "bot-bottle-orch-gateway=1"
 # the source IP the gateway attributes by is the address on this network.
 GATEWAY_NETWORK = "bot-bottle-gateway"
 
-# mitmproxy's CA dir in the bundle. A persistent named volume here keeps the
-# gateway's self-generated CA STABLE across container recreation — every agent
-# installs this one CA to trust the shared gateway's TLS interception, so it
-# must not rotate when the gateway restarts.
+# mitmproxy's CA dir in the bundle. The host's gateway-CA dir (see
+# `host_gateway_ca_dir`) is bind-mounted here so the gateway's self-generated
+# CA stays STABLE across container recreation — every agent installs this one
+# CA to trust the shared gateway's TLS interception, so it must not rotate when
+# the gateway restarts. A host bind-mount rather than a named volume: a named
+# volume is silently wiped by `docker volume prune`, minting a fresh CA that
+# breaks every running bottle (issue #450).
 MITMPROXY_HOME = "/home/mitmproxy/.mitmproxy"
-GATEWAY_CA_VOLUME = "bot-bottle-gateway-mitmproxy"
 GATEWAY_CA_CERT = f"{MITMPROXY_HOME}/mitmproxy-ca-cert.pem"
 
+# The CA material mitmproxy writes into its confdir. mitmproxy reuses these on
+# startup when present and generates them only on first run, so persisting them
+# is what makes the CA stable; deleting them (see `rotate_gateway_ca`) forces a
+# fresh CA on the next start. `mitmproxy-ca.pem` (cert + private key) is the
+# signing identity; the rest are derived encodings agents/clients consume.
+GATEWAY_CA_GLOB = "mitmproxy-ca*"
+
 # The gateway data-plane image + its Dockerfile. Kept as a local constant
 # rather than imported from the backend layer, which would drag
 # the whole backend layer into the lean orchestrator (see #359); unify when
@@ -73,6 +83,26 @@ def _host_db_dir() -> str:
     return str(db_dir)
 
 
+def rotate_gateway_ca(ca_dir: Path | None = None) -> list[Path]:
+    """Delete the persisted mitmproxy CA so the next gateway start mints a
+    fresh one — the explicit, deliberate CA-rollover path (issue #450).
+
+    Persistence keeps the CA stable across restarts precisely because mitmproxy
+    reuses the on-disk CA; rotation is therefore just removing that material.
+    Returns the files removed (empty when there was no CA yet); idempotent.
+
+    This only clears the on-disk CA. It does NOT stop the running gateway (whose
+    mitmproxy still holds the old CA in memory) or re-provision agents — the
+    caller recreates the gateway to mint the new CA and re-attaches bottles.
+    `rotate-ca` on the orchestrator CLI wires those steps together."""
+    ca_dir = ca_dir if ca_dir is not None else host_gateway_ca_dir()
+    removed: list[Path] = []
+    for path in sorted(ca_dir.glob(GATEWAY_CA_GLOB)):
+        path.unlink()
+        removed.append(path)
+    return removed
+
+
 class GatewayError(Exception):
     """The shared gateway failed to build/start/stop (non-zero `docker` exit)."""
 
@@ -221,9 +251,10 @@ class DockerGateway(Gateway):
             "--name", self.name,
             "--label", GATEWAY_LABEL,
             "--network", self.network,
-            # Persist the self-generated CA so it survives restarts (agents
-            # trust it) — see GATEWAY_CA_VOLUME.
-            "--volume", f"{GATEWAY_CA_VOLUME}:{MITMPROXY_HOME}",
+            # Persist the self-generated CA on the host so it survives both
+            # container recreation AND docker volume pruning (agents trust it)
+            # — see host_gateway_ca_dir / issue #450.
+            "--volume", f"{host_gateway_ca_dir()}:{MITMPROXY_HOME}",
             # Share the one host DB: the supervise daemon queues proposals
             # into the same file the orchestrator (and the operator, over
             # HTTP) reads — no second, disconnected DB in the container.
@@ -272,7 +303,7 @@ class DockerGateway(Gateway):
 
 
 __all__ = [
-    "Gateway", "DockerGateway", "GatewayError",
+    "Gateway", "DockerGateway", "GatewayError", "rotate_gateway_ca",
     "GATEWAY_NAME", "GATEWAY_LABEL", "GATEWAY_IMAGE", "GATEWAY_NETWORK",
-    "GATEWAY_CA_VOLUME", "GATEWAY_CA_CERT",
+    "GATEWAY_CA_CERT", "GATEWAY_CA_GLOB",
 ]

bot_bottle/orchestrator/lifecycle.py

@@ -23,10 +23,16 @@ from pathlib import Path
 
 from .. import log
 from ..docker_cmd import run_docker
-from ..paths import CONTROL_PLANE_TOKEN_ENV, bot_bottle_root, host_control_plane_token
+from ..paths import (
+    CONTROL_PLANE_TOKEN_ENV,
+    bot_bottle_root,
+    host_control_plane_token,
+    host_gateway_ca_dir,
+)
 from ..supervise import DB_PATH_IN_CONTAINER
 from .gateway import (
-    GATEWAY_CA_VOLUME,
+    GATEWAY_DOCKERFILE,
+    GATEWAY_IMAGE,
     GATEWAY_NETWORK,
     GatewayError,
     MITMPROXY_HOME,
@@ -160,9 +166,10 @@ class OrchestratorService:
             )
 
     def _build_images(self) -> None:
-        """Build the orchestrator image (build intermediate), then the infra
-        image. Both are cache-aware: a no-op when nothing changed."""
+        """Build the gateway base, the orchestrator intermediate, then the
+        infra image. All are cache-aware: a no-op when nothing changed."""
         for tag, dockerfile in (
+            (GATEWAY_IMAGE, GATEWAY_DOCKERFILE),
             (ORCHESTRATOR_IMAGE, ORCHESTRATOR_DOCKERFILE),
             (self.image, INFRA_DOCKERFILE),
         ):
@@ -188,9 +195,13 @@ class OrchestratorService:
             "--label", f"{INFRA_SOURCE_HASH_LABEL}={current_hash}",
             "--network", self.network,
             # Host CLI reaches the control plane here (loopback only).
-            "--publish", f"127.0.0.1:{self.port}:{self.port}",
-            # Persist the mitmproxy CA so it survives container recreation.
-            "--volume", f"{GATEWAY_CA_VOLUME}:{MITMPROXY_HOME}",
+            # gateway_init always starts the orchestrator on DEFAULT_PORT (8099)
+            # inside the container; self.port is the host-side published port.
+            "--publish", f"127.0.0.1:{self.port}:{DEFAULT_PORT}",
+            # Persist the mitmproxy CA on the host so it survives container
+            # recreation AND docker volume pruning (issue #450): every agent
+            # trusts this one CA, so a fresh one would break all running bottles.
+            "--volume", f"{host_gateway_ca_dir()}:{MITMPROXY_HOME}",
             # Shared supervise DB (same file the operator reads over HTTP).
             "--volume", f"{_host_db_dir()}:{_SUPERVISE_DB_DIR_IN_CONTAINER}",
             "--env", f"SUPERVISE_DB_PATH={DB_PATH_IN_CONTAINER}",
@@ -206,8 +217,9 @@ class OrchestratorService:
             # Control-plane secret: required by the orchestrator (to enforce)
             # and by the gateway daemons (to present on /resolve calls).
             "--env", CONTROL_PLANE_TOKEN_ENV,
-            # Gateway daemons reach the orchestrator over loopback.
-            "--env", f"BOT_BOTTLE_ORCHESTRATOR_URL=http://127.0.0.1:{self.port}",
+            # Gateway daemons reach the orchestrator over loopback at its
+            # fixed internal port (DEFAULT_PORT), independent of self.port.
+            "--env", f"BOT_BOTTLE_ORCHESTRATOR_URL=http://127.0.0.1:{DEFAULT_PORT}",
             # Opt the orchestrator into gateway_init's supervise tree.
             "--env", f"BOT_BOTTLE_GATEWAY_DAEMONS={_INFRA_DAEMONS}",
             self.image,

bot_bottle/orchestrator/registry.py

@@ -32,6 +32,7 @@ import hmac
 import secrets
 import sqlite3
 import time
+from collections.abc import Iterable
 from dataclasses import dataclass
 from pathlib import Path
 
@@ -42,6 +43,12 @@ from ..paths import host_db_path
 # 256 bits of urandom, URL-safe — unguessable per-bottle identity token.
 IDENTITY_TOKEN_BYTES = 32
 
+# How recently a row must have been registered to be exempt from
+# `reap_absent`. Covers the window between `container run` and the address
+# becoming visible to another launch's enumeration, so reconciliation never
+# reaps a bottle that is still coming up.
+DEFAULT_REAP_GRACE_SECONDS = 120.0
+
 
 def new_identity_token() -> str:
     """A fresh per-bottle identity token (PRD 0070 attribution defence)."""
@@ -106,6 +113,22 @@ _MIGRATIONS = TableMigrations(
         # egress allowlist / routes / git config selected by source IP. The
         # multi-tenant gateway resolves it per request via `attribute`.
         "ALTER TABLE orchestrator_bottles ADD COLUMN policy TEXT NOT NULL DEFAULT ''",
+        # v4 — per-bottle encrypted egress secrets (PRD prd-new-secret-provider).
+        # One row per env-var: key (env-var name) is plaintext for auditing;
+        # value is the encrypted token string. The encryption key (ENV_VAR_SECRET)
+        # lives only in the agent's environment — a row alone cannot recover the
+        # credential.
+        """
+        CREATE TABLE IF NOT EXISTS bottled_agent_secrets (
+            bottled_agent_id TEXT NOT NULL,
+            key              TEXT NOT NULL,
+            value            TEXT NOT NULL,
+            type             TEXT NOT NULL DEFAULT 'injected_env_var'
+        )
+        """,
+        # v5 — index for fast per-bottle lookups and bulk DELETE on teardown.
+        "CREATE INDEX IF NOT EXISTS idx_bottled_agent_secrets_id "
+        "ON bottled_agent_secrets (bottled_agent_id, type)",
     ],
 )
 
@@ -225,6 +248,70 @@ class RegistryStore(DbStore):
             ).fetchall()
         return [_row_to_record(r) for r in rows]
 
+    def reap_absent(
+        self,
+        live_source_ips: Iterable[str],
+        *,
+        grace_seconds: float = DEFAULT_REAP_GRACE_SECONDS,
+        now: float | None = None,
+    ) -> list[BottleRecord]:
+        """Delete active rows whose source IP is not held by a live bottle.
+
+        A row only ever leaves the registry two ways: an explicit
+        `teardown_bottle` (the launcher's cleanup callback) or the supersede
+        sweep in `register`. Neither runs when the launching CLI dies hard —
+        SIGKILL, a closed terminal, a host sleep/crash — so the row outlives
+        its container. That orphan is not inert: source IPs are recycled by
+        the backend's DHCP, and `by_source_ip` fail-closes on ambiguity, so a
+        leftover row at a reused address can brick the *next* bottle that
+        lands on it (no policy resolved -> every host denied, reported to the
+        agent as "not in the allowlist"). Reconciling against the live set at
+        launch keeps the registry from accumulating those landmines.
+
+        Restores the invariant the data plane needs: **at most one active row
+        per live address, and none at all for a dead one.** Two cases, because
+        a dead bottle's address may already have been handed to a live one:
+
+          * no live bottle holds the address — every row there is an orphan;
+          * a live bottle holds it but several rows claim it — the newest
+            registration is authoritative and the rest are orphans, the same
+            rule `register`'s same-IP supersede sweep applies. Without this
+            second case a recycled address stays ambiguous, which is exactly
+            the state that resolves no policy.
+
+        `grace_seconds` protects an in-flight launch: registration happens
+        moments after `container run`, and a concurrent launch's address may
+        not be visible to the caller's enumeration yet. Rows younger than the
+        grace window are never reaped, so reconciliation can't race a bottle
+        that is still coming up. Returns the deleted records."""
+        live = {ip for ip in live_source_ips if ip}
+        cutoff = (time.time() if now is None else now) - grace_seconds
+        with self._connection() as conn:
+            rows = conn.execute(
+                "SELECT * FROM orchestrator_bottles WHERE state = 'active'",
+            ).fetchall()
+            by_ip: dict[str, list[BottleRecord]] = {}
+            for row in rows:
+                rec = _row_to_record(row)
+                by_ip.setdefault(rec.source_ip, []).append(rec)
+            candidates: list[BottleRecord] = []
+            for ip, recs in by_ip.items():
+                if ip not in live:
+                    candidates.extend(recs)
+                    continue
+                # Keep the newest claim on a live address; supersede the rest.
+                recs.sort(key=lambda r: r.created_at)
+                candidates.extend(recs[:-1])
+            doomed = [r for r in candidates if r.created_at <= cutoff]
+            for rec in doomed:
+                conn.execute(
+                    "DELETE FROM orchestrator_bottles WHERE bottle_id = ?",
+                    (rec.bottle_id,),
+                )
+        if doomed:
+            self._chmod()
+        return doomed
+
     def by_source_ip(self, source_ip: str) -> BottleRecord | None:
         """Network-layer attribution: the single active bottle at this source
         IP, or None if unknown or ambiguous (more than one — a
@@ -255,6 +342,57 @@ class RegistryStore(DbStore):
             return None
         return rec
 
+    # --- encrypted egress secret store ------------------------------------
+
+    def store_agent_secrets(
+        self,
+        bottle_id: str,
+        encrypted_values: dict[str, str],
+        secret_type: str = "injected_env_var",
+    ) -> None:
+        """Replace all stored secrets for *bottle_id* with *encrypted_values*
+        (env-var name → encrypted ciphertext). Deletes then re-inserts so a
+        re-registration is always consistent with the current token set."""
+        with self._connection() as conn:
+            conn.execute(
+                "DELETE FROM bottled_agent_secrets "
+                "WHERE bottled_agent_id = ? AND type = ?",
+                (bottle_id, secret_type),
+            )
+            conn.executemany(
+                "INSERT INTO bottled_agent_secrets "
+                "(bottled_agent_id, key, value, type) VALUES (?, ?, ?, ?)",
+                [(bottle_id, k, v, secret_type) for k, v in encrypted_values.items()],
+            )
+        self._chmod()
+
+    def get_agent_secrets(
+        self,
+        bottle_id: str,
+        secret_type: str = "injected_env_var",
+    ) -> dict[str, str]:
+        """Return {env_var_name: encrypted_value} for *bottle_id*, or {} if none."""
+        with self._connection() as conn:
+            rows = conn.execute(
+                "SELECT key, value FROM bottled_agent_secrets "
+                "WHERE bottled_agent_id = ? AND type = ?",
+                (bottle_id, secret_type),
+            ).fetchall()
+        return {row[0]: row[1] for row in rows}
+
+    def delete_agent_secrets(
+        self,
+        bottle_id: str,
+        secret_type: str = "injected_env_var",
+    ) -> None:
+        """Remove all stored secrets for *bottle_id* (e.g. on teardown)."""
+        with self._connection() as conn:
+            conn.execute(
+                "DELETE FROM bottled_agent_secrets "
+                "WHERE bottled_agent_id = ? AND type = ?",
+                (bottle_id, secret_type),
+            )
+
 
 __all__ = [
     "BottleRecord",
@@ -262,4 +400,5 @@ __all__ = [
     "new_identity_token",
     "default_db_path",
     "IDENTITY_TOKEN_BYTES",
+    "DEFAULT_REAP_GRACE_SECONDS",
 ]

bot_bottle/orchestrator/reprovision.py

@@ -0,0 +1,35 @@
+"""Shared host-side join for backend-discovered bottle encryption keys."""
+
+from __future__ import annotations
+
+from .client import OrchestratorClient, OrchestratorClientError
+
+
+def reprovision_bottles(
+    client: OrchestratorClient,
+    secrets_by_source_ip: dict[str, str],
+) -> int:
+    """Restore tokens for registered bottles whose backend exposes a key.
+
+    Backends own discovery because containers and microVMs have different
+    enumeration primitives. This helper owns the shared registry join and
+    intentionally tolerates one bad/missing key without blocking a launch.
+    """
+    restored = 0
+    for bottle in client.list_bottles():
+        bottle_id = bottle.get("bottle_id")
+        source_ip = bottle.get("source_ip")
+        if not isinstance(bottle_id, str) or not isinstance(source_ip, str):
+            continue
+        secret = secrets_by_source_ip.get(source_ip, "").strip()
+        if not secret:
+            continue
+        try:
+            if client.reprovision_gateway(bottle_id, secret):
+                restored += 1
+        except OrchestratorClientError:
+            continue
+    return restored
+
+
+__all__ = ["reprovision_bottles"]

bot_bottle/orchestrator/rotate_ca.py

@@ -0,0 +1,62 @@
+"""Rotate the shared gateway's mitmproxy CA (issue #450).
+
+    python -m bot_bottle.orchestrator.rotate_ca
+
+A deliberate CA rollover has two halves: drop the *persisted* CA so a fresh one
+is minted, and drop the *running* gateway so its mitmproxy (which holds the old
+CA in memory) is replaced. This one-shot command does both:
+
+  1. Delete the persisted CA under the host gateway-CA dir — the next gateway
+     start generates a new one (mitmproxy reuses an existing CA, generates only
+     when absent).
+  2. Force-remove the infra / standalone-gateway containers so the stale
+     in-memory CA is gone; the next bottle launch's idempotent `ensure_running`
+     brings the gateway back up and mints the fresh CA.
+
+It does NOT re-provision the new CA into already-running bottles — those must be
+re-attached so they install the new trust anchor. Rotation is thus an explicit,
+operator-driven action with a brief egress interruption, not an automatic one.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from ..docker_cmd import run_docker
+from ..paths import host_gateway_ca_dir
+from .gateway import GATEWAY_NAME, rotate_gateway_ca
+from .lifecycle import INFRA_NAME
+
+# The containers whose mitmproxy would still be serving the old CA from memory:
+# the consolidated infra container and the standalone per-host gateway.
+_GATEWAY_CONTAINERS = (INFRA_NAME, GATEWAY_NAME)
+
+
+def _out(msg: str) -> None:
+    sys.stdout.write(f"rotate-ca: {msg}\n")
+
+
+def main(argv: list[str] | None = None) -> int:
+    del argv  # no flags — a single deliberate action
+    ca_dir: Path = host_gateway_ca_dir()
+    removed = rotate_gateway_ca(ca_dir)
+    if removed:
+        _out(f"removed {len(removed)} CA file(s) from {ca_dir}")
+    else:
+        _out(f"no persisted CA under {ca_dir}; a fresh one is minted on next start")
+
+    # Drop any running gateway so its in-memory (now-stale) CA is replaced on
+    # the next launch. `rm --force` on an absent name is a tolerated no-op.
+    for name in _GATEWAY_CONTAINERS:
+        proc = run_docker(["docker", "rm", "--force", name])
+        if proc.returncode == 0 and proc.stdout.strip():
+            _out(f"removed running container {name}")
+
+    _out("done — the next bottle launch remints the CA; re-attach bottles to "
+         "install the new trust anchor")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

bot_bottle/orchestrator/secret_store.py

@@ -0,0 +1,94 @@
+"""Symmetric encryption for per-bottle egress secrets (PRD prd-new-secret-provider).
+
+Each agent receives a random ENV_VAR_SECRET at startup — passed as an env var,
+never logged or persisted. The host uses this key to encrypt each egress auth
+token value before writing it to the bottled_agent_secrets table; the DB rows
+(ciphertext, plaintext env-var name) without the key are insufficient to
+recover the credentials.
+
+On orchestrator restart the in-memory token map is lost. The host-side
+reattachment path reads ENV_VAR_SECRET from the running agent container via
+``docker exec … printenv ENV_VAR_SECRET`` and posts it to
+``POST /bottles/<id>/reprovision_gateway``; the orchestrator decrypts the
+stored rows and re-populates ``_tokens``.
+
+Encryption scheme: HMAC-SHA256 used as a PRF in CTR mode (stdlib-only,
+no external deps). Each value is encrypted independently. The output blob is
+``nonce (16 bytes) || ciphertext`` encoded as URL-safe base64 (no padding).
+
+    keystream_block_i = HMAC-SHA256(key, nonce || i.to_bytes(4, "big"))
+    ciphertext_i      = plaintext_i XOR keystream_block_i[:len(plaintext_i)]
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import secrets
+
+_KEY_BYTES = 32    # 256-bit key from ENV_VAR_SECRET
+_NONCE_BYTES = 16  # 128-bit random nonce per encrypt call
+_BLOCK = 32        # HMAC-SHA256 output width == one keystream block
+
+# Env-var name the agent container receives at startup.
+ENV_VAR_SECRET_NAME = "ENV_VAR_SECRET"
+
+
+def new_env_var_secret() -> str:
+    """Generate a fresh ENV_VAR_SECRET: 32 random bytes as URL-safe base64."""
+    return base64.urlsafe_b64encode(secrets.token_bytes(_KEY_BYTES)).rstrip(b"=").decode()
+
+
+def _b64dec(s: str) -> bytes:
+    return base64.urlsafe_b64decode(s + "=" * (-len(s) % 4))
+
+
+def _keystream(key: bytes, nonce: bytes, block_index: int) -> bytes:
+    return hmac.new(
+        key, nonce + block_index.to_bytes(4, "big"), hashlib.sha256
+    ).digest()
+
+
+def encrypt_value(secret_b64: str, plaintext: str) -> str:
+    """Encrypt a single string value with *secret_b64* (the ENV_VAR_SECRET).
+
+    Returns a URL-safe base64 blob ``nonce || ciphertext`` suitable for
+    the ``bottled_agent_secrets.value`` column."""
+    key = _b64dec(secret_b64)
+    pt = plaintext.encode()
+    nonce = secrets.token_bytes(_NONCE_BYTES)
+    ct = bytearray()
+    for i in range(0, len(pt), _BLOCK):
+        chunk = pt[i : i + _BLOCK]
+        ks = _keystream(key, nonce, i)[: len(chunk)]
+        ct.extend(p ^ k for p, k in zip(chunk, ks))
+    return base64.urlsafe_b64encode(nonce + bytes(ct)).rstrip(b"=").decode()
+
+
+def decrypt_value(secret_b64: str, blob_b64: str) -> str:
+    """Decrypt a blob produced by :func:`encrypt_value`.
+
+    Returns the original plaintext string. Raises ``ValueError`` for malformed
+    input or a key mismatch (wrong key produces garbage, not an error, unless
+    the plaintext is non-UTF-8 — treat all such failures as wrong key)."""
+    key = _b64dec(secret_b64)
+    try:
+        blob = _b64dec(blob_b64)
+    except Exception as exc:
+        raise ValueError(f"invalid ciphertext blob: {exc}") from exc
+    if len(blob) < _NONCE_BYTES:
+        raise ValueError("ciphertext blob too short")
+    nonce, ciphertext = blob[:_NONCE_BYTES], blob[_NONCE_BYTES:]
+    pt = bytearray()
+    for i in range(0, len(ciphertext), _BLOCK):
+        chunk = ciphertext[i : i + _BLOCK]
+        ks = _keystream(key, nonce, i)[: len(chunk)]
+        pt.extend(c ^ k for c, k in zip(chunk, ks))
+    try:
+        return bytes(pt).decode()
+    except UnicodeDecodeError as exc:
+        raise ValueError(f"decryption produced non-UTF-8 output (wrong key?): {exc}") from exc
+
+
+__all__ = ["ENV_VAR_SECRET_NAME", "new_env_var_secret", "encrypt_value", "decrypt_value"]

bot_bottle/orchestrator/service.py

@@ -13,15 +13,20 @@ Launch lifecycle:
     and returns the record. If the broker rejects/fails, the registry entry
     is rolled back so a failed launch leaves no orphan.
   * `teardown_bottle` sends a signed teardown request, then deregisters.
+  * `reconcile` sweeps rows whose bottle is no longer running — the
+    self-heal for the teardown paths that never got to run (a hard-killed
+    launcher), since an orphan row at a recycled source IP bricks the next
+    bottle that lands on it.
 """
 
 from __future__ import annotations
 
 import json
+from collections.abc import Iterable
 from datetime import datetime, timezone
 
 from .broker import LaunchBroker, LaunchRequest, sign_request
-from .registry import BottleRecord, RegistryStore
+from .registry import DEFAULT_REAP_GRACE_SECONDS, BottleRecord, RegistryStore
 from .gateway import Gateway
 from ..supervise import (
     AuditEntry,
@@ -82,13 +87,22 @@ class Orchestrator:
         metadata: str = "",
         policy: str = "",
         tokens: dict[str, str] | None = None,
+        env_var_secret: str = "",
     ) -> BottleRecord:
         """Register a bottle (with its gateway policy + in-memory egress auth
         tokens) and broker its launch. Rolls the registry entry back if the
-        launch doesn't take, so a failure leaves no orphan."""
+        launch doesn't take, so a failure leaves no orphan.
+
+        When *env_var_secret* is provided alongside *tokens*, the token values
+        are also encrypted and written to ``bottled_agent_secrets`` so they can
+        survive an orchestrator restart (see ``reprovision_from_secret``)."""
         rec = self.registry.register(source_ip, metadata=metadata, policy=policy)
         if tokens:
             self._tokens[rec.bottle_id] = dict(tokens)
+            if env_var_secret:
+                from .secret_store import encrypt_value
+                encrypted = {k: encrypt_value(env_var_secret, v) for k, v in tokens.items()}
+                self.registry.store_agent_secrets(rec.bottle_id, encrypted)
         req = LaunchRequest(
             op="launch",
             bottle_id=rec.bottle_id,
@@ -117,6 +131,30 @@ class Orchestrator:
         self._tokens.pop(bottle_id, None)
         return True
 
+    def reconcile(
+        self,
+        live_source_ips: Iterable[str],
+        *,
+        grace_seconds: float = DEFAULT_REAP_GRACE_SECONDS,
+    ) -> list[str]:
+        """Drop registry rows for bottles that are no longer running, and
+        forget their in-memory egress tokens. Returns the reaped bottle ids.
+
+        The caller supplies the live set because only the host can enumerate
+        its own containers — the orchestrator runs *inside* the infra
+        container and has no view of the backend. Deliberately does not
+        broker a teardown: the container is already gone, so there is nothing
+        to stop, and a broker error must not stop the sweep from clearing
+        the row that would otherwise brick the next bottle at that address.
+
+        See `RegistryStore.reap_absent` for why orphans accumulate and why
+        they are harmful rather than merely untidy."""
+        reaped = self.registry.reap_absent(
+            live_source_ips, grace_seconds=grace_seconds)
+        for rec in reaped:
+            self._tokens.pop(rec.bottle_id, None)
+        return [rec.bottle_id for rec in reaped]
+
     def tokens_for(self, bottle_id: str) -> dict[str, str]:
         """The bottle's in-memory egress auth tokens (env_name -> value), or
         empty. The gateway injects these per request; they are never
@@ -255,6 +293,26 @@ class Orchestrator:
             ))
         return True, ""
 
+    # --- secret reprovision -----------------------------------------------
+
+    def reprovision_from_secret(self, bottle_id: str, env_var_secret: str) -> bool:
+        """Re-inject a bottle's egress tokens from its ENV_VAR_SECRET.
+
+        Reads the encrypted rows from ``bottled_agent_secrets``, decrypts each
+        value with *env_var_secret*, and restores ``_tokens[bottle_id]``.
+        Returns True on success, False when no stored secrets exist for this
+        bottle or decryption fails (wrong key / corrupt data)."""
+        from .secret_store import decrypt_value
+        encrypted = self.registry.get_agent_secrets(bottle_id)
+        if not encrypted:
+            return False
+        try:
+            self._tokens[bottle_id] = {k: decrypt_value(env_var_secret, v)
+                                       for k, v in encrypted.items()}
+        except ValueError:
+            return False
+        return True
+
     # --- consolidated gateway ----------------------------------------------
 
     def ensure_gateway(self) -> None:

bot_bottle/paths.py

@@ -33,6 +33,13 @@ HOST_DB_FILENAME = "bot-bottle.db"
 CONTROL_PLANE_TOKEN_FILENAME = "control-plane-token"
 CONTROL_PLANE_TOKEN_ENV = "BOT_BOTTLE_CONTROL_PLANE_TOKEN"
 
+# The host directory holding the gateway's persistent mitmproxy CA. Bind-mounted
+# into the infra/gateway container at mitmproxy's confdir so the self-generated
+# CA survives container recreation — every agent installs this one CA to trust
+# the shared gateway's TLS interception, so it must not rotate on restart. See
+# host_gateway_ca_dir() for why this is a host bind-mount, not a named volume.
+GATEWAY_CA_DIRNAME = "gateway-ca"
+
 
 def bot_bottle_root() -> Path:
     """The app data root — `$BOT_BOTTLE_ROOT` if set, else `~/.bot-bottle`."""
@@ -59,6 +66,23 @@ def host_db_dir() -> Path:
     return db_dir
 
 
+def host_gateway_ca_dir() -> Path:
+    """The directory holding the gateway's persistent mitmproxy CA, created if
+    missing. Backends bind-mount this into the infra/gateway container at
+    mitmproxy's confdir so the CA persists across container recreation.
+
+    A host bind-mount under the app-data root — deliberately NOT a Docker
+    named volume. A named volume survives `docker rm` but is silently wiped by
+    `docker volume prune` / `docker system prune --volumes` during routine host
+    maintenance; the gateway then mints a fresh CA that every already-running
+    bottle distrusts, failing the TLS handshake even after it reconnects to the
+    moved gateway (issue #450). A path under the root docker never prunes it,
+    and it stays directly inspectable + rotatable from the host."""
+    ca_dir = bot_bottle_root() / GATEWAY_CA_DIRNAME
+    ca_dir.mkdir(parents=True, exist_ok=True)
+    return ca_dir
+
+
 def host_control_plane_token() -> str:
     """The per-host control-plane secret, minted (256-bit, url-safe) and
     persisted 0600 on first use, then reused.
@@ -94,8 +118,10 @@ __all__ = [
     "HOST_DB_FILENAME",
     "CONTROL_PLANE_TOKEN_FILENAME",
     "CONTROL_PLANE_TOKEN_ENV",
+    "GATEWAY_CA_DIRNAME",
     "bot_bottle_root",
     "host_db_path",
     "host_db_dir",
+    "host_gateway_ca_dir",
     "host_control_plane_token",
 ]

bot_bottle/store_manager.py

@@ -6,9 +6,11 @@ from pathlib import Path
 
 try:
     from .audit_store import AuditStore
+    from .config_store import ConfigStore
     from .queue_store import QueueStore
 except ImportError:
     from audit_store import AuditStore  # type: ignore[import-not-found]  # pylint: disable=import-error,no-name-in-module
+    from config_store import ConfigStore  # type: ignore[import-not-found]  # pylint: disable=import-error,no-name-in-module
     from queue_store import QueueStore  # type: ignore[import-not-found]  # pylint: disable=import-error,no-name-in-module
 
 _instance: StoreManager | None = None
@@ -47,11 +49,13 @@ class StoreManager:
         return (
             QueueStore("", self.db_path).is_migrated()
             and AuditStore(self.db_path).is_migrated()
+            and ConfigStore(self.db_path).is_migrated()
         )
 
     def migrate(self) -> None:
         QueueStore("", self.db_path).migrate()
         AuditStore(self.db_path).migrate()
+        ConfigStore(self.db_path).migrate()
 
 
 __all__ = ["StoreManager"]

bot_bottle/supervise_server.py

@@ -168,15 +168,16 @@ _ROUTES_YAML_DESCRIPTION = (
     "Full proposed /etc/egress/routes.yaml content. "
     "Each route entry accepts these keys:\n"
     "  host: <hostname>  (required)\n"
-    "  auth_scheme: Bearer|token  (must pair with token_env)\n"
-    "  token_env: <ENV_VAR_NAME>  (must pair with auth_scheme)\n"
-    "  matches:  (optional list of match entries)\n"
-    "    - paths: [{type: prefix|exact|regex, value: /...}]\n"
-    "      methods: [GET, POST, ...]\n"
-    "      headers: [{name: X-Hdr, value: val, type: exact|regex}]\n"
-    "  git:  (optional; omit to block git clone/fetch)\n"
-    "    fetch: true\n"
-    "  dlp:  (optional DLP scanner overrides)\n"
+    "  inspect: false  (opaque whole-host TLS tunnel; no HTTP controls)\n"
+    "  inspect:  (omit for inspected defaults)\n"
+    "    auth_scheme: Bearer|token  (must pair with token_env)\n"
+    "    token_env: <ENV_VAR_NAME>  (must pair with auth_scheme)\n"
+    "    matches:  (optional list of match entries)\n"
+    "      - paths: [{type: prefix|exact|regex, value: /...}]\n"
+    "        methods: [GET, POST, ...]\n"
+    "        headers: [{name: X-Hdr, value: val, type: exact|regex}]\n"
+    "    git:  (optional; omit to block git clone/fetch)\n"
+    "      fetch: true\n"
     "    outbound_detectors: [token_patterns, known_secrets]\n"
     "    inbound_detectors: [naive_injection_detection]\n"
     "    outbound_on_match: block|redact|supervise  (default supervise)\n"

docs/prds/0070-per-host-orchestrator.md

@@ -312,6 +312,44 @@ reaches over the RPC rather than a shared mount into the VM. WAL on the
 shared DB is therefore a deliberate, tested future change — not enabled ad
 hoc. `sqlite3` itself is stdlib, so "the host needs SQLite" is a non-cost.
 
+### Gateway CA: host-resident, like the DB
+
+The shared gateway bumps TLS with a self-generated mitmproxy CA, and **every
+bottle installs that CA** into its trust store to accept the bumped leaves. So
+the CA is durable per-host state with the same rule as the DB: it must outlive
+any single gateway container, or a restart mints a fresh CA that every
+already-running bottle distrusts — the TLS handshake then fails even after the
+bottle re-resolves and reconnects to the moved gateway (issue #450, a
+re-attachment blocker distinct from #443/#445).
+
+The CA lives on the **host filesystem** at `bot_bottle_root()/gateway-ca`
+(`host_gateway_ca_dir()`), bind-mounted into the container at mitmproxy's
+confdir. This is deliberately a host bind-mount, **not a container-runtime
+named volume**: a named volume survives ordinary container removal but can be
+silently wiped by Docker's or Apple Container's volume-prune commands during
+routine host maintenance, which is exactly how the ephemeral-CA symptom shows
+up in practice. A path under the app-data root is not managed or pruned by the
+container runtime, and stays directly inspectable and rotatable from the host.
+mitmproxy reuses an existing CA and generates one only on first run, so the
+bind-mount alone gives
+"adopt-existing, generate-on-first-run" for free.
+
+The macOS backend uses the same host-resident CA directory and bind-mounts it
+into the consolidated Apple infra container. Its `bot-bottle-mac-db` named
+volume remains container-only because that prevents incoherent cross-kernel
+SQLite locking, but the CA is deliberately not stored there: Apple Container
+also has a `container volume prune` operation, and the named volume is
+temporarily unreferenced while the infra container is recreated. Keeping the
+CA on the host makes both ordinary recreation and volume pruning safe.
+
+**Deliberate rollover** is the explicit inverse: `rotate_gateway_ca()` removes
+the persisted CA material so the next start remints it, and the
+`python -m bot_bottle.orchestrator.rotate_ca` one-shot wires that together with
+dropping the running gateway container (whose mitmproxy still holds the old CA
+in memory). Rotation does not auto-re-provision the new CA into running bottles
+— those re-attach to install the new anchor — so it is an operator action with
+a brief egress interruption, never an implicit one.
+
 ## Sequencing
 
 Jump straight to the **virtualized** end state (not a host-daemon stepping

docs/prds/prd-new-ci-artifact-coverage.md

@@ -0,0 +1,110 @@
+# PRD prd-new: CI artifact-based coverage and local Firecracker candidate flow
+
+- **Status:** Active
+- **Author:** Claude
+- **Created:** 2026-07-21
+- **Issue:** #446
+
+## Summary
+
+Restructure the CI test pipeline to run each test suite exactly once, upload
+small `.coverage.*` artifacts, and combine them in a lightweight aggregation
+job. Move the infra build onto the KVM runner so the ~194 MB rootfs never
+crosses the network for PRs. On main-branch pushes, publish the byte-identical
+rootfs that was tested.
+
+## Motivation
+
+The prior pipeline had two redundant costs:
+
+1. **Duplicate artifact transfers.** `build-infra` (ubuntu-latest) built and
+   uploaded the ~194 MB rootfs; `integration-firecracker` downloaded it; the
+   `coverage` job downloaded it a second time. Combined download overhead: ~83
+   seconds per run, plus the ~70-second upload.
+
+2. **Duplicate test execution.** `integration-firecracker` ran the Firecracker
+   integration suite; `coverage` ran the entire unit + integration suite again
+   on the same KVM runner to collect coverage data. Every line of Firecracker
+   code was tested twice per CI run.
+
+## Goals
+
+- Each test suite (unit, integration-docker, integration-firecracker) executes
+  exactly once per workflow run.
+- PRs incur no large artifact transfers — the rootfs stays on the KVM runner.
+- Main-branch pushes publish a byte-for-byte identical rootfs to the one that
+  passed the integration tests.
+- Concurrent workflow runs cannot cross-publish candidates (naturally enforced
+  by Gitea Actions' per-run artifact scoping).
+- Failed or cancelled runs block publication (enforced by the `needs:` chain on
+  `publish-infra`).
+
+## Non-goals
+
+- Changing test semantics or the coverage policy (ADR 0004).
+- Removing the KVM runner guard on `integration-firecracker` and `coverage`.
+- Changing how `publish_infra.py` builds or uploads the rootfs.
+
+## Design
+
+### Job graph
+
+```
+unit ──────────────────────────────────┐
+integration-docker ────────────────────┤──► coverage ──► publish-infra (main only)
+integration-firecracker (KVM) ─────────┘
+```
+
+### `unit`
+
+Unchanged except: `coverage run` writes `--data-file=.coverage.unit`; the file
+is uploaded as the `coverage-unit` artifact.
+
+### `integration-docker`
+
+Adds a `coverage` install step. `coverage run` writes `--data-file=.coverage.docker`;
+the file is uploaded as `coverage-docker`.
+
+### `integration-firecracker` (KVM runner)
+
+Replaces the old `stage-firecracker-inputs` → `build-infra` → download chain:
+
+1. Builds the infra candidate locally with
+   `BOT_BOTTLE_FC_DROPBEAR=/var/cache/bot-bottle-fc/dropbear`.
+2. Boots the candidate and runs integration tests with coverage, writing
+   `.coverage.firecracker`.
+3. Uploads the small `coverage-firecracker` artifact unconditionally.
+4. On main-branch pushes only, uploads the rootfs as `infra-candidate` and the
+   dropbear as `firecracker-inputs` so `publish-infra` can verify and publish
+   the byte-identical artifact.
+
+### `coverage`
+
+Moves from a KVM runner to `ubuntu-latest`. No tests are re-executed:
+
+1. Downloads `coverage-unit`, `coverage-docker`, and `coverage-firecracker`.
+2. Runs `scripts/coverage.sh aggregate critical`, which calls
+   `coverage combine` then `coverage report`.
+3. Runs the diff-coverage gate (`scripts/diff_coverage.py`).
+
+Coverage files use `relative_files = True` (`.coveragerc`) so they combine
+cleanly across runners with different absolute workspace paths.
+
+### `publish-infra`
+
+Depends on all four predecessor jobs (unchanged gate). Downloads `infra-candidate`
+and `firecracker-inputs` that were uploaded by `integration-firecracker` on
+main — the same byte sequence that passed the integration tests.
+
+### Eliminated jobs
+
+- `stage-firecracker-inputs`: existed only to copy the dropbear to ubuntu-latest
+  for `build-infra`. No longer needed.
+- `build-infra`: the infra candidate is now built on the KVM runner in
+  `integration-firecracker`.
+
+### Script changes
+
+`scripts/coverage.sh` gains an `aggregate` mode (`coverage.sh aggregate [critical]`)
+that combines pre-existing `.coverage.*` files instead of re-running tests.
+The existing run mode (`coverage.sh [critical]`) is preserved for local dev.

docs/prds/prd-new-claude-forward-host-credentials.md

@@ -0,0 +1,146 @@
+# 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.

docs/prds/prd-new-consolidate-docker-infra-backend.md

@@ -90,8 +90,9 @@ first (`DockerGateway.ensure_running`), then orchestrator. After this PRD:
 - Single `docker run` of `bot-bottle-infra:latest`
 - Container name: `bot-bottle-infra` (replaces `bot-bottle-orch-gateway` +
   `bot-bottle-orchestrator`)
-- Published ports: `127.0.0.1:{port}:{port}` for the control plane (same as
-  today)
+- Published ports: `127.0.0.1:{host_port}:8099` for the control plane
+  (`gateway_init` listens on a fixed internal port 8099; the caller-chosen
+  host port maps to it)
 - Bind mounts: repo root + host root (same as today)
 - `DockerGateway` becomes an implementation detail of `OrchestratorService`
   rather than a separately started container; the gateway image name

docs/prds/prd-new-modernize-built-in-agent-images.md

@@ -0,0 +1,47 @@
+# PRD prd-new: Modernize built-in agent images
+
+- **Status:** Draft
+- **Author:** Codex
+- **Created:** 2026-07-21
+- **Issue:** #451
+
+## Summary
+
+Keep every built-in agent provider on Debian's current stable release and make
+Podman available inside each image. This gives agents a consistent, modern
+userspace and an OCI container tool without requiring per-project setup.
+
+## Problem
+
+The Claude, Codex, and Pi images inherit the generic `node:22-slim` tag. That
+tag does not state which Debian release the project supports and currently
+leaves the images on the older Bookworm release. None of the built-in images
+installs Podman, so tasks that need to inspect or build OCI images must first
+modify the bottle or cannot run at all.
+
+## Goals / success criteria
+
+- Every Dockerfile under `bot_bottle/contrib/*/Dockerfile` explicitly inherits
+  `node:22-trixie-slim`, based on Debian 13 (the current stable release).
+- Every built-in agent image installs Podman from Debian stable.
+- Every built-in agent image retains an SSH client for Git-over-SSH workflows.
+- The non-root agent user owns a traversable XDG Git configuration directory,
+  so Git can load bot-bottle's global git-gate rewrites without permission
+  errors.
+- A shared test enforces both requirements for current and future built-in
+  providers.
+
+## Non-goals
+
+- Configuring privileged or nested-container execution for bottles.
+- Pinning Podman outside Debian's stable package repository.
+- Changing the Node.js or agent CLI release policy.
+
+## Design
+
+Use the explicit `node:22-trixie-slim` base rather than the floating `slim`
+variant. Install the `podman` package with each image's existing `apt-get`
+dependency layer, so package metadata and caches are still removed in the same
+layer. Treat Debian stable as the Podman stability and update channel; this
+keeps the images stdlib/distribution-first and avoids adding a third-party
+package repository.

docs/prds/prd-new-nested-containers.md

@@ -0,0 +1,153 @@
+# PRD prd-new: Containers inside a bottle
+
+- **Status:** Draft
+- **Author:** Claude
+- **Created:** 2026-07-21
+- **Issue:** #392
+
+## Summary
+
+Let an agent run `docker` and `docker compose` *inside* its bottle by starting
+a guest-local rootless podman service that exposes a Docker-compatible API
+socket. Gated per bottle by `nested_containers: true`. No host daemon socket is
+mounted and no capability is added to the guest, on any backend.
+
+## Problem
+
+Agent tasks routinely involve containers: `docker compose up` to verify a
+scaffolded stack, a throwaway database for a test run, building an image to
+check a Dockerfile works. Bottles have no way to do any of that, so those tasks
+either fail or get done outside the bottle — which defeats the point of the
+bottle.
+
+## Goals / success criteria
+
+- A bottle with `nested_containers: true` on the `macos-container` backend can
+  run `docker compose up -d --wait` against a stock compose file, pulling from
+  a routed registry and serving from the workspace.
+- The agent's habits do not change: `docker` and `docker compose`, not
+  `podman`.
+- No host Docker socket is mounted, on any backend.
+- No capability is added to the Apple Container guest.
+- Backends without a guest-local engine reject the flag with a clear error
+  rather than ignoring it.
+- Bottles that do not set the flag carry none of its cost.
+
+## Non-goals
+
+- Nested containers as an isolation layer. The single-UID mapping means `root`
+  inside a nested container is the agent user outside it. This is for build and
+  test workloads; the bottle stays the security boundary.
+- The `docker` and `firecracker` backends. Both reject the flag for now.
+- Reaching registries that are not routed through the bottle's egress proxy.
+
+## Design
+
+### Why podman, not rootless Docker
+
+Apple Container's capability bounding set omits `CAP_SYS_ADMIN`, which the
+kernel requires in order to write a multi-range `uid_map` via `newuidmap`.
+Rootless Docker has no path that avoids that write, so it cannot run in a
+bottle without granting `CAP_SYS_ADMIN` — which is close to root in practical
+terms and gives up most of what the bottle is for.
+
+Podman does have a path: with **no** subordinate UID range configured it falls
+back to a single-UID self-mapping, which an unprivileged process may write
+itself. The image build therefore *removes* the agent user's `/etc/subuid` and
+`/etc/subgid` entries rather than adding them — their presence is exactly what
+would send podman down the `newuidmap` path. Full negative result in
+[`docs/research/rootless-docker-in-apple-container-spike.md`](../research/rootless-docker-in-apple-container-spike.md).
+
+### The flag, and its name
+
+The flag is kept because it gates real costs, not because podman needs a
+privilege grant: ~100MB of derived image, a resident service per bottle, and
+relaxed modes on `/dev/fuse` and `/dev/net/tun` that the majority of bottles
+should not get.
+
+It is named `nested_containers`, not `docker_access`. It implies no Docker and
+grants access to nothing on the host — naming it after Docker access would
+describe the one thing the design refuses to do.
+
+### Shape
+
+- `bot_bottle/backend/macos_container/nested_containers.py` — derived-image
+  build, guest env, device preparation, service start/readiness.
+- `bot_bottle/backend/macos_container/nested-containers-init.sh` — the
+  unprivileged bootstrap that runs inside the bottle. Fails closed on every
+  prerequisite it needs (podman, the storage/network helpers, writable device
+  nodes, an *empty* subordinate range) rather than degrading.
+- The derived image `…-nested-containers` layers the Docker CLI, the compose
+  plugin, and podman 5's networking stack — `passt` (pasta), `netavark`,
+  `nftables`, `aardvark-dns` — plus `fuse-overlayfs`, `slirp4netns`, and
+  `uidmap` onto the agent image. Podman itself already ships in every built-in
+  image (#451), but with `--no-install-recommends`, so none of the networking
+  pieces arrive with it. Each absence fails at a different and misleading
+  layer: no pasta and nothing starts; no `nft` and containers are created but
+  never start; no aardvark-dns and DNS inside a container fails while
+  everything else looks healthy. Image pulls keep working throughout, which is
+  what makes these read as compat-API bugs.
+- `BottleBackend.supports_nested_containers` — false by default, so a backend
+  that cannot honor the flag fails in the shared `prepare` template.
+
+Guest configuration the single-UID mapping forces:
+`ignore_chown_errors` (no second UID for layers to be chowned to),
+`cgroups="disabled"` and `cgroup_manager="cgroupfs"` (no cgroup delegation
+reaches the guest), `events_logger="file"` (no journald socket).
+
+### Registry reach
+
+Image pulls egress through the bottle's proxy like everything else, so each
+registry needs a route — **and so does the CDN it redirects blobs to**, which
+is a separate host: `production.cloudfront.docker.com` for Docker Hub,
+`pkg-containers.githubusercontent.com` for GHCR, `cdn0*.quay.io` for quay.
+Without those the pull authenticates, fetches the manifest, and then 403s
+partway through. Docker Hub and GHCR need `preserve_auth: true` — their
+token dance uses a client-fetched per-scope bearer token that the proxy would
+otherwise strip. Layer pulls should also set `dlp.outbound_detectors: false`
+and `dlp.inbound_detectors: false`: body scanning on a multi-hundred-MB layer
+is what triggers #455, and a registry route's scanned bodies are compressed
+layer blobs rather than anything a detector can read.
+
+### Reaching the network from a nested container
+
+Public DNS inside a nested container fails by design: everything egresses
+through the proxy. What was actually broken was reaching the proxy at all, and
+it took four attempts to fix because podman applies proxy settings at several
+layers and the last writer wins:
+
+| Layer | Applies to |
+|---|---|
+| `~/.docker/config.json` proxies block | **every container the Docker CLI starts** — client-side, beats everything below |
+| service environment | podman's own pulls, non-CLI API clients |
+| `containers.conf` `env` | native `podman run` |
+| `containers.conf` `hosts_file`, `http_proxy` | native `podman run` only — the compat API ignores both |
+
+The gateway is named `bot-bottle-gateway`, which resolves only through the
+bottle's `/etc/hosts`; a nested container gets its own. Since no config key
+reaches the compat path, the name is resolved in the bottle and the *address*
+is substituted into the proxy URL at each layer above. `NO_PROXY` keeps the
+name, which is matched against what a client asks for.
+
+The gateway TLS-intercepts, so the CA bundle is mounted read-only and
+`SSL_CERT_FILE`, `CURL_CA_BUNDLE`, `REQUESTS_CA_BUNDLE`, and
+`NODE_EXTRA_CA_CERTS` point at it — no distro-specific trust commands.
+
+## Verified on macOS 26 / Apple Container 1.0.0 / podman 5.4.2
+
+With plain `docker`, no extra flags: image pulls from Docker Hub, GHCR, and
+quay; `docker run` with correct exit-code propagation; `docker compose` up,
+logs, down, and a published port curl'd from the bottle; `curl https://quay.io`
+and `https://pypi.org/simple/` returning 200 from inside a nested container;
+and `https://example.com` returning **403** — the egress allowlist applies to
+nested containers, not just the bottle.
+
+Alpine's BusyBox `wget` drops the connection after TLS interception and
+reports "error getting response". The proxy logs the decrypted request, and
+`curl` on the same host succeeds, so this is a BusyBox client limitation
+rather than anything in the egress path.
+
+## Open questions
+
+- Whether the `docker` and `firecracker` backends want an equivalent, or
+  whether guest-local containers stay macOS-only.

docs/prds/prd-new-secret-provider-encrypted-env.md

@@ -0,0 +1,131 @@
+# PRD prd-new: Encrypted at-rest egress secrets (SecretProvider, interim slice)
+
+- **Status:** Draft
+- **Author:** didericis
+- **Created:** 2026-07-21
+- **Issue:** #355
+
+## Summary
+
+An interim step toward the generic `SecretProvider` (#355) that stops short
+of per-request minting. Today the orchestrator holds each bottle's egress
+auth tokens **in process memory only**, so any infra-container recreation
+silently strips every already-running bottle of its upstream credentials.
+This PRD makes those secrets survive a gateway restart by persisting them
+**encrypted**, under a key that is not itself sitting next to the
+ciphertext.
+
+The end state in #355 — short-lived, scoped credentials minted per request
+— removes the need to store anything durable at all. That is a larger
+change gated on per-upstream minting support. This slice buys back
+restart-survivability now without regressing to plaintext secrets at rest.
+
+## Problem
+
+`Orchestrator._tokens` (`bot_bottle/orchestrator/service.py:74-79`) is a
+plain in-memory dict, deliberately never written to the registry DB:
+
+> Held **in memory only** — never written to the registry DB — so the
+> gateway can inject each bottle's upstream credential without secrets at
+> rest. Lost on restart (re-launch re-registers them); the future
+> SecretProvider (#355) replaces this with per-request minting.
+
+The registry itself *is* durable (SQLite on a container-only volume), and
+so is the gateway CA since #450 / `2cd44cf7`. The tokens are now the only
+piece of gateway state that does not survive a restart, which makes the
+failure mode both silent and confusing.
+
+### Observed failure
+
+Checking out a branch that touches `bot_bottle/**/*.py` changes
+`source_hash()` (`bot_bottle/orchestrator/lifecycle.py:88-99`).
+`MacosInfraService._source_current()`
+(`bot_bottle/backend/macos_container/infra.py:159-169`) sees the mismatch
+and `ensure_running()` force-removes and recreates the infra container
+(`infra.py:198-208`). The registry rows survive on the DB volume; the CA
+survives on its host bind-mount; `_tokens` comes back empty.
+
+Every already-running bottle then fails closed, mid-session, on its next
+outbound request:
+
+- `/resolve` succeeds — the bottle is still `active` in
+  `orchestrator_bottles` and its policy blob is served intact, including
+  `- host: "api.anthropic.com"` with `auth_scheme: Bearer` /
+  `token_env: EGRESS_TOKEN_0`.
+- `tokens_for()` returns `{}`, so the resolved env overlay has no
+  `EGRESS_TOKEN_0`.
+- `decide()` (`bot_bottle/egress_addon_core.py:644-652`) blocks with
+  `egress: route for 'api.anthropic.com' declared auth but env var
+  'EGRESS_TOKEN_0' is unset` — an 89-byte `403` on every request.
+
+Confirmed live on the macOS backend on 2026-07-21: two bottles running
+since 20:29/20:30 were still registered `active` with valid policy after
+the 23:05 infra recreation, and both took 89-byte `403`s from then on,
+while a bottle launched *after* the recreation egressed normally. The
+recovery today is to relaunch every affected bottle.
+
+Note this is a re-attachment blocker distinct from #443/#445 and from #450
+— the CA and the gateway address were both fine. It is specifically the
+credential wipe.
+
+## Goals / Success criteria
+
+1. A bottle's egress auth tokens survive infra-container recreation: an
+   already-running bottle keeps egressing across a gateway restart with no
+   relaunch and no operator action.
+2. Secrets are **never** at rest in plaintext, and never at rest next to a
+   key that trivially decrypts them.
+3. Compromise of the registry DB file alone does not yield usable
+   upstream credentials.
+4. The stored form is revocable and rotatable without relaunching bottles
+   that are not affected.
+5. When the retained bottle record reaches the lifecycle status `removed`,
+   its stored secrets are destroyed. Status/event persistence and the removal
+   transition land separately; this interim slice intentionally retains the
+   ciphertext across today's teardown/reconcile calls until that lifecycle is
+   available.
+6. Migration is transparent: existing bottles keep working, no manifest
+   changes required.
+
+## Non-goals
+
+- **Per-request minting** of short-lived scoped credentials. That is the
+  #355 end state; this PRD is explicitly the interim slice and should not
+  foreclose it.
+- Generalizing `DeployKeyProvisioner` into the full `SecretProvider` ABC,
+  or the manifest-level `{ provider: <name> }` reference surface.
+- User-extensible provider discovery (`~/.bot-bottle/contrib/<name>/`).
+- Changing the `/resolve` contract's shape (it already carries `tokens`).
+- Fixing the *trigger* — `source_hash` churn on branch switch. Recreating
+  infra is legitimate; it just must not cost running bottles their
+  credentials. A separate guard that refuses recreation while bottles are
+  active is complementary and out of scope here.
+
+## Design
+
+> **TODO (didericis):** the encryption flow goes here — key custody, where
+> the key material lives relative to the ciphertext, the wrap/unwrap path
+> at register and at `/resolve`, and what an attacker who holds only the
+> DB (or only the host, or only the infra container) can recover.
+
+Constraints the design has to satisfy, for reference while drafting:
+
+- The gateway's `PolicyResolver` needs the cleartext at request time, on
+  the data-plane path, so unwrap has to be cheap enough to sit in a
+  per-flow `/resolve` (or be cached in memory after first unwrap).
+- The infra container is recreated routinely and unattended. Anything
+  requiring an interactive unlock on every recreation defeats the goal.
+- The DB lives on a container-only volume that the host does not mount, so
+  host-side and guest-side components see different filesystems — that
+  asymmetry is available as a place to split custody.
+- The agent must never be able to reach the key material. It is a separate
+  container with no control-plane token, which is the existing boundary.
+
+## Open questions
+
+- Where does the unwrap key live, and what recreates/re-derives it when the
+  infra container is rebuilt?
+- Is the cleartext cached in memory after first unwrap, or unwrapped per
+  request? (Latency vs. exposure window.)
+- What is the rotation story — re-wrap in place, or force re-registration?
+- Does this land behind a flag, or replace `_tokens` outright?

docs/research/egress-proxy-oom-on-large-downloads.md

@@ -0,0 +1,86 @@
+# Egress proxy OOMs on large downloads
+
+Found on 2026-07-21 while running the rootless-podman spike
+(`docs/research/rootless-docker-in-apple-container-spike.md`). Recorded
+rather than fixed — the fix is a security-relevant decision, not a
+mechanical patch.
+
+## Summary
+
+A single large HTTPS download through the gateway kills the egress
+proxy. `mitmdump` buffers whole response bodies so the DLP detectors can
+scan them, grows past the gateway container's memory limit, and is
+OOM-killed by the cgroup. Nothing restarts it.
+
+Two properties make this worse than a failed download:
+
+- **The gateway is a per-host singleton.** Every bottle shares it, so
+  one bottle's download takes egress away from all of them.
+- **There is no restart on death.** The gateway supervisor is
+  `while : ; do wait ; done`; a killed daemon stays dead until the infra
+  container is recreated.
+
+So ordinary agent activity — pulling a container image, downloading a
+model or dataset, fetching a large tarball — is a denial of service
+against every other bottle on the host. No malice required, though it is
+trivially reachable on purpose.
+
+## Evidence
+
+Triggered by `docker compose up` pulling `quay.io/fedora/python-312`
+(two layers, ~82MB and ~83MB) inside a bottle. The pull itself
+succeeded; the *next* request failed:
+
+```
+initializing source docker://quay.io/fedora/python-312:latest:
+  pinging container registry quay.io: Get "https://quay.io/v2/":
+  proxyconnect tcp: dial tcp 192.168.128.39:9099: connect: connection refused
+```
+
+From the gateway's `dmesg`:
+
+```
+python3 invoked oom-killer: gfp_mask=0x100cca(GFP_HIGHUSER_MOVABLE), order=0
+oom-kill:constraint=CONSTRAINT_MEMCG,
+  oom_memcg=/container/bot-bottle-mac-infra,
+  task_memcg=/container/bot-bottle-mac-infra,task=mitmdump,pid=118
+Memory cgroup out of memory: Killed process 118 (mitmdump)
+  total-vm:1391936kB, anon-rss:997768kB
+```
+
+~1GB RSS against a 1024MB container. Note the amplification: ~165MB of
+layers produced ~1GB of resident memory, so the buffering is several
+copies deep (encoded body, decoded body, and the text conversion the
+regex detectors scan).
+
+Afterwards the gateway container was still running and healthy-looking —
+orchestrator, supervise, and git-http all alive — with no `mitmdump`
+process at all, and it stayed that way until the container was
+recreated. A liveness check on the container would not have caught this.
+
+## Reproduction
+
+1. Launch any bottle with an egress route to a host serving a large file.
+2. Download >~150MB over HTTPS through the proxy.
+3. `dmesg | grep -i oom` inside `bot-bottle-mac-infra`, and note that no
+   `mitmdump` process remains.
+
+Beware a false negative when checking: truncating the process listing
+(`cut -c1-45`) cuts before the binary name, because `mitmdump` runs as
+`/usr/local/bin/python3.12 /usr/local/bin/mitmdump …`.
+
+## Fix options, not yet chosen
+
+1. **Restart dead daemons.** Smallest change and strictly an
+   improvement: an OOM then degrades one download instead of removing
+   egress for every bottle. Does not stop the OOM.
+2. **Cap the scanned body size.** Above a threshold, stop buffering —
+   either skip the scan or stream it. This is the root-cause fix and a
+   security decision: a size threshold is exactly the hole an exfiltrator
+   would aim for, so "skip above N" trades a DoS for a covert channel.
+   Streaming with a bounded window keeps coverage, at more complexity.
+3. **Raise the gateway's memory limit.** Moves the threshold; does not
+   remove it.
+
+Worth noting that (1) and (2) are complementary — the restart gap is
+worth closing regardless of how the memory behaviour is resolved.

docs/research/firecracker-image-remote-store.md

@@ -0,0 +1,178 @@
+# Firecracker Image Remote Store
+
+**Date:** 2026-07-22  
+**Context:** PR #459 (run-dir leak fix) surfaced that committed Firecracker snapshots
+currently live only on the host machine. Once a host is wiped or a run-dir is
+evicted, a user's preserved bottle is gone. This note investigates a secure remote
+store so committed images survive host turnover and can be restored without the
+user having to pre-flag which sessions to keep.
+
+## Verdict
+
+Backblaze B2 + Cloudflare CDN is the cost-optimal choice for most deployments.
+Cloudflare R2 is the simpler zero-config option at slightly higher storage cost.
+Self-hosted MinIO is the right call for air-gapped or on-premises installs.
+
+On the image-size front, zstd-compressing the committed tar before upload
+produces roughly a 60–70% reduction with negligible impact on restore latency.
+OverlayFS (for in-flight working rootfs, not for the committed artifact) cuts
+per-instance disk use to ~10–50 MB per extra bottle sharing the same base.
+
+---
+
+## What Gets Stored
+
+The Firecracker backend produces two artifact types:
+
+| Artifact | Created by | Size | Lifetime |
+|----------|-----------|------|---------|
+| `rootfs/agent-<digest>/` (dir) | `image_builder.py` → `mke2fs -d` | ~1 GB as ext4 | Cached per Dockerfile hash; evictable |
+| `committed/<slug>/rootfs.tar` | `FirecrackerFreezer._freeze` via SSH tar | 500 MB–1 GB | User-preserved; must survive host wipe |
+
+The committed artifact is a tar of the guest's live filesystem streamed out over
+SSH (`freezer.py:58–90`). At resume time `launch.py` calls `mke2fs -d` to
+rebuild a fresh ext4 from this tar. The tar — not the ext4 — is what needs to be
+pushed to remote storage and pulled back at restore time.
+
+The base image cache (`rootfs/agent-<digest>/`) is derivable from the Dockerfile
+and can be rebuilt on demand; it is lower priority for remote storage.
+
+---
+
+## Storage Candidates
+
+### Object storage
+
+| Provider | Storage | Egress | Notes |
+|----------|---------|--------|-------|
+| **Backblaze B2** | $0.006/GB | Free (via Cloudflare Bandwidth Alliance) | Cheapest storage; pairs with Cloudflare CDN to eliminate egress |
+| **Cloudflare R2** | $0.015/GB | $0 always | Zero-config egress; no lifecycle transitions (limitation) |
+| **Wasabi** | $0.0069/GB | Free (1:1 ratio) | 90-day minimum retention; good for archival; lifecycle evaluated daily |
+| **AWS S3** | $0.023/GB | $0.09/GB | Richest lifecycle support; expensive at scale; avoid unless already in AWS |
+| **MinIO** (self-hosted) | Host cost only | None | S3-compatible; best for private/on-prem deployments |
+
+**B2 + Cloudflare CDN** is effectively $0.006/GB with zero egress — about 18×
+cheaper than S3 for restore-heavy workloads. **R2** is the zero-config choice
+($0 egress by default, no Bandwidth Alliance pairing needed) at a slightly
+higher storage rate.
+
+**Cloudflare R2's missing lifecycle support** is the main caveat: auto-eviction
+rules (evict images older than N days) cannot currently be expressed natively in
+R2. Wasabi and S3 both support declarative lifecycle policies.
+
+### Retention policy recommendation
+
+The comment proposes:
+- Retain images for ~1 week by default
+- Warn when approaching a capacity threshold
+- Auto-evict oldest images once threshold is exceeded
+
+This maps cleanly to an application-level policy (not a provider lifecycle rule),
+which avoids the R2 limitation and works consistently across providers:
+
+1. On `commit`: upload tar, record `(slug, size_bytes, uploaded_at)` in a local
+   or remote manifest file.
+2. On startup / on `list`: scan the manifest, warn if total stored size exceeds
+   e.g. 80% of the configured threshold.
+3. On eviction run (CLI or cron): delete objects older than `retention_days`
+   (default 7) that push total over `max_capacity`; oldest-first.
+
+This keeps the policy logic in bot-bottle and the storage provider as a dumb
+object store — no vendor-specific lifecycle API required.
+
+---
+
+## Image Size Reduction
+
+### Current artifact sizes
+
+A typical committed tar for a Claude Code agent image is 500 MB–1 GB uncompressed.
+The per-run ext4 (copy of the base, written at `start`) adds another ~1 GB of
+local disk. The leak fix in this PR addresses the ext4 copies; the remote store
+addresses the committed tars.
+
+### Compression
+
+zstd compression of the committed tar before upload is the highest-leverage
+single change:
+
+| Codec | Typical size (1 GB rootfs) | Compress speed | Decompress speed |
+|-------|---------------------------|---------------|-----------------|
+| gzip | 350–430 MB | ~100 MB/s | ~500 MB/s |
+| **zstd (default)** | **330–360 MB** | **~400 MB/s** | **~2 GB/s** |
+| xz | 290–320 MB | ~20 MB/s | ~200 MB/s |
+
+**zstd is the best trade-off**: 65–67% size reduction, near-instantaneous
+decompression. The `tar` call in `freezer.py` could pipe through `zstd` before
+writing to disk and to the remote; `resume` decompresses on the way back. A
+`.tar.zst` suffix marks compressed artifacts so old tars remain restorable
+without the codec.
+
+### SquashFS for the base image cache
+
+The `rootfs/agent-<digest>/` directory (the buildah-exported tree) is rebuilt by
+`image_builder.py` and turned into per-run ext4 by `mke2fs -d`. Storing the
+base as a SquashFS image instead of a flat directory tree would reduce it from
+~1 GB to ~330–360 MB and make the cache remote-friendly. Firecracker does not
+directly boot SquashFS, but the existing `mke2fs -d` path reads a directory tree
+— a SquashFS mount could serve as the source. This is a larger change and lower
+priority than tar compression.
+
+### OverlayFS for per-run rootfs
+
+Multiple simultaneous bottles sharing the same agent image today each get a full
+`mke2fs -d` copy (~1 GB). OverlayFS (read-only base + writable sparse overlay)
+would reduce this to ~10–50 MB per instance beyond the first:
+
+- Mount the base image directory as read-only lower layer
+- Attach a sparse ext4 or tmpfs writable layer per bottle
+- Pass the merged overlay to Firecracker as the block device
+
+E2B's public write-up on Firecracker + OverlayFS confirms this approach works
+at scale. The `launch.py` changes would be non-trivial (device mapper or
+`fuse-overlayfs` plumbing), so this is a follow-up rather than a prerequisite
+for the remote store.
+
+---
+
+## Recommended Approach
+
+**Phase 1 — remote store with zstd (tight scope, actionable now)**
+
+1. Add `--zstd` to the `tar` call in `FirecrackerFreezer._freeze`; name the
+   artifact `rootfs.tar.zst`. Keep uncompressed restore path for legacy tars.
+2. Add a `bb firecracker upload <slug>` / `bb firecracker pull <slug>` pair that
+   pushes/fetches the compressed tar to the configured object store (S3-compatible
+   API, so B2, R2, MinIO, and Wasabi all work with the same client).
+3. Store a `manifest.json` in the bucket (or a local mirror) tracking slug →
+   `{size, uploaded_at}`. Use it for threshold warnings and eviction.
+4. Default retention: 7 days, configurable via `firecracker.image_retention_days`
+   in `~/.config/bot-bottle/config.toml` (or equivalent).
+5. Warn at 80% of `max_capacity` (default e.g. 50 GB); evict oldest on commit
+   once at 100%.
+
+**Storage recommendation:** Cloudflare R2 for hosted deployments (zero egress,
+zero config), MinIO for private/on-premises.
+
+**Phase 2 — base image cache compression**
+
+Compress the `agent-<digest>` cache dir as a `.tar.zst` to save ~65% on repeated
+image uploads. Low urgency since the base image is rebuildable.
+
+**Phase 3 — OverlayFS per-run disk**
+
+Replace the full per-run ext4 copy with an OverlayFS sparse layer. Largest disk
+impact (~90–95% savings per concurrent bottle) but highest implementation
+complexity. Track as a separate PRD.
+
+---
+
+## Open Questions
+
+- Does the host have a configured object-store credential path, or should the
+  remote store be an opt-in with an explicit `bb config set image-store.url ...`?
+- Should `commit` automatically upload, or should upload be an explicit step to
+  avoid surprise egress?
+- What is the acceptable cold-start latency for a restore from remote? A 330 MB
+  zstd tar at 100 Mbit/s takes ~26 s; at 1 Gbit/s, ~2.6 s. This bounds the
+  retention strategy (evict from local after successful upload vs keep local copy).

docs/research/rootless-docker-in-apple-container-spike.md

@@ -0,0 +1,359 @@
+# Rootless Docker inside Apple Container bottles
+
+Spike branch: `spike/rootless-docker-macos` (`a4d8461`)
+
+**Outcome:** the podman recommendation below shipped as the
+`nested_containers` bottle flag — see
+[`docs/prds/prd-new-nested-containers.md`](../prds/prd-new-nested-containers.md).
+The `docker_access` name used throughout the spike text was renamed on the
+way in; it granted no access to anything on the host.
+
+## Summary
+
+**Negative result.** Rootless Docker cannot run inside an Apple
+Container bottle without granting the bottle `CAP_SYS_ADMIN`. This is a
+kernel constraint on writing multi-range `uid_map`, not a packaging gap
+we can close with a better init script, a different base image, or more
+careful `/etc/subuid` handling.
+
+The spike was built on the premise — stated in
+`bot_bottle/backend/macos_container/rootless_docker.py` — that it would
+*"deliberately refuse to compensate for missing prerequisites with outer
+capabilities, a privileged container, or a host Docker socket."* That
+premise is exactly what the experiment falsified. The two ways forward
+are to abandon the premise (add `CAP_SYS_ADMIN` to the bottle, and with
+it most of the isolation the bottle exists to provide) or to abandon
+rootless Docker.
+
+Recommendation: abandon rootless Docker. Podman does not have this
+problem — see [Podman is not blocked by
+this](#podman-is-not-blocked-by-this) below.
+
+## Local environment
+
+Tested on 2026-07-21:
+
+```console
+$ sw_vers
+ProductName:		macOS
+ProductVersion:		26.5.1
+BuildVersion:		25F80
+
+$ container --version
+container CLI version 1.0.0 (build: release, commit: ee848e3)
+
+$ uname -a   # inside the bottle
+Linux ... 6.18.15 #1 SMP Tue Mar 17 01:36:53 UTC 2026 aarch64 GNU/Linux
+```
+
+## The failure
+
+`tests/integration/test_macos_rootless_docker_spike.py` builds the
+image, launches the bottle, and dies in `rootless_docker.start`:
+
+```
++ exec rootlesskit --net=slirp4netns --mtu=65520 ... dockerd-rootless.sh
+[rootlesskit:parent] error: failed to setup UID/GID map:
+  newuidmap 1100 [0 1000 1 1 100000 65536] failed:
+  newuidmap: write to uid_map failed: Operation not permitted
+```
+
+## Why it fails
+
+Every prerequisite you would normally suspect is present and correct in
+the guest:
+
+| Check | Result |
+| --- | --- |
+| `/usr/bin/newuidmap` | `-rwsr-xr-x root root` — setuid bit intact, survived the OCI export |
+| `/` mount options | `rw,relatime` — **not** `nosuid` |
+| `NoNewPrivs` | `0` |
+| `Seccomp` | `0`, no filters |
+| `/etc/subuid`, `/etc/subgid` | `node:100000:65536` in both |
+| user namespace | `user:[4026531837]`, identical to pid 1 — the *initial* userns |
+| `unshare -U -r true` | succeeds |
+| `/proc/sys/user/max_user_namespaces` | `4505` |
+
+The one thing that is missing is in the capability bounding set that
+Apple Container gives the container:
+
+```
+CapBnd: 00000000a80425fb
+= chown, dac_override, fowner, fsetid, kill, setgid, setuid, setpcap,
+  net_bind_service, net_raw, sys_chroot, mknod, audit_write, setfcap
+```
+
+No `CAP_SYS_ADMIN`. That is the whole story, and the chain is:
+
+1. The kernel's `map_write()` gates writing a `uid_map` on
+   `file_ns_capable(file, ns, CAP_SYS_ADMIN)` — capability over the
+   **new** user namespace, evaluated against the credentials that opened
+   `/proc/<pid>/uid_map`.
+2. `newuidmap` is setuid-root, so it runs with euid 0 — but its
+   capability sets are clamped by the bounding set, which has no
+   `CAP_SYS_ADMIN`.
+3. `cap_capable()` has a shortcut that grants *all* capabilities when
+   the caller's userns is the new namespace's parent **and**
+   `ns->owner == cred->euid`. It does not apply: the namespace was
+   created by `node` (uid 1000) while `newuidmap` runs as euid 0.
+4. So the check falls through to the effective-set test in the initial
+   userns, which fails. `EPERM`.
+
+Note that the single-line unprivileged path (`unshare -U -r`) works
+precisely because it does not go through `newuidmap` and does not need
+`CAP_SYS_ADMIN`. Only the multi-range subuid mapping that rootless
+Docker requires does.
+
+This is the same constraint that makes upstream's `dind-rootless` image
+require `--privileged`. It is not specific to Apple Container, except
+that Apple Container gives us no bounding set that includes
+`CAP_SYS_ADMIN` by default.
+
+## It does work with the capability — which is the point
+
+Adding the capability clears the failure immediately, and exposes one
+further, much smaller blocker: `/dev/net/tun` exists (the kernel has
+tun; `/proc/misc` lists `200 tun`) but Apple Container creates it
+`crw------- root root`, so uid 1000 cannot open it and `slirp4netns`
+fails with `open: Permission denied`. A `chmod 0666 /dev/net/tun` as
+root inside the bottle fixes that, and needs no capability beyond what
+the bottle already has.
+
+With both applied by hand, the daemon comes up completely:
+
+```console
+$ container run --rm -u root --cap-add CAP_SYS_ADMIN \
+    bot-bottle-claude:latest-rootless-docker sh -c '...'
+Server Version: 20.10.24+dfsg1
+Storage Driver: fuse-overlayfs
+Cgroup Driver: none
+Cgroup Version: 2
+API listen on /tmp/rt/docker.sock
+```
+
+So `rootless-docker-init.sh` and `rootless_docker.py` are *correct*.
+The spike did not fail on a bug. It failed on its own premise.
+
+Two secondary findings from that run, relevant if anyone revisits this:
+
+- Debian's `docker.io` package pins Docker **20.10** (EOL), not the 28.x
+  implied by the `docker:28-cli` compose plugin the image copies in.
+- `Cgroup Driver: none` — no resource limits on nested containers.
+
+## Why we should not just add the capability
+
+`CAP_SYS_ADMIN` is close to a superset of "root" in practical terms —
+mount, `pivot_root`, namespace manipulation, and a long tail of
+subsystem-specific powers. Granting it to the agent bottle would
+undercut the containment argument the rest of the backend is built
+around, including the deliberately narrow choices immediately adjacent
+to it in `launch.py` (`--cap-drop CAP_NET_RAW`, no `NET_ADMIN`, a
+host-only agent network). Trading all of that for nested `docker
+compose` is a bad exchange.
+
+## Podman is not blocked by this
+
+Sanity-checked on the same host, same kernel, same runtime, so the
+comparison is apples to apples:
+
+| Scenario | Result |
+| --- | --- |
+| Podman rootless, `/etc/subuid` populated | **Fails identically** — `newuidmap: write to uid_map failed: Operation not permitted` |
+| Podman rootless, no subuid ranges, `--network=host` | **Works**, no added capabilities |
+| Podman rootless, no subuid ranges, default netns, `/dev/net/tun` at `0600` | Fails — `slirp4netns: open("/dev/net/tun"): Permission denied` |
+| Podman rootless, no subuid ranges, default netns, `/dev/net/tun` at `0666` | **Works**, no added capabilities |
+
+The difference is that podman degrades gracefully when no subuid range
+is available: it falls back to a single-UID self-mapping, which an
+unprivileged process may write itself, so `newuidmap` is never invoked
+and `CAP_SYS_ADMIN` is never needed. Docker's rootless mode has no
+equivalent fallback.
+
+The cost of that fallback is real and should be weighed before building
+on it: with a single-UID mapping, every UID inside a nested container
+collapses onto the bottle's own uid 1000. There is no UID separation
+between the agent and anything it runs — `root` in a nested container is
+the agent user outside it. It also requires `ignore_chown_errors` on the
+storage driver. Whether that is acceptable depends on whether the bottle
+boundary (which is unchanged) or the nested-container boundary (which is
+effectively nil) is the one we are relying on.
+
+## What the podman spike then needed
+
+The podman implementation that replaced the Docker one on this branch
+turned up two more device-node blockers of the same shape as
+`/dev/net/tun` — Apple Container creates the node, but 0600 root:root:
+
+- **`/dev/fuse`** — blocks the `fuse-overlayfs` storage driver
+  (`fuse: failed to open /dev/fuse: Permission denied`). Without it the
+  only working driver is `vfs`, which copies whole layers per container.
+- **`/dev/net/tun`** — blocks `slirp4netns`, which rootless podman uses
+  for the default bridge network.
+
+Both are fixed by `chmod 0666` as root inside the bottle, which needs no
+capability the bottle does not already hold. This is categorically
+different from the `CAP_SYS_ADMIN` requirement: it is a permission on a
+node that already exists, not an outer privilege grant.
+
+One design note worth recording: the agent-facing surface stays `docker`
+and `docker compose`, pointed at podman's Docker-compatible API socket
+via `DOCKER_HOST`. Setting `netns="host"` in `containers.conf` does *not*
+propagate through that compat API — stock `docker run` and compose files
+request bridge networking explicitly — so slirp4netns (and therefore the
+`/dev/net/tun` chmod) is required for ordinary compose files to work at
+all. Host networking remains available per-workload via
+`--network=host`.
+
+Verified working in a bottle with zero added capabilities: fuse-overlayfs
+storage, the compat API socket, `docker run` on both bridge and host
+networking, and published ports.
+
+### Nested pulls collide with our own egress DLP
+
+The first live run got podman up and `docker compose` running, then
+failed on the image pull:
+
+```
+web Pulling
+initializing source docker://python:3.12-alpine: reading manifest ...
+StatusCode: 403, egress DLP: Generic Bearer JWT found in body
+```
+
+This is bot-bottle's own egress scanner, not a podman problem. The
+Docker registry auth flow carries a bearer JWT *by protocol*, and the
+`token_patterns` detector's `Generic Bearer JWT` rule
+(`Bearer\s+[A-Za-z0-9._\-]{50,}`) matches it on every pull. Any bottle
+that pulls images will hit this.
+
+The fix is per-route detector scoping, which the egress config already
+supports — drop `token_patterns` on the registry hosts and keep
+`known_secrets`:
+
+```json
+{"host": "registry-1.docker.io",
+ "dlp": {"outbound_detectors": ["known_secrets"]}}
+```
+
+That is the right trade rather than a grudging one: `known_secrets`
+matches the bottle's *actual* credential values, so real exfil through a
+registry host is still caught. `token_patterns` on a registry route only
+ever produces protocol noise.
+
+Worth generalising later: any manifest enabling `nested_containers` needs
+this on its registry routes, so it probably belongs in a shared
+registry-route snippet rather than being copy-pasted per bottle.
+
+### And then registry auth collides with the Authorization strip
+
+With DLP scoped, the pull failed differently: `unauthorized:
+authentication required`. This one is architectural.
+
+`egress_addon.py` strips agent-set `Authorization` unconditionally
+before forwarding — deliberately, so an agent cannot smuggle a
+credential out in a header the DLP detectors don't recognise. A route
+may carry gateway-injected auth instead, but only from a *static* token
+in an env var (`auth_scheme` + `token_env`).
+
+Docker registry auth doesn't fit that shape. The client fetches a
+short-lived, per-repository-scope bearer token from `auth.docker.io` and
+presents it to `registry-1.docker.io`. There is no static token to
+inject, and the token the client legitimately obtained is stripped.
+
+Measured inside a bottle, by hand:
+
+| Step | Result |
+| --- | --- |
+| Fetch token from `auth.docker.io` | 200, 5409-byte token body |
+| Manifest request **with** that valid token | 401 |
+| Manifest request with **no** Authorization | 401 — identical |
+
+A valid token behaves exactly like sending none, which is direct
+evidence the header never arrives. Any nested-container workflow that
+pulls from a registry is blocked on this, so it is not a detail that can
+be deferred: pulling base images is most of what nested containers are
+for.
+
+### Registries that skip the token dance work today
+
+Not every registry needs the stripped header. Measured directly:
+
+| Registry | Manifest request with no `Authorization` |
+| --- | --- |
+| `quay.io` | 200 |
+| `mcr.microsoft.com` | 200 |
+| `registry.k8s.io` | 307 (redirect, no auth) |
+| `ghcr.io` | 401 |
+| `registry-1.docker.io` | 401 |
+
+So "just add the registry to the bottle config" genuinely works — for
+quay, MCR, registry.k8s.io, or any unauthenticated internal registry.
+Docker Hub and GHCR are the ones that need the strip resolved. The
+acceptance test uses quay for exactly this reason.
+
+Resolving it for Docker Hub means picking one of:
+
+1. **Per-route opt-in to preserve client Authorization.** Smallest
+   change. Note the compounding effect on exactly these routes: the DLP
+   scoping above already removed `token_patterns` there, so a
+   preserved-auth registry route is one where the agent may send bearer
+   tokens that neither the strip nor the pattern detector inspects.
+   `known_secrets` still applies, so the bottle's real credentials are
+   still caught.
+2. **A registry-aware gateway** that performs the token dance itself and
+   injects the result. Preserves the invariant fully; materially more
+   work, and it makes the gateway speak a specific registry protocol.
+3. **Pre-seed images at provision time** (host-side `container image
+   save` into podman storage), so bottles never pull at runtime.
+   Preserves the invariant, and limits nested containers to
+   pre-approved images — which fits the custody positioning, at the cost
+   of no ad-hoc `docker pull`.
+4. **Stop.** Nested containers are not supported on this backend.
+
+### Podman 4.3.1 silently swallows container exit codes
+
+Debian bookworm — which the current agent base image is built on —
+ships podman 4.3.1. Through its Docker-compatible API, `docker run`
+returns 0 no matter what the container did:
+
+| Command | podman 4.3.1 | podman 5.4.2 |
+| --- | --- | --- |
+| `docker run … sh -c 'exit 7'` (compat API) | **0** | 7 |
+| `docker run … sh -c 'exit 0'` (compat API) | 0 | 0 |
+| `podman run … sh -c 'exit 7'` (native) | 7 | 7 |
+
+This is worse than a broken feature: every failing command an agent runs
+via `docker run` reports success. A test suite, a build step, or a CI
+script inside a bottle would pass while failing. It also silently
+defeated the acceptance test's egress-containment assertion, which is
+why that assertion now checks an in-band marker rather than an exit
+code.
+
+Podman 5.4.2 (Debian trixie) fixes it, but needs two packages that
+bookworm's podman does not: `passt` (podman 5's default network tool)
+and `nftables` (netavark shells out to `nft`; without it every run fails
+with `unable to upgrade to tcp, received 500`). With both installed,
+exit codes propagate correctly and the compat API behaves.
+
+The open question this leaves is where podman 5 comes from, since the
+agent base is bookworm-based:
+
+1. **Move the agent images to Debian trixie.** Trixie is current stable.
+   Correct, and the blast radius is every bottle, not just this feature.
+2. **Drop the compat socket and use podman natively** (`podman-docker`
+   provides a `docker` shim; compose comes from `podman-compose`).
+   Native podman propagates exit codes correctly even on 4.3.1. Contained
+   to this feature, at the cost of `docker compose` becoming
+   `docker-compose`/`podman-compose`.
+3. **Ship bookworm's podman 4.3.1 with the compat socket** — not viable.
+   Silent false success is a correctness bug agents cannot see.
+
+## Recommendation
+
+1. Do not revive rootless Docker on this backend. This document is the
+   record of why.
+2. Nested containers, if wanted, come from podman under the
+   single-mapping constraint — with the explicit understanding that the
+   nested-container boundary carries no security weight. `root` in a
+   nested container is the agent user outside it.
+3. Nested containers are therefore a build/test convenience. The bottle
+   remains the security boundary, exactly as it was.

scripts/coverage.sh

@@ -1,15 +1,19 @@
 #!/usr/bin/env bash
 # Combined unit + integration coverage (see docs/decisions/0004-coverage-policy.md).
 #
-# Runs the unit suite, then appends the integration suite (which skips
-# cleanly when Docker / the backend CLIs are unavailable), and prints one
-# combined report. The integration suite is what scores the subprocess /
-# backend orchestration modules, so the number here is the policy's
-# yardstick — not the unit-only badge.
+# Two modes:
 #
-# Usage:
-#   scripts/coverage.sh            # combined report
-#   scripts/coverage.sh critical   # also report just the critical modules
+#   scripts/coverage.sh [critical]
+#     Run mode (default, for local dev): executes the unit suite then the
+#     integration suite under coverage and prints a combined report.
+#
+#   scripts/coverage.sh aggregate [critical]
+#     Aggregate mode (used by CI): combines pre-existing .coverage.* files
+#     produced by individual test jobs and prints a combined report. No tests
+#     are re-executed; no KVM or Docker dependency.
+#
+# Pass "critical" as the last argument in either mode to also report just the
+# critical modules (ADR 0004 target: 90%).
 set -euo pipefail
 
 cd "$(dirname "$0")/.."
@@ -21,6 +25,22 @@ PY="${PYTHON:-python3}"
 # README "core coverage" badge can't drift; comma-join it for --include.
 CRITICAL=$(grep -vE '^[[:space:]]*(#|$)' scripts/critical-modules.txt | paste -sd, -)
 
+if [ "${1:-}" = "aggregate" ]; then
+    # Aggregate mode: combine .coverage.* artifacts already in the workspace.
+    echo "== combining coverage artifacts ==" >&2
+    "$PY" -m coverage combine
+
+    echo "== combined report ==" >&2
+    "$PY" -m coverage report -m
+
+    if [ "${2:-}" = "critical" ]; then
+        echo "== critical modules (ADR 0004 target: 90%) ==" >&2
+        "$PY" -m coverage report --include="$CRITICAL"
+    fi
+    exit 0
+fi
+
+# Run mode (default): execute both suites under coverage in this process.
 rm -f .coverage
 
 echo "== unit ==" >&2

tests/integration/test_sandbox_escape.py

@@ -172,7 +172,7 @@ class TestSandboxEscape(unittest.TestCase):
         # base image without producing five confusing
         # command-not-found failures down the suite.
         missing: list[str] = []
-        for tool in ("curl", "git", "dig"):
+        for tool in ("curl", "git", "dig", "ssh"):
             r = cls._bottle.exec(f"command -v {tool} >/dev/null 2>&1")
             if r.returncode != 0:
                 missing.append(tool)

tests/unit/_docker_bottle_plan.py

@@ -46,7 +46,9 @@ def _manifest(*, supervise: bool, with_git: bool, with_egress: bool) -> Manifest
         bottle["egress"] = {
             "routes": [{
                 "host": "api.example",
-                "auth": {"scheme": "Bearer", "token_ref": "TOK"},
+                "inspect": {
+                    "auth": {"scheme": "Bearer", "token_ref": "TOK"},
+                },
             }],
         }
     return ManifestIndex.from_json_obj({

tests/unit/test_agent_provider.py

@@ -9,11 +9,15 @@ 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 CODEX_HOST_CREDENTIAL_TOKEN_REF
+from bot_bottle.egress import (
+    CLAUDE_HOST_CREDENTIAL_TOKEN_REF,
+    CODEX_HOST_CREDENTIAL_TOKEN_REF,
+)
 
 
 def _jwt(exp: int) -> str:
@@ -292,6 +296,67 @@ 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(

tests/unit/test_backend_prepare.py

@@ -21,7 +21,7 @@ from bot_bottle.backend.firecracker import FirecrackerBottleBackend
 from bot_bottle.manifest import ManifestIndex
 
 
-def _manifest() -> ManifestIndex:
+def _manifest(*, nested_containers: bool = False) -> ManifestIndex:
     return ManifestIndex.from_json_obj({
         "bottles": {
             "dev": {
@@ -29,6 +29,7 @@ def _manifest() -> ManifestIndex:
                     "LITERAL_ENV": "literal-value",
                     "FORWARDED_ENV": "${HOST_SECRET_ENV}",
                 },
+                "nested_containers": nested_containers,
             },
         },
         "agents": {
@@ -41,9 +42,11 @@ def _manifest() -> ManifestIndex:
     })
 
 
-def _spec(tmp: Path, *, identity: str) -> BottleSpec:
+def _spec(
+    tmp: Path, *, identity: str, nested_containers: bool = False,
+) -> BottleSpec:
     return BottleSpec(
-        manifest=_manifest(),
+        manifest=_manifest(nested_containers=nested_containers),
         agent_name="demo",
         copy_cwd=False,
         user_cwd=str(tmp),
@@ -113,6 +116,42 @@ class TestFirecrackerPrepare(_FakeStateMixin, unittest.TestCase):
         self.assertEqual({"FORWARDED_ENV": "secret-value"}, plan.forwarded_env)
 
 
+class TestNestedContainersRejection(_FakeStateMixin, unittest.TestCase):
+    """A backend with no guest-local engine must refuse the flag outright.
+
+    Ignoring it would leave the agent without `docker`, and the only ways to
+    fake it here (a host daemon socket, a privileged container) are what
+    issue #392 rules out.
+    """
+
+    def test_docker_backend_refuses_the_flag(self) -> None:
+        backend = DockerBottleBackend()
+        spec = _spec(
+            Path(self.tmp.name), identity="demo-docker", nested_containers=True,
+        )
+        with (
+            patch(
+                "bot_bottle.backend.resolve_common.die", side_effect=RuntimeError,
+            ) as die,
+            self.assertRaises(RuntimeError),
+        ):
+            backend.prepare(spec, Path(self.tmp.name) / "stage")
+        self.assertIn("nested_containers", die.call_args.args[0])
+        self.assertIn("docker", die.call_args.args[0])
+
+    def test_firecracker_backend_refuses_the_flag(self) -> None:
+        backend = FirecrackerBottleBackend()
+        spec = _spec(Path(self.tmp.name), identity="demo-fc", nested_containers=True)
+        with (
+            patch(
+                "bot_bottle.backend.resolve_common.die", side_effect=RuntimeError,
+            ) as die,
+            self.assertRaises(RuntimeError),
+        ):
+            backend.prepare(spec, Path(self.tmp.name) / "stage")
+        self.assertIn("firecracker", die.call_args.args[0])
+
+
 class TestMintSlug(unittest.TestCase):
     def _spec(self, *, label: str = "", identity: str = "") -> BottleSpec:
         manifest = _manifest()

tests/unit/test_backend_secret_reprovision.py

@@ -0,0 +1,160 @@
+"""Backend-agnostic and backend-specific encrypted-secret recovery tests."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import tempfile
+import unittest
+from pathlib import Path
+from types import SimpleNamespace
+from unittest.mock import Mock, patch
+
+from bot_bottle.orchestrator.reprovision import reprovision_bottles
+from bot_bottle.backend.firecracker import consolidated_launch as fc
+from bot_bottle.backend.macos_container import consolidated_launch as mac
+from bot_bottle.backend.docker import consolidated_launch as docker
+from bot_bottle.orchestrator.client import OrchestratorClientError
+
+
+def _proc(returncode: int = 0, stdout: str = "", stderr: str = ""):
+    return subprocess.CompletedProcess([], returncode, stdout=stdout, stderr=stderr)
+
+
+class TestSharedReprovision(unittest.TestCase):
+    def test_joins_registry_records_by_source_ip(self) -> None:
+        client = Mock()
+        client.list_bottles.return_value = [
+            {"bottle_id": "b1", "source_ip": "10.0.0.1"},
+            {"bottle_id": "b2", "source_ip": "10.0.0.2"},
+            {"bottle_id": 3, "source_ip": "10.0.0.3"},
+        ]
+        client.reprovision_gateway.side_effect = [True, False]
+        count = reprovision_bottles(
+            client, {"10.0.0.1": " key-1\n", "10.0.0.2": "key-2"},
+        )
+        self.assertEqual(1, count)
+        self.assertEqual(
+            [("b1", "key-1"), ("b2", "key-2")],
+            [call.args for call in client.reprovision_gateway.call_args_list],
+        )
+
+    def test_one_failure_does_not_block_other_bottles(self) -> None:
+        client = Mock()
+        client.list_bottles.return_value = [
+            {"bottle_id": "b1", "source_ip": "10.0.0.1"},
+            {"bottle_id": "b2", "source_ip": "10.0.0.2"},
+        ]
+        client.reprovision_gateway.side_effect = [
+            OrchestratorClientError("bad key"), True,
+        ]
+        self.assertEqual(
+            1,
+            reprovision_bottles(
+                client, {"10.0.0.1": "key-1", "10.0.0.2": "key-2"},
+            ),
+        )
+
+
+class TestMacosReprovision(unittest.TestCase):
+    def test_reads_configured_container_env_and_reprovisions(self) -> None:
+        endpoint = mac.GatewayEndpoint("http://orch", "10.0.0.9", "PEM", "net")
+        agent = SimpleNamespace(slug="demo")
+        client = Mock()
+        with patch.object(mac, "enumerate_active", return_value=[agent]), \
+             patch.object(mac.container_mod, "inspect_container_network_ip",
+                          return_value="10.0.0.1"), \
+             patch.object(mac.container_mod, "read_container_env", return_value="key"), \
+             patch.object(mac, "OrchestratorClient", return_value=client), \
+             patch.object(mac, "reprovision_bottles", return_value=1) as restore, \
+             patch.object(mac, "info"):
+            mac._reprovision_running_bottles(endpoint)
+        restore.assert_called_once_with(client, {"10.0.0.1": "key"})
+
+    def test_enumeration_failure_is_best_effort(self) -> None:
+        endpoint = mac.GatewayEndpoint("http://orch", "10.0.0.9", "PEM", "net")
+        with patch.object(mac, "enumerate_active",
+                          side_effect=mac.EnumerationError("failed")), \
+             patch.object(mac, "info") as info:
+            mac._reprovision_running_bottles(endpoint)
+        self.assertIn("skipped", info.call_args.args[0])
+
+
+class TestDockerReprovision(unittest.TestCase):
+    def test_maps_network_containers_to_keys(self) -> None:
+        inspect = _proc(stdout=(
+            "bot-bottle-infra 172.18.0.2/16\n"
+            "bot-bottle-a 172.18.0.3/16\n"
+            "malformed\n"
+        ))
+        key = _proc(stdout="secret\n")
+        client = Mock()
+        with patch.object(docker, "OrchestratorClient", return_value=client), \
+             patch.object(docker, "run_docker", side_effect=[inspect, key]), \
+             patch.object(docker, "reprovision_bottles", return_value=1) as restore, \
+             patch.object(docker.log, "info"):
+            docker._reprovision_running_bottles("http://orch")
+        restore.assert_called_once_with(client, {"172.18.0.3": "secret"})
+
+    def test_missing_docker_is_best_effort(self) -> None:
+        with patch.object(docker, "run_docker", side_effect=FileNotFoundError("docker")), \
+             patch.object(docker.log, "info") as info:
+            docker._reprovision_running_bottles("http://orch")
+        self.assertIn("skipped", info.call_args.args[0])
+
+
+class TestFirecrackerReprovision(unittest.TestCase):
+    def _run_dir(self, root: Path, ip: str = "10.243.0.3") -> Path:
+        run_dir = root / "demo"
+        run_dir.mkdir()
+        (run_dir / "bottle_id_ed25519").write_text("key")
+        (run_dir / "config.json").write_text(json.dumps({
+            "boot-source": {"boot_args": f"root=/dev/vda ip={ip}::gw:mask::eth0:off"}
+        }))
+        return run_dir
+
+    def test_extracts_guest_ip_from_config(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            run_dir = self._run_dir(Path(tmp))
+            self.assertEqual("10.243.0.3", fc._guest_ip_from_config(run_dir / "config.json"))
+            self.assertEqual("", fc._guest_ip_from_config(run_dir / "missing.json"))
+
+    def test_persists_key_over_stdin_not_argv(self) -> None:
+        with patch.object(fc.util, "ssh_base_argv", return_value=["ssh", "guest"]), \
+             patch.object(fc.subprocess, "run", return_value=_proc()) as run:
+            fc.persist_env_var_secret(Path("/key"), "10.0.0.1", "super-secret")
+        self.assertEqual("super-secret", run.call_args.kwargs["input"])
+        self.assertNotIn("super-secret", " ".join(run.call_args.args[0]))
+
+    def test_persist_failure_is_fatal_to_launch(self) -> None:
+        with patch.object(fc.util, "ssh_base_argv", return_value=["ssh", "guest"]), \
+             patch.object(fc.subprocess, "run", return_value=_proc(1, stderr="denied")):
+            with self.assertRaisesRegex(fc.ConsolidatedLaunchError, "denied"):
+                fc.persist_env_var_secret(Path("/key"), "10.0.0.1", "secret")
+
+    def test_reads_live_vm_key_and_reprovisions(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            run_dir = self._run_dir(Path(tmp))
+            client = Mock()
+            with patch.object(fc.cleanup, "live_run_dirs", return_value=(run_dir,)), \
+                 patch.object(fc.util, "ssh_base_argv", return_value=["ssh", "guest"]), \
+                 patch.object(fc.subprocess, "run", return_value=_proc(stdout="secret\n")), \
+                 patch.object(fc, "reprovision_bottles", return_value=1) as restore, \
+                 patch.object(fc, "info"):
+                fc._reprovision_running_bottles(client)
+        restore.assert_called_once_with(client, {"10.243.0.3": "secret"})
+
+    def test_unreadable_vm_is_skipped(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            run_dir = self._run_dir(Path(tmp))
+            client = Mock()
+            with patch.object(fc.cleanup, "live_run_dirs", return_value=(run_dir,)), \
+                 patch.object(fc.util, "ssh_base_argv", return_value=["ssh", "guest"]), \
+                 patch.object(fc.subprocess, "run", return_value=_proc(1)), \
+                 patch.object(fc, "reprovision_bottles", return_value=0) as restore:
+                fc._reprovision_running_bottles(client)
+        restore.assert_called_once_with(client, {})
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/unit/test_backend_util.py

@@ -0,0 +1,29 @@
+"""Unit: shared cross-backend helpers in backend/util.py."""
+
+from __future__ import annotations
+
+import unittest
+from unittest.mock import patch
+
+from bot_bottle.backend import util as backend_util
+
+
+class TestPollCaCert(unittest.TestCase):
+    def test_returns_pem_on_first_success(self) -> None:
+        result = backend_util.poll_ca_cert(lambda: "PEM", timeout=1.0)
+        self.assertEqual("PEM", result)
+
+    def test_raises_timeout_error_when_cert_never_appears(self) -> None:
+        with self.assertRaises(TimeoutError):
+            backend_util.poll_ca_cert(lambda: None, timeout=0.0)
+
+    def test_polls_until_cert_appears(self) -> None:
+        responses = iter([None, None, "-----BEGIN CERTIFICATE-----\n"])
+        with patch("bot_bottle.backend.util.time.sleep") as mock_sleep:
+            result = backend_util.poll_ca_cert(lambda: next(responses), timeout=5.0)
+        self.assertTrue(result.startswith("-----BEGIN CERTIFICATE-----"))
+        self.assertEqual(2, mock_sleep.call_count)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/unit/test_builtin_agent_images.py

@@ -0,0 +1,51 @@
+"""Unit contracts shared by all built-in agent images."""
+
+from __future__ import annotations
+
+import re
+import unittest
+from pathlib import Path
+
+
+_CONTRIB_DIR = Path(__file__).resolve().parents[2] / "bot_bottle/contrib"
+_AGENT_DOCKERFILES = tuple(sorted(_CONTRIB_DIR.glob("*/Dockerfile")))
+
+
+class TestBuiltinAgentImages(unittest.TestCase):
+    def test_all_use_debian_trixie_stable(self):
+        self.assertTrue(_AGENT_DOCKERFILES)
+        for dockerfile in _AGENT_DOCKERFILES:
+            with self.subTest(provider=dockerfile.parent.name):
+                self.assertRegex(
+                    dockerfile.read_text(),
+                    r"(?m)^FROM node:22-trixie-slim\s*$",
+                )
+
+    def test_none_install_podman(self):
+        # podman lives in the nested-containers derived layer (nested_containers.py),
+        # not in the base agent images, so bottles without the flag pay no cost.
+        for dockerfile in _AGENT_DOCKERFILES:
+            with self.subTest(provider=dockerfile.parent.name):
+                self.assertNotRegex(
+                    dockerfile.read_text(),
+                    re.compile(r"(?m)^\s*podman(?:\s|\\|$)"),
+                )
+
+    def test_all_install_ssh_client(self):
+        for dockerfile in _AGENT_DOCKERFILES:
+            with self.subTest(provider=dockerfile.parent.name):
+                self.assertRegex(
+                    dockerfile.read_text(),
+                    re.compile(r"(?m)^\s*openssh-client(?:\s|\\|$)"),
+                )
+
+    def test_all_prepare_node_git_config_directory(self):
+        for dockerfile in _AGENT_DOCKERFILES:
+            with self.subTest(provider=dockerfile.parent.name):
+                dockerfile_text = dockerfile.read_text()
+                self.assertIn("install -d -o node -g node", dockerfile_text)
+                self.assertIn("/home/node/.config/git", dockerfile_text)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/unit/test_cli_login.py

@@ -6,6 +6,9 @@ import json
 import os
 import tempfile
 import unittest
+import urllib.error
+from email.message import Message
+from typing import Any
 from unittest.mock import MagicMock, patch
 
 
@@ -16,7 +19,9 @@ class TestFlagParsing(unittest.TestCase):
 
     def test_console_url_equals_form(self) -> None:
         from bot_bottle.cli.login import _flag
-        self.assertEqual(_flag(["--console-url=http://x"], "--console-url"), "http://x")
+        self.assertEqual(
+            _flag(["--console-url=http://x"], "--console-url"), "http://x"
+        )
 
     def test_label_flag(self) -> None:
         from bot_bottle.cli.login import _flag
@@ -27,6 +32,42 @@ class TestFlagParsing(unittest.TestCase):
         self.assertIsNone(_flag([], "--console-url"))
 
 
+class TestHttpHelpers(unittest.TestCase):
+    def test_post_sends_json_and_decodes_response(self) -> None:
+        from bot_bottle.cli.login import _post
+
+        response = MagicMock()
+        response.__enter__.return_value.read.return_value = b'{"ok": true}'
+        with patch("urllib.request.urlopen", return_value=response) as urlopen:
+            self.assertEqual(
+                _post("http://console/start", {"label": "host"}), {"ok": True}
+            )
+
+        request = urlopen.call_args.args[0]
+        self.assertEqual(request.data, b'{"label": "host"}')
+        self.assertEqual(request.get_header("Content-type"), "application/json")
+
+    def test_get_decodes_success_response(self) -> None:
+        from bot_bottle.cli.login import _get
+
+        response = MagicMock()
+        response.__enter__.return_value.status = 200
+        response.__enter__.return_value.read.return_value = b'{"status": "pending"}'
+        with patch("urllib.request.urlopen", return_value=response):
+            self.assertEqual(
+                _get("http://console/status"), (200, {"status": "pending"})
+            )
+
+    def test_get_returns_http_error_status(self) -> None:
+        from bot_bottle.cli.login import _get
+
+        error = urllib.error.HTTPError(
+            "http://console/status", 410, "gone", Message(), None
+        )
+        with patch("urllib.request.urlopen", side_effect=error):
+            self.assertEqual(_get("http://console/status"), (410, {}))
+
+
 class TestSaveCredentials(unittest.TestCase):
     def test_writes_json_and_sets_perms(self) -> None:
         from bot_bottle.cli.login import _save_credentials
@@ -42,8 +83,47 @@ class TestSaveCredentials(unittest.TestCase):
             self.assertEqual(data["refresh_token"], "rt")
             self.assertEqual(oct(path.stat().st_mode & 0o777), oct(0o600))
 
+    def test_temp_file_is_private_before_replace(self) -> None:
+        """Temp file must be 0600 at the moment os.replace is called."""
+        from bot_bottle.cli.login import _save_credentials
+        from pathlib import Path as _Path
+
+        tmp_perms_at_replace: list[int] = []
+        real_replace = os.replace
+
+        def _spy_replace(
+            src: str | os.PathLike[str], dst: str | os.PathLike[str]
+        ) -> None:
+            tmp_perms_at_replace.append(_Path(src).stat().st_mode & 0o777)
+            real_replace(src, dst)
+
+        with tempfile.TemporaryDirectory() as tmp:
+            with patch.dict(os.environ, {"BOT_BOTTLE_ROOT": tmp}):
+                with patch("os.replace", side_effect=_spy_replace):
+                    path = _save_credentials("http://c", "hid", "at", "rt")
+                self.assertEqual(len(tmp_perms_at_replace), 1)
+                self.assertEqual(oct(tmp_perms_at_replace[0]), oct(0o600))
+                self.assertEqual(oct(path.stat().st_mode & 0o777), oct(0o600))
+
+    def test_cleanup_on_write_failure(self) -> None:
+        """Temp file is removed and no credentials remain if replace fails."""
+        from bot_bottle.cli.login import _save_credentials
+
+        with tempfile.TemporaryDirectory() as tmp:
+            with patch.dict(os.environ, {"BOT_BOTTLE_ROOT": tmp}):
+                with patch("os.replace", side_effect=OSError("disk full")):
+                    with self.assertRaises(OSError):
+                        _save_credentials("http://c", "hid", "at", "rt")
+            leftovers = [f for f in os.listdir(tmp) if f.startswith(".console-")]
+            self.assertEqual(leftovers, [])
+
 
 class TestCmdLoginMissingUrl(unittest.TestCase):
+    def test_help_returns_0(self) -> None:
+        from bot_bottle.cli.login import cmd_login
+
+        self.assertEqual(cmd_login(["--help"]), 0)
+
     def test_returns_1_without_url(self) -> None:
         from bot_bottle.cli.login import cmd_login
         with patch.dict(os.environ, {}, clear=True):
@@ -55,18 +135,26 @@ class TestCmdLoginMissingUrl(unittest.TestCase):
         """Exits 1 (network error) not because of missing URL when env var is set."""
         from bot_bottle.cli.login import cmd_login
 
-        def _fail_post(url, payload):
+        def _fail_post(_url: str, _payload: dict[str, Any]) -> dict[str, Any]:
             raise OSError("connection refused")
 
         with tempfile.TemporaryDirectory() as tmp:
-            with patch.dict(os.environ, {"BB_CONSOLE_URL": "http://localhost:9999", "BOT_BOTTLE_ROOT": tmp}):
+            with patch.dict(
+                os.environ,
+                {
+                    "BB_CONSOLE_URL": "http://localhost:9999",
+                    "BOT_BOTTLE_ROOT": tmp,
+                },
+            ):
                 with patch("bot_bottle.cli.login._post", side_effect=_fail_post):
                     result = cmd_login([])
         self.assertEqual(result, 1)
 
 
 class TestCmdLoginFlow(unittest.TestCase):
-    def _run_with_mocks(self, poll_responses: list[dict], tmp: str) -> int:
+    def _run_with_mocks(
+        self, poll_responses: list[dict[str, Any]], tmp: str
+    ) -> int:
         from bot_bottle.cli.login import cmd_login
 
         start_resp = {
@@ -78,20 +166,18 @@ class TestCmdLoginFlow(unittest.TestCase):
 
         poll_iter = iter(poll_responses)
 
-        def _fake_post(url, payload):
+        def _fake_post(
+            _url: str, _payload: dict[str, Any]
+        ) -> dict[str, Any]:
             return start_resp
 
-        def _fake_get(url):
-            try:
-                resp = next(poll_iter)
-            except StopIteration:
-                return 200, {"status": "pending"}
-            return 200, resp
+        def _fake_get(_url: str) -> tuple[int, dict[str, Any]]:
+            return 200, next(poll_iter, {"status": "pending"})
 
         with patch.dict(os.environ, {"BOT_BOTTLE_ROOT": tmp}):
             with patch("bot_bottle.cli.login._post", side_effect=_fake_post):
                 with patch("bot_bottle.cli.login._get", side_effect=_fake_get):
-                    with patch("bot_bottle.cli.login._POLL_SLEEP", 0):
+                    with patch("time.sleep"):
                         return cmd_login(["--console-url", "http://console"])
 
     def test_approved_flow_returns_0(self) -> None:
@@ -106,7 +192,7 @@ class TestCmdLoginFlow(unittest.TestCase):
                 [{"status": "pending"}, approved], tmp
             )
             self.assertEqual(result, 0)
-            with open(os.path.join(tmp, "console.json")) as f:
+            with open(os.path.join(tmp, "console.json"), encoding="utf-8") as f:
                 creds = json.loads(f.read())
             self.assertEqual(creds["host_id"], "hid")
 
@@ -121,17 +207,52 @@ class TestCmdLoginFlow(unittest.TestCase):
         start_resp = {
             "device_code": "dc",
             "user_code": "ZZZ-ZZZ",
-            "expires_in": 0,  # already expired
-            "poll_interval": 0,
+            "expires_in": 0,  # already expired; loop never runs
+            "poll_interval": 2,
         }
 
         with tempfile.TemporaryDirectory() as tmp:
             with patch.dict(os.environ, {"BOT_BOTTLE_ROOT": tmp}):
                 with patch("bot_bottle.cli.login._post", return_value=start_resp):
-                    with patch("bot_bottle.cli.login._POLL_SLEEP", 0):
-                        result = cmd_login(["--console-url", "http://console"])
+                    result = cmd_login(["--console-url", "http://console"])
         self.assertEqual(result, 1)
 
+    def test_poll_interval_from_server_is_used(self) -> None:
+        """time.sleep must be called with the server-provided poll_interval."""
+        from bot_bottle.cli.login import cmd_login
+
+        server_interval = 7
+        start_resp = {
+            "device_code": "dc",
+            "user_code": "ABC-DEF",
+            "expires_in": 300,
+            "poll_interval": server_interval,
+        }
+        approved = {
+            "status": "approved",
+            "host_id": "hid",
+            "access_token": "at",
+            "refresh_token": "rt",
+        }
+        poll_iter = iter([{"status": "pending"}, approved])
+
+        def _fake_get(_url: str) -> tuple[int, dict[str, str]]:
+            return 200, next(poll_iter)
+
+        with tempfile.TemporaryDirectory() as tmp:
+            with patch.dict(os.environ, {"BOT_BOTTLE_ROOT": tmp}):
+                with patch("bot_bottle.cli.login._post", return_value=start_resp):
+                    with patch(
+                        "bot_bottle.cli.login._get", side_effect=_fake_get
+                    ):
+                        with patch("time.sleep") as mock_sleep:
+                            result = cmd_login(["--console-url", "http://console"])
+
+        self.assertEqual(result, 0)
+        self.assertTrue(mock_sleep.called)
+        for call in mock_sleep.call_args_list:
+            self.assertEqual(call.args[0], server_interval)
+
 
 class TestDispatcherRegistration(unittest.TestCase):
     def test_login_in_commands(self) -> None:

tests/unit/test_cli_module_entry.py

@@ -0,0 +1,40 @@
+"""The CLI package is runnable as `python -m bot_bottle.cli`."""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+import unittest
+from pathlib import Path
+
+_REPO_ROOT = Path(__file__).resolve().parents[2]
+
+
+def _run(*args: str) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        [sys.executable, "-m", "bot_bottle.cli", *args],
+        cwd=_REPO_ROOT,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+
+
+class TestModuleEntry(unittest.TestCase):
+    def test_help_exits_zero(self) -> None:
+        result = _run("--help")
+        self.assertEqual(result.returncode, 0, result.stderr)
+        self.assertIn("login", result.stderr)
+
+    def test_no_args_prints_usage(self) -> None:
+        # main() returns 2 with no command, matching the cli.py entry point.
+        self.assertEqual(_run().returncode, 2)
+
+    def test_subcommand_help_reaches_handler(self) -> None:
+        result = _run("login", "--help")
+        self.assertEqual(result.returncode, 0, result.stderr)
+        self.assertIn("--console-url", result.stderr)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/unit/test_cli_start_headless.py

@@ -176,6 +176,18 @@ class TestCmdStartHeadless(unittest.TestCase):
         self.assertEqual("researcher-2", self._spec().label)
 
 
+    def test_cached_images_sets_cached_policy(self):
+        start_mod.cmd_start(
+            ["--headless", "--cached-images", "researcher", "--bottle", "claude",
+             "--prompt", "Do it"]
+        )
+        self.assertEqual("cached", self._spec().image_policy)
+
+    def test_cached_images_requires_headless(self):
+        with self.assertRaises(Die):
+            start_mod.cmd_start(["--cached-images", "researcher"])
+        self._launch_mock.assert_not_called()
+
 
 class TestPrepareWithPreflight(unittest.TestCase):
     """prepare_with_preflight calls render_preflight with the plan and backend name."""

tests/unit/test_cli_start_selector.py

@@ -65,6 +65,12 @@ class TestCmdStartSelector(unittest.TestCase):
         )
         self._modal_patch.start()
 
+        self._image_policy_patch = patch(
+            "bot_bottle.cli.start._select_image_policy",
+            return_value="fresh",
+        )
+        self._image_policy_patch.start()
+
         self._env_patch = patch.dict(os.environ, {}, clear=False)
         self._env_patch.start()
         os.environ.pop("BOT_BOTTLE_BACKEND", None)
@@ -75,6 +81,7 @@ class TestCmdStartSelector(unittest.TestCase):
         self._agent_picker_patch.stop()
         self._bottle_picker_patch.stop()
         self._modal_patch.stop()
+        self._image_policy_patch.stop()
         self._env_patch.stop()
 
     # ------------------------------------------------------------------
@@ -133,6 +140,19 @@ class TestCmdStartSelector(unittest.TestCase):
         spec = self._launch_mock.call_args[0][0]
         self.assertEqual(("claude", "dev"), spec.bottle_names)
 
+    def test_image_policy_forwarded_to_spec(self):
+        with patch("bot_bottle.cli.start._select_image_policy", return_value="cached"):
+            start_mod.cmd_start(["researcher"])
+        self._launch_mock.assert_called_once()
+        spec = self._launch_mock.call_args[0][0]
+        self.assertEqual("cached", spec.image_policy)
+
+    def test_image_policy_cancel_returns_0(self):
+        with patch("bot_bottle.cli.start._select_image_policy", return_value=None):
+            rc = start_mod.cmd_start(["researcher"])
+        self.assertEqual(0, rc)
+        self._launch_mock.assert_not_called()
+
     def test_empty_bottle_selection_forwarded(self):
         self._bottle_picker_mock.return_value = []
         start_mod.cmd_start(["researcher"])
@@ -214,6 +234,7 @@ class TestCmdStartLabelCollision(unittest.TestCase):
         ).start()
         # Stub the bottle picker to always return a selection.
         patch.object(tui_mod, "filter_multiselect", return_value=["claude"]).start()
+        patch("bot_bottle.cli.start._select_image_policy", return_value="fresh").start()
         self.addCleanup(patch.stopall)
 
     def test_no_collision_proceeds_without_reprompt(self):

tests/unit/test_cli_start_stale.py

@@ -0,0 +1,146 @@
+"""Unit: _launch_bottle StaleImageError handling.
+
+Exercises prelaunch_checks / backend.launch flow:
+  - headless mode → die on stale
+  - interactive mode, user declines → stop without launching
+  - interactive mode, user confirms → skip stale check and launch once
+"""
+
+from __future__ import annotations
+
+import io
+import tempfile
+import unittest
+from types import SimpleNamespace
+from typing import Any, cast
+from unittest.mock import MagicMock, patch
+
+from bot_bottle.image_cache import StaleImageError
+from bot_bottle.log import Die
+
+
+def _fake_plan() -> Any:
+    provision = SimpleNamespace(startup_args=())
+    return cast(Any, SimpleNamespace(
+        agent_provision=provision,
+        agent_provider_template="claude",
+        slug="dev-abc",
+    ))
+
+
+def _ok_cm(bottle: Any) -> MagicMock:
+    """Return a context-manager mock that yields `bottle`."""
+    cm = MagicMock()
+    cm.__enter__ = MagicMock(return_value=bottle)
+    cm.__exit__ = MagicMock(return_value=False)
+    return cm
+
+
+class TestLaunchBottleStaleHandling(unittest.TestCase):
+    def setUp(self) -> None:
+        self._tmp = tempfile.mkdtemp(prefix="cli-stale-test.")
+
+    def _spec(self) -> Any:
+        from bot_bottle.backend import BottleSpec
+        from bot_bottle.manifest import ManifestIndex
+        idx = ManifestIndex.from_json_obj({
+            "bottles": {"dev": {}},
+            "agents": {"demo": {"skills": [], "prompt": "", "bottle": "dev"}},
+        })
+        return BottleSpec(
+            manifest=idx,
+            agent_name="demo",
+            copy_cwd=False,
+            user_cwd=self._tmp,
+            identity="dev-abc",
+        )
+
+    def _run_launch(self, **patch_kwargs: Any) -> int:
+        import bot_bottle.cli.start as start_mod
+        spec = self._spec()
+        with patch.object(start_mod, "prepare_with_preflight",
+                          return_value=(_fake_plan(), "dev-abc")), \
+             patch.object(start_mod, "settle_state"), \
+             patch.object(start_mod, "info"):
+            return start_mod._launch_bottle(
+                spec,
+                dry_run=False,
+                backend_name="docker",
+                **patch_kwargs,
+            )
+
+    def test_headless_stale_calls_die(self) -> None:
+        """In headless mode (assume_yes=True), a StaleImageError from prelaunch_checks must call die()."""
+        import bot_bottle.cli.start as start_mod
+
+        backend_mock = MagicMock()
+        backend_mock.prelaunch_checks.side_effect = StaleImageError("image is 5 day(s) old")
+
+        with patch.object(start_mod, "get_bottle_backend", return_value=backend_mock), \
+             patch.object(start_mod, "die", side_effect=Die()):
+            with self.assertRaises(Die):
+                self._run_launch(assume_yes=True)
+
+        backend_mock.launch.assert_not_called()
+
+    def test_interactive_user_declines_stops_before_launch(self) -> None:
+        """Interactive user answering 'n' → launch is never called."""
+        import bot_bottle.cli.start as start_mod
+
+        backend_mock = MagicMock()
+        backend_mock.prelaunch_checks.side_effect = StaleImageError("image is 5 day(s) old")
+
+        with patch.object(start_mod, "get_bottle_backend", return_value=backend_mock), \
+             patch.object(start_mod, "read_tty_line", return_value="n"), \
+             patch("sys.stderr", new_callable=io.StringIO):
+            rc = self._run_launch(assume_yes=False)
+
+        self.assertEqual(0, rc)
+        backend_mock.launch.assert_not_called()
+
+    def test_interactive_user_confirms_launches_once(self) -> None:
+        """Interactive user answering 'y' → prelaunch stale error is bypassed; launch called once."""
+        import bot_bottle.cli.start as start_mod
+
+        bottle_mock = MagicMock()
+        bottle_mock.name = "dev-abc"
+
+        backend_mock = MagicMock()
+        backend_mock.prelaunch_checks.side_effect = StaleImageError("image is 5 day(s) old")
+        backend_mock.launch.return_value = _ok_cm(bottle_mock)
+
+        with patch.object(start_mod, "get_bottle_backend", return_value=backend_mock), \
+             patch.object(start_mod, "read_tty_line", return_value="y"), \
+             patch.object(start_mod, "attach_agent", return_value=0), \
+             patch.object(start_mod, "capture_claude_session_state"), \
+             patch("sys.stderr", new_callable=io.StringIO):
+            rc = self._run_launch(assume_yes=False)
+
+        self.assertEqual(0, rc)
+        backend_mock.prelaunch_checks.assert_called_once()
+        backend_mock.launch.assert_called_once()
+
+    def test_interactive_yes_uppercase_also_accepted(self) -> None:
+        """'Y' or 'YES' should also be accepted as confirmation."""
+        import bot_bottle.cli.start as start_mod
+
+        bottle_mock = MagicMock()
+        bottle_mock.name = "dev-abc"
+
+        backend_mock = MagicMock()
+        backend_mock.prelaunch_checks.side_effect = StaleImageError("image is 5 day(s) old")
+        backend_mock.launch.return_value = _ok_cm(bottle_mock)
+
+        with patch.object(start_mod, "get_bottle_backend", return_value=backend_mock), \
+             patch.object(start_mod, "read_tty_line", return_value="YES"), \
+             patch.object(start_mod, "attach_agent", return_value=0), \
+             patch.object(start_mod, "capture_claude_session_state"), \
+             patch("sys.stderr", new_callable=io.StringIO):
+            rc = self._run_launch(assume_yes=False)
+
+        self.assertEqual(0, rc)
+        backend_mock.launch.assert_called_once()
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/unit/test_config_store.py

@@ -0,0 +1,86 @@
+"""Unit tests for the host-side configuration store."""
+
+from __future__ import annotations
+
+import sqlite3
+import tempfile
+import unittest
+from pathlib import Path
+
+from bot_bottle.config_store import (
+    DEFAULT_CACHED_IMAGE_STALE_WARNING_DAYS,
+    ConfigStore,
+)
+from bot_bottle.store_manager import StoreManager
+
+
+class TestConfigStore(unittest.TestCase):
+    def test_cached_image_warning_days_defaults_to_one(self) -> None:
+        with tempfile.TemporaryDirectory(prefix="config-store.") as tmp:
+            store = ConfigStore(Path(tmp) / "bot-bottle.db")
+            store.migrate()
+            self.assertEqual(
+                DEFAULT_CACHED_IMAGE_STALE_WARNING_DAYS,
+                store.cached_image_stale_warning_days(),
+            )
+
+    def test_cached_image_warning_days_reads_value(self) -> None:
+        with tempfile.TemporaryDirectory(prefix="config-store.") as tmp:
+            store = ConfigStore(Path(tmp) / "bot-bottle.db")
+            store.migrate()
+            store.set_cached_image_stale_warning_days(7)
+            self.assertEqual(7, store.cached_image_stale_warning_days())
+
+    def test_config_schema_uses_explicit_settings_columns(self) -> None:
+        with tempfile.TemporaryDirectory(prefix="config-store.") as tmp:
+            store = ConfigStore(Path(tmp) / "bot-bottle.db")
+            store.migrate()
+            with sqlite3.connect(store.db_path) as conn:
+                conn.row_factory = sqlite3.Row
+                columns = [
+                    row["name"]
+                    for row in conn.execute("PRAGMA table_info(bot_bottle_config)")
+                ]
+            self.assertEqual([
+                "id",
+                "cached_image_stale_warning_days",
+            ], columns)
+
+    def test_store_manager_includes_config_store(self) -> None:
+        with tempfile.TemporaryDirectory(prefix="config-store.") as tmp:
+            db = Path(tmp) / "bot-bottle.db"
+            manager = StoreManager(db)
+            self.assertFalse(manager.is_migrated())
+            manager.migrate()
+            self.assertTrue(manager.is_migrated())
+
+    def test_cached_image_warning_days_returns_default_when_db_missing(self) -> None:
+        # When the db file doesn't exist yet (parent exists, file doesn't),
+        # the store returns the default without touching the file.
+        with tempfile.TemporaryDirectory(prefix="config-store.") as tmp:
+            store = ConfigStore(Path(tmp) / "missing.db")
+            self.assertEqual(
+                DEFAULT_CACHED_IMAGE_STALE_WARNING_DAYS,
+                store.cached_image_stale_warning_days(),
+            )
+
+    def test_cached_image_warning_days_returns_default_on_null_value(self) -> None:
+        # If the row exists but the value is NULL (or not castable to int),
+        # the store falls back to the default.
+        with tempfile.TemporaryDirectory(prefix="config-store.") as tmp:
+            db_path = Path(tmp) / "bot-bottle.db"
+            store = ConfigStore(db_path)
+            store.migrate()
+            # Write a NULL value directly.
+            with sqlite3.connect(db_path) as conn:
+                conn.execute(
+                    "UPDATE bot_bottle_config SET cached_image_stale_warning_days = NULL WHERE id = 1"
+                )
+            self.assertEqual(
+                DEFAULT_CACHED_IMAGE_STALE_WARNING_DAYS,
+                store.cached_image_stale_warning_days(),
+            )
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/unit/test_consolidated_compose.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import dataclasses
 import unittest
 
 from bot_bottle.backend.docker.consolidated_compose import consolidated_agent_compose
@@ -46,6 +47,15 @@ class TestConsolidatedAgentCompose(unittest.TestCase):
         # forwarded secrets are bare names (value inherited from process env).
         self.assertIn("CLAUDE_CODE_OAUTH_TOKEN", env)
 
+    def test_env_var_secret_stays_a_bare_name(self) -> None:
+        plan = _plan(with_egress=True, supervise=True, with_git=True)
+        plan = dataclasses.replace(plan, env_var_secret="secret-value")
+        env = consolidated_agent_compose(
+            plan, gateway_ip=_GW, source_ip=_IP, network=_NET,
+        )["services"]["agent"]["environment"]
+        self.assertIn("ENV_VAR_SECRET", env)
+        self.assertNotIn("ENV_VAR_SECRET=secret-value", env)
+
 
 if __name__ == "__main__":
     unittest.main()

tests/unit/test_contrib_claude_auth.py

@@ -0,0 +1,186 @@
+"""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()

tests/unit/test_docker_launch_committed_image.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import contextlib
+import dataclasses
 import io
 import tempfile
 import unittest
@@ -18,6 +19,7 @@ from bot_bottle.backend.docker.bottle_plan import DockerBottlePlan
 from bot_bottle.backend.docker.consolidated_launch import LaunchContext
 from bot_bottle.egress import EgressPlan
 from bot_bottle.git_gate import GitGatePlan
+from bot_bottle.log import Die
 from bot_bottle.manifest import ManifestIndex
 from tests.unit import use_bottle_root
 
@@ -92,6 +94,7 @@ class TestLaunchCommittedImage(unittest.TestCase):
                 mock.patch.object(launch_mod.docker_mod, "image_exists", return_value=image_present), \
                 mock.patch.object(launch_mod.docker_mod, "build_image", side_effect=_build), \
                 mock.patch.object(launch_mod.docker_mod, "verify_agent_image"), \
+                mock.patch.object(launch_mod.docker_mod, "image_created_at"), \
                 mock.patch.object(launch_mod, "launch_consolidated", return_value=_CTX), \
                 mock.patch.object(launch_mod, "teardown_consolidated"), \
                 mock.patch.object(launch_mod, "DockerGateway", return_value=gw), \
@@ -112,7 +115,8 @@ class TestLaunchCommittedImage(unittest.TestCase):
         with self._patched(
             committed_tag=committed_tag, image_present=image_present, compose=compose,
         ) as built:
-            with launch_mod.launch(plan, provision=mock.Mock(return_value=None)):
+            images = launch_mod.build_or_load_images(plan)
+            with launch_mod.launch(plan, images, provision=mock.Mock(return_value=None)):
                 pass
         return built
 
@@ -127,14 +131,34 @@ class TestLaunchCommittedImage(unittest.TestCase):
             captured.append(p)
             return {"services": {"agent": {}}}
 
-        with self._patched(committed_tag=_COMMITTED_TAG, image_present=True, compose=compose):
-            with launch_mod.launch(_plan(self._tmp), provision=mock.Mock(return_value=None)):
+        with self._patched(committed_tag=_COMMITTED_TAG, image_present=True, compose=compose) as _:
+            plan = _plan(self._tmp)
+            images = launch_mod.build_or_load_images(plan)
+            with launch_mod.launch(plan, images, provision=mock.Mock(return_value=None)):
                 pass
         self.assertEqual(_COMMITTED_TAG, captured[0].image)
 
     def test_falls_back_to_build_when_no_committed_image(self) -> None:
         self.assertEqual([_DEFAULT_IMAGE], self._run_launch(_plan(self._tmp), committed_tag=None))
 
+    def test_cached_images_skip_build_when_present(self) -> None:
+        base = _plan(self._tmp)
+        plan = dataclasses.replace(
+            base,
+            spec=dataclasses.replace(base.spec, image_policy="cached"),
+        )
+        built = self._run_launch(plan, committed_tag=None, image_present=True)
+        self.assertEqual([], built)
+
+    def test_cached_images_die_when_agent_missing(self) -> None:
+        base = _plan(self._tmp)
+        plan = dataclasses.replace(
+            base,
+            spec=dataclasses.replace(base.spec, image_policy="cached"),
+        )
+        with self.assertRaises(Die):
+            self._run_launch(plan, committed_tag=None, image_present=False)
+
     def test_falls_back_to_build_when_committed_image_missing_from_daemon(self) -> None:
         built = self._run_launch(_plan(self._tmp), committed_tag=_COMMITTED_TAG, image_present=False)
         self.assertEqual([_DEFAULT_IMAGE], built)

tests/unit/test_docker_launch_teardown.py

@@ -16,7 +16,7 @@ from pathlib import Path
 from unittest import mock
 
 from bot_bottle.agent_provider import AgentProvisionPlan
-from bot_bottle.backend import BottleSpec
+from bot_bottle.backend import BottleImages, BottleSpec
 from bot_bottle.backend.docker import launch as launch_mod
 from bot_bottle.backend.docker.bottle_plan import DockerBottlePlan
 from bot_bottle.backend.docker.consolidated_launch import LaunchContext
@@ -91,8 +91,11 @@ class TestTeardownWarning(unittest.TestCase):
             bottle_id="b1", identity_token="t", source_ip="172.20.0.4",
             network="bot-bottle-gateway", gateway_ip="172.20.0.2",
             orchestrator_url="http://orch:8099",
+            env_var_secret="encryption-key",
         )
 
+        images = BottleImages(agent="bot-bottle-claude:latest", sidecar="bot-bottle-sidecars:latest")
+
         with mock.patch.object(launch_mod.docker_mod, "build_image"), \
              mock.patch.object(launch_mod.docker_mod, "verify_agent_image"), \
              mock.patch.object(launch_mod, "launch_consolidated", return_value=ctx), \
@@ -105,7 +108,7 @@ class TestTeardownWarning(unittest.TestCase):
              mock.patch.object(
                  launch_mod, "write_compose_file", return_value=Path("/tmp/compose.yml"),
              ), \
-             mock.patch.object(launch_mod, "compose_up"), \
+             mock.patch.object(launch_mod, "compose_up") as compose_up, \
              mock.patch.object(launch_mod, "compose_dump_logs"), \
              mock.patch.object(
                  launch_mod, "compose_down",
@@ -113,13 +116,16 @@ class TestTeardownWarning(unittest.TestCase):
              ), \
              contextlib.redirect_stderr(buf):
             provision = mock.Mock(return_value=None)
-            with launch_mod.launch(plan, provision=provision):
+            with launch_mod.launch(plan, images, provision=provision):
                 pass
 
         output = buf.getvalue()
         self.assertIn("bot-bottle: warning:", output)
         self.assertIn("bot-bottle-test-teardown-abc", output)
         self.assertIn("compose-down", output)
+        self.assertEqual(
+            "encryption-key", compose_up.call_args.kwargs["env"]["ENV_VAR_SECRET"],
+        )
 
 
 if __name__ == "__main__":

tests/unit/test_docker_provision_git_user.py

@@ -45,12 +45,15 @@ _PROVIDER = _Provider()
 
 
 def _plan(*, git_user: dict | None = None,  # type: ignore
+          git_repos: dict | None = None,  # type: ignore
           copy_cwd: bool = False,
           user_cwd: str = "/tmp/x",
           stage_dir: Path | None = None) -> DockerBottlePlan:
     bottle_json: dict = {}  # type: ignore
     if git_user is not None:
         bottle_json["git-gate"] = {"user": git_user}
+    if git_repos is not None:
+        bottle_json.setdefault("git-gate", {})["repos"] = git_repos
     index = ManifestIndex.from_json_obj({
         "bottles": {"dev": bottle_json},
         "agents": {"demo": {"skills": [], "prompt": "", "bottle": "dev"}},
@@ -125,6 +128,62 @@ class TestProvisionGitUser(unittest.TestCase):
         _PROVIDER.provision_git(bottle, _plan(stage_dir=self.stage))
         self.assertEqual([], _git_config_exec_calls(bottle))
 
+    def test_repairs_git_xdg_directory_for_runtime_user(self):
+        bottle = _make_bottle()
+        _PROVIDER.provision_git(bottle, _plan(stage_dir=self.stage))
+
+        script, user = next(
+            (call.args[0], call.kwargs.get("user", "node"))
+            for call in bottle.exec.call_args_list
+            if "/home/node/.config/git" in call.args[0]
+        )
+        self.assertEqual("root", user)
+        self.assertIn("chown node:node /home/node", script)
+        self.assertIn("chmod 755 /home/node", script)
+        self.assertIn("mkdir -p /home/node/.config/git", script)
+        self.assertIn("chown -R node:node /home/node/.config", script)
+        self.assertIn("chmod -R u+rwX,go+rX /home/node/.config", script)
+
+    def test_fails_closed_when_home_permissions_cannot_be_repaired(self):
+        bottle = _make_bottle()
+        bottle.exec.return_value = ExecResult(1, "", "read-only filesystem")
+
+        with self.assertRaises(SystemExit):
+            _PROVIDER.provision_git(bottle, _plan(stage_dir=self.stage))
+
+    def _git_plan(self) -> DockerBottlePlan:
+        return _plan(
+            git_repos={
+                "repo": {
+                    "url": "ssh://git@example.com/repo.git",
+                    "key": {"provider": "static", "path": "/dev/null"},
+                    "host_key": "ssh-ed25519 AAAA",
+                },
+            },
+            stage_dir=self.stage,
+        )
+
+    def test_fails_closed_when_gitconfig_permissions_cannot_be_set(self):
+        bottle = _make_bottle()
+        bottle.exec.side_effect = [
+            ExecResult(0, "", ""),
+            ExecResult(1, "", "chown failed"),
+        ]
+
+        with self.assertRaises(SystemExit):
+            _PROVIDER.provision_git(bottle, self._git_plan())
+
+    def test_fails_closed_when_runtime_user_cannot_read_gitconfig(self):
+        bottle = _make_bottle()
+        bottle.exec.side_effect = [
+            ExecResult(0, "", ""),
+            ExecResult(0, "", ""),
+            ExecResult(1, "", "permission denied"),
+        ]
+
+        with self.assertRaises(SystemExit):
+            _PROVIDER.provision_git(bottle, self._git_plan())
+
     def test_sets_name_and_email(self):
         plan = _plan(
             git_user={"name": "Eric Bauerfeld", "email": "eric@dideric.is"},