docs: reposition README around provider-neutral secure substrate

Lead with the agnostic + security story instead of the single-user security framing. New hero positions bot-bottle as a neutral control plane that runs any agent (Claude, Codex, or a drop-in contrib plugin) inside an isolation boundary the agent can't touch. Restructure Features into three pillars — neutral substrate, isolation boundary, host-matched isolation — promoting provider-agnosticism (PRD 0053 user plugins) from a buried bullet to a headline. No capability claims changed; per-provider auth/image detail preserved as a note linking to Manifest. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YcU7nerbg8cVj9R4EkpfLJ
docs: activate install script prd
2026-06-24 01:21:05 -04:00 · 2026-06-23 21:47:12 -04:00 · 2026-06-23 21:47:12 -04:00 · 2026-06-23 21:46:44 -04:00 · 2026-06-23 21:46:44 -04:00 · 2026-06-23 21:46:44 -04:00
47 changed files with 2482 additions and 59 deletions
@@ -5,28 +5,43 @@
 # 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)
-[![pylint](https://img.shields.io/badge/pylint-9.92%2F10-brightgreen)](https://github.com/PyCQA/pylint)
+[![pylint](https://img.shields.io/badge/pylint-9.93%2F10-brightgreen)](https://github.com/PyCQA/pylint)
 [![pyright](https://img.shields.io/badge/pyright-0%20errors-brightgreen)](https://github.com/microsoft/pyright)

-**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.
+**Run any coding agent like it might be compromised — and lose nothing when it is.**

-**Solution:** Ephemeral, per agent "bottles" the agent cannot modify that scan all traffic for data exfiltration and limit capabilities and egress to only what the agent needs.
+bot-bottle is a provider-neutral, security-first substrate for autonomous agents. Bring Claude Code, Codex, or your own harness; each one runs in an ephemeral, per-agent "bottle" it cannot modify, where every byte of egress is scanned for exfiltration and capabilities are narrowed to exactly what the task declares.

-## Features
+**Problem:** You want to let a coding agent run unsupervised, but a prompt-injected or misbehaving agent — or a poisoned repo, MCP server, or skill — can wreck your environment or exfiltrate your secrets. Locking yourself to one vendor's cloud doesn't fix that; it just moves the blast radius.

- **Per-bottle egress allowlist** — TLS-bumped HTTP/HTTPS chokepoint with a per-manifest host allowlist and request-body DLP scanner; DoH and arbitrary hosts blocked by default.
+**Solution:** A neutral control plane that runs *whatever agent you choose* inside an isolation boundary the agent can't touch: TLS-bumped egress allowlisting, outbound/inbound DLP, gitleaks-gated pushes, and host secrets the agent never sees. Swap the agent; keep the guarantees.
+
+## Why bot-bottle
+
+### A neutral substrate — bring your own agent
+
+- **Provider-agnostic by design** — Claude and Codex ship built in; any other agent (Gemini, Aider, a local-model wrapper) is a drop-in plugin at `~/.bot-bottle/contrib/<name>/` — no fork, no PR against this repo. The manifest accepts any provider template, and the isolation, egress, and git guarantees are identical across all of them.
+- **One control plane, every harness** — the same bottle, egress policy, and supervise flow wrap whichever agent you run, so switching or mixing providers doesn't change your security posture.
+- **Composable bottles (`extends:`)** — keep provider/runtime policy in one base bottle (e.g. `claude.md`) and overlay task bottles on top.
+
+### An isolation boundary the agent can't touch
+
+- **Per-bottle egress allowlist** — TLS-bumped HTTP/HTTPS chokepoint with a per-manifest host allowlist; per-route path/method/header `matches` filtering; outbound DLP scanning for known tokens and secrets, inbound DLP scanning for prompt-injection attempts; DoH and arbitrary hosts blocked by default.
 - **Tokens the agent never sees** — host secrets live in a sidecar; the agent dials `http://sidecar:9099/<path>` and the proxy strips inbound `Authorization` and injects the real token before forwarding. `printenv` in the agent shows proxy URLs only.
 - **Gitleaks-scanned push (git-gate)** — `bottle.git` remotes route through a per-bottle `git daemon` that gitleaks-scans incoming refs pre-receive and forwards clean refs upstream over SSH. The agent never holds the upstream credential.
 - **Manifest-scoped skills + secrets** — each bottle declares its skills, env, git identity, remotes, and egress routes; unknown keys die at load.
 - **Trust boundary at `$HOME`** — bottles (credentials, egress, remotes) live only under `~/.bot-bottle/bottles/`. Repos may ship agents but not bottles, so a cloned repo can't redirect an env var to an attacker host.
- **Composable bottles (`extends:`)** — keep provider/runtime policy in one base bottle (e.g. `claude.md`) and overlay task bottles on top.
+
+### Isolation that matches your host
+
 - **Parallel, isolated bottles** — each bottle runs in its own backend-owned isolation boundary; bottles don't share state or talk to each other.
- **Provider templates (Claude, Codex)** — `Dockerfile.claude` / `Dockerfile.codex`, or a bottle-supplied Dockerfile. Claude auth via long-lived OAuth token; Codex via opt-in host device-auth forwarding.
 - **gVisor auto-detect** — on Linux hosts where `runsc` is registered with Docker, every bottle launches under it for a userspace syscall barrier; no manifest config required.
 - **Apple Container backend (macOS default when available)** — runs the agent and sidecar bundle with Apple's `container` CLI, using a host-only agent network plus a separate sidecar egress network.
 - **Smolmachines backend** — runs the agent in a libkrun micro-VM while the sidecar bundle stays in Docker. TSI and smolmachines DNS filtering close the raw DNS exfiltration gap that exists in the legacy Docker backend.
 - **Legacy Docker backend** — still available for examples, CI, and hosts without Apple Container via `BOT_BOTTLE_BACKEND=docker` or `--backend=docker`.

+Per-provider auth (Claude long-lived OAuth token; Codex opt-in host device-auth forwarding) and per-provider images (`Dockerfile.claude` / `Dockerfile.codex`, or a bottle-supplied Dockerfile) are configured on the bottle — see [Manifest](#manifest).
+
 ## Architecture

 On the default macOS Apple Container backend, a bottle is an agent container on a host-only internal network plus a sidecar bundle attached to both that internal network and a NAT egress network. The agent gets HTTP(S)_PROXY and CA bundle env vars pointing at the sidecar's internal-network IP, so HTTP/HTTPS traffic flows through the sidecar instead of direct egress. `bottle.git` / git-gate is intentionally deferred on this backend until a safe Apple Container key-delivery path exists.
@@ -68,6 +83,27 @@ The Docker topology looks like this:

 When the agent exits, `cli.py` tears down every sidecar and both networks; nothing about a bottle persists between runs.

+## Install
+
+Install the CLI with the bootstrap script:
+
+```sh
+curl -fsSL https://gitea.dideric.is/didericis/bot-bottle/raw/branch/main/install.sh | sh
+```
+
+The script checks Python 3.11+, checks Docker daemon reachability, creates the `~/.bot-bottle/` config directories, installs the Python package with `pipx` when available or `pip --user` otherwise, then runs:
+
+```sh
+bot-bottle doctor
+```
+
+Python-native installers can use the package metadata directly:
+
+```sh
+pipx install git+https://gitea.dideric.is/didericis/bot-bottle.git
+uv tool install git+https://gitea.dideric.is/didericis/bot-bottle.git
+```
+
 ## Quickstart

 On compatible macOS hosts, the default backend requires Apple's `container` CLI and does not require Docker. The smolmachines backend requires Docker on the host for the sidecar bundle plus smolvm. The legacy Docker backend requires Docker. Claude bottles also need a long-lived Claude Code OAuth token (`claude setup-token`) exported as `BOT_BOTTLE_CLAUDE_OAUTH_TOKEN`.
@@ -106,8 +142,15 @@ egress:
  routes:
    - host: gitea.dideric.is
      auth:
-        scheme: token
+        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)
+        outbound_detectors: [token_patterns, known_secrets]
+        inbound_detectors: false   # disable response scanning for this host
 ---

 The `gitea-dev` bottle. Provider auth via the inherited Claude route;
@@ -126,6 +169,23 @@ skills:
 You help maintain Gitea-hosted projects.
 ````

+**Egress route fields:**
+
+| Field | Required | Description |
+|---|---|---|
+| `host` | yes | Hostname to allowlist. One entry per host. |
+| `role` | no | Reserved for future use. The key is recognised but any value is currently rejected at load. Provider auth routes (e.g. Claude's `api.anthropic.com`) are injected automatically from `agent_provider.auth_token`, not via `role`. |
+| `auth.scheme` | when `auth` present | `Bearer` or `token`. Injected by the proxy; the agent never sees the value. |
+| `auth.token_ref` | when `auth` present | Env-var name holding the secret on the host. |
+| `matches` | no | Array of `{paths, methods, headers}` filters. A request must match at least one entry (if any are given) to be forwarded. |
+| `matches[].paths` | no | Array of `{type, value}`. `type` is `prefix` (default), `exact`, or `regex`. |
+| `matches[].methods` | no | Array of HTTP method strings, e.g. `[GET, POST]`. |
+| `matches[].headers` | no | Array of `{name, value, type}`. `type` is `exact` (default) or `regex`. |
+| `dlp` | no | Per-route DLP overrides. Omit to use defaults (all detectors on). |
+| `dlp.outbound_detectors` | no | `false` disables outbound scanning; list restricts to named detectors (`token_patterns`, `known_secrets`). |
+| `dlp.inbound_detectors` | no | `false` disables inbound scanning; list restricts to named detectors (`naive_injection_detection`). |
+| `git.fetch` | no | `true` permits smart HTTP clone/fetch (`git-upload-pack`) for this host. Push (`git-receive-pack`) remains blocked. |
+
 More examples in `examples/`. Full design lives under `docs/prds/`; the trust-boundary rationale is in `docs/prds/0011-per-file-md-manifest.md`.

 ## Trademarks
@@ -0,0 +1,96 @@
+# Per-bottle sidecar bundle image (PRD 0024).
+#
+# Collapses the prior per-sidecar images (egress, git-gate,
+# supervise) into one. A small stdlib-Python init supervisor at
+# /app/sidecar_init.py spawns all daemons, forwards SIGTERM, and
+# propagates per-daemon stdout/stderr to the container log with a
+# `[name]` prefix. See PRD 0024 for the rationale.
+#
+# Layout:
+#
+#   /usr/bin/gitleaks                    gitleaks binary
+#   /app/egress_addon.py + siblings      mitmproxy addon (egress)
+#   /app/egress-entrypoint.sh            mitmdump launcher
+#   /app/supervise_server.py + .py       supervise MCP server
+#   /app/sidecar_init.py                 PID 1 supervisor
+#   /etc/egress/routes.yaml              bind-mounted at run time
+#   /etc/git-gate/pre-receive            docker-cp'd at start time
+#   /git-gate-entrypoint.sh              docker-cp'd at start time
+#   /git-gate/creds/*                    docker-cp'd at start time
+#   /git/*                               bare repos, populated at runtime
+#   /run/supervise/queue/                bind-mounted at run time
+#   /home/mitmproxy/.mitmproxy/          mitmproxy CA dir
+#
+# Exposed ports inside the container:
+#   9099  egress (mitmproxy, agent-facing HTTPS proxy)
+#   9418  git-gate (git-daemon)
+#   9420  git-gate smart HTTP (smolmachines agent-facing transport)
+#   9100  supervise (MCP HTTP)
+
+# Stage 1: gitleaks binary. The upstream gitleaks image is alpine
+# with the binary at /usr/bin/gitleaks. Pinned by digest in lockstep
+# with Dockerfile.git-gate's prior base (now deleted at chunk 3).
+FROM zricethezav/gitleaks@sha256:c00b6bd0aeb3071cbcb79009cb16a60dd9e0a7c60e2be9ab65d25e6bc8abbb7f AS gitleaks-src
+
+# Stage 2: assembly. mitmproxy/mitmproxy is debian-slim-based with
+# Python + mitmdump pre-installed — heavier than the others, so
+# this stage starts there and pulls the standalone binaries in.
+FROM mitmproxy/mitmproxy:11.1.3
+
+# Run as root inside the bundle. The bundle is the isolation
+# boundary; per-daemon user separation inside it is not load-bearing
+# and complicates the supervisor's spawn path.
+USER root
+
+# Runtime system deps:
+#   git supplies the `git daemon` subcommand (no separate package)
+#     plus the core `git` binary the pre-receive hook invokes.
+#   openssh-client supplies the upstream SSH transport the
+#     pre-receive hook uses to forward accepted refs.
+#   ca-certificates is needed for mitmdump upstream TLS (the
+#     base image already has it; listed for explicitness).
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends \
+      git openssh-client ca-certificates \
+ && rm -rf /var/lib/apt/lists/*
+
+# Pull the standalone binaries into the final image.
+COPY --from=gitleaks-src /usr/bin/gitleaks /usr/bin/gitleaks
+
+# Project Python: addon + server modules + the init supervisor.
+# Kept flat under /app/ so mitmdump's loader resolves them as
+# top-level siblings (absolute imports), matching the prior
+# Dockerfile.egress / Dockerfile.supervise layout.
+COPY bot_bottle/egress_addon_core.py /app/egress_addon_core.py
+COPY bot_bottle/egress_addon.py      /app/egress_addon.py
+COPY bot_bottle/dlp_detectors.py     /app/dlp_detectors.py
+COPY bot_bottle/yaml_subset.py       /app/yaml_subset.py
+COPY bot_bottle/supervise.py         /app/supervise.py
+COPY bot_bottle/supervise_server.py  /app/supervise_server.py
+COPY bot_bottle/sidecar_init.py      /app/sidecar_init.py
+COPY bot_bottle/git_http_backend.py  /app/git_http_backend.py
+COPY bot_bottle/egress_entrypoint.sh /app/egress-entrypoint.sh
+RUN chmod +x /app/egress-entrypoint.sh
+
+# Pre-create runtime directories the compose renderer + start
+# step expect to exist. `docker cp` does not create intermediate
+# dirs, and bind mounts won't either if the parent is missing.
+RUN mkdir -p \
+      /etc/egress \
+      /etc/git-gate \
+      /git-gate/creds \
+      /git \
+      /run/supervise/queue \
+      /home/mitmproxy/.mitmproxy
+
+# Documentation only — the compose renderer publishes whichever
+# subset the bottle uses.
+EXPOSE 8888 9099 9418 9420 9100
+
+# WORKDIR matches Dockerfile.supervise's prior layout so the
+# in-app same-dir import in supervise_server.py stays deterministic.
+WORKDIR /app
+
+# PID 1 is the supervisor. It owns signal handling and exit-code
+# propagation; no `exec` chain in the entrypoint itself.
+ENTRYPOINT ["python3", "/app/sidecar_init.py"]
@@ -526,6 +526,11 @@ from .docker import DockerBottleBackend  # noqa: E402  # pylint: disable=wrong-i
 from .macos_container import MacosContainerBottleBackend  # noqa: E402  # pylint: disable=wrong-import-position
 from .smolmachines import SmolmachinesBottleBackend  # noqa: E402  # pylint: disable=wrong-import-position

+# Freezer is imported after the backend classes for the same reason:
+# Freezer.commit_slug constructs ActiveAgent, which must be fully
+# defined first.
+from .freeze import CommitCancelled, Freezer, get_freezer  # noqa: E402  # pylint: disable=wrong-import-position
+

 # The dict is heterogeneous: each value is a BottleBackend specialized
 # over its own plan type. Concrete plan types are erased here because
@@ -613,9 +618,12 @@ __all__ = [
    "BottleCleanupPlan",
    "BottlePlan",
    "BottleSpec",
+    "CommitCancelled",
    "ExecResult",
+    "Freezer",
    "enumerate_active_agents",
    "get_bottle_backend",
+    "get_freezer",
    "has_backend",
    "known_backend_names",
 ]
@@ -58,10 +58,17 @@ from .sidecar_bundle import (
 )


-# Repo root, used as the build context for the bundle Dockerfile.
+# Repo root or installed site-packages root, used as the build context for
+# Dockerfiles that COPY bot_bottle source files.
 _REPO_DIR = str(Path(__file__).resolve().parent.parent.parent.parent)


+def _sidecar_bundle_dockerfile() -> str:
+    if (Path(_REPO_DIR) / SIDECAR_BUNDLE_DOCKERFILE).is_file():
+        return SIDECAR_BUNDLE_DOCKERFILE
+    return f"bot_bottle/{SIDECAR_BUNDLE_DOCKERFILE}"
+
+
 def bottle_plan_to_compose(plan: DockerBottlePlan) -> dict[str, Any]:
    """Render a Compose v2 spec dict from a fully-resolved
    DockerBottlePlan.
@@ -183,7 +190,7 @@ def _sidecar_bundle_service(plan: DockerBottlePlan) -> dict[str, Any]:
        "image": SIDECAR_BUNDLE_IMAGE,
        "build": {
            "context": _REPO_DIR,
-            "dockerfile": SIDECAR_BUNDLE_DOCKERFILE,
+            "dockerfile": _sidecar_bundle_dockerfile(),
        },
        "container_name": sidecar_bundle_container_name(plan.slug),
        "networks": {
@@ -0,0 +1,23 @@
+"""DockerFreezer — snapshot a Docker bottle via `docker commit`."""
+
+from __future__ import annotations
+
+from .. import ActiveAgent
+from ..freeze import Freezer
+from .util import commit_container
+from ...log import info
+
+
+class DockerFreezer(Freezer):
+    """Freezes a Docker bottle by running `docker commit`."""
+
+    backend_name = "docker"
+
+    def _freeze(self, agent: ActiveAgent) -> str:
+        container = f"bot-bottle-{agent.slug}"
+        image_tag = f"bot-bottle-committed-{agent.slug}:latest"
+        commit_container(container, image_tag)
+        return image_tag
+
+    def _export_hint(self, slug: str, image_ref: str) -> None:
+        info(f"to export for migration:      docker save {image_ref} -o {slug}.tar")
@@ -47,6 +47,7 @@ from ...bottle_state import (
    bottle_state_dir,
    egress_state_dir,
    git_gate_state_dir,
+    read_committed_image,
 )
 from .compose import (
    bottle_plan_to_compose,
@@ -91,12 +92,22 @@ def launch(
        )

    try:
-        # Step 1: agent image build. Sidecar images get built lazily by
-        # `docker compose up` via the renderer's `build:` directives.
-        docker_mod.build_image(
-            plan.image, _REPO_DIR,
-            dockerfile=plan.dockerfile_path,
-        )
+        # Step 1: agent image. Use a committed snapshot when one exists
+        # and is present in the local daemon; otherwise build from the
+        # Dockerfile. Sidecar images get built lazily by `docker compose
+        # up` via the renderer's `build:` directives.
+        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,
+            )

        internal_network = network_mod.network_name_for_slug(plan.slug)
        egress_network = network_mod.network_egress_name_for_slug(plan.slug)
@@ -12,9 +12,10 @@ from __future__ import annotations
 import os


-# Bundle image. Defaults to a built-locally tag (built from the
-# repo's Dockerfile.sidecars via compose `build:`). Operators
-# pinning to a published digest can override via env.
+# Bundle image. Defaults to a built-locally tag. Source checkouts
+# build from the repo-root Dockerfile.sidecars; installed packages
+# build from the packaged copy under bot_bottle/.
+# Operators pinning to a published digest can override via env.
 SIDECAR_BUNDLE_IMAGE = os.environ.get(
    "BOT_BOTTLE_SIDECAR_IMAGE",
    "bot-bottle-sidecars:latest",
@@ -152,6 +152,21 @@ def build_image(ref: str, context: str, *, dockerfile: str = "") -> None:
 #         )


+def commit_container(container_name: str, image_tag: str) -> None:
+    """Run `docker commit <container_name> <image_tag>` to snapshot the
+    running container's filesystem state as a local Docker image."""
+    result = subprocess.run(
+        ["docker", "commit", container_name, image_tag],
+        capture_output=True, text=True, check=False,
+    )
+    if result.returncode != 0:
+        die(
+            f"docker commit {container_name!r} → {image_tag!r} failed: "
+            f"{(result.stderr or '').strip() or '<no stderr>'}"
+        )
+    info(f"committed {container_name!r} → {image_tag!r}")
+
+
 def image_id(ref: str) -> str:
    """Return the content-addressed image ID (e.g.
    `sha256:abcd...`) for `ref`. The smolmachines backend keys its
@@ -0,0 +1,100 @@
+"""Freezer — snapshot a running bottle to a resumable artifact.
+
+Follows the same pattern as BottleBackend: a shared base class with
+common post-freeze steps (write committed-image path, mark preserved,
+print resume hint) and backend-specific subclasses in their respective
+backend directories.
+
+Entry points:
+  Freezer.commit(agent)      — freeze by ActiveAgent
+  Freezer.commit_slug(slug)  — convenience wrapper for cmd_commit
+  get_freezer(backend_name)  — factory
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from . import ActiveAgent
+from ..bottle_state import mark_preserved, write_committed_image
+from ..log import die, info
+
+
+class CommitCancelled(Exception):
+    """Raised by Freezer._freeze when the user declines a confirmation prompt."""
+
+
+class Freezer(ABC):
+    """Freezes a running bottle to a resumable artifact.
+
+    The base class owns the shared post-commit steps:
+      - write_committed_image  — records the artifact path in per-bottle state
+      - mark_preserved         — prevents teardown from removing the state dir
+      - resume hint            — printed to stderr after the snapshot
+
+    Subclasses implement _freeze with the backend-specific snapshot
+    operation and optionally override _export_hint for migration hints.
+    """
+
+    backend_name: str
+
+    def commit(self, agent: ActiveAgent) -> None:
+        """Freeze the bottle for `agent` to a resumable artifact.
+
+        Calls _freeze for the backend-specific snapshot, then writes the
+        committed image reference to per-bottle state and marks the bottle
+        preserved so the next `./cli.py resume` boots from the snapshot.
+
+        Raises CommitCancelled if the user declines an interactive
+        confirmation prompt (e.g. the macos-container stop prompt).
+        """
+        image_ref = self._freeze(agent)
+        write_committed_image(agent.slug, image_ref)
+        mark_preserved(agent.slug)
+        info(f"to resume from this snapshot: ./cli.py resume {agent.slug}")
+        self._export_hint(agent.slug, image_ref)
+
+    @abstractmethod
+    def _freeze(self, agent: ActiveAgent) -> str:
+        """Backend-specific snapshot. Returns the image tag or artifact path
+        stored by write_committed_image. Raises CommitCancelled if the user
+        declines a stop-confirmation prompt."""
+
+    def _export_hint(self, slug: str, image_ref: str) -> None:
+        """Optionally print an export-for-migration hint after committing.
+        Overridden by backends that provide a meaningful export command."""
+
+    def commit_slug(self, slug: str) -> None:
+        """Convenience entry for cmd_commit when only a slug is available."""
+        from ..bottle_state import read_metadata
+        metadata = read_metadata(slug)
+        agent = ActiveAgent(
+            backend_name=self.backend_name,
+            slug=slug,
+            agent_name=metadata.agent_name if metadata else "",
+            started_at=metadata.started_at if metadata else "",
+            services=(),
+        )
+        self.commit(agent)
+
+
+def get_freezer(backend_name: str) -> Freezer:
+    """Return the Freezer for the named backend.
+
+    backend_name "" is treated as "docker" for backward compatibility
+    with state dirs written before the backend field was added."""
+    resolved = backend_name or "docker"
+    if resolved == "docker":
+        from .docker.freezer import DockerFreezer
+        return DockerFreezer()
+    if resolved == "macos-container":
+        from .macos_container.freezer import MacosContainerFreezer
+        return MacosContainerFreezer()
+    if resolved == "smolmachines":
+        from .smolmachines.freezer import SmolmachinesFreezer
+        return SmolmachinesFreezer()
+    die(
+        f"commit is only supported for docker, macos-container, and "
+        f"smolmachines; backend {backend_name!r} has no freezer"
+    )
+    raise AssertionError("unreachable")
@@ -0,0 +1,31 @@
+"""MacosContainerFreezer — snapshot a macOS container bottle.
+
+Apple Container removes containers when they stop, making stop-then-export
+impossible. Instead, commit_container execs into the running container and
+streams the root filesystem via tar. The bottle continues running after commit.
+"""
+
+from __future__ import annotations
+
+from .. import ActiveAgent
+from ..freeze import Freezer
+from .util import commit_container
+from ...log import info
+
+
+class MacosContainerFreezer(Freezer):
+    """Freezes a macOS-container bottle via exec-tar + image rebuild."""
+
+    backend_name = "macos-container"
+
+    def _freeze(self, agent: ActiveAgent) -> str:
+        container = f"bot-bottle-{agent.slug}"
+        image_tag = f"bot-bottle-committed-{agent.slug}:latest"
+        commit_container(container, image_tag)
+        return image_tag
+
+    def _export_hint(self, slug: str, image_ref: str) -> None:
+        info(
+            f"to export for migration:      "
+            f"container image save {image_ref} -o {slug}.tar"
+        )
@@ -17,7 +17,11 @@ from contextlib import ExitStack, contextmanager
 from pathlib import Path
 from typing import Callable, Generator

-from ...bottle_state import egress_state_dir, git_gate_state_dir
+from ...bottle_state import (
+    egress_state_dir,
+    git_gate_state_dir,
+    read_committed_image,
+)
 from ...egress import EGRESS_ROUTES_IN_CONTAINER, egress_resolve_token_values
 from ...git_gate import revoke_git_gate_provisioned_keys
 from ...log import die, info, warn
@@ -83,7 +87,7 @@ def launch(

    try:
        plan = _mint_certs(plan)
-        _build_images(plan)
+        plan = _build_images(plan)

        internal_network = internal_network_name(plan.slug)
        egress_network = egress_network_name(plan.slug)
@@ -134,17 +138,28 @@ def _mint_certs(plan: MacosContainerBottlePlan) -> MacosContainerBottlePlan:
    return dataclasses.replace(plan, egress_plan=egress_plan)


-def _build_images(plan: MacosContainerBottlePlan) -> None:
+def _build_images(plan: MacosContainerBottlePlan) -> MacosContainerBottlePlan:
    container_mod.build_image(
        SIDECAR_BUNDLE_IMAGE,
        _REPO_DIR,
        dockerfile=SIDECAR_BUNDLE_DOCKERFILE,
    )
+    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


 def _create_networks(
@@ -313,7 +328,6 @@ def _agent_run_argv(
        "container", "run",
        "--name", plan.container_name,
        "--detach",
-        "--rm",
        "--network", internal_network,
    ]
    for entry in _agent_env_entries(plan, sidecar_ip):
@@ -8,6 +8,7 @@ import ipaddress
 import platform
 import shutil
 import subprocess
+import tempfile
 import time
 from typing import Iterable

@@ -72,6 +73,53 @@ def build_image(ref: str, context: str, *, dockerfile: str = "") -> None:
    subprocess.run(args, check=True)


+def commit_container(container_name: str, image_tag: str) -> None:
+    """Snapshot a running Apple Container as a local image.
+
+    `container export` requires a stopped container, but Apple Container
+    removes containers when they stop, making stop-then-export impossible.
+    Instead, exec into the running container as root and stream the root
+    filesystem out via tar, then build a new image from that archive.
+    The bottle continues running after commit.
+    """
+    with tempfile.TemporaryDirectory(prefix="bot-bottle-container-commit.") as tmp:
+        rootfs_tar = os.path.join(tmp, "rootfs.tar")
+        dockerfile = os.path.join(tmp, "Dockerfile")
+        with open(rootfs_tar, "wb") as tar_out:
+            result = subprocess.run(
+                [
+                    _CONTAINER, "exec",
+                    "--user", "root",
+                    container_name,
+                    "tar", "--create",
+                    "--exclude=./proc",
+                    "--exclude=./sys",
+                    "--exclude=./dev",
+                    "--exclude=./run",
+                    "--file=-",
+                    "--directory=/",
+                    ".",
+                ],
+                stdout=tar_out,
+                stderr=subprocess.PIPE,
+                check=False,
+            )
+        if result.returncode != 0:
+            die(
+                f"container exec tar {container_name!r} failed: "
+                f"{(result.stderr or b'').decode().strip() or '<no stderr>'}"
+            )
+        with open(dockerfile, "w", encoding="utf-8") as f:
+            f.write(
+                "FROM scratch\n"
+                "ADD rootfs.tar /\n"
+                "USER node\n"
+                "WORKDIR /home/node\n"
+            )
+        build_image(image_tag, tmp, dockerfile=dockerfile)
+    info(f"committed {container_name!r} → {image_tag!r}")
+
+
 def _ensure_builder_dns() -> None:
    dns = dns_server()
    status = _builder_status()
@@ -218,6 +266,36 @@ def container_exists(name: str) -> bool:
    return name in {line.strip() for line in result.stdout.splitlines()}


+def container_is_running(name: str) -> bool:
+    """Return True if the named container is currently running.
+
+    `container list` without `--all` lists only running containers."""
+    result = subprocess.run(
+        [_CONTAINER, "list", "--quiet"],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if result.returncode != 0:
+        return False
+    return name in {line.strip() for line in result.stdout.splitlines()}
+
+
+def stop_container(name: str) -> None:
+    """Stop the named container without deleting it."""
+    result = subprocess.run(
+        [_CONTAINER, "stop", name],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if result.returncode != 0:
+        die(
+            f"container stop {name!r} failed: "
+            f"{(result.stderr or '').strip() or '<no stderr>'}"
+        )
+
+
 def force_remove_container(name: str) -> None:
    if container_exists(name):
        subprocess.run(
@@ -145,7 +145,12 @@ class SmolmachinesBottle(Bottle):
        script = exec_shell_script(agent_argv, self.terminal_title, self.terminal_color) if tty else None
        if script is None:
            return subprocess.run(agent_argv, check=False).returncode
-        return subprocess.run(["sh", "-lc", script], check=False).returncode
+        # Use sh -c (not -lc) so the script inherits PATH from the calling
+        # process. sh -l sources login-shell init files (e.g. /etc/profile)
+        # which may NOT include smolvm's location when it was installed via
+        # homebrew. The calling process (./cli.py) already has smolvm on PATH
+        # (provision steps succeed), so -c is sufficient.
+        return subprocess.run(["sh", "-c", script], check=False).returncode

    # smolvm/libkrun can SIGKILL an otherwise-normal exec during
    # early-VM provisioning. Retry once after a short settle so
@@ -0,0 +1,145 @@
+"""SmolmachinesFreezer — snapshot a smolmachines bottle.
+
+`smolvm pack create --from-vm` requires the VM to be stopped, and smolvm
+removes VMs when stopped (same issue as Apple Container). Instead, exec
+into the running VM as root to write a gzip-compressed tar of the root
+filesystem to /var/tmp, then copy it to the host with `smolvm machine cp`,
+build a Docker image from the archive, convert it to a smolmachine artifact
+via the existing registry pipeline, and record the sidecar path. The VM
+stays running throughout."""
+
+from __future__ import annotations
+
+import tempfile
+from pathlib import Path
+
+from .. import ActiveAgent
+from ..freeze import Freezer
+from ..docker import util as docker_mod
+from .local_registry import crane_push_tarball, ephemeral_registry
+from .smolvm import machine_cp, machine_exec, pack_create
+from ...bottle_state import bottle_state_dir
+from ...log import die, info
+
+
+# Temp file written inside the VM during commit. Lives in /var/tmp
+# (on-disk, unlike tmpfs /tmp) to survive for machine_cp.
+_VM_COMMIT_TAR = "/var/tmp/.bot-bottle-commit.tar.gz"
+
+
+class SmolmachinesFreezer(Freezer):
+    """Freezes a smolmachines bottle via exec-tar + Docker image + smolmachine pack.
+
+    The VM is NOT stopped. We exec into the running VM to write a compressed
+    tar of the root filesystem to /var/tmp, copy it to the host with
+    machine_cp, build a Docker image (Docker's ADD decompresses .tar.gz
+    automatically), then run the same image→registry→pack_create pipeline
+    that _ensure_smolmachine uses for fresh builds."""
+
+    backend_name = "smolmachines"
+
+    def _freeze(self, agent: ActiveAgent) -> str:
+        machine = f"bot-bottle-{agent.slug}"
+        image_ref = f"bot-bottle-committed-{agent.slug}:latest"
+        output_dir = bottle_state_dir(agent.slug)
+        output_dir.mkdir(parents=True, exist_ok=True)
+        binary = output_dir / "committed-smolmachine"
+        sidecar = output_dir / "committed-smolmachine.smolmachine"
+        _snapshot_running_vm(machine, image_ref, binary)
+        return str(sidecar)
+
+    def _export_hint(self, slug: str, image_ref: str) -> None:
+        info(f"to export for migration:      cp {image_ref} {slug}.smolmachine")
+
+
+def _snapshot_running_vm(machine: str, image_ref: str, binary: Path) -> None:
+    """Exec-tar the running VM, build a Docker image, and pack to a smolmachine.
+
+    binary:  destination for the launcher (sibling .smolmachine is the artifact
+             that machine_create --from consumes, same convention as pack_create).
+    """
+    with tempfile.TemporaryDirectory(prefix="bot-bottle-vm-commit.") as tmp:
+        tmp_path = Path(tmp)
+        # Use .tar.gz — Docker ADD decompresses automatically and the
+        # compressed archive fits in the VM's /var/tmp more easily.
+        rootfs_tar_gz = tmp_path / "rootfs.tar.gz"
+        dockerfile = tmp_path / "Dockerfile"
+
+        _exec_tar_to_file(machine, rootfs_tar_gz)
+
+        dockerfile.write_text(
+            "FROM scratch\n"
+            "ADD rootfs.tar.gz /\n"
+            "USER node\n"
+            "WORKDIR /home/node\n"
+        )
+        docker_mod.build_image(image_ref, str(tmp_path), dockerfile=str(dockerfile))
+
+    image_tarball = binary.parent / "committed.image.tar"
+    docker_mod.save(image_ref, str(image_tarball))
+    try:
+        with ephemeral_registry() as handle:
+            digest = docker_mod.image_id(image_ref).split(":", 1)[-1][:16]
+            push_ref = f"{handle.push_endpoint}/bot-bottle-committed:{digest}"
+            pack_ref = f"{handle.pull_endpoint}/bot-bottle-committed:{digest}"
+            crane_push_tarball(handle, str(image_tarball), push_ref)
+            pack_create(pack_ref, binary)
+    finally:
+        image_tarball.unlink(missing_ok=True)
+
+
+def _exec_tar_to_file(machine: str, dest: Path) -> None:
+    """Snapshot the running VM's root filesystem to dest (.tar.gz).
+
+    Writes a gzip-compressed tar to _VM_COMMIT_TAR inside the VM via
+    machine_exec (same mechanism as provisioning), then copies it to the
+    host with machine_cp. This avoids binary-stdout piping through the
+    smolvm exec channel, which does not reliably handle large binary output.
+
+    A connectivity probe (machine_exec true) runs first so a concurrent-exec
+    limitation (smolvm may reject a second exec while -i -t is active) is
+    reported clearly rather than as a silent failure."""
+    # Connectivity probe — if smolvm rejects concurrent exec while an
+    # interactive session is running, fail clearly here.
+    probe = machine_exec(machine, ["true"])
+    if probe.returncode != 0:
+        die(
+            f"smolvm exec is not available for {machine!r} "
+            f"(exit {probe.returncode}: {probe.stderr.strip() or probe.stdout.strip() or '<no output>'}). "
+            f"If an interactive session is active, smolvm may not support concurrent exec."
+        )
+
+    # Create the compressed tar inside the VM.
+    # tar exits 1 when files change during archiving (normal for a live
+    # filesystem); only treat exit > 1 as fatal.
+    tar_result = machine_exec(
+        machine,
+        [
+            "tar", "--create", "--gzip",
+            "--exclude=./proc",
+            "--exclude=./sys",
+            "--exclude=./dev",
+            "--exclude=./run",
+            # /tmp and /var/tmp are ephemeral. Their stale contents
+            # (e.g. /tmp/claude-<uid>) have uid remapped by smolvm's
+            # pack process, causing Claude Code to refuse to use them
+            # on resume. Exclude both; _init_vm recreates them with
+            # mkdir -p + correct ownership on every boot.
+            "--exclude=./tmp",
+            "--exclude=./var/tmp",
+            f"--file={_VM_COMMIT_TAR}",
+            "--directory=/",
+            ".",
+        ],
+    )
+    if tar_result.returncode > 1:
+        die(
+            f"smolvm exec tar {machine!r} failed (exit {tar_result.returncode}): "
+            f"{tar_result.stderr.strip() or tar_result.stdout.strip() or '<no output>'}"
+        )
+
+    # Copy from VM to host, then clean up.
+    try:
+        machine_cp(f"{machine}:{_VM_COMMIT_TAR}", str(dest))
+    finally:
+        machine_exec(machine, ["rm", "-f", _VM_COMMIT_TAR])
@@ -40,8 +40,12 @@ from ..docker.git_gate import (
    GIT_GATE_HOOK_IN_CONTAINER,
 )
 from ...git_gate import revoke_git_gate_provisioned_keys
-from ...log import warn
-from ...bottle_state import egress_state_dir, git_gate_state_dir
+from ...log import info, warn
+from ...bottle_state import (
+    egress_state_dir,
+    git_gate_state_dir,
+    read_committed_image,
+)
 from . import loopback_alias as _loopback
 from . import sidecar_bundle as _bundle
 from . import smolvm as _smolvm
@@ -85,14 +89,7 @@ def launch(
        plan = _start_bundle(plan, network, loopback_ip, stack)
        plan = _discover_urls(plan, loopback_ip)

-        # Build the agent image and pack it into a `.smolmachine`
-        # artifact (or hit the per-Dockerfile-digest cache). Runs
-        # here, not in prepare, so the docker-build output doesn't
-        # garble the dashboard's preflight modal.
-        agent_from_path = _ensure_smolmachine(
-            plan.agent_image,
-            dockerfile=plan.agent_dockerfile_path,
-        )
+        agent_from_path = _agent_from_path(plan)

        _launch_vm(plan, agent_from_path, loopback_ip, stack)
        _init_vm(plan)
@@ -279,10 +276,16 @@ def _init_vm(plan: SmolmachinesBottlePlan) -> None:
    All folded into one sh -c to avoid back-to-back exec calls
    immediately after machine_start (libkrun exec-channel race).

+    mkdir -p guards: when booting from a committed snapshot, /tmp and
+    /var/tmp are excluded from the archive (they're ephemeral and their
+    stale contents would have wrong uid after smolvm's uid remap). The
+    directories must be created before chown/chmod can set permissions.
+
    wait_exec_ready polls until the exec channel is ready for the
    subsequent provision calls, replacing the empirical sleep."""
    _smolvm.machine_exec(plan.machine_name, [
        "sh", "-c",
+        "mkdir -p /tmp /var/tmp && "
        "chown -R node:node /home/node && "
        "chown root:root /tmp /var/tmp && "
        "chmod 1777 /tmp /var/tmp",
@@ -386,6 +389,30 @@ def _resolve_token_env(
    return egress_resolve_token_values(plan.egress_plan.token_env_map, effective_env)


+def _agent_from_path(plan: SmolmachinesBottlePlan) -> Path:
+    """Return the `.smolmachine` artifact used for `machine create --from`.
+
+    Prefer a committed VM artifact when one is recorded and still
+    present. If the file was removed, fall back to the normal image
+    build + pack cache path.
+    """
+    committed = read_committed_image(plan.slug)
+    if committed:
+        committed_path = Path(committed)
+        if committed_path.is_file():
+            info(f"using committed smolmachine {str(committed_path)!r}")
+            return committed_path
+
+    # Build the agent image and pack it into a `.smolmachine`
+    # artifact (or hit the per-Dockerfile-digest cache). Runs here,
+    # not in prepare, so the docker-build output doesn't garble the
+    # dashboard's preflight modal.
+    return _ensure_smolmachine(
+        plan.agent_image,
+        dockerfile=plan.agent_dockerfile_path,
+    )
+
+
 def _ensure_smolmachine(image_ref: str, *, dockerfile: str = "") -> Path:
    """Build the agent docker image and convert it into a
    `.smolmachine` artifact, caching the result under
@@ -25,6 +25,7 @@ smolvm binary."""

 from __future__ import annotations

+import json
 import shutil
 import subprocess
 import time
@@ -94,6 +95,16 @@ def pack_create(image: str, output: Path) -> None:
    _smolvm("pack", "create", "--image", image, "-o", str(output))


+def pack_create_from_vm(name: str, output: Path) -> None:
+    """`smolvm pack create --from-vm <name> -o <output>`.
+
+    Snapshots an existing persistent VM into a pack artifact. As
+    with `pack_create`, smolvm writes a launcher at `output` and the
+    bootable sidecar at `output.smolmachine`.
+    """
+    _smolvm("pack", "create", "--from-vm", name, "-o", str(output))
+
+
 # --- Machine lifecycle ---------------------------------------------------


@@ -143,6 +154,21 @@ def machine_create(
    _smolvm(*args)


+def machine_is_running(name: str) -> bool:
+    """Return True if the named VM is in the 'running' state."""
+    result = _smolvm("machine", "ls", "--json", check=False)
+    if result.returncode != 0:
+        return False
+    try:
+        machines = json.loads(result.stdout or "[]")
+    except ValueError:
+        return False
+    return any(
+        isinstance(m, dict) and m.get("name") == name and m.get("state") == "running"
+        for m in machines
+    )
+
+
 def machine_start(name: str) -> None:
    """`smolvm machine start --name NAME`."""
    _smolvm("machine", "start", "--name", name)
@@ -43,6 +43,7 @@ from . import supervise as _supervise
 # Directory layout: ~/.bot-bottle/state/<identity>/...
 _STATE_SUBDIR = "state"
 _PER_BOTTLE_DOCKERFILE_NAME = "Dockerfile"
+_COMMITTED_IMAGE_NAME = "committed-image"
 _TRANSCRIPT_SUBDIR = "transcript"
 # Per-sidecar scratch subdirs. PRD 0018 chunk 2: bind-mount sources
 # live here so chunk 3's `docker compose up` can find them at stable
@@ -179,6 +180,32 @@ def write_per_bottle_dockerfile(identity: str, content: str) -> Path:
    return p


+def committed_image_path(identity: str) -> Path:
+    return bottle_state_dir(identity) / _COMMITTED_IMAGE_NAME
+
+
+def write_committed_image(identity: str, image_tag: str) -> Path:
+    """Persist the committed image tag for `identity`. The next
+    `cli.py resume <identity>` will boot from this image instead of
+    rebuilding from the Dockerfile."""
+    path = committed_image_path(identity)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(image_tag.strip() + "\n")
+    path.chmod(0o644)
+    return path
+
+
+def read_committed_image(identity: str) -> str | None:
+    """Return the committed image tag for `identity`, or None if no
+    commit has been recorded. Used by the Docker launch step to skip
+    the Dockerfile build when a committed snapshot exists."""
+    path = committed_image_path(identity)
+    if not path.is_file():
+        return None
+    tag = path.read_text().strip()
+    return tag or None
+
+
 def per_bottle_image_tag(identity: str) -> str:
    """Image tag for a rebuilt bottle. Distinct from the base
    bot-bottle-claude:latest so per-bottle rebuilds don't collide in
@@ -314,6 +341,7 @@ __all__ = [
    "bottle_state_dir",
    "cleanup_state",
    "clear_preserve_marker",
+    "committed_image_path",
    "egress_state_dir",
    "git_gate_state_dir",
    "is_preserved",
@@ -323,9 +351,11 @@ __all__ = [
    "per_bottle_dockerfile_path",
    "per_bottle_image_tag",
    "preserve_marker_path",
+    "read_committed_image",
    "read_metadata",
    "supervise_state_dir",
    "transcript_snapshot_dir",
+    "write_committed_image",
    "write_metadata",
    "write_per_bottle_dockerfile",
 ]
@@ -1,6 +1,6 @@
 """Main CLI dispatcher.

-Commands: cleanup, edit, info, init, list, resume, start, supervise
+Commands: cleanup, commit, doctor, edit, info, init, list, resume, start, supervise
 """

 from __future__ import annotations
@@ -12,6 +12,8 @@ from ..manifest import ManifestError
 from ._common import PROG
 from . import list as _list_mod
 from .cleanup import cmd_cleanup
+from .commit import cmd_commit
+from .doctor import cmd_doctor
 from .edit import cmd_edit
 from .info import cmd_info
 from .init import cmd_init
@@ -23,6 +25,8 @@ cmd_list = _list_mod.cmd_list

 COMMANDS = {
    "cleanup": cmd_cleanup,
+    "commit": cmd_commit,
+    "doctor": cmd_doctor,
    "edit": cmd_edit,
    "info": cmd_info,
    "init": cmd_init,
@@ -37,6 +41,8 @@ def usage() -> None:
    sys.stderr.write(f"usage: {PROG} <command> [args...]\n\n")
    sys.stderr.write("Commands:\n")
    sys.stderr.write("  cleanup   stop and remove all active bot-bottle containers\n")
+    sys.stderr.write("  commit    snapshot a running bottle's container state to a Docker image\n")
+    sys.stderr.write("  doctor    check Python, Docker, and bot-bottle config prerequisites\n")
    sys.stderr.write("  edit      open an agent in vim for editing\n")
    sys.stderr.write("  info      print env, skills, and prompt details for a named agent\n")
    sys.stderr.write("  init      interactively create a new agent and add it to bot-bottle.json\n")
@@ -6,7 +6,7 @@ import os
 import sys
 from pathlib import Path

-PROG = "cli.py"
+PROG = Path(sys.argv[0]).name or "bot-bottle"
 USER_CWD = os.getcwd()
 REPO_DIR = str(Path(__file__).resolve().parent.parent.parent)

@@ -0,0 +1,53 @@
+"""commit: freeze a running bottle's state to a resumable artifact.
+
+Docker bottles are committed to a local Docker image. Macos-container
+bottles are exported and rebuilt as a local Apple Container image.
+Smolmachines bottles are packed from the running VM into a
+`.smolmachine` artifact. The resulting reference is stored in
+per-bottle state so the next `./cli.py resume <slug>` boots from the
+snapshot instead of rebuilding from the Dockerfile.
+"""
+
+from __future__ import annotations
+
+import argparse
+
+from ..backend import enumerate_active_agents
+from ..backend.freeze import CommitCancelled, get_freezer
+from ..bottle_state import read_metadata
+from ..log import die
+from ._common import PROG
+from . import tui
+
+
+def cmd_commit(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(prog=f"{PROG} commit", add_help=True)
+    parser.add_argument(
+        "slug",
+        nargs="?",
+        default=None,
+        help=(
+            "bottle slug from `cli.py list active` "
+            "(omit to pick interactively)"
+        ),
+    )
+    args = parser.parse_args(argv)
+
+    slug = args.slug
+    if slug is None:
+        active = enumerate_active_agents()
+        if not active:
+            die("no active bottles; start one with `./cli.py start`")
+        choices = [a.slug for a in active]
+        slug = tui.filter_select(choices, title="Select bottle to commit")
+        if slug is None:
+            return 0
+
+    metadata = read_metadata(slug)
+    backend = metadata.backend if metadata else ""
+
+    try:
+        get_freezer(backend).commit_slug(slug)
+    except CommitCancelled:
+        return 0
+    return 0
@@ -0,0 +1,73 @@
+"""doctor: validate host prerequisites for running bot-bottle."""
+
+from __future__ import annotations
+
+import argparse
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+from ._common import PROG
+
+
+def _ok(label: str, detail: str) -> None:
+    print(f"ok: {label}: {detail}")
+
+
+def _fail(label: str, detail: str) -> None:
+    print(f"fail: {label}: {detail}")
+
+
+def _check_python() -> bool:
+    version = sys.version_info
+    detail = f"{version.major}.{version.minor}.{version.micro}"
+    if version >= (3, 11):
+        _ok("python", detail)
+        return True
+    _fail("python", f"{detail}; need 3.11 or newer")
+    return False
+
+
+def _check_docker() -> bool:
+    docker = shutil.which("docker")
+    if not docker:
+        _fail("docker", "docker command not found")
+        return False
+    try:
+        result = subprocess.run(
+            [docker, "info"],
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            check=False,
+            timeout=10,
+        )
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        _fail("docker", f"daemon check failed: {exc}")
+        return False
+    if result.returncode == 0:
+        _ok("docker", "daemon reachable")
+        return True
+    _fail("docker", "daemon not reachable")
+    return False
+
+
+def _check_config_dir() -> bool:
+    config = Path.home() / ".bot-bottle"
+    if config.is_dir():
+        _ok("config", str(config))
+        return True
+    _fail("config", f"{config} does not exist")
+    return False
+
+
+def cmd_doctor(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(prog=f"{PROG} doctor", add_help=True)
+    parser.parse_args(argv)
+
+    checks = (
+        _check_python(),
+        _check_docker(),
+        _check_config_dir(),
+    )
+    return 0 if all(checks) else 1
@@ -53,6 +53,7 @@ from ..supervise import (
    TOOL_CAPABILITY_BLOCK,
    TOOL_ALLOW,
    TOOL_EGRESS_BLOCK,
+    TOOL_GITLEAKS_ALLOW,
    archive_proposal,
    list_pending_proposals,
    render_diff,
@@ -140,6 +141,8 @@ def _suffix_for_tool(tool: str) -> str:
        return ".dockerfile"
    if tool in (TOOL_ALLOW, TOOL_EGRESS_BLOCK):
        return ".yaml"
+    if tool == TOOL_GITLEAKS_ALLOW:
+        return ".txt"
    return ".txt"


@@ -201,6 +204,23 @@ def reject(qp: QueuedProposal, *, reason: str) -> None:
    _write_audit(qp, action=STATUS_REJECTED, notes=reason, diff_before="", diff_after="")


+def _approve_from_tui(
+    stdscr: "curses._CursesWindow",  # type: ignore
+    qp: QueuedProposal,
+    *,
+    final_file: str | None = None,
+    notes: str = "",
+) -> str:
+    """Approve from curses, prompting for any tool-specific audit note."""
+    if qp.proposal.tool == TOOL_GITLEAKS_ALLOW and final_file is None:
+        notes = _prompt(stdscr, "allow reason (test fixture/false positive): ")
+        if not notes:
+            return "approve aborted (empty reason)"
+    approve(qp, final_file=final_file, notes=notes)
+    verb = "modified+approved" if final_file is not None else "approved"
+    return _approval_status(qp, verb)
+
+
 def _write_audit(
    qp: QueuedProposal,
    *,
@@ -384,18 +404,22 @@ def _main_loop(stdscr: "curses._CursesWindow") -> None:  # type: ignore
            _detail_view(stdscr, qp, green_attr=green_attr)
        elif key == ord("a"):
            try:
-                approve(qp)
-                status_line = _approval_status(qp, "approved")
+                status_line = _approve_from_tui(stdscr, qp)
            except ApplyError as e:
                status_line = f"apply failed: {e}"
        elif key == ord("m"):
+            if qp.proposal.tool == TOOL_GITLEAKS_ALLOW:
+                status_line = "modify unavailable for gitleaks-allow"
+                continue
            edited = _modify(stdscr, qp)
            if edited is None:
                status_line = "modify aborted (no change)"
            else:
                try:
-                    approve(qp, final_file=edited, notes="operator modified before approving")
-                    status_line = _approval_status(qp, "modified+approved")
+                    status_line = _approve_from_tui(
+                        stdscr, qp, final_file=edited,
+                        notes="operator modified before approving",
+                    )
                except ApplyError as e:
                    status_line = f"apply failed: {e}"
        elif key == ord("r"):
@@ -493,15 +517,20 @@ def _detail_view(
            offset = max(0, len(lines) - 1)
        elif key == ord("a"):
            try:
-                approve(qp)
+                _approve_from_tui(stdscr, qp)
            except ApplyError:
                pass
            return
        elif key == ord("m"):
+            if qp.proposal.tool == TOOL_GITLEAKS_ALLOW:
+                return
            edited = _modify(stdscr, qp)
            if edited is not None:
                try:
-                    approve(qp, final_file=edited, notes="operator modified before approving")
+                    _approve_from_tui(
+                        stdscr, qp, final_file=edited,
+                        notes="operator modified before approving",
+                    )
                except ApplyError:
                    pass
            return
@@ -247,6 +247,164 @@ cat > "$refs_file"

 zero=0000000000000000000000000000000000000000

+supervise_gitleaks_allow() {
+  log_opts=$1
+  ref=$2
+  report_file=$(mktemp)
+  if ! gitleaks git \
+      --log-opts="$log_opts" \
+      --no-banner \
+      --redact \
+      --ignore-gitleaks-allow \
+      --report-format=json \
+      --report-path="$report_file" \
+      --exit-code 0 \
+      1>&2; then
+    rm -f "$report_file"
+    echo "git-gate: gitleaks inline-suppression scan failed for $ref" >&2
+    return 1
+  fi
+
+  proposal_id=$(
+    GITLEAKS_ALLOW_REF="$ref" python3 - "$report_file" <<'PY'
+import datetime
+import hashlib
+import json
+import os
+import sys
+import uuid
+from pathlib import Path
+
+report_path = Path(sys.argv[1])
+queue_dir = os.environ.get("SUPERVISE_QUEUE_DIR", "")
+slug = os.environ.get("SUPERVISE_BOTTLE_SLUG", "")
+if not queue_dir or not slug:
+    sys.exit(2)
+
+try:
+    raw = json.loads(report_path.read_text() or "[]")
+except json.JSONDecodeError:
+    sys.exit(3)
+if not isinstance(raw, list):
+    sys.exit(3)
+if not raw:
+    sys.exit(0)
+
+ref = os.environ.get("GITLEAKS_ALLOW_REF", "")
+lines = [
+    "gitleaks inline suppression requires supervisor approval",
+    f"ref: {ref}",
+    "",
+]
+for i, finding in enumerate(raw, 1):
+    if not isinstance(finding, dict):
+        continue
+    file_path = finding.get("File", "")
+    line_no = finding.get("StartLine", finding.get("Line", ""))
+    rule_id = finding.get("RuleID", "")
+    commit = finding.get("Commit", "")
+    line = finding.get("Line", "")
+    lines.extend([
+        f"finding {i}:",
+        f"  file: {file_path}",
+        f"  line: {line_no}",
+        f"  rule: {rule_id}",
+        f"  commit: {commit}",
+        f"  code: {line}",
+        "",
+    ])
+
+payload = "\n".join(lines).rstrip() + "\n"
+proposal_id = str(uuid.uuid4())
+proposal = {
+    "id": proposal_id,
+    "bottle_slug": slug,
+    "tool": "gitleaks-allow",
+    "proposed_file": payload,
+    "justification": (
+        "git-gate found gitleaks findings hidden by # gitleaks:allow; "
+        "approve only for dummy test fixtures or confirmed false positives"
+    ),
+    "arrival_timestamp": datetime.datetime.now(
+        datetime.timezone.utc
+    ).isoformat(),
+    "current_file_hash": hashlib.sha256(payload.encode("utf-8")).hexdigest(),
+}
+queue = Path(queue_dir)
+queue.mkdir(parents=True, exist_ok=True)
+path = queue / f"{proposal_id}.proposal.json"
+tmp = path.with_suffix(path.suffix + ".tmp")
+with tmp.open("w", encoding="utf-8") as f:
+    json.dump(proposal, f, indent=2)
+    f.write("\n")
+os.chmod(tmp, 0o600)
+os.replace(tmp, path)
+print(proposal_id)
+PY
+  )
+  rc=$?
+  rm -f "$report_file"
+  if [ "$rc" -eq 0 ] && [ -z "$proposal_id" ]; then
+    return 0
+  fi
+  if [ "$rc" -ne 0 ]; then
+    echo "git-gate: cannot route # gitleaks:allow finding to supervisor; refusing push" >&2
+    return 1
+  fi
+
+  queue_dir=${SUPERVISE_QUEUE_DIR:-}
+  response_file="$queue_dir/${proposal_id}.response.json"
+  timeout=${SUPERVISE_GITLEAKS_ALLOW_TIMEOUT_SECONDS:-300}
+  case "$timeout" in
+    ''|*[!0-9]*)
+      echo "git-gate: invalid SUPERVISE_GITLEAKS_ALLOW_TIMEOUT_SECONDS=$timeout" >&2
+      return 1
+      ;;
+  esac
+  echo "git-gate: queued # gitleaks:allow supervisor approval $proposal_id" >&2
+  echo "git-gate: approve with './cli.py supervise' to continue this push" >&2
+  waited=0
+  while [ "$waited" -lt "$timeout" ]; do
+    if [ -f "$response_file" ]; then
+      status=$(python3 - "$response_file" <<'PY'
+import json
+import sys
+try:
+    with open(sys.argv[1], encoding="utf-8") as f:
+        raw = json.load(f)
+except (OSError, json.JSONDecodeError):
+    sys.exit(1)
+status = raw.get("status")
+if not isinstance(status, str):
+    sys.exit(1)
+print(status)
+PY
+      ) || status=""
+      case "$status" in
+        approved|modified)
+          mkdir -p "$queue_dir/processed"
+          mv -f "$queue_dir/${proposal_id}.proposal.json" "$queue_dir/processed/" 2>/dev/null || true
+          mv -f "$queue_dir/${proposal_id}.response.json" "$queue_dir/processed/" 2>/dev/null || true
+          echo "git-gate: supervisor approved # gitleaks:allow for $ref" >&2
+          return 0
+          ;;
+        rejected)
+          echo "git-gate: supervisor rejected # gitleaks:allow for $ref" >&2
+          return 1
+          ;;
+        *)
+          echo "git-gate: invalid supervisor response for # gitleaks:allow" >&2
+          return 1
+          ;;
+      esac
+    fi
+    sleep 1
+    waited=$((waited + 1))
+  done
+  echo "git-gate: supervisor approval timed out for # gitleaks:allow; refusing push" >&2
+  return 1
+}
+
 # Phase 1: gitleaks scan each ref's incoming commits.
 while IFS=' ' read -r old new ref; do
  [ -z "$ref" ] && continue
@@ -268,6 +426,9 @@ while IFS=' ' read -r old new ref; do
    echo "git-gate: gitleaks rejected push to $ref" >&2
    exit 1
  fi
+  if ! supervise_gitleaks_allow "$log_opts" "$ref"; then
+    exit 1
+  fi
 done < "$refs_file"

 # Phase 2: forward each ref to the upstream (`origin`, configured
@@ -19,7 +19,7 @@ Bottle schema (frontmatter):
    repos:      { <name>: <git-gate-entry>, ... }  # optional
  egress: { routes: [ <egress-route>, ... ] }
    # route keys: host, matches, auth, role, dlp
-  supervise:    <bool>                          # optional
+  supervise:    <bool>                          # optional (default true)

 Agent schema (frontmatter):
  bottle:        <bottle-name>          # required
@@ -111,13 +111,13 @@ class ManifestBottle:
    # identity without any git-gate.repos upstreams, and vice versa.
    git_user: ManifestGitUser = field(default_factory=ManifestGitUser)
    egress: ManifestEgressConfig = field(default_factory=ManifestEgressConfig)
-    # Opt-in per-bottle stuck-recovery sidecar (PRD 0013). When true,
-    # the launch step brings up a supervise sidecar that exposes MCP
-    # tools to the agent (egress-block, capability-block) plus mounts
-    # the current-config dir read-only into the agent at
-    # /etc/bot-bottle/current-config. False (the default) skips the
-    # sidecar and mount.
-    supervise: bool = False
+    # Per-bottle stuck-recovery sidecar (PRD 0013). When true (the
+    # default, issue #249), the launch step brings up a supervise
+    # sidecar that exposes MCP tools to the agent (egress-block,
+    # capability-block) plus mounts the current-config dir read-only
+    # into the agent at /etc/bot-bottle/current-config. Set
+    # `supervise: false` to skip the sidecar and mount.
+    supervise: bool = True

    @classmethod
    def from_dict(cls, name: str, raw: object) -> "ManifestBottle":
@@ -190,7 +190,7 @@ class ManifestBottle:
            else ManifestEgressConfig()
        )

-        supervise_raw = d.get("supervise", False)
+        supervise_raw = d.get("supervise", True)
        if not isinstance(supervise_raw, bool):
            raise ManifestError(
                f"bottle '{name}' supervise must be a boolean "
@@ -51,11 +51,13 @@ SUPERVISE_PORT = 9100
 TOOL_CAPABILITY_BLOCK = "capability-block"
 TOOL_EGRESS_BLOCK = "egress-block"
 TOOL_ALLOW = "allow"
+TOOL_GITLEAKS_ALLOW = "gitleaks-allow"
 TOOL_LIST_EGRESS_ROUTES = "list-egress-routes"
 TOOLS: tuple[str, ...] = (
    TOOL_ALLOW,
    TOOL_CAPABILITY_BLOCK,
    TOOL_EGRESS_BLOCK,
+    TOOL_GITLEAKS_ALLOW,
    TOOL_LIST_EGRESS_ROUTES,
 )

@@ -553,6 +555,7 @@ __all__ = [
    "EGRESS_FORWARD_PROXY",
    "EGRESS_INTROSPECT_URL",
    "TOOL_CAPABILITY_BLOCK",
+    "TOOL_GITLEAKS_ALLOW",
    "TOOL_LIST_EGRESS_ROUTES",
    "archive_proposal",
    "audit_dir",
@@ -0,0 +1,159 @@
+# PRD 0060: Commit bottle state to an image
+
+- **Status:** Active
+- **Author:** Claude
+- **Created:** 2026-06-20
+- **Issue:** #194
+
+## Summary
+
+Add a `commit` CLI command that freezes a running bottle's state to a
+resumable local artifact. Docker bottles are stored as Docker images;
+smolmachines bottles are stored as `.smolmachine` artifacts. Operators
+can then resume the bottle from that exact filesystem snapshot, or
+export the artifact to migrate work to a different host.
+
+## Problem
+
+When a long-running agent session is interrupted — by a host reboot, a
+network failure, or a planned infrastructure migration — the in-progress
+container state is lost. `cli.py resume` rebuilds the agent image from
+the Dockerfile and reprovi-sions the bottle, but that returns the guest
+to its initial state, not to wherever the agent was mid-task.
+
+There is no mechanism today to capture "what's installed / configured
+inside the running container right now" and make it reproducible. The
+`capability-block` flow writes a new Dockerfile and marks the bottle for
+resume, but that only applies when the agent itself has requested a
+capability change; it doesn't help the operator who wants to take a
+snapshot before a planned host reboot or hardware migration.
+
+## Goals / Success Criteria
+
+- `./cli.py commit [<slug>]` takes a snapshot of the running agent and
+  stores it as a local artifact.
+- Without a slug argument the command shows the same interactive picker
+  as `start` (the list of active slugs).
+- The committed artifact reference is stored in per-bottle state so
+  that the next `./cli.py resume <slug>` automatically uses the
+  snapshot instead of rebuilding from the Dockerfile.
+- `mark_preserved` is called so the state dir survives the normal
+  session-end cleanup.
+- A backend-specific export hint is printed so operators know how to
+  migrate the snapshot.
+- The command errors clearly on unsupported backends.
+
+## Non-goals
+
+- macOS-container backend support.
+- Automatic commit on agent exit.
+- Image push to a remote registry.
+- Storing the image tag in the manifest or sharing it between operators.
+
+## Design
+
+### Docker image tag
+
+`bot-bottle-committed-<slug>:latest` — namespaced under `bot-bottle-`
+to match existing image naming conventions; `committed` distinguishes it
+from the build-time image (`bot-bottle-claude:latest`) and the
+capability-block rebuild image (`bot-bottle-rebuilt-<identity>:latest`).
+
+### State storage
+
+A new plain-text file `committed-image` is added to the per-bottle state
+directory:
+
+```
+~/.bot-bottle/state/<identity>/
+    metadata.json
+    Dockerfile            (capability-block override; optional)
+    committed-image       (committed artifact reference; optional)
+    transcript/
+```
+
+`bottle_state.committed_image_path(identity)` returns the path.
+`write_committed_image` / `read_committed_image` are the read/write
+helpers, matching the existing `per_bottle_dockerfile` pattern. Docker
+stores a Docker tag in this file; smolmachines stores the absolute path
+to the committed `.smolmachine` artifact.
+
+### `commit` command
+
+```
+./cli.py commit [<slug>]
+```
+
+1. Resolve slug (arg or interactive picker from `enumerate_active_agents`).
+2. Check metadata and branch by backend.
+3. For Docker, derive container name `bot-bottle-<slug>` and run
+   `docker commit <container> bot-bottle-committed-<slug>:latest`.
+4. For smolmachines, derive machine name `bot-bottle-<slug>` and run
+   `smolvm pack create --from-vm <machine> -o ~/.bot-bottle/state/<slug>/committed-smolmachine`.
+5. Write the Docker image tag or smolmachine artifact path to
+   `~/.bot-bottle/state/<slug>/committed-image`.
+6. Call `mark_preserved(<slug>)` so the state dir survives session-end.
+7. Print the resume hint and a backend-specific export example.
+
+### Resume from committed image
+
+`bot_bottle/backend/docker/launch.py` already rebuilds the agent image
+at the top of the `launch` context manager. The change is a check
+immediately before that step:
+
+```python
+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)
+```
+
+Replacing `agent_provision.image` propagates to `plan.image` (a
+property) and from there to the Compose spec renderer's `_agent_service`
+→ `image:` field, so the container boots from the committed snapshot.
+The build step is skipped entirely when a committed image is found and
+exists locally.
+
+If the committed image has been deleted from the local daemon (e.g.
+after `docker rmi` or a `docker system prune`), the launch falls back
+to a normal Dockerfile build, matching the pre-commit behavior.
+
+### Resume from committed smolmachine
+
+`bot_bottle/backend/smolmachines/launch.py` checks the committed
+reference before the normal Docker build -> pack cache path:
+
+```python
+committed = read_committed_image(plan.slug)
+if committed and Path(committed).is_file():
+    return Path(committed)
+return _ensure_smolmachine(plan.agent_image, dockerfile=plan.agent_dockerfile_path)
+```
+
+The returned path is passed to `smolvm machine create --from`, so the
+resumed VM boots from the committed snapshot. If the artifact has been
+deleted, launch falls back to the normal build and pack flow.
+
+## Testing strategy
+
+- Unit tests for `write_committed_image` / `read_committed_image` in
+  `tests/unit/test_bottle_state.py`, using the existing `_FakeHomeMixin`
+  pattern.
+- Unit tests for `commit_container` in `tests/unit/test_docker_util_image.py`,
+  mocking `subprocess.run` and asserting on the `docker commit` argv.
+- Unit tests for `cmd_commit` argument parsing, Docker commit,
+  smolmachines pack, and the unsupported backend error path, mocking
+  `enumerate_active_agents`, `commit_container`, and
+  `pack_create_from_vm`.
+- Unit tests for the launch-step committed-image branch: patch
+  `read_committed_image` to return a tag, patch `image_exists` to return
+  True, and assert that `build_image` is not called and `plan.image` is
+  overridden.
+- Unit tests for the smolmachines launch-step committed-artifact branch:
+  patch `read_committed_image` to return an existing path and assert the
+  normal `_ensure_smolmachine` path is skipped.
@@ -0,0 +1,101 @@
+# PRD 0061: Gitleaks inline suppression supervision
+
+- **Status:** Active
+- **Author:** codex
+- **Created:** 2026-06-10
+- **Issue:** #208
+
+## Summary
+
+Route every `# gitleaks:allow` inline suppression through the existing
+supervisor approval queue before git-gate forwards a push upstream. The
+annotation remains available for test fixtures and confirmed false positives,
+but it no longer lets an agent silently bypass the gate's secret scan.
+
+## Problem
+
+Gitleaks supports inline suppression comments. With the default behaviour,
+a pushed line that contains a secret-like value and `# gitleaks:allow` is
+ignored by gitleaks and accepted by git-gate. That is convenient for dummy
+credentials in tests, but it also gives an agent a one-line bypass for a real
+secret. Once the commit lands, the diff alone cannot prove whether the
+suppression was legitimate.
+
+## Goals / Success Criteria
+
+1. Git-gate continues to run the normal gitleaks scan for every incoming ref.
+2. After the normal scan passes, git-gate runs a second scan with
+   `--ignore-gitleaks-allow` and a JSON report so suppressed findings become
+   visible.
+3. If that second scan reports no suppressed findings, the push proceeds
+   unchanged.
+4. If it reports suppressed findings, git-gate creates a `gitleaks-allow`
+   supervisor proposal containing the ref, file path, line number, rule,
+   commit, and flagged line for each finding.
+5. The push proceeds only when the supervisor explicitly approves the
+   proposal; rejection, malformed responses, missing supervisor configuration,
+   and timeout all refuse the push.
+6. The supervisor TUI requires a reason when approving a `gitleaks-allow`
+   proposal, so the audit trail records whether the approval was for a test
+   fixture or a false positive.
+
+## Non-goals
+
+- Replacing gitleaks or changing the main secret-detection rule set.
+- Removing support for `# gitleaks:allow`.
+- Automatically classifying fixture files or false positives.
+- Adding new supervisor transport or authentication mechanisms.
+
+## Design
+
+### Git-gate flow
+
+`git_gate_render_hook()` emits a `supervise_gitleaks_allow` shell helper.
+For each incoming ref, git-gate first runs the existing gitleaks command. If
+that scan passes, it runs:
+
+```sh
+gitleaks git \
+  --log-opts="$log_opts" \
+  --no-banner \
+  --redact \
+  --ignore-gitleaks-allow \
+  --report-format=json \
+  --report-path="$report_file" \
+  --exit-code 0
+```
+
+The second pass keeps the push path non-interactive while producing a report
+of findings that would otherwise have been hidden by inline suppression.
+
+### Supervisor proposal
+
+When the JSON report contains findings, an embedded Python helper writes a
+proposal into `SUPERVISE_QUEUE_DIR` using the existing proposal schema. The
+proposal uses:
+
+- `tool: "gitleaks-allow"`
+- a text payload with the ref and each finding's file, line, rule, commit,
+  and redacted code line
+- a justification that tells the operator to approve only dummy test fixtures
+  or confirmed false positives
+
+Git-gate then waits for `<proposal-id>.response.json` for
+`SUPERVISE_GITLEAKS_ALLOW_TIMEOUT_SECONDS`, defaulting to 300 seconds.
+`approved` and `modified` responses allow the push; `rejected`, invalid
+responses, invalid timeout configuration, or timeout refuse it.
+
+### Supervisor UI
+
+`TOOL_GITLEAKS_ALLOW` is added to the supervisor tool registry. The curses
+supervisor renders the proposal as text and allows approval or rejection.
+Modification is unavailable for this proposal type because there is no file
+patch to apply. Approval from the TUI prompts for a non-empty reason and
+writes that reason to the response/audit path.
+
+### Tests
+
+Unit tests assert that the rendered git-gate hook includes the second gitleaks
+pass, supervisor queue fields, and fail-closed messages. Supervisor tests cover
+the new tool constant, proposal archiving, and the required TUI approval
+reason.
@@ -0,0 +1,75 @@
+# PRD prd-new: Install script
+
+- **Status:** Active
+- **Author:** didericis
+- **Created:** 2026-06-06
+- **Issue:** #197
+
+## Summary
+
+Add a proper Python package distribution and a thin `install.sh` bootstrapper so users can install bot-bottle with a single command without cloning the repo.
+
+## Problem
+
+There is currently no install path for new users. The only way to run bot-bottle is to clone the repo and invoke `cli.py` directly. This blocks any HN-style public demo: readers want `curl | sh` or `pipx install`, not a manual clone-and-configure flow.
+
+## Goals / Success Criteria
+
+- `curl -fsSL <url>/install.sh | sh` (or equivalent) leaves a working `bot-bottle` command on PATH.
+- Python-native users can install with `pipx install bot-bottle` or `uv tool install bot-bottle`.
+- `install.sh` validates prerequisites (Python ≥ 3.11, Docker) and exits with a clear message if they are missing. It does not silently install Docker.
+- `install.sh` runs `bot-bottle doctor` (or equivalent diagnostic) after install to confirm the environment is ready.
+- The package has no runtime pip dependencies (stdlib-only, matching the existing constraint).
+
+## Non-goals
+
+- Bundling a Python runtime or producing a standalone binary.
+- Automatic Docker installation.
+- Plugin architecture changes (out of scope; see issue #197 for future direction).
+- Publishing to PyPI in this PR — the package structure is the deliverable; publishing is a separate step.
+
+## Design
+
+### Package structure
+
+Add a minimal `pyproject.toml` at the repo root:
+
+```toml
+[project]
+name = "bot-bottle"
+version = "0.1.0"
+requires-python = ">=3.11"
+dependencies = []
+
+[project.scripts]
+bot-bottle = "bot_bottle.cli:main"
+```
+
+The existing `bot_bottle/` package and `cli.py` entry point already contain the logic; this just wires up the standard entry point. `cli.py` may need a small refactor to expose a `main()` callable if it uses `if __name__ == "__main__"` only.
+
+### `install.sh`
+
+A thin bootstrapper that:
+
+1. Checks `python3 --version` ≥ 3.11; exits with instructions if not met.
+2. Checks `docker info` exits 0; exits with instructions if Docker is not running.
+3. Installs via `pipx` if available, otherwise falls back to `pip install --user`.
+4. Runs `bot-bottle doctor` to verify the install.
+
+The script must be idempotent (safe to re-run) and must not require `sudo`.
+
+### `bot-bottle doctor`
+
+A new subcommand that checks and reports:
+
+- Python version.
+- Docker daemon reachability.
+- Whether `~/.bot-bottle/` config directory exists.
+
+Exits 0 if all checks pass, non-zero otherwise.
+
+## Decisions
+
+- `install.sh` is hosted from the repo's raw Gitea URL for now:
+  `https://gitea.dideric.is/didericis/bot-bottle/raw/branch/main/install.sh`.
+- Should `version` in `pyproject.toml` be driven by a git tag at build time (e.g. via `hatch-vcs`) or kept as a static string? Static is simpler for now.
@@ -1,14 +1,14 @@
 ---
 agent_provider:
  template: claude
-
-egress:
-  routes:
-    - host: api.anthropic.com
-      role: claude_code_oauth
-      auth:
-        scheme: Bearer
-        token_ref: BOT_BOTTLE_CLAUDE_OAUTH_TOKEN
+  # auth_token names the host env var holding the Claude OAuth token. The
+  # provider injects a provider-owned api.anthropic.com egress route that
+  # re-injects this token as the Bearer header; the agent only ever sees a
+  # placeholder CLAUDE_CODE_OAUTH_TOKEN. DLP defaults (token_patterns,
+  # known_secrets outbound; naive_injection_detection inbound) apply to
+  # that route. To scan additional hosts, declare them under egress.routes
+  # with per-route matches/dlp (see README "Egress route fields").
+  auth_token: BOT_BOTTLE_CLAUDE_OAUTH_TOKEN
 ---

 Common Claude provider boundary. Drop this file into
@@ -0,0 +1,50 @@
+#!/bin/sh
+set -eu
+
+PACKAGE_SPEC="${BOT_BOTTLE_INSTALL_SPEC:-git+https://gitea.dideric.is/didericis/bot-bottle.git}"
+MIN_PYTHON="3.11"
+
+say() {
+    printf 'bot-bottle install: %s\n' "$*" >&2
+}
+
+die() {
+    say "error: $*"
+    exit 1
+}
+
+command -v python3 >/dev/null 2>&1 || die "python3 is required (version ${MIN_PYTHON} or newer)"
+
+python3 - <<'PY' || die "python3 3.11 or newer is required"
+import sys
+
+raise SystemExit(0 if sys.version_info >= (3, 11) else 1)
+PY
+
+command -v docker >/dev/null 2>&1 || die "Docker is required; install Docker and start the daemon, then re-run this script"
+docker info >/dev/null 2>&1 || die "Docker is installed but the daemon is not reachable; start Docker and re-run this script"
+
+mkdir -p \
+    "${HOME}/.bot-bottle/agents" \
+    "${HOME}/.bot-bottle/bottles" \
+    "${HOME}/.bot-bottle/contrib"
+
+if command -v pipx >/dev/null 2>&1; then
+    say "installing with pipx"
+    pipx install --force "${PACKAGE_SPEC}"
+else
+    say "pipx not found; installing with python3 -m pip --user"
+    python3 -m pip install --user --upgrade "${PACKAGE_SPEC}"
+fi
+
+if command -v bot-bottle >/dev/null 2>&1; then
+    BOT_BOTTLE_BIN="bot-bottle"
+elif [ -x "${HOME}/.local/bin/bot-bottle" ]; then
+    BOT_BOTTLE_BIN="${HOME}/.local/bin/bot-bottle"
+    say "using ${BOT_BOTTLE_BIN}; add ${HOME}/.local/bin to PATH for future shells"
+else
+    die "bot-bottle was installed but is not on PATH"
+fi
+
+say "running bot-bottle doctor"
+"${BOT_BOTTLE_BIN}" doctor
@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "bot-bottle"
+version = "0.1.0"
+description = "Self-hosted sandbox for AI coding agents with egress controls"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "Apache-2.0" }
+dependencies = []
+
+[project.scripts]
+bot-bottle = "bot_bottle.cli:main"
+
+[tool.setuptools.packages.find]
+include = ["bot_bottle*"]
+
+[tool.setuptools.package-data]
+bot_bottle = [
+    "Dockerfile.sidecars",
+    "egress_entrypoint.sh",
+    "contrib/claude/Dockerfile",
+    "contrib/codex/Dockerfile",
+    "contrib/pi/Dockerfile",
+]
@@ -0,0 +1,216 @@
+"""Unit: Freezer class hierarchy."""
+
+from __future__ import annotations
+
+import tempfile
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+
+from bot_bottle import supervise, bottle_state
+from bot_bottle.backend import ActiveAgent
+from bot_bottle.backend.freeze import get_freezer
+from bot_bottle.backend.docker.freezer import DockerFreezer
+from bot_bottle.backend.macos_container.freezer import MacosContainerFreezer
+from bot_bottle.backend.smolmachines.freezer import SmolmachinesFreezer
+
+
+class _FakeHomeMixin:
+    def _setup_fake_home(self):
+        self._tmp = tempfile.TemporaryDirectory(prefix="freezer-test.")
+        original = supervise.bot_bottle_root
+
+        def fake_root() -> Path:
+            return Path(self._tmp.name) / ".bot-bottle"
+
+        supervise.bot_bottle_root = fake_root  # type: ignore[assignment]
+        self._restore = lambda: setattr(supervise, "bot_bottle_root", original)
+
+    def _teardown_fake_home(self):
+        self._restore()
+        self._tmp.cleanup()
+
+
+def _make_agent(slug: str, backend: str = "docker") -> ActiveAgent:
+    return ActiveAgent(
+        backend_name=backend,
+        slug=slug,
+        agent_name="dev",
+        started_at="t",
+        services=(),
+    )
+
+
+class TestGetFreezer(unittest.TestCase):
+    def test_docker(self):
+        self.assertIsInstance(get_freezer("docker"), DockerFreezer)
+
+    def test_empty_backend_gives_docker(self):
+        self.assertIsInstance(get_freezer(""), DockerFreezer)
+
+    def test_macos_container(self):
+        self.assertIsInstance(get_freezer("macos-container"), MacosContainerFreezer)
+
+    def test_smolmachines(self):
+        self.assertIsInstance(get_freezer("smolmachines"), SmolmachinesFreezer)
+
+    def test_unknown_backend_dies(self):
+        with patch("bot_bottle.backend.freeze.die", side_effect=SystemExit("die")):
+            with self.assertRaises(SystemExit):
+                get_freezer("unknown-backend")
+
+
+class TestFreezerBaseCommit(_FakeHomeMixin, unittest.TestCase):
+    """The base Freezer.commit() owns the shared post-freeze steps."""
+
+    def setUp(self):
+        self._setup_fake_home()
+
+    def tearDown(self):
+        self._teardown_fake_home()
+
+    def test_writes_committed_image_and_marks_preserved(self):
+        slug = "dev-abc12"
+        bottle_state.write_metadata(bottle_state.BottleMetadata(
+            identity=slug, agent_name="dev", cwd="", copy_cwd=False,
+            started_at="t", backend="docker",
+        ))
+        freezer = get_freezer("docker")
+        agent = _make_agent(slug)
+
+        with patch.object(freezer, "_freeze", return_value="bot-bottle-committed-dev-abc12:latest"), \
+             patch("bot_bottle.backend.freeze.info"):
+            freezer.commit(agent)
+
+        self.assertEqual(
+            "bot-bottle-committed-dev-abc12:latest",
+            bottle_state.read_committed_image(slug),
+        )
+        self.assertTrue(bottle_state.is_preserved(slug))
+
+    def test_commit_slug_passes_correct_slug_to_freeze(self):
+        slug = "dev-abc12"
+        bottle_state.write_metadata(bottle_state.BottleMetadata(
+            identity=slug, agent_name="dev", cwd="", copy_cwd=False,
+            started_at="t", backend="docker",
+        ))
+        freezer = get_freezer("docker")
+        captured = {}
+
+        def capture_freeze(agent: ActiveAgent) -> str:
+            captured["slug"] = agent.slug
+            return "some-ref"
+
+        with patch.object(freezer, "_freeze", side_effect=capture_freeze), \
+             patch("bot_bottle.backend.freeze.info"):
+            freezer.commit_slug(slug)
+
+        self.assertEqual(slug, captured["slug"])
+
+
+class TestDockerFreezer(_FakeHomeMixin, unittest.TestCase):
+    def setUp(self):
+        self._setup_fake_home()
+
+    def tearDown(self):
+        self._teardown_fake_home()
+
+    def test_commits_container_and_records_image(self):
+        slug = "dev-abc12"
+        bottle_state.write_metadata(bottle_state.BottleMetadata(
+            identity=slug, agent_name="dev", cwd="", copy_cwd=False,
+            started_at="t", backend="docker",
+        ))
+        freezer = DockerFreezer()
+        agent = _make_agent(slug)
+
+        with patch("bot_bottle.backend.docker.freezer.commit_container") as mock_commit, \
+             patch("bot_bottle.backend.freeze.info"), \
+             patch("bot_bottle.backend.docker.freezer.info"):
+            freezer.commit(agent)
+
+        mock_commit.assert_called_once_with(
+            f"bot-bottle-{slug}",
+            f"bot-bottle-committed-{slug}:latest",
+        )
+        self.assertEqual(
+            f"bot-bottle-committed-{slug}:latest",
+            bottle_state.read_committed_image(slug),
+        )
+        self.assertTrue(bottle_state.is_preserved(slug))
+
+
+class TestMacosContainerFreezer(_FakeHomeMixin, unittest.TestCase):
+    def setUp(self):
+        self._setup_fake_home()
+
+    def tearDown(self):
+        self._teardown_fake_home()
+
+    def _write_meta(self, slug: str) -> None:
+        bottle_state.write_metadata(bottle_state.BottleMetadata(
+            identity=slug, agent_name="dev", cwd="", copy_cwd=False,
+            started_at="t", backend="macos-container",
+        ))
+
+    def test_commits_running_container_without_stopping(self):
+        """Commit should exec-tar the running container, not stop it."""
+        slug = "dev-abc12"
+        self._write_meta(slug)
+        freezer = MacosContainerFreezer()
+        agent = _make_agent(slug, "macos-container")
+
+        with patch("bot_bottle.backend.macos_container.freezer.commit_container") as mock_commit, \
+             patch("bot_bottle.backend.freeze.info"), \
+             patch("bot_bottle.backend.macos_container.freezer.info"):
+            freezer.commit(agent)
+
+        mock_commit.assert_called_once_with(
+            f"bot-bottle-{slug}",
+            f"bot-bottle-committed-{slug}:latest",
+        )
+        self.assertEqual(
+            f"bot-bottle-committed-{slug}:latest",
+            bottle_state.read_committed_image(slug),
+        )
+        self.assertTrue(bottle_state.is_preserved(slug))
+
+
+class TestSmolmachinesFreezer(_FakeHomeMixin, unittest.TestCase):
+    def setUp(self):
+        self._setup_fake_home()
+
+    def tearDown(self):
+        self._teardown_fake_home()
+
+    def _write_meta(self, slug: str) -> None:
+        bottle_state.write_metadata(bottle_state.BottleMetadata(
+            identity=slug, agent_name="dev", cwd="", copy_cwd=False,
+            started_at="t", backend="smolmachines",
+        ))
+
+    def test_snapshots_running_vm_without_stopping(self):
+        """Commit should exec-tar the running VM, not stop it."""
+        slug = "dev-abc12"
+        self._write_meta(slug)
+        freezer = SmolmachinesFreezer()
+        agent = _make_agent(slug, "smolmachines")
+
+        with patch("bot_bottle.backend.smolmachines.freezer._snapshot_running_vm") as mock_snap, \
+             patch("bot_bottle.backend.freeze.info"), \
+             patch("bot_bottle.backend.smolmachines.freezer.info"):
+            freezer.commit(agent)
+
+        expected_binary = bottle_state.bottle_state_dir(slug) / "committed-smolmachine"
+        mock_snap.assert_called_once_with(
+            f"bot-bottle-{slug}",
+            f"bot-bottle-committed-{slug}:latest",
+            expected_binary,
+        )
+        expected_sidecar = str(expected_binary.with_suffix(".smolmachine"))
+        self.assertEqual(expected_sidecar, bottle_state.read_committed_image(slug))
+        self.assertTrue(bottle_state.is_preserved(slug))
+
+
+if __name__ == "__main__":
+    unittest.main()
@@ -277,5 +277,56 @@ class TestBottleMetadataBackend(_FakeHomeMixin, unittest.TestCase):
        self.assertEqual("", loaded.backend)


+class TestCommittedImage(_FakeHomeMixin, unittest.TestCase):
+    """write_committed_image / read_committed_image round-trip."""
+
+    def setUp(self):
+        self._setup_fake_home()
+
+    def tearDown(self):
+        self._teardown_fake_home()
+
+    def test_returns_none_when_absent(self):
+        self.assertIsNone(bottle_state.read_committed_image("dev"))
+
+    def test_write_then_read_roundtrip(self):
+        bottle_state.write_committed_image("dev", "bot-bottle-committed-dev:latest")
+        self.assertEqual(
+            "bot-bottle-committed-dev:latest",
+            bottle_state.read_committed_image("dev"),
+        )
+
+    def test_strips_trailing_newline_on_read(self):
+        path = bottle_state.committed_image_path("dev")
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text("bot-bottle-committed-dev:latest\n\n")
+        self.assertEqual(
+            "bot-bottle-committed-dev:latest",
+            bottle_state.read_committed_image("dev"),
+        )
+
+    def test_isolated_per_slug(self):
+        bottle_state.write_committed_image("dev", "bot-bottle-committed-dev:latest")
+        bottle_state.write_committed_image("api", "bot-bottle-committed-api:latest")
+        self.assertEqual(
+            "bot-bottle-committed-dev:latest",
+            bottle_state.read_committed_image("dev"),
+        )
+        self.assertEqual(
+            "bot-bottle-committed-api:latest",
+            bottle_state.read_committed_image("api"),
+        )
+
+    def test_path_under_state_dir(self):
+        path = bottle_state.committed_image_path("dev")
+        self.assertTrue(str(path).endswith("/.bot-bottle/state/dev/committed-image"))
+
+    def test_empty_content_returns_none(self):
+        path = bottle_state.committed_image_path("dev")
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text("   \n")
+        self.assertIsNone(bottle_state.read_committed_image("dev"))
+
+
 if __name__ == "__main__":
    unittest.main()
@@ -0,0 +1,143 @@
+"""Unit: cli.py commit command."""
+
+from __future__ import annotations
+
+import tempfile
+import unittest
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+from bot_bottle.cli.commit import cmd_commit
+from bot_bottle import supervise
+from bot_bottle import bottle_state
+from bot_bottle.backend.freeze import CommitCancelled
+
+
+class _FakeHomeMixin:
+    def _setup_fake_home(self):
+        self._tmp = tempfile.TemporaryDirectory(prefix="cli-commit-test.")
+        original = supervise.bot_bottle_root
+
+        def fake_root() -> Path:
+            return Path(self._tmp.name) / ".bot-bottle"
+
+        supervise.bot_bottle_root = fake_root  # type: ignore[assignment]
+        self._restore = lambda: setattr(supervise, "bot_bottle_root", original)
+
+    def _teardown_fake_home(self):
+        self._restore()
+        self._tmp.cleanup()
+
+
+class TestCmdCommitSlugArg(_FakeHomeMixin, unittest.TestCase):
+    """cmd_commit with an explicit slug delegates to get_freezer."""
+
+    def setUp(self):
+        self._setup_fake_home()
+
+    def tearDown(self):
+        self._teardown_fake_home()
+
+    def _write_meta(self, slug: str, backend: str) -> None:
+        bottle_state.write_metadata(bottle_state.BottleMetadata(
+            identity=slug, agent_name="dev", cwd="", copy_cwd=False,
+            started_at="t", backend=backend,
+        ))
+
+    def test_commits_docker_bottle(self):
+        slug = "dev-abc12"
+        self._write_meta(slug, "docker")
+
+        with patch("bot_bottle.cli.commit.get_freezer") as mock_gf:
+            mock_freezer = MagicMock()
+            mock_gf.return_value = mock_freezer
+            rc = cmd_commit([slug])
+
+        self.assertEqual(0, rc)
+        mock_gf.assert_called_once_with("docker")
+        mock_freezer.commit_slug.assert_called_once_with(slug)
+
+    def test_empty_backend_passed_to_get_freezer(self):
+        """Old state dirs without a backend field pass '' to get_freezer."""
+        slug = "dev-abc12"
+        self._write_meta(slug, "")
+
+        with patch("bot_bottle.cli.commit.get_freezer") as mock_gf:
+            mock_freezer = MagicMock()
+            mock_gf.return_value = mock_freezer
+            rc = cmd_commit([slug])
+
+        self.assertEqual(0, rc)
+        mock_gf.assert_called_once_with("")
+
+    def test_commits_macos_container_bottle(self):
+        slug = "dev-abc12"
+        self._write_meta(slug, "macos-container")
+
+        with patch("bot_bottle.cli.commit.get_freezer") as mock_gf:
+            mock_freezer = MagicMock()
+            mock_gf.return_value = mock_freezer
+            rc = cmd_commit([slug])
+
+        self.assertEqual(0, rc)
+        mock_gf.assert_called_once_with("macos-container")
+        mock_freezer.commit_slug.assert_called_once_with(slug)
+
+    def test_commits_smolmachines_bottle(self):
+        slug = "dev-abc12"
+        self._write_meta(slug, "smolmachines")
+
+        with patch("bot_bottle.cli.commit.get_freezer") as mock_gf:
+            mock_freezer = MagicMock()
+            mock_gf.return_value = mock_freezer
+            rc = cmd_commit([slug])
+
+        self.assertEqual(0, rc)
+        mock_gf.assert_called_once_with("smolmachines")
+
+    def test_returns_zero_on_commit_cancelled(self):
+        slug = "dev-abc12"
+        self._write_meta(slug, "macos-container")
+
+        with patch("bot_bottle.cli.commit.get_freezer") as mock_gf:
+            mock_freezer = MagicMock()
+            mock_freezer.commit_slug.side_effect = CommitCancelled
+            mock_gf.return_value = mock_freezer
+            rc = cmd_commit([slug])
+
+        self.assertEqual(0, rc)
+
+
+class TestCmdCommitNoActiveBottles(_FakeHomeMixin, unittest.TestCase):
+    def setUp(self):
+        self._setup_fake_home()
+
+    def tearDown(self):
+        self._teardown_fake_home()
+
+    def test_dies_when_no_active_bottles_and_no_slug(self):
+        with patch(
+            "bot_bottle.cli.commit.enumerate_active_agents", return_value=[],
+        ), patch(
+            "bot_bottle.cli.commit.die", side_effect=SystemExit("die"),
+        ) as mock_die:
+            with self.assertRaises(SystemExit):
+                cmd_commit([])
+
+        mock_die.assert_called_once()
+
+    def test_returns_zero_when_picker_cancelled(self):
+        active = MagicMock()
+        active.slug = "dev-abc12"
+        with patch(
+            "bot_bottle.cli.commit.enumerate_active_agents", return_value=[active],
+        ), patch(
+            "bot_bottle.cli.commit.tui.filter_select", return_value=None,
+        ):
+            rc = cmd_commit([])
+
+        self.assertEqual(0, rc)
+
+
+if __name__ == "__main__":
+    unittest.main()
@@ -0,0 +1,51 @@
+"""Unit: `bot-bottle doctor` host prerequisite checks."""
+
+from __future__ import annotations
+
+import tempfile
+import unittest
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+from bot_bottle.cli import doctor
+
+
+class TestDoctor(unittest.TestCase):
+    def test_success_when_prerequisites_present(self):
+        with tempfile.TemporaryDirectory() as tmp, patch.object(
+            doctor.Path, "home", return_value=Path(tmp),
+        ), patch.object(
+            doctor.shutil, "which", return_value="/usr/bin/docker",
+        ), patch.object(
+            doctor.subprocess, "run",
+            return_value=MagicMock(returncode=0),
+        ):
+            Path(tmp, ".bot-bottle").mkdir()
+            self.assertEqual(0, doctor.cmd_doctor([]))
+
+    def test_missing_config_fails(self):
+        with tempfile.TemporaryDirectory() as tmp, patch.object(
+            doctor.Path, "home", return_value=Path(tmp),
+        ), patch.object(
+            doctor.shutil, "which", return_value="/usr/bin/docker",
+        ), patch.object(
+            doctor.subprocess, "run",
+            return_value=MagicMock(returncode=0),
+        ):
+            self.assertEqual(1, doctor.cmd_doctor([]))
+
+    def test_missing_docker_fails_before_daemon_check(self):
+        with tempfile.TemporaryDirectory() as tmp, patch.object(
+            doctor.Path, "home", return_value=Path(tmp),
+        ), patch.object(
+            doctor.shutil, "which", return_value=None,
+        ), patch.object(
+            doctor.subprocess, "run",
+        ) as run:
+            Path(tmp, ".bot-bottle").mkdir()
+            self.assertEqual(1, doctor.cmd_doctor([]))
+            run.assert_not_called()
+
+
+if __name__ == "__main__":
+    unittest.main()
@@ -301,6 +301,19 @@ class TestSidecarBundleShape(unittest.TestCase):
        self.assertEqual("bot-bottle-sidecars:latest", sc["image"])
        self.assertEqual("Dockerfile.sidecars", sc["build"]["dockerfile"])

+    def test_bundle_uses_packaged_dockerfile_when_root_missing(self):
+        from bot_bottle.backend.docker import compose as compose_mod
+
+        original = compose_mod._REPO_DIR
+        try:
+            compose_mod._REPO_DIR = "/tmp/does-not-exist"
+            self.assertEqual(
+                "bot_bottle/Dockerfile.sidecars",
+                compose_mod._sidecar_bundle_dockerfile(),
+            )
+        finally:
+            compose_mod._REPO_DIR = original
+
    def test_bundle_container_name_uses_sidecars_prefix(self):
        sc = self._render()["services"]["sidecars"]
        self.assertEqual(f"bot-bottle-sidecars-{SLUG}", sc["container_name"])
@@ -0,0 +1,192 @@
+"""Unit: Docker launch step uses committed image when available."""
+
+from __future__ import annotations
+
+import contextlib
+import io
+import tempfile
+import unittest
+from pathlib import Path
+from typing import Any
+from unittest import mock
+
+from bot_bottle.agent_provider import AgentProvisionPlan
+from bot_bottle.backend import BottleSpec
+from bot_bottle.backend.docker import launch as launch_mod
+from bot_bottle.backend.docker.bottle_plan import DockerBottlePlan
+from bot_bottle.egress import EgressPlan
+from bot_bottle.git_gate import GitGatePlan
+from bot_bottle.manifest import ManifestIndex
+
+
+_SLUG = "dev-abc12"
+_COMMITTED_TAG = f"bot-bottle-committed-{_SLUG}:latest"
+_DEFAULT_IMAGE = "bot-bottle-claude:latest"
+
+_IDX = ManifestIndex.from_json_obj({
+    "bottles": {"dev": {}},
+    "agents": {"demo": {"skills": [], "prompt": "", "bottle": "dev"}},
+})
+
+
+def _plan(tmp: str) -> DockerBottlePlan:
+    stage = Path(tmp)
+    spec = BottleSpec(
+        manifest=_IDX,
+        agent_name="demo",
+        copy_cwd=False,
+        user_cwd=tmp,
+        identity=_SLUG,
+    )
+    return DockerBottlePlan(
+        spec=spec,
+        manifest=_IDX.load_for_agent("demo"),
+        stage_dir=stage,
+        git_gate_plan=GitGatePlan(
+            slug=_SLUG,
+            entrypoint_script=stage / "entrypoint.sh",
+            hook_script=stage / "hook.sh",
+            access_hook_script=stage / "access-hook.sh",
+            upstreams=(),
+        ),
+        egress_plan=EgressPlan(
+            slug=_SLUG,
+            routes_path=stage / "egress.yaml",
+            routes=(),
+            token_env_map={},
+        ),
+        supervise_plan=None,
+        agent_provision=AgentProvisionPlan(
+            template="claude",
+            command="claude",
+            prompt_mode="append_file",
+            image=_DEFAULT_IMAGE,
+            dockerfile="",
+            guest_home="/home/node",
+            instance_name=f"bot-bottle-{_SLUG}",
+            prompt_file=stage / "prompt.txt",
+            guest_env={},
+        ),
+        slug=_SLUG,
+        forwarded_env={},
+        use_runsc=False,
+    )
+
+
+class TestLaunchCommittedImage(unittest.TestCase):
+    def setUp(self) -> None:
+        self._tmp = tempfile.mkdtemp(prefix="launch-committed-test.")
+
+    def tearDown(self) -> None:
+        import shutil
+        shutil.rmtree(self._tmp, ignore_errors=True)
+
+    def _run_launch(
+        self,
+        plan: DockerBottlePlan,
+        *,
+        committed_tag: str | None = None,
+        image_present: bool = True,
+    ) -> list[str]:
+        """Drive launch() through its full sequence with the committed-image
+        behaviour controlled by the arguments. Returns the images that were
+        passed to `build_image` (empty list if it was never called)."""
+        built: list[str] = []
+
+        def fake_build(image: str, ctx: str, *, dockerfile: str = "") -> None:
+            del ctx, dockerfile
+            built.append(image)
+
+        with mock.patch.object(
+            launch_mod, "read_committed_image", return_value=committed_tag,
+        ), mock.patch.object(
+            launch_mod.docker_mod, "image_exists", return_value=image_present,
+        ), mock.patch.object(
+            launch_mod.docker_mod, "build_image", side_effect=fake_build,
+        ), mock.patch.object(
+            launch_mod, "egress_tls_init",
+            return_value=(Path("/egress_ca"), Path("/egress_cert")),
+        ), mock.patch.object(
+            launch_mod.network_mod, "network_name_for_slug",
+            return_value="bb-internal",
+        ), mock.patch.object(
+            launch_mod.network_mod, "network_egress_name_for_slug",
+            return_value="bb-egress",
+        ), mock.patch.object(
+            launch_mod, "bottle_plan_to_compose",
+            return_value={"services": {"agent": {}}},
+        ), 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_dump_logs"), \
+           mock.patch.object(launch_mod, "compose_down"), \
+           contextlib.redirect_stderr(io.StringIO()):
+            provision = mock.Mock(return_value=None)
+            with launch_mod.launch(plan, provision=provision):
+                pass
+
+        return built
+
+    def test_skips_build_when_committed_image_present(self) -> None:
+        plan = _plan(self._tmp)
+        built = self._run_launch(plan, committed_tag=_COMMITTED_TAG, image_present=True)
+        self.assertEqual([], built, "build_image should not be called when committed image exists")
+
+    def test_uses_committed_image_in_compose_spec(self) -> None:
+        """The compose spec renderer receives the committed image tag via
+        plan.image — captured here by checking what bottle_plan_to_compose
+        was called with."""
+        plan = _plan(self._tmp)
+        captured_plans: list[DockerBottlePlan] = []
+
+        def fake_compose(p: DockerBottlePlan) -> dict[str, Any]:
+            captured_plans.append(p)
+            return {"services": {"agent": {}}}
+
+        with mock.patch.object(
+            launch_mod, "read_committed_image", return_value=_COMMITTED_TAG,
+        ), mock.patch.object(
+            launch_mod.docker_mod, "image_exists", return_value=True,
+        ), mock.patch.object(
+            launch_mod.docker_mod, "build_image",
+        ), mock.patch.object(
+            launch_mod, "egress_tls_init",
+            return_value=(Path("/egress_ca"), Path("/egress_cert")),
+        ), mock.patch.object(
+            launch_mod.network_mod, "network_name_for_slug",
+            return_value="bb-internal",
+        ), mock.patch.object(
+            launch_mod.network_mod, "network_egress_name_for_slug",
+            return_value="bb-egress",
+        ), mock.patch.object(
+            launch_mod, "bottle_plan_to_compose", side_effect=fake_compose,
+        ), 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_dump_logs"), \
+           mock.patch.object(launch_mod, "compose_down"), \
+           contextlib.redirect_stderr(io.StringIO()):
+            provision = mock.Mock(return_value=None)
+            with launch_mod.launch(plan, provision=provision):
+                pass
+
+        self.assertEqual(1, len(captured_plans))
+        self.assertEqual(_COMMITTED_TAG, captured_plans[0].image)
+
+    def test_falls_back_to_build_when_no_committed_image(self) -> None:
+        plan = _plan(self._tmp)
+        built = self._run_launch(plan, committed_tag=None)
+        self.assertEqual([_DEFAULT_IMAGE], built)
+
+    def test_falls_back_to_build_when_committed_image_missing_from_daemon(self) -> None:
+        plan = _plan(self._tmp)
+        built = self._run_launch(
+            plan, committed_tag=_COMMITTED_TAG, image_present=False,
+        )
+        self.assertEqual([_DEFAULT_IMAGE], built)
+
+
+if __name__ == "__main__":
+    unittest.main()
@@ -67,5 +67,46 @@ class TestSave(unittest.TestCase):
        )


+class TestCommitContainer(unittest.TestCase):
+    def test_runs_docker_commit(self):
+        with patch.object(
+            docker_mod.subprocess, "run", return_value=_ok(),
+        ) as run, patch.object(docker_mod, "info"):
+            docker_mod.commit_container(
+                "bot-bottle-dev-abc12",
+                "bot-bottle-committed-dev-abc12:latest",
+            )
+        argv = run.call_args.args[0]
+        self.assertEqual(
+            [
+                "docker", "commit",
+                "bot-bottle-dev-abc12",
+                "bot-bottle-committed-dev-abc12:latest",
+            ],
+            argv,
+        )
+
+    def test_dies_on_docker_commit_failure(self):
+        with patch.object(
+            docker_mod.subprocess, "run", return_value=_fail("No such container"),
+        ), patch.object(
+            docker_mod, "die", side_effect=SystemExit("die"),
+        ) as die:
+            with self.assertRaises(SystemExit):
+                docker_mod.commit_container("missing-container", "some:tag")
+        die.assert_called_once()
+        self.assertIn("missing-container", die.call_args.args[0])
+
+    def test_die_message_includes_image_tag(self):
+        with patch.object(
+            docker_mod.subprocess, "run", return_value=_fail("boom"),
+        ), patch.object(
+            docker_mod, "die", side_effect=SystemExit("die"),
+        ) as die:
+            with self.assertRaises(SystemExit):
+                docker_mod.commit_container("ctr", "my-tag:v1")
+        self.assertIn("my-tag:v1", die.call_args.args[0])
+
+
 if __name__ == "__main__":
    unittest.main()
@@ -199,6 +199,30 @@ class TestHookRender(unittest.TestCase):
        self.assertIn('set -- "$@" --push-option="$opt"', hook)
        self.assertIn('git push "$@" origin "$refspec"', hook)

+    def test_inline_gitleaks_allow_routes_to_supervisor(self):
+        hook = git_gate_render_hook()
+        # First gitleaks runs normally; only if that passes does the
+        # hook ask gitleaks to ignore inline allow comments and report
+        # the suppressed findings for human approval.
+        self.assertIn("--ignore-gitleaks-allow", hook)
+        self.assertIn("--report-format=json", hook)
+        self.assertIn('"tool": "gitleaks-allow"', hook)
+        self.assertIn("SUPERVISE_QUEUE_DIR", hook)
+        self.assertIn("SUPERVISE_BOTTLE_SLUG", hook)
+        self.assertIn("supervisor approved # gitleaks:allow", hook)
+        self.assertIn("supervisor rejected # gitleaks:allow", hook)
+
+    def test_inline_gitleaks_allow_fails_closed_without_supervisor(self):
+        hook = git_gate_render_hook()
+        self.assertIn(
+            "cannot route # gitleaks:allow finding to supervisor; refusing push",
+            hook,
+        )
+        self.assertIn(
+            "supervisor approval timed out for # gitleaks:allow; refusing push",
+            hook,
+        )
+

 class TestAccessHookRender(unittest.TestCase):
    def test_access_hook_refreshes_origin_on_upload_pack(self):
@@ -0,0 +1,34 @@
+"""Unit: install.sh static contract checks."""
+
+from __future__ import annotations
+
+import subprocess
+import unittest
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[2]
+
+
+class TestInstallScript(unittest.TestCase):
+    def test_shell_syntax(self):
+        result = subprocess.run(
+            ["sh", "-n", str(ROOT / "install.sh")],
+            check=False,
+            capture_output=True,
+            text=True,
+        )
+        self.assertEqual("", result.stderr)
+        self.assertEqual(0, result.returncode)
+
+    def test_contract_phrases(self):
+        script = (ROOT / "install.sh").read_text(encoding="utf-8")
+        self.assertIn("python3", script)
+        self.assertIn("docker info", script)
+        self.assertIn("pipx install --force", script)
+        self.assertIn("pip install --user --upgrade", script)
+        self.assertIn('"${BOT_BOTTLE_BIN}" doctor', script)
+
+
+if __name__ == "__main__":
+    unittest.main()
@@ -9,8 +9,12 @@ from types import SimpleNamespace
 from typing import cast
 from unittest.mock import patch

+from bot_bottle.agent_provider import AgentProvisionPlan
+from bot_bottle.backend import BottleSpec
 from bot_bottle.backend.macos_container import launch
 from bot_bottle.backend.macos_container.bottle_plan import MacosContainerBottlePlan
+from bot_bottle.egress import EgressPlan
+from bot_bottle.git_gate import GitGatePlan
 from bot_bottle.manifest import ManifestIndex

 _MANIFEST = ManifestIndex.from_json_obj({
@@ -261,5 +265,80 @@ class TestMacosContainerLaunchArgv(unittest.TestCase):
        )


+def _build_plan(stage_dir: Path) -> MacosContainerBottlePlan:
+    return MacosContainerBottlePlan(
+        spec=cast(BottleSpec, SimpleNamespace()),
+        manifest=_MANIFEST,
+        stage_dir=stage_dir,
+        git_gate_plan=cast(GitGatePlan, SimpleNamespace(upstreams=())),
+        egress_plan=cast(EgressPlan, SimpleNamespace()),
+        supervise_plan=None,
+        agent_provision=AgentProvisionPlan(
+            template="claude",
+            command="claude",
+            prompt_mode="append_file",
+            image="bot-bottle-agent:latest",
+            dockerfile="/repo/Dockerfile",
+            guest_home="/home/node",
+            instance_name="bot-bottle-dev-abc",
+            prompt_file=stage_dir / "prompt.txt",
+            guest_env={},
+        ),
+        slug="dev-abc",
+        forwarded_env={},
+    )
+
+
+class TestMacosContainerLaunchCommittedImage(unittest.TestCase):
+    def setUp(self):
+        self._tmp = tempfile.TemporaryDirectory()
+        self.stage_dir = Path(self._tmp.name)
+
+    def tearDown(self):
+        self._tmp.cleanup()
+
+    def test_build_images_uses_committed_image_when_present(self):
+        plan = _build_plan(self.stage_dir)
+        calls = []
+
+        def fake_build(image: str, context: str, *, dockerfile: str = "") -> None:
+            calls.append((image, context, dockerfile))
+
+        with patch.object(
+            launch, "read_committed_image",
+            return_value="bot-bottle-committed-dev-abc:latest",
+        ), patch.object(
+            launch.container_mod, "image_exists", return_value=True,
+        ), patch.object(
+            launch.container_mod, "build_image", side_effect=fake_build,
+        ), patch.object(launch, "info"):
+            updated = launch._build_images(plan)
+
+        self.assertEqual("bot-bottle-committed-dev-abc:latest", updated.image)
+        self.assertEqual(1, len(calls))
+        self.assertEqual(launch.SIDECAR_BUNDLE_IMAGE, calls[0][0])
+
+    def test_build_images_builds_agent_when_committed_image_missing(self):
+        plan = _build_plan(self.stage_dir)
+        calls = []
+
+        def fake_build(image: str, context: str, *, dockerfile: str = "") -> None:
+            calls.append((image, context, dockerfile))
+
+        with patch.object(
+            launch, "read_committed_image",
+            return_value="bot-bottle-committed-dev-abc:latest",
+        ), patch.object(
+            launch.container_mod, "image_exists", return_value=False,
+        ), patch.object(
+            launch.container_mod, "build_image", side_effect=fake_build,
+        ):
+            updated = launch._build_images(plan)
+
+        self.assertEqual("bot-bottle-agent:latest", updated.image)
+        self.assertEqual(2, len(calls))
+        self.assertEqual("bot-bottle-agent:latest", calls[1][0])
+
+
 if __name__ == "__main__":
    unittest.main()
@@ -73,6 +73,53 @@ resolver #2
        )
        self.assertTrue(run.call_args_list[-1].kwargs["check"])

+    def test_commit_container_execs_tar_and_builds_image(self):
+        # stderr is bytes because subprocess.run uses stderr=PIPE without text=True
+        completed = util.subprocess.CompletedProcess(
+            args=[], returncode=0, stdout=b"", stderr=b"",
+        )
+        dockerfile_text = ""
+
+        def fake_build_image(image_tag: str, context: str, *, dockerfile: str = "") -> None:
+            nonlocal dockerfile_text
+            with open(dockerfile, encoding="utf-8") as f:
+                dockerfile_text = f.read()
+
+        with patch.object(util.subprocess, "run", return_value=completed) as run, \
+             patch.object(util, "build_image", side_effect=fake_build_image) as build_image, \
+             patch.object(util, "info"):
+            util.commit_container(
+                "bot-bottle-dev-abc12",
+                "bot-bottle-committed-dev-abc12:latest",
+            )
+
+        argv = run.call_args.args[0]
+        self.assertEqual("container", argv[0])
+        self.assertEqual("exec", argv[1])
+        self.assertIn("bot-bottle-dev-abc12", argv)
+        self.assertIn("tar", argv)
+        self.assertIn("--directory=/", argv)
+        build_image.assert_called_once()
+        self.assertEqual(
+            "bot-bottle-committed-dev-abc12:latest",
+            build_image.call_args.args[0],
+        )
+        self.assertIn("ADD rootfs.tar /\n", dockerfile_text)
+        self.assertIn("USER node\n", dockerfile_text)
+        self.assertIn("WORKDIR /home/node\n", dockerfile_text)
+
+    def test_commit_container_dies_on_exec_tar_failure(self):
+        failed = util.subprocess.CompletedProcess(
+            args=[], returncode=1, stdout=b"", stderr=b"No such container",
+        )
+        with patch.object(util.subprocess, "run", return_value=failed), \
+             patch.object(util, "die", side_effect=SystemExit("die")) as die:
+            with self.assertRaises(SystemExit):
+                util.commit_container("missing-container", "some:tag")
+
+        die.assert_called_once()
+        self.assertIn("missing-container", die.call_args.args[0])
+
    def test_build_image_restarts_builder_when_dns_mismatches(self):
        status = util.subprocess.CompletedProcess(
            args=[],
@@ -0,0 +1,27 @@
+"""Unit: Python package metadata for install script PRD."""
+
+from __future__ import annotations
+
+import tomllib
+import unittest
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[2]
+
+
+class TestPyproject(unittest.TestCase):
+    def test_console_script_and_no_runtime_dependencies(self):
+        data = tomllib.loads((ROOT / "pyproject.toml").read_text(encoding="utf-8"))
+        project = data["project"]
+        self.assertEqual("bot-bottle", project["name"])
+        self.assertEqual(">=3.11", project["requires-python"])
+        self.assertEqual([], project["dependencies"])
+        self.assertEqual(
+            "bot_bottle.cli:main",
+            project["scripts"]["bot-bottle"],
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()
@@ -16,6 +16,8 @@ from __future__ import annotations
 import tempfile
 import unittest
 from pathlib import Path
+from types import SimpleNamespace
+from typing import Any, cast
 from unittest.mock import patch

 from bot_bottle.backend.smolmachines import launch as _launch_mod
@@ -141,5 +143,46 @@ class TestEnsureSmolmachine(unittest.TestCase):
        self.assertTrue(str(pack_args[1]).endswith(f"{digest}.smolmachine"))


+class TestAgentFromPath(unittest.TestCase):
+    def _plan(self) -> Any:
+        return cast(Any, SimpleNamespace(
+            slug="dev-abc12",
+            agent_image="bot-bottle-claude:latest",
+            agent_dockerfile_path="/repo/Dockerfile",
+        ))
+
+    def test_uses_committed_artifact_when_present(self):
+        with tempfile.TemporaryDirectory(prefix="committed-smolmachine.") as tmp:
+            artifact = Path(tmp) / "committed-smolmachine.smolmachine"
+            artifact.write_text("")
+            with patch.object(
+                _launch_mod, "read_committed_image", return_value=str(artifact),
+            ), patch.object(
+                _launch_mod, "_ensure_smolmachine",
+            ) as ensure, patch.object(
+                _launch_mod, "info",
+            ):
+                result = _launch_mod._agent_from_path(self._plan())
+
+        self.assertEqual(artifact, result)
+        ensure.assert_not_called()
+
+    def test_falls_back_when_committed_artifact_missing(self):
+        packed = Path("/cache/agent.smolmachine")
+        with patch.object(
+            _launch_mod, "read_committed_image",
+            return_value="/missing/committed.smolmachine",
+        ), patch.object(
+            _launch_mod, "_ensure_smolmachine", return_value=packed,
+        ) as ensure:
+            result = _launch_mod._agent_from_path(self._plan())
+
+        self.assertEqual(packed, result)
+        ensure.assert_called_once_with(
+            "bot-bottle-claude:latest",
+            dockerfile="/repo/Dockerfile",
+        )
+
+
 if __name__ == "__main__":
    unittest.main()
@@ -24,6 +24,7 @@ from bot_bottle.backend.smolmachines.smolvm import (
    machine_start,
    machine_stop,
    pack_create,
+    pack_create_from_vm,
    wait_exec_ready,
 )

@@ -63,6 +64,17 @@ class TestArgvShapes(unittest.TestCase):
            argv,
        )

+    def test_pack_create_from_vm_argv(self):
+        with self._patch_run() as m:
+            pack_create_from_vm("bot-bottle-dev-abc12", Path("/tmp/committed"))
+        argv = m.call_args.args[0]
+        self.assertEqual(
+            ["smolvm", "pack", "create",
+             "--from-vm", "bot-bottle-dev-abc12",
+             "-o", "/tmp/committed"],
+            argv,
+        )
+
    def test_machine_create_minimal(self):
        with self._patch_run() as m:
            machine_create("agent-xyz")
@@ -193,6 +205,14 @@ class TestErrorPath(unittest.TestCase):
            with self.assertRaises(SmolvmError):
                pack_create("missing:tag", Path("/tmp/out"))

+    def test_pack_create_from_vm_failure_raises(self):
+        with patch(
+            "bot_bottle.backend.smolmachines.smolvm.subprocess.run",
+            return_value=_fail("pack failed"),
+        ):
+            with self.assertRaises(SmolvmError):
+                pack_create_from_vm("bot-bottle-dev-abc12", Path("/tmp/out"))
+
    def test_exec_failure_returns_result(self):
        # The in-VM command's exit code is what Bottle.exec sees;
        # `false` exiting non-zero is not a smolvm failure.
@@ -17,6 +17,7 @@ from bot_bottle.supervise import (
    STATUS_MODIFIED,
    STATUS_REJECTED,
    TOOL_CAPABILITY_BLOCK,
+    TOOL_GITLEAKS_ALLOW,
    archive_proposal,
    audit_log_path,
    list_pending_proposals,
@@ -320,6 +321,7 @@ class TestToolConstants(unittest.TestCase):
                supervise.TOOL_ALLOW,
                TOOL_CAPABILITY_BLOCK,
                supervise.TOOL_EGRESS_BLOCK,
+                TOOL_GITLEAKS_ALLOW,
                supervise.TOOL_LIST_EGRESS_ROUTES,
            ),
            supervise.TOOLS,
@@ -19,6 +19,7 @@ from bot_bottle.supervise import (
    STATUS_MODIFIED,
    STATUS_REJECTED,
    TOOL_CAPABILITY_BLOCK,
+    TOOL_GITLEAKS_ALLOW,
    read_audit_entries,
    read_response,
    sha256_hex,
@@ -33,6 +34,7 @@ def _proposal(slug: str = "dev", tool: str = TOOL_CAPABILITY_BLOCK) -> Proposal:
        TOOL_CAPABILITY_BLOCK: "FROM python:3.13\n",
        supervise.TOOL_ALLOW: "routes:\n  - host: example.com\n",
        supervise.TOOL_EGRESS_BLOCK: "routes:\n  - host: example.com\n",
+        TOOL_GITLEAKS_ALLOW: "file: tests/test_fixture.py\nline: 3\n",
    }
    payload = payloads.get(tool, "")
    return Proposal.new(
@@ -170,6 +172,30 @@ class TestApproveReject(_FakeHomeMixin, unittest.TestCase):
        self.assertEqual(STATUS_APPROVED, entries[0].operator_action)
        self.assertEqual("needed for dev", entries[0].justification)

+    def test_approve_gitleaks_allow_leaves_response_for_gate(self):
+        qp = self._enqueue(tool=TOOL_GITLEAKS_ALLOW)
+        supervise_cli.approve(qp, notes="dummy fixture")
+        # Gate polls the queue dir for the response; TUI must not archive it.
+        resp = read_response(qp.queue_dir, qp.proposal.id)
+        self.assertEqual(STATUS_APPROVED, resp.status)
+        self.assertEqual("dummy fixture", resp.notes)
+        self.assertFalse((qp.queue_dir / "processed").exists())
+
+    def test_tui_gitleaks_allow_requires_reason(self):
+        qp = self._enqueue(tool=TOOL_GITLEAKS_ALLOW)
+        with patch.object(supervise_cli, "_prompt", return_value=""):
+            status = supervise_cli._approve_from_tui(None, qp)  # type: ignore[arg-type]
+        self.assertEqual("approve aborted (empty reason)", status)
+        self.assertFalse((qp.queue_dir / "processed").exists())
+
+    def test_tui_gitleaks_allow_writes_reason(self):
+        qp = self._enqueue(tool=TOOL_GITLEAKS_ALLOW)
+        with patch.object(supervise_cli, "_prompt", return_value="test fixture"):
+            status = supervise_cli._approve_from_tui(None, qp)  # type: ignore[arg-type]
+        self.assertIn("approved gitleaks-allow", status)
+        resp = read_response(qp.queue_dir, qp.proposal.id)
+        self.assertEqual("test fixture", resp.notes)
+

 # class TestCapabilityApplyWiring(_FakeHomeMixin, unittest.TestCase):
 #     # DISABLED — capability_apply functionality is currently commented out.
Author	SHA1	Message	Date
didericis	bd663196dc	docs: reposition README around provider-neutral secure substrate test / unit (pull_request) Successful in 36s Details test / integration (pull_request) Successful in 17s Details Lead with the agnostic + security story instead of the single-user security framing. New hero positions bot-bottle as a neutral control plane that runs any agent (Claude, Codex, or a drop-in contrib plugin) inside an isolation boundary the agent can't touch. Restructure Features into three pillars — neutral substrate, isolation boundary, host-matched isolation — promoting provider-agnosticism (PRD 0053 user plugins) from a buried bullet to a headline. No capability claims changed; per-provider auth/image detail preserved as a note linking to Manifest. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YcU7nerbg8cVj9R4EkpfLJ	2026-06-24 01:21:05 -04:00
didericis-codex	6b0de88be6	docs: activate install script prd lint / lint (push) Successful in 1m39s Details test / unit (pull_request) Successful in 31s Details test / integration (pull_request) Successful in 16s Details	2026-06-23 21:47:12 -04:00
didericis-codex	9a941e59be	feat: add install script packaging	2026-06-23 21:47:12 -04:00
didericis	d7a3539755	ci(prd): rename PRD to prd-new placeholder per new convention	2026-06-23 21:46:44 -04:00
didericis	cfe57a50d0	docs(prd): renumber PRD 0054 → 0057 (0054 slot taken by named-labelled-agents)	2026-06-23 21:46:44 -04:00
didericis	e5d551861c	docs(prd): PRD 0054 - install script	2026-06-23 21:46:44 -04:00
didericis	369d332204	Default the supervise flag to true test / unit (pull_request) Successful in 36s Details test / integration (pull_request) Successful in 17s Details lint / lint (push) Successful in 1m40s Details test / unit (push) Successful in 30s Details test / integration (push) Successful in 15s Details Update Quality Badges / update-badges (push) Successful in 1m44s Details Issue #249: bottles should be supervised by default. Rather than remove the flag (which would make supervision mandatory and is the wrong plane for cost-control enforcement — see #251), keep the opt-out and flip the default. Bottles that omit `supervise:` now get the stuck-recovery sidecar; `supervise: false` still skips it. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YcU7nerbg8cVj9R4EkpfLJ	2026-06-23 20:48:04 -04:00
didericis	31cde11b0d	docs: correct stale role field and claude provider auth example lint / lint (push) Successful in 1m53s Details The egress route fields table described `role` as a functional field that wires built-in auth flows. PRD 0029 removed the `claude_code_oauth` role; the manifest parser now rejects any `role` value as reserved-for-future-use. Provider auth routes are injected from `agent_provider.auth_token`. - README: fix the `role` row to state it is reserved and any value is rejected at load. - examples/bottles/claude.md: the manual `api.anthropic.com` route used the rejected `role` key and, even without it, would be silently dropped (provider-injected routes win for a provisioned host) — so its auth never took effect and the dlp comments described a route that never exists in the plan. Replace it with the canonical `agent_provider.auth_token` shape. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YcU7nerbg8cVj9R4EkpfLJ	2026-06-23 17:53:18 -04:00
didericis-claude	c41751f3b9	docs: add role and git.fetch to egress route fields table Both fields were missing from the reference table added in the preceding commit — `role` is visible in examples/bottles/claude.md and `git.fetch` is documented in PRD 0052 but neither appeared in the README table.	2026-06-23 17:48:19 -04:00
didericis	e2422c20a0	docs: document egress matches, dlp fields, and detector defaults	2026-06-23 17:48:19 -04:00
github-actions[bot]	de71533a17	ci(prd): assign sequential numbers to new PRDs	2026-06-23 21:47:01 +00:00
didericis-claude	88c4f61901	fix: don't archive gitleaks-allow response before gate reads it test / unit (pull_request) Successful in 41s Details test / integration (pull_request) Successful in 18s Details lint / lint (push) Successful in 1m52s Details prd-number / assign-numbers (push) Successful in 45s Details test / unit (push) Successful in 36s Details test / integration (push) Successful in 21s Details Update Quality Badges / update-badges (push) Successful in 1m19s Details The TUI was calling archive_proposal for gitleaks-allow immediately after write_response, moving the response file to processed/ within microseconds. The git-gate shell loop polls queue_dir for the response file every second — it never sees it and hangs until timeout. capability-block is handled by the MCP sidecar which archives after reading; gitleaks-allow is handled by the shell gate which archives after processing. Let the gate own the archive step.	2026-06-23 17:37:01 -04:00
didericis-claude	c666eaa63f	fix: add TOOL_GITLEAKS_ALLOW to __all__ in supervise.py	2026-06-23 17:36:08 -04:00
didericis-codex	83eb9e4041	docs(prd): add gitleaks allow supervision	2026-06-23 17:36:08 -04:00
didericis-codex	33333ac4d9	Supervise gitleaks inline allow exceptions	2026-06-23 17:36:08 -04:00
github-actions[bot]	4d56f515bc	ci(prd): assign sequential numbers to new PRDs	2026-06-23 21:32:54 +00:00
didericis-claude	c48c3688b8	fix(smolmachines): exclude /tmp+/var/tmp from snapshot; mkdir -p on boot test / unit (pull_request) Successful in 36s Details test / integration (pull_request) Successful in 23s Details lint / lint (push) Successful in 1m59s Details prd-number / assign-numbers (push) Successful in 1m8s Details test / unit (push) Successful in 35s Details test / integration (push) Successful in 21s Details Update Quality Badges / update-badges (push) Successful in 1m22s Details On resume from a committed snapshot, smolvm's pack process remaps all file uids to the host uid (501 on macOS). Files in /tmp that were created during the session (e.g. /tmp/claude-1000 owned by node=uid 1000) get remapped to 501. Claude Code then refuses to use the temp directory because it's owned by a different uid. Two-part fix: - Exclude ./tmp and ./var/tmp from the tar in _exec_tar_to_file. Both directories are ephemeral; a resumed VM should start with clean temp directories identical to a fresh VM. - Add mkdir -p /tmp /var/tmp to _init_vm before chown/chmod, so the directories are created if the committed snapshot omitted them.	2026-06-23 16:53:41 -04:00
didericis-claude	6040b20e6e	fix(smolmachines): write tar to VM file then machine_cp to host Replace the Popen/stdout=PIPE approach with a write-then-copy strategy that avoids binary-stdout piping through the smolvm exec channel entirely: 1. Probe connectivity with `machine_exec(machine, ["true"])` first. If this fails while an interactive session is running, the error now says "concurrent exec not available" instead of the opaque "<no stderr>". 2. Run `tar --create --gzip --file=/var/tmp/.bot-bottle-commit.tar.gz` inside the VM via machine_exec (same mechanism used during provisioning). tar writes to a file in the VM, not stdout, so smolvm never has to transmit binary data over the exec channel. 3. Copy the compressed archive to the host with machine_cp. 4. Dockerfile switches to ADD rootfs.tar.gz / — Docker decompresses gzip tarballs automatically.	2026-06-23 16:53:41 -04:00
didericis-claude	f2775101a0	fix(smolmachines): pipe tar stdout via PIPE not file fd smolvm machine exec requires stdout to be a pipe, not a regular file descriptor. Passing stdout=file caused smolvm to return non-zero with no stderr (the error was silently swallowed or went to the regular-file fd instead of reaching us). Switch _snapshot_running_vm to a new _exec_tar_to_file helper that uses Popen with stdout=PIPE and streams the tar to disk via shutil.copyfileobj. A background thread drains stderr concurrently to prevent deadlock when the stderr pipe buffer fills while we are writing stdout data.	2026-06-23 16:53:41 -04:00
didericis-claude	dd99c495f4	fix(smolmachines): use sh -c not sh -lc in exec_agent The terminal-decoration wrapper script is invoked with sh -lc, which sources login-shell init files (/etc/profile, ~/.profile) rather than interactive-shell files (~/.zshrc). smolvm is typically installed via homebrew whose PATH setup lands in ~/.zprofile or ~/.zshrc — not picked up by sh -l — so pty_resize.py's Popen(["smolvm", ...]) raises FileNotFoundError, pty_resize exits non-zero, and the trailing reset- printf makes sh exit 0. The caller sees "session ended (exit 0)" immediately with no agent output. Use sh -c instead. The calling process (./cli.py) inherits the user's interactive shell PATH where smolvm is present, confirmed by the provision steps (machine_exec) succeeding before exec_agent is reached.	2026-06-23 16:53:41 -04:00
didericis-claude	eb64a52ffa	fix(smolmachines): commit via exec-tar instead of stop→pack smolvm pack create --from-vm requires the VM to be stopped, and stopping a smolmachines VM terminates any running interactive session. Instead, mirror the macos-container approach: exec into the running VM as root and stream the root filesystem via tar (smolvm machine exec -- tar), build a Docker image from the archive, push to an ephemeral local registry, and run smolvm pack create --image to produce the .smolmachine artifact. The VM stays running throughout the commit. Remove the stop-confirm prompt and machine_is_running check that were added in the previous commit — neither is needed when we no longer stop.	2026-06-23 16:53:41 -04:00
didericis-claude	d11e3940fa	fix(smolmachines): stop VM before pack commit, with confirm prompt smolvm pack create --from-vm requires the VM to be stopped. Add machine_is_running() to smolvm.py (via machine ls --json state field), and add the same confirm-stop flow to SmolmachinesFreezer that was originally designed for macos-container: if running, prompt the user, stop the VM, then pack. Already-stopped VMs are packed directly.	2026-06-23 16:53:41 -04:00
didericis-claude	a32c0c7865	test: update macos-container tests for exec-tar commit approach - Rename export test to reflect new exec-tar mechanism; update argv assertions to match the new `container exec ... tar` command shape - Change mock stderr from str to bytes (subprocess.PIPE without text=True) - Add type annotation to capture_freeze closure to satisfy pyright	2026-06-23 16:53:41 -04:00
didericis-claude	ccb2956562	fix(macos-container): commit via exec-tar instead of stop→export Apple Container removes containers when they stop, making the stop-then-export flow impossible regardless of the --rm flag. Replace `container export` (requires stopped container) with `container exec --user root <name> tar --create ... --file=- --directory=/ .` streamed to a temp file, then build the committed image from that archive as before. The bottle stays running after commit, which is better UX. Drop the stop-confirm prompt from MacosContainerFreezer since we no longer need to stop the container at all.	2026-06-23 16:53:41 -04:00
didericis-claude	c6362fda7b	fix(macos-container): remove --rm from agent run so commit can export container stop was removing the container immediately (due to --rm) before container export could run. The force_remove_container teardown callback on the ExitStack already handles cleanup on normal exit, so --rm was redundant. Without it, the stopped container stays available for container export to snapshot.	2026-06-23 16:53:41 -04:00
didericis-claude	cb321f7ad4	refactor(freezer): drop Bottle from commit signature Freezer._freeze only ever used bottle.name, which is always f"bot-bottle-{agent.slug}". Remove the Bottle parameter from commit() and _freeze(), derive the container name from agent.slug directly in each subclass, and delete the _NamedBottle stub that existed solely to paper over this.	2026-06-23 16:53:41 -04:00
didericis-claude	311cd46185	refactor(commit): introduce Freezer class hierarchy across backends Adds a Freezer ABC (backend/freeze.py) that encapsulates the stop-commit-mark-preserved flow for all backends, following the same pattern as BottleBackend. Each backend gets its own Freezer subclass: DockerFreezer — docker commit MacosContainerFreezer — container export + image rebuild; prompts to stop if the container is running SmolmachinesFreezer — smolvm pack create --from-vm The base class owns write_committed_image, mark_preserved, and the resume hint. Subclasses implement _freeze() and optionally override _export_hint() for migration instructions. Freezer.commit(agent, bottle) is the primary entry point for use within a live launch context. Freezer.commit_slug(slug) is a convenience wrapper for cmd_commit, which no longer branches on backend names itself. get_freezer(backend_name) is the factory, analogous to get_bottle_backend(). CommitCancelled is raised by MacosContainerFreezer when the user declines the stop prompt; cmd_commit catches it and returns 0.	2026-06-23 16:53:41 -04:00
didericis-claude	28335f453f	fix(commit): stop running macos-container bottle before committing `container export` requires the container to be stopped first. When a running bottle is detected, prompt the user to confirm, stop the container, then commit. Adds `container_is_running` and `stop_container` helpers to the macos-container util. Addresses #240 (comment)	2026-06-23 16:53:41 -04:00
didericis-claude	a1aa8feb85	fix: correct Manifest/ManifestIndex usage and add missing type annotations in tests - test_docker_launch_committed_image: replace Manifest.from_json_obj (nonexistent) with ManifestIndex.from_json_obj; pass manifest= arg to DockerBottlePlan constructor (required by BottlePlan base class) - test_macos_container_launch: cast SimpleNamespace stubs to their expected types (BottleSpec, GitGatePlan, EgressPlan) in _build_plan; add str type annotations to fake_build parameter signatures - test_macos_container_util: add str type annotations to fake_build_image parameter signatures	2026-06-23 16:53:41 -04:00
didericis	cb3bb209d6	feat: support macos-container bottle commits	2026-06-23 16:53:41 -04:00
didericis-codex	6e73cc4d86	feat: support smolmachines bottle commit	2026-06-23 16:53:41 -04:00
didericis-claude	64fac71025	docs(prd): mark commit-bottle-state PRD as Active	2026-06-23 16:53:41 -04:00
didericis-claude	f8ac22c316	feat(cli): add commit command to snapshot running bottle state Adds `./cli.py commit [<slug>]` which runs `docker commit` on the active agent container and stores the resulting image tag in per-bottle state. The next `./cli.py resume <slug>` automatically boots from the committed snapshot instead of rebuilding from the Dockerfile, preserving all in-container state across restarts and migrations. - bottle_state: add write_committed_image / read_committed_image helpers - docker/util: add commit_container wrapper around `docker commit` - docker/launch: check for a committed image before the Dockerfile build step; fall back to normal build if the image is absent from the daemon - cli/commit: new command with interactive slug picker; errors clearly on non-Docker backends - 50 new unit tests covering all paths Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-06-23 16:53:41 -04:00
Quality Badge Bot	9465857a99	chore: update quality badges - Pylint: 9.93/10 - Pyright: 0 errors [skip ci]	2026-06-23 20:46:17 +00:00