docs: defer broker replay protection to its own issue (#494)

Per PR review, replay protection is too heavy for the host control
server MVP. Drop it from the four-gap framing (now three gaps), remove
the enforcement design section and implementation chunk, and track the
iat-window + jti-cache work in #494 as an independent in-process change.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

.gitea/workflows/test.yml

@@ -102,20 +102,6 @@ jobs:
           python3 --version
           python3 cli.py backend status --backend=docker
 
-      - name: Preflight — clear any leftover poisoned gateway network
-        run: |
-          # The gateway network has a fixed name and persists across jobs on
-          # this shared runner. A pre-fix or concurrent launch can leave it with
-          # a malformed IPv6 subnet that trips docker's own ParseAddr in
-          # `network inspect` (see PR #515); the code now self-heals it, but the
-          # heal can't run if `network inspect` is what's broken on some daemon
-          # versions. Drop the network here so this run recreates it IPv4-only.
-          # Remove the attached gateway container first (else `network rm` fails
-          # on active endpoints); both are recreated by ensure_running. Harmless
-          # when absent.
-          docker rm --force bot-bottle-orch-gateway 2>/dev/null || true
-          docker network rm bot-bottle-gateway 2>/dev/null || true
-
       - name: Run integration tests (docker) with coverage
         env:
           BOT_BOTTLE_BACKEND: docker
@@ -298,7 +284,7 @@ jobs:
       - name: Combined coverage (unit + docker integration)
         run: PYTHON=python3 bash scripts/coverage.sh aggregate critical
 
-      - name: Diff-coverage gate (changed lines >= 80%)
+      - name: Diff-coverage gate (changed lines >= 90%)
         run: |
           git fetch --no-tags origin main:refs/remotes/origin/main
-          python3 scripts/diff_coverage.py --base origin/main --min 80
+          python3 scripts/diff_coverage.py --base origin/main --min 90

bot_bottle/backend/docker/gateway.py

@@ -140,43 +140,12 @@ class DockerGateway(Gateway):
             marker = inspected.stdout.strip()
             if marker in {"", self._subnet}:
                 return
-            # Inspectable but mislabelled: the stale auto-IPAM network created
-            # by older releases. Replace it below.
-            stale = True
-        else:
-            # inspect failed. Classify by stderr — do NOT assume "not absent"
-            # implies "poisoned": a transient daemon/API error, permission
-            # failure, timeout, or bad context also fails here, and destroying
-            # the shared gateway on that guess would tear the network out from
-            # under every live bottle.
-            err = inspected.stderr.lower()
-            if "no such network" in err or "not found" in err:
-                # Absent: nothing to replace — create it below.
-                stale = False
-            elif "parseaddr" in err:
-                # Present but poisoned. A daemon that default-enables IPv6
-                # attaches an fdd0::/64 subnet whose `::1/64` gateway trips
-                # docker's own netip.ParseAddr in `network inspect`/`ls`, so the
-                # command exits non-zero with that signature. A fixed release
-                # never *creates* such a network, but one can survive on a
-                # shared host from an older or concurrent launch — and
-                # `--ipv6=false` alone can't heal it, since the create below only
-                # no-ops on "already exists". Force-replace it so later reads
-                # (e.g. `_network_cidr` pinning a source IP) stop failing.
-                stale = True
-            else:
-                # Unrecognized failure: no evidence the network is malformed.
-                # Surface it rather than mutate shared state on a guess.
-                raise GatewayError(
-                    f"gateway network {self.network} could not be inspected: "
-                    f"{inspected.stderr.strip()}"
-                )
-        if stale:
-            # Migrate the stale/poisoned network. Removing the fixed gateway is
-            # safe here: this launch recreates it.
+        if inspected.returncode == 0:
+            # Migrate the stale auto-IPAM network created by older releases.
+            # Removing the fixed gateway is safe here: this launch recreates it.
             run_docker(["docker", "rm", "--force", self.name])
             removed = run_docker(["docker", "network", "rm", self.network])
-            if removed.returncode != 0 and "no such network" not in removed.stderr.lower():
+            if removed.returncode != 0:
                 raise GatewayError(
                     f"gateway network {self.network} needs explicit subnet "
                     f"{self._subnet} but could not be replaced: "

docs/decisions/0004-coverage-policy.md

@@ -3,10 +3,6 @@
 - **Status:** Accepted
 - **Date:** 2026-06-25
 - **Deciders:** didericis
-- **Revised:** 2026-07-27 — thresholds relaxed (critical minimum 90→85%,
-  diff-coverage gate 90→80%) to cut low-value test churn on changed lines.
-  The risk-weighting structure and the "global is informational" rule are
-  unchanged.
 
 ## Context
 
@@ -38,7 +34,7 @@ a regression (Goodhart's law).
 Coverage is **risk-weighted**, measured over the **combined unit +
 integration** suites, with three rules:
 
-1. **Critical modules must remain ≥ 85%.** The curated security/logic core
+1. **Critical modules must remain ≥ 90%.** The curated security/logic core
    covers the host and gateway egress policy, manifest trust boundary,
    git-gate enforcement, supervise protocol/server, YAML parser, and bottle
    state. The concrete module list lives in `scripts/critical-modules.txt`;
@@ -59,7 +55,7 @@ integration** suites, with three rules:
 
 The forward-looking guard is a **diff-coverage gate**
 (`scripts/diff_coverage.py`): new/changed executable lines on a branch
-must be ≥ 80% covered. This catches regressions where they are
+must be ≥ 90% covered. This catches regressions where they are
 introduced without forcing a back-fill crusade through legacy glue. The
 gate skips lines in omitted files (there is no coverage data for them),
 so the omit list cannot launder *new* logic into the dark: anything that

docs/prds/prd-new-host-control-server.md

@@ -0,0 +1,273 @@
+# PRD prd-new: Host control server
+
+- **Status:** Draft
+- **Author:** Claude
+- **Created:** 2026-07-26
+- **Issue:** #468
+
+## Summary
+
+Promote the in-process launch broker into a standalone **host control
+server**: the single privileged component on the host. Both the CLI and the
+orchestrator drive it over HTTP; it brokers agent launches, owns the
+orchestrator's own lifecycle, and is the sole writer of host-durable state (the
+tamper-evident audit record). This closes the three gaps between today's
+well-formed broker *contract* ([`orchestrator/broker.py`](../../bot_bottle/orchestrator/broker.py))
+and a real out-of-process service — transport, durable provisioned secret,
+and a disciplined op vocabulary — and splits host state by
+owner and lifetime. The prize: **the CLI no longer needs the Docker socket**,
+which is what finally lets a dedicated Gitea runner user drop the
+root-equivalent `docker` group (PRD 0070, "Relationship to other work").
+
+## Problem
+
+Container launches run directly from a short-lived CLI process against the
+Docker socket. That socket is root-equivalent, so every host that launches
+bottles hands root to whoever invokes the CLI — including a CI runner user we
+want to keep unprivileged. PRD 0070 already argues for replacing the fat socket
+with a **thin, structured, auditable** launch broker, and the contract for that
+broker exists and is tested in-process. But it is *only* in-process:
+`LaunchBroker.submit(token)` is a method call from
+`OrchestratorCore.launch_bottle` ([`service.py:116`](../../bot_bottle/orchestrator/service.py)),
+and `DockerBroker` is on no production path — every backend starts the
+orchestrator with `--broker stub` ([`__main__.py:54`](../../bot_bottle/orchestrator/__main__.py)).
+
+Three gaps stand between that scaffold and a host service:
+
+1. **No transport.** `submit` is an in-process call. A real service needs a
+   `BrokerClient` that POSTs the signed token and a host-side HTTP server that
+   verifies and acts.
+2. **The signing secret is ephemeral and self-generated.**
+   [`__main__.py:53`](../../bot_bottle/orchestrator/__main__.py) does
+   `secrets.token_bytes(32)` and hands the *same value* to signer and verifier —
+   viable only because they share a process. A separate daemon needs the secret
+   provisioned out of band and durable across orchestrator restarts.
+3. **The op vocabulary is `launch` / `teardown` only.** Everything else
+   host-privileged still lives in the CLI, so the schema has to grow — carefully,
+   since PRD 0070's security argument rests on "structured requests only, static
+   flags + ids."
+
+Separately, host state has no clear owner. `OrchestratorCore.reconcile` takes
+`live_source_ips` as a parameter *only because the orchestrator cannot see the
+backend* ([`service.py:137`](../../bot_bottle/orchestrator/service.py)); the
+egress traffic log is written to the container's stderr; and there is no durable,
+tamper-evident home for the audit record that survives orchestrator destruction.
+
+## Goals / Success Criteria
+
+- A standalone host control server that the CLI and orchestrator reach over
+  **HTTP**, with three entry paths working end to end:
+  - `web console -(iroh)-> orchestrator -(http)-> host controller -> launch`
+  - `cli -(http)-> orchestrator -(http)-> host controller -> launch`
+  - `cli -(http)-> host controller` — start / restart / status of the
+    orchestrator **itself** (the bootstrap/recovery path #391 targets).
+- The launch op is expressed as a **signed JWT of static flags + ids only**,
+  verified against a closed schema.
+- The signing secret is **provisioned out of band and durable** across
+  orchestrator restarts (a `TrustDomain` per #476, with a key the orchestrator
+  never holds for the host controller's *own* endpoints).
+- Host-privileged operations move off the CLI to the control server; **the CLI
+  no longer opens the Docker socket** for bottle operations.
+- `Orchestrator.reconcile` no longer takes `live_source_ips` — live-bottle
+  enumeration becomes an internal control-server call.
+- Host-durable state lands as an **append-only, hash-chained JSONL** audit log
+  owned solely by the host controller; operational state stays SQLite owned
+  solely by the orchestrator.
+
+## Non-goals
+
+- **Removing standing privilege.** This converts on-demand privilege (a CLI the
+  user invokes) into standing privilege (a daemon under launchd/systemd). The
+  win is that the privilege is *narrower* (structured requests vs. a raw socket),
+  not that it disappears. "Always running" is an accepted new property.
+- **Asymmetric signing.** We stay HS256 — see Design / "Signing stays
+  symmetric."
+- **Integrity against a live compromised orchestrator.** Host-location of the
+  audit log does not buy this: the orchestrator makes the decisions being audited
+  and can forge or omit entries wherever the file lives. An off-box copy is the
+  answer, tracked separately.
+- **A single unified DB for all state.** Impossible over a guest-kernel share
+  (SQLite locking is not coherent); state is split by owner and lifetime instead.
+- **The generic `SecretProvider` (#355)** and **remote terminal design (#478)** —
+  both ride the same door but are their own work.
+
+## Design
+
+### Topology
+
+The host controller is the sole privileged component. The orchestrator becomes a
+client of it for launches, and the CLI becomes a client of it for *both* bottle
+operations (indirectly, through the orchestrator) and orchestrator lifecycle
+(directly, for bootstrap/recovery — startup can't route through the thing being
+started).
+
+```
+web console ─(iroh)─▶ orchestrator ─┐
+                                    ├─(http, signed JWT)─▶ host controller ─▶ launch
+cli ────────(http)──▶ orchestrator ─┘
+cli ────────(http, bearer)──────────────────────────────▶ host controller   (orchestrator lifecycle)
+```
+
+### Transport: `BrokerClient` + host server
+
+`LaunchBroker.submit(token)` keeps its exact signature and semantics; only the
+*wire* changes. A new `BrokerClient` implements the same submit contract by
+POSTing the signed token to the host controller (stdlib `urllib`, like the
+existing [`orchestrator/client.py`](../../bot_bottle/orchestrator/client.py)),
+and the host controller's launch handler is the existing `verify_request` +
+`_launch`/`_teardown` path, now reached over HTTP instead of a method call. The
+in-process `StubBroker` stays for the dev-harness and tests; `DockerBroker`'s
+`_launch`/`_teardown` bodies move behind the server unchanged. Because the client
+satisfies the same interface `OrchestratorCore` already depends on, the core does
+not change to gain a real backend.
+
+### Signing stays symmetric (HS256)
+
+PRD 0070 nominally specifies asymmetric; the code is HS256 and we keep it.
+Asymmetric matters when the verifier is *less* privileged than the signer — here
+it is the reverse: the host controller (verifier) is strictly more privileged
+than the orchestrator (signer), and a controller that could forge orchestrator
+requests gains nothing, since it is already the component that launches. Staying
+symmetric also honors the no-runtime-deps policy (stdlib has no Ed25519). This
+matches the reasoning already inlined in `broker.py`'s module docstring.
+
+### Replay protection is out of scope (tracked in #494)
+
+Once the launch token travels over a wire, a captured token could be replayed —
+`sign_request` already emits `jti`/`iat` but `verify_request` reads neither, so
+there is no expiry window or `jti` cache today. Enforcing that (an `iat` window +
+a self-trimming `jti` cache) is a pure in-process change that lands independently
+of this work, and it is deferred to **#494** rather than gating the MVP of the
+host control server. Nothing here depends on it; it can merge before or after.
+
+### Op vocabulary and the "ids + static flags" rule (gap 3)
+
+Each op moved off the CLI widens the privileged surface, so growth is governed by
+one explicit rule, enforced in `verify_request`'s schema check:
+
+> A broker op carries **only ids and enumerated static flags** — a bottle id, a
+> pool slot, a **content-addressed** image ref chosen from a fixed set, an op
+> name from a closed vocabulary. Never a free-form path, argv, command, or
+> caller-supplied filesystem location. If an operation cannot be expressed that
+> way, it does not become a broker op.
+
+Operations that fit and move off the CLI (all today in
+`backend/*/consolidated_launch.py`, driven by a short-lived CLI process):
+
+| Op | What it does | Fits the rule because |
+|---|---|---|
+| `launch` / `teardown` | existing | ids + slot + image ref |
+| `orchestrator.ensure_running` | start the infra container | no arguments |
+| `orchestrator.{start,restart,status}` | lifecycle (the #391 path) | no arguments |
+| `list_live` | enumerate running bottles for reconcile | no arguments; returns ids/IPs |
+| `allocate_ip` | `next_free_ip` over `_network_container_ips` | no arguments; returns an IP |
+| `provision_git_gate` | `cp`/`exec` a per-bottle deploy key into the gateway | bottle id + key handle, no path |
+| `reprovision` | `docker exec printenv <ENV_VAR_SECRET>` on a live agent | bottle id + secret *name* |
+
+Image **builds** stay with the orchestrator for v1 (PRD 0070 §Memory: builds run
+control-plane-side; a dedicated slim build unit is later, #468-adjacent), so no
+`build` broker op is added here.
+
+With `list_live` as an internal control-server call, `Orchestrator.reconcile`'s
+`live_source_ips` parameter goes away — the tell PRD 0070 called out that the
+orchestrator couldn't see the backend disappears with it.
+
+### Secret provisioning (gap 2)
+
+The shared HS256 secret becomes a durable, out-of-band artifact via the
+**`TrustDomain`** seam (#476,
+[`trust_domain.py`](../../bot_bottle/trust_domain.py)):
+
+- The **launch-broker secret** is a `TrustDomain` whose key
+  (`host_signing_key(<file>)`, minted 0600 on first use, durable under
+  `bot_bottle_root()`) is provisioned to the orchestrator (signer) and the host
+  controller (verifier). Durability across orchestrator restarts is what makes
+  re-adoption work — a restart re-verifies against the same key.
+- The **host controller's own lifecycle endpoints** (the direct `cli -> host
+  controller` path) get a **separate** `TrustDomain` key the orchestrator never
+  holds — exactly the second domain #476's PRD reserves. The orchestrator must
+  not be able to mint the credentials used to start and stop it.
+
+This reuses the seam #476 landed rather than re-deriving provisioning per
+backend (the PR #471 bug class).
+
+### One daemon, structurally separate handlers (open decision 1)
+
+The audit writer and the broker live in **one daemon** for install simplicity,
+but with **no shared parsing** and **different credentials per handler**:
+
+- the **launch** handler requires the signed launch **JWT** (provenance +
+  un-coercible schema);
+- the **audit-append** handler takes a plain **bearer token** and writes to the
+  JSONL log.
+
+This does not defend against orchestrator compromise (it holds both creds) — it
+stops a bug in the boring audit path from reaching the privileged launch path.
+The launcher stays small enough to audit line-by-line, per PRD 0070.
+
+### State ownership: split by owner and lifetime
+
+A single mounted DB is impossible — SQLite locking is not coherent across guest
+kernels over a share, which is why the macOS backend already uses a container-only
+volume (`INFRA_DB_VOLUME`). So state splits three ways (depends on #469, which
+gets `bot-bottle.db` off the data plane first):
+
+| Owner | State | Home | Shape |
+|---|---|---|---|
+| **Orchestrator** | `orchestrator_bottles` registry; `bottled_agent_secrets` (encrypted egress tokens); `supervise_proposals` / `supervise_responses` | volume nothing else mounts (generalizing the macOS design) | **SQLite** — mutable, transactional, queried |
+| **Host controller** | supervise audit entries; egress traffic log (today → container stderr); host-side config | host filesystem, survives orchestrator/volume destruction | **JSONL** — append-only |
+| **Gateway** | none | — | after #469 the data plane holds no DB state |
+
+The historical record is **JSONL, not SQLite**, because it is append-only, never
+updated, never transactionally queried: `O_APPEND` writes are atomic, there is no
+locking protocol to get wrong, hash-chaining for tamper-evidence is cheap, and it
+survives container-runtime volume pruning (the #450 lesson) and stays readable
+without the orchestrator running. Both halves of "the audit record" — supervise
+decisions and the egress traffic log — land in the one place.
+
+The orchestrator is **sole mounter and sole writer** of its SQLite volume; the
+host controller is **sole writer** of the JSONL log, over the authenticated
+audit-append channel.
+
+## Implementation chunks
+
+Ordered, each independently mergeable:
+
+1. **`BrokerClient` + host launch server** over HTTP, reusing `verify_request`
+   and the existing `DockerBroker` bodies. Wire `OrchestratorCore` to a
+   `BrokerClient` behind a flag; keep `StubBroker` for the dev-harness. Closes
+   gap 1.
+2. **Durable secret via `TrustDomain`** — provision the launch-broker key to
+   signer + verifier; add the host controller's own lifecycle `TrustDomain`.
+   Closes gap 2.
+3. **Grow the op vocabulary** one op at a time (`list_live` first — it also
+   removes `reconcile`'s `live_source_ips`), each behind the ids + static-flags
+   rule. Closes gap 3.
+4. **JSONL audit log** — the host-controller-owned, hash-chained historical
+   record with the plain-bearer audit-append handler; redirect the egress traffic
+   log into it.
+5. **Drop the Docker socket from the CLI** once every host-privileged op it used
+   is a broker op — the payoff that unblocks the unprivileged Gitea runner user.
+
+## Open questions
+
+1. **Schema-width rule enforcement.** The "ids + static flags" rule is stated;
+   should `verify_request` reject unknown claim keys outright (strict schema) to
+   keep the surface from drifting? Leaning yes.
+2. **Audit-append back-pressure.** What the audit handler does if the JSONL sink
+   is unavailable (fail-closed vs. buffer) — resolve before shipping chunk 5.
+
+## References
+
+- **PRD 0070** — the contract, the launch broker, and the state tiers this
+  implements.
+- **#469** — get `bot-bottle.db` off the data plane (lands underneath this).
+- **#476** ([`prd-new-control-plane-auth-provisioning`](prd-new-control-plane-auth-provisioning.md))
+  — the `TrustDomain` seam this plugs the host controller's key into.
+- **#391** — backend-agnostic orchestrator restart (the bootstrap path).
+- **#494** — enforce broker replay protection (`iat` window + `jti` cache); split
+  out of this PRD as an independent in-process change.
+- **#386** — prebuilt images from the Gitea OCI registry (the fixed image set the
+  broker validates against).
+- **#355** — generic `SecretProvider`.
+- **#478** — remote terminal design.

docs/research/agent-sandbox-landscape.md

@@ -32,17 +32,9 @@ not a principled scope exclusion: both are major hosted sandbox platforms and
 belong in this landscape even though they target platform builders rather than
 bot-bottle's local single-operator workflow.
 
-Updated 2026-07-27 after a scan of recent Show HN launches: **Black LLAB,
-Eve, CloudRouter, Nucleus, yolo-cage, and Sandbox Agent SDK** added as a
-dated entrant cohort. They sharpen the comparison on three axes the original
-table underweighted: the browser/preview loop, parallel-agent operator UX, and
-a provider-neutral automation/session API.
-
 ## Summary
 
-The main table compares bot-bottle against fifteen canonical
-isolation/sandbox tools; a later section evaluates six recent HN entrants
-without widening an already unwieldy table.
+The main table compares bot-bottle against fifteen isolation/sandbox tools.
 Governance/pre-action authorization and credential-only layers are covered
 separately because they don't provide VM or container isolation. None
 duplicate bot-bottle's combination of local
@@ -550,199 +542,6 @@ them.
   framework runtime is not compromised.
 - **Maturity**: Specification + reference implementation, 2026.
 
-## Recent HN entrants (added 2026-07-27)
-
-These are grouped by launch date rather than promoted into the main table.
-Several are young or sparsely documented, and putting them beside mature
-runtime platforms with false precision would obscure the useful comparison.
-The HN launch posts are the evidence snapshot; feature claims should be
-rechecked against their repositories before relying on them for a security
-decision.
-
-### Black LLAB
-
-- **Source**: https://github.com/isaacdear/black-llab ;
-  HN launch https://news.ycombinator.com/item?id=47402394
-- **Isolation/locality**: Local Docker environment, with an isolated container
-  created for each agent task. Shared host kernel; no stronger boundary is
-  claimed.
-- **Agent integration**: General local/cloud model workspace. Its headline is
-  dynamic routing of simple prompts to local models and complex prompts to
-  hosted models, with code execution and web scraping inside the task
-  container.
-- **Network/credentials**: No default-deny egress, payload inspection, or
-  host-side credential injection documented in the launch.
-- **Competitive read**: Superficial overlap ("a container per agent task"),
-  but not a direct security-policy competitor. Its useful challenge is the
-  integrated model-selection UX, which bot-bottle intentionally leaves to the
-  selected agent provider.
-- **Maturity**: Early solo project; HN launch received 1 point.
-
-### Eve
-
-- **Source**: https://eve.new/ ;
-  HN launch https://news.ycombinator.com/item?id=47721255
-- **Isolation/locality**: Managed, hosted Linux sandbox per user/session
-  (claimed 2 vCPU, 4 GB RAM, 10 GB disk), with filesystem, code execution,
-  headless Chromium, and service connectors.
-- **Agent integration**: End-user OpenClaw-style agent product. An orchestrator
-  routes subtasks to specialist models and can run parallel subagents that
-  coordinate through a shared filesystem. Web UI and iMessage are primary
-  interaction surfaces.
-- **Network/credentials**: Broad connectors are a product feature; the launch
-  does not document bot-bottle-style default-deny route policy, content DLP,
-  or credentials held outside the sandbox.
-- **Competitive read**: Adjacent, not direct. Eve sells a managed colleague;
-  bot-bottle lets an operator run existing coding-agent CLIs under local
-  containment. Eve nevertheless demonstrates the appeal of background work,
-  live progress, browser capability, and mobile notification.
-- **Maturity**: Commercial hosted product; HN launch received 71 points and
-  39 comments.
-
-### CloudRouter
-
-- **Source**: https://github.com/manaflow-ai/manaflow/tree/main/packages/cloudrouter ;
-  HN launch https://news.ycombinator.com/item?id=47006393
-- **Isolation/locality**: Claude Code or Codex runs locally and provisions
-  remote cloud VMs/GPUs for execution. Project files are uploaded to the VM;
-  each machine exposes auth-protected VNC, VS Code, and Jupyter surfaces.
-- **Agent integration**: A skill plus CLI lets the coding agent itself start,
-  command, inspect, and tear down machines. Browser automation is integrated,
-  including snapshots and screenshots. Parallel disposable compute is the
-  central workflow.
-- **Network/credentials**: The launch emphasizes remote resource isolation and
-  authenticated UI endpoints, not default-deny guest egress, payload DLP, or
-  proxy-held application credentials.
-- **Competitive read**: The closest recent workflow competitor. It directly
-  addresses parallel coding agents, environmental conflict, and closing the
-  browser/test loop, but trades local custody for elastic cloud compute.
-  Cloud VMs and GPUs could be a future bot-bottle backend; they do not replace
-  its manifest/policy layer.
-- **Maturity**: Active open-source monorepo project; HN launch received
-  138 points and 36 comments.
-
-### Nucleus
-
-- **Source**: https://github.com/coproduct-opensource/nucleus ;
-  HN launch https://news.ycombinator.com/item?id=46855770
-- **Isolation/locality**: Firecracker microVM with an enforcing MCP tool proxy.
-- **Agent integration/config**: Compositional permission envelope for
-  read/write/run actions. The envelope is non-escalating and can tighten or
-  terminate, with scoped approval tokens for gated operations.
-- **Network/credentials**: Default-deny egress, DNS allowlist, iptables drift
-  detection, time/budget caps, and hash-chained audit logging are claimed.
-  Remote append-only audit storage and attestation were roadmap items at
-  launch.
-- **Competitive read**: Direct on security architecture, especially
-  non-escalating policy and tamper-evident audit. It is an early execution/tool
-  proxy rather than a provider-neutral, one-command coding-agent product. Its
-  tool-level action envelope is semantically finer than bot-bottle's network
-  boundary; bot-bottle is stronger on turnkey agent/provider integration,
-  credential custody, Git mediation, and long-running operator workflow.
-- **Maturity**: Early OSS experiment; HN launch received 3 points.
-
-### yolo-cage
-
-- **Source**: https://github.com/borenstein/yolo-cage ;
-  HN launch https://news.ycombinator.com/item?id=46706796
-- **Isolation/locality**: Local sandbox for running multiple coding agents in
-  YOLO mode. The launch discussion describes a VM boundary.
-- **Agent integration**: Built around the native Claude Code experience and
-  motivated by running many agents in parallel without permission-prompt
-  fatigue.
-- **Network/Git/credentials**: Strict egress filtering, configurable HTTP
-  middleware, and mediated `git`/`gh` dispatch are the main value. The launch
-  discussion explicitly identifies provider credential handling as unfinished
-  and difficult because Claude state spans multiple host paths.
-- **Competitive read**: The closest new threat-model competitor. It shares
-  bot-bottle's premise that filesystem isolation alone is insufficient and
-  that Git plus authorized HTTP channels need mediation. bot-bottle currently
-  leads on cross-provider support, proxy-held Claude/Codex/forge credentials,
-  typed per-role manifests, content DLP, and supervision. yolo-cage's simpler
-  pitch and narrower Claude-first setup may be easier to explain.
-- **Maturity**: Early local tool; HN launch received 60 points and 76 comments.
-
-### Sandbox Agent SDK
-
-- **Source**: https://github.com/rivet-dev/sandbox-agent ;
-  HN launch https://news.ycombinator.com/item?id=46795584
-- **Isolation/locality**: Does not provide the isolation primitive. It runs
-  inside E2B, Daytona, Modal, Cloudflare Containers, Agent Computer, BoxLite,
-  Docker, or another sandbox provider. Embedded mode can also run locally
-  without a sandbox.
-- **Agent integration**: Provider-neutral Rust server/SDK exposing a common
-  HTTP/SSE/OpenAPI interface across Claude Code, Codex, OpenCode, Cursor, Amp,
-  and Pi, plus a universal event/session schema for external storage and
-  replay. It also exposes filesystem, managed-process, terminal, MCP, skills,
-  custom-tool, and computer-use APIs. TypeScript is the primary SDK surface.
-- **Network/credentials**: Delegated to the chosen sandbox provider.
-- **Credential posture**: Its documented convenience command extracts real
-  OpenAI/Anthropic credentials from local agent configuration and passes them
-  as environment variables into the sandbox. That is materially weaker than
-  bot-bottle's host-side credential custody, but it is an integration choice,
-  not a structural limitation: a sandbox provider could put a credential
-  proxy underneath the same SDK.
-- **Competitive read**: A serious architectural threat despite not supplying
-  isolation. Sandbox Agent is trying to standardize the boundary *above* the
-  sandbox: one client protocol, session model, and UI/control surface across
-  every coding agent and runtime. If that boundary becomes the ecosystem
-  standard, users and application builders may choose a sandbox provider plus
-  Sandbox Agent rather than a vertically integrated launcher. bot-bottle's
-  manifests would then be valuable chiefly as a local policy/backend
-  implementation unless they expose an equally usable control contract.
-- **Maturity**: Apache 2.0, ~1.5k stars and 426 commits at the 2026-07-27
-  check; HN launch received 41 points.
-
-#### Why the Sandbox Agent architecture is strategically different
-
-The manifest and the universal control protocol solve different layers:
-
-- A bot-bottle manifest is a **trusted launch-time policy composition**. It
-  selects the agent role, isolation backend, image, skills, egress routes,
-  credentials, Git mediation, and supervision policy. Crucially, identity and
-  secret references live on the host side of the trust boundary.
-- Sandbox Agent is a **runtime control and observation protocol**. A remote
-  client creates sessions, sends messages, handles permissions, configures
-  skills/MCP, manipulates files/processes/desktops, and streams normalized
-  events. It deliberately delegates sandbox lifecycle, Git management,
-  storage, network policy, and credential security to other products.
-
-That makes it complementary in a component diagram but competitive in product
-architecture. The layer that becomes the stable integration point tends to own
-the ecosystem. Three plausible threat paths matter:
-
-1. **Standard control plane, interchangeable runtimes.** Applications integrate
-   once with Sandbox Agent and treat E2B, Daytona, BoxLite, Docker, or a future
-   local microVM as replaceable compute. A provider that bundles adequate
-   egress and credential custody makes bot-bottle's end-to-end launcher less
-   necessary.
-2. **Policy grows upward.** Sandbox Agent already configures permissions,
-   skills, MCP, custom tools, filesystem/process access, and computer use. If
-   it adds a declarative, host-verifiable policy document, the overlap with
-   agent/bottle manifests becomes substantial even if enforcement remains
-   delegated.
-3. **UI and session ownership.** Its universal transcript schema, Inspector,
-   React components, event replay, and remote terminal/computer APIs can become
-   the natural basis for desktop, web, and mobile agent managers. bot-bottle's
-   security layer could remain stronger while losing the operator surface and
-   distribution channel.
-
-The counter-position is not to claim that manifests and an API are mutually
-exclusive. The defensible split is:
-
-- bot-bottle owns the trusted policy and enforcement plane outside the agent;
-- a provider-neutral protocol owns agent process control and normalized
-  events; and
-- the operator UI consumes both.
-
-This suggests an explicit compatibility decision rather than parallel,
-accidental protocol design: evaluate running Sandbox Agent inside a bottle and
-exposing it only through the authenticated bot-bottle control plane. If its
-schema is suitable, adopting it could turn a threat into an integration while
-keeping manifests as the higher-trust policy source. If it is unsuitable,
-bot-bottle should still publish a stable provider-neutral session/event API so
-frontends do not depend on Claude/Codex/Pi-specific process behavior.
-
 ## Comparison table
 
 *Isolation/sandbox tools only. AGT and OAP are governance layers — see their per-project notes above.*
@@ -817,70 +616,6 @@ would be a *backend* bot-bottle could call, not a competitor to its
 manifest layer. endo-familiar is in a different paradigm entirely:
 capability passing rather than kernel boundaries.
 
-**Recent entrants change two parts of this read.** yolo-cage is closer to the
-actual threat model than agent-safehouse or litterbox: it combines a VM-style
-boundary with mediated Git and filtered HTTP specifically for parallel coding
-agents. Sandbox Agent SDK is the more important strategic entrant even though
-it supplies no isolation. It can become the standard agent-control layer above
-all of these runtimes, including a future bot-bottle backend. CloudRouter is
-the clearest workflow challenge because its browser/desktop/GPU loop makes
-parallel agents visibly more capable, not merely safer.
-
-## Gap evaluation after the 2026-07-27 entrant scan
-
-### Material gaps
-
-1. **A stable provider-neutral control and event protocol.** This is the
-   largest newly visible gap. bot-bottle normalizes launch/provisioning across
-   providers, but an external UI or orchestrator still lacks one documented
-   contract for creating a Claude/Codex/Pi session, sending input, handling
-   permission/supervision events, streaming normalized output, reconnecting,
-   and replaying history. Sandbox Agent SDK addresses exactly this layer and
-   is already portable across many sandbox providers.
-2. **Browser/preview closure.** CloudRouter and Eve make a browser or desktop
-   part of the standard agent environment and expose screenshots/live viewing
-   to the operator. bot-bottle can run dev servers and supports nested
-   containers, but it does not present a first-class browser/computer-use
-   primitive or an auth-protected preview surface. For coding agents expected
-   to verify UI work, this is a real product gap.
-3. **Unified parallel-session operator UX.** Named persistent bottles and
-   supervision provide the substrate, but the recent products make task
-   switching, live progress, notifications, terminal attach, diffs, and
-   session history the product. Security depth will not compensate for a
-   visibly rougher daily loop.
-4. **Normalized transcript persistence and replay.** bot-bottle preserves
-   provider-specific state for resume; it does not expose a provider-neutral
-   event record suitable for audit, replay, analytics, or a web/mobile client.
-   This is both a UX gap and an audit gap.
-
-### Important, but not necessarily bot-bottle features
-
-- **Cloud VM/GPU provisioning.** Valuable for elastic workloads and could be a
-  backend, but it conflicts with the local-custody default and should not
-  displace core policy work.
-- **Automatic model routing.** Black LLAB and Eve sell task-to-model routing.
-  bot-bottle's provider-template boundary can host that choice without making
-  it part of the trusted sandbox policy.
-- **A thousand SaaS connectors.** This broadens capability and blast radius.
-  The bot-bottle-native answer should remain explicit, scoped forge/egress
-  associations rather than connector count as a goal.
-- **SDK-driven sandbox lifecycle as the primary configuration model.** Useful
-  for platform builders, but not a replacement for reviewable, host-owned
-  manifests. A control API and a declarative policy source are compatible;
-  neither should silently become the other.
-
-### Areas where bot-bottle remains ahead
-
-- real provider and forge credentials remain outside the agent process rather
-  than being extracted into its environment;
-- authorized HTTP payloads are scanned, not merely destination-filtered;
-- Git writes traverse a distinct gate with secret scanning and host-held
-  upstream credentials;
-- role policy is host-owned, composable, and separate from untrusted repo
-  content; and
-- local Firecracker/Apple Container execution preserves operator custody
-  without requiring a hosted sandbox platform.
-
 ## Borrowable ideas
 
 ### Already shipped or otherwise addressed
@@ -907,19 +642,6 @@ parallel agents visibly more capable, not merely safer.
 
 ### Still worth considering
 
-- **Sandbox Agent compatibility or an equivalent stable protocol (highest
-  priority):** spike running its server inside a bottle behind bot-bottle's
-  authenticated control plane. Compare its session/event schema, permission
-  model, restore semantics, and provider coverage with current provider
-  adapters. Adopt compatibility if it preserves the host-owned trust boundary;
-  otherwise specify bot-bottle's own stable API before building another UI.
-- **First-class browser/preview loop** (from CloudRouter and Eve): give a
-  bottle an optional browser/computer-use capability plus an operator-visible,
-  authenticated preview/screenshot surface. Treat its network access as part
-  of the bottle policy, not an implicit bypass.
-- **Provider-neutral transcript/event persistence** (from Sandbox Agent SDK):
-  retain enough normalized structure for replay and audit while preserving the
-  provider-native state needed for exact resume.
 - **Live network activity in the supervisor TUI** (from Docker sbx): show
   allowed and blocked connections and let the operator propose policy changes
   from the existing supervision surface.
@@ -930,11 +652,10 @@ parallel agents visibly more capable, not merely safer.
   closer review. This needs a carefully specified trust model before it can be
   more than a heuristic.
 
-Not worth borrowing: SDK-first *policy configuration* as used by boxlite /
-microsandbox (cuts against the reviewable declarative-manifest stance), and
-the hosted-SaaS custody model of tilde.run (cuts against the "infrastructure I
-control" goal). A provider-neutral runtime-control API is a separate concern
-and is worth borrowing.
+Not worth borrowing: the SDK-first programmatic API style of boxlite /
+microsandbox (cuts against the declarative-manifest stance), and the
+hosted-SaaS dashboard model of tilde.run (cuts against the
+"infrastructure I control" goal).
 
 ## Publishing and positioning verdict
 
@@ -958,15 +679,9 @@ bot-bottle remains unusual in combining:
 The practical wedge is “as easy as native yolo, with declarative role policy
 and self-hosted custody,” including scoped access to private LAN/Tailnet
 services that cloud-first runtimes cannot provide without additional network
-plumbing. The main competitive risks are now:
-
-- a local wrapper such as yolo-cage, claudebox, or Docker sbx growing a
-  role-manifest and credential-custody layer;
-- Sandbox Agent SDK becoming the standard control/session boundary and making
-  the runtime beneath it interchangeable; and
-- GUI products such as SuperHQ or CloudRouter adding equivalent policy and
-  audit depth before bot-bottle closes the browser/preview and
-  parallel-session UX gaps.
+plumbing. The main competitive risks are a local wrapper such as claudebox or
+Docker sbx growing a role-manifest layer, and GUI products such as SuperHQ
+adding equivalent policy and audit depth.
 
 ## Caveats
 

docs/research/sandbox-agent-sdk-architecture.md

@@ -1,536 +0,0 @@
-# Sandbox Agent SDK and bot-bottle: protocol versus product
-
-This note asks whether [Sandbox Agent SDK](https://github.com/rivet-dev/sandbox-agent)
-and bot-bottle compete for the same architectural layer, whether bot-bottle
-can productize the turnkey ecosystem/DX layer above it, and how far the
-Docker/OCI analogy actually holds.
-
-Research conducted 2026-07-27. Sandbox Agent SDK was at the `0.4.x` line,
-Apache 2.0, and documented support for Claude Code, Codex, OpenCode, Cursor,
-Amp, and Pi at the time of review.
-
-## Summary
-
-**The projects are complementary at the component boundary and competitive at
-the product boundary.** Sandbox Agent SDK normalizes how software controls a
-coding-agent process inside an arbitrary sandbox. bot-bottle decides what
-sandbox to create, what trusted role and policy it receives, how credentials
-and Git access cross the boundary, how traffic is constrained, and how an
-operator launches and supervises the result.
-
-The Docker analogy is useful with one correction:
-
-- Sandbox Agent SDK is not equivalent to Linux container APIs or OCI itself.
-  It is closer to a **containerd shim plus a portable exec/session API for
-  coding agents**. It adapts incompatible agent processes to one HTTP/SSE
-  contract.
-- A future independent agent-session specification would be the closer OCI
-  analogue.
-- bot-bottle can credibly occupy the **Docker Engine / Compose / Desktop**
-  layer: packaging, policy composition, lifecycle, networking, credentials,
-  storage, operator UX, and a one-command experience above interchangeable
-  agent adapters and isolation runtimes.
-
-That is a viable position, but “turnkey wrapper” undersells it. A thin wrapper
-is replaceable. The valuable product is a **turnkey, policy-first coding-agent
-runtime** whose manifest compiles trusted operator intent into multiple
-enforcement planes. Sandbox Agent SDK may be one internal process-control
-component of that product.
-
-The recommended direction is:
-
-1. Keep the bot-bottle manifest as the host-owned source of trusted policy.
-2. Spike Sandbox Agent SDK as the in-bottle provider/session adapter.
-3. Expose a stable, provider-neutral bot-bottle control API, compatible with
-   Sandbox Agent where practical.
-4. Keep security decisions and authoritative audit outside the sandbox.
-5. Build the ecosystem around policy packs, agent images, skills, backends,
-   operator UI, and trusted integrations—not around a proprietary transcript
-   protocol.
-
-## What each project is today
-
-### Sandbox Agent SDK
-
-Sandbox Agent is a Rust server that runs alongside the coding agent. A client
-connects over HTTP, streams events over SSE, and uses one API across agent
-implementations. Its documented surface includes:
-
-- creating and restoring agent sessions;
-- sending messages and streaming normalized events;
-- handling permissions;
-- configuring MCP servers, skills, and custom tools;
-- filesystem and managed-process APIs;
-- interactive terminal access;
-- computer-use/desktop operations;
-- a universal session/transcript schema;
-- an Inspector UI, React components, CLI, TypeScript SDK, and OpenAPI spec.
-
-It can run in embedded mode or inside E2B, Daytona, Modal, Cloudflare
-Containers, Agent Computer, BoxLite, Docker, and other environments. It
-explicitly leaves these concerns to the caller or sandbox provider:
-
-- sandbox creation and lifecycle;
-- Git repository management;
-- durable session storage;
-- network policy;
-- isolation strength; and
-- secure credential delivery.
-
-Its documented credential convenience path extracts real provider credentials
-from local agent configuration and passes them into the sandbox environment.
-That is convenient but is not an acceptable security boundary for bot-bottle.
-
-Sources:
-
-- [Sandbox Agent repository and architecture](https://github.com/rivet-dev/sandbox-agent)
-- [Sandbox Agent documentation](https://sandboxagent.dev/docs)
-- [HTTP API](https://sandboxagent.dev/docs/api-reference)
-- [Universal session/transcript schema](https://sandboxagent.dev/docs/session-transcript-schema)
-
-### bot-bottle
-
-bot-bottle is a host-side launch, policy, and enforcement system for existing
-coding-agent CLIs. Its current architecture includes:
-
-- agent and bottle manifests with composition via `extends:`;
-- a host-only trust boundary for roles, identity, and secret references;
-- provider templates and plugins for Claude Code, Codex, Pi, and custom
-  providers;
-- Firecracker on KVM Linux and Apple Container on macOS, with Docker fallback;
-- image construction and provider-specific provisioning;
-- default-deny inspected egress with path/method/header policy;
-- payload DLP on authorized channels;
-- real credentials held outside the agent and injected by the gateway;
-- Git mediation, upstream credential custody, and gitleaks scanning;
-- a per-host authenticated orchestrator and shared gateway;
-- named bottle lifecycle, resume, supervision, and audit state; and
-- a CLI/TUI intended to make full-permission agents operationally tolerable.
-
-The provider layer currently normalizes launch-time concerns—command, image,
-prompt delivery, files, skills, environment, verification, and provider-owned
-egress routes. It does **not** yet expose a stable provider-neutral runtime
-contract for sessions, messages, transcripts, terminals, or normalized events.
-That is the gap Sandbox Agent directly illuminates.
-
-Sources in this repository:
-
-- [`README.md`](../../README.md)
-- [`0070-per-host-orchestrator.md`](../prds/0070-per-host-orchestrator.md)
-- [`0026-agent-provider-templates.md`](../prds/0026-agent-provider-templates.md)
-- [`0053-user-provider-plugins.md`](../prds/0053-user-provider-plugins.md)
-- [`agent_provider.py`](../../bot_bottle/agent_provider.py)
-
-## The layer model
-
-The cleanest architecture has four layers:
-
-| Layer | Responsibility | Likely owner |
-|---|---|---|
-| Operator product | Install, select a role, launch, observe, intervene, resume, review changes | bot-bottle |
-| Trusted policy and lifecycle | Compose manifest, choose backend/image, hold credentials, enforce egress/Git, persist authoritative audit | bot-bottle |
-| Agent control protocol | Start provider process, create session, send input, stream normalized events, terminal/computer operations | Sandbox Agent or a compatible protocol |
-| Isolation primitive | VM/container/process boundary, filesystem, CPU/memory, networking substrate | Firecracker, Apple Container, Docker, E2B, Daytona, BoxLite, etc. |
-
-The important boundary is between trusted policy/lifecycle and agent control.
-The agent-control daemon runs in the environment being treated as untrusted.
-It can report what the agent says happened, but it cannot authoritatively prove
-that policy was enforced. Egress decisions, credential custody, Git scanning,
-bottle identity, and security audit must remain outside it.
-
-### Proposed composition
-
-```text
-operator UI / CLI / API
-          |
-          v
-bot-bottle orchestrator  (trusted)
-  - resolves manifest
-  - owns bottle identity and lifecycle
-  - stores authoritative audit
-  - authenticates clients
-          |
-          +--------------------------+
-          |                          |
-          v                          v
-isolation backend              shared gateway  (trusted)
-Firecracker / Apple / Docker   - egress policy + DLP
-          |                    - credential injection
-          |                    - Git mediation
-          v
-bottle / guest  (untrusted)
-  - Sandbox Agent server
-  - Claude Code / Codex / Pi subprocess
-  - workspace, skills, MCP configuration
-```
-
-The bot-bottle manifest would compile into both sides:
-
-- **outside the bottle:** backend, network, egress, credentials, Git,
-  supervision, identity, and authoritative lifecycle;
-- **inside the bottle:** selected provider, prompt, skills, MCP configuration,
-  startup arguments, and non-secret session metadata.
-
-Sandbox Agent should never receive real secrets merely because its API offers
-a credential extraction helper. Provider and forge requests should continue
-to use bot-bottle's placeholder/proxy pattern.
-
-## How accurate is the Docker/OCI analogy?
-
-### The useful part
-
-The container ecosystem separates low-level execution from a product that
-ordinary developers operate. OCI defines interoperable image, runtime, and
-distribution specifications. Docker Engine adds a daemon, API, CLI, object
-model, images, networks, volumes, and lifecycle; Docker Desktop and related
-products add installation, updates, UI, integrations, policy, and team
-workflows.
-
-The same separation can exist for coding agents:
-
-| Container ecosystem | Agent-sandbox ecosystem |
-|---|---|
-| OCI/runtime contract | A future open agent session/event contract |
-| `runc` / runtime adapter | Claude/Codex/Pi adapter |
-| containerd shim and task/exec API | Sandbox Agent server and HTTP/SSE session API |
-| containerd / CRI-style lifecycle | Sandbox-provider lifecycle APIs |
-| Docker Engine / Compose | bot-bottle orchestrator + manifests + backends + gateway |
-| Docker Desktop / Hub ecosystem | bot-bottle desktop/mobile UX, policy packs, agent images, skills, trusted integrations |
-
-Sandbox Agent makes coding-agent processes portable in roughly the way a shim
-makes runtimes consumable through a common lifecycle interface. bot-bottle can
-make the entire safe-agent system usable without asking the operator to
-assemble that plumbing.
-
-Official container references:
-
-- [Open Container Initiative](https://opencontainers.org/)
-- [OCI Runtime Specification](https://github.com/opencontainers/runtime-spec)
-- [Docker Engine architecture](https://docs.docker.com/engine/)
-- [Docker alternative runtimes and containerd shims](https://docs.docker.com/engine/daemon/alternative-runtimes/)
-
-### Where the analogy breaks
-
-1. **Sandbox Agent is an implementation, not an independent standard.**
-   Its OpenAPI document is public, but the project currently owns the server,
-   adapters, schema, and evolution. OCI is an independently governed set of
-   specifications with multiple implementations.
-2. **It sits above, not below, the isolation boundary.** Linux namespaces,
-   cgroups, VMs, and OCI runtimes create the boundary. Sandbox Agent controls a
-   process after some other system has created that boundary.
-3. **It reaches into product territory.** Inspector, React components,
-   computer-use APIs, skills/MCP configuration, transcripts, and restoration
-   are not merely low-level primitives. Sandbox Agent can continue growing
-   upward into the same UI and orchestration space bot-bottle might occupy.
-4. **Coding agents are semantically uneven.** Normalizing a container
-   lifecycle is easier than claiming full behavioral parity across Claude
-   Code, Codex, Cursor, Amp, OpenCode, and Pi. A universal schema can become a
-   lowest common denominator or accumulate provider-specific escape hatches.
-5. **The security contract is not standardized.** An agent-session API says
-   little about whether credentials are visible, egress is controlled, Git is
-   mediated, or audit is trustworthy. Those are core bot-bottle concerns.
-
-The positioning should therefore say “Docker-like product layer above an open
-agent-control protocol,” not “Sandbox Agent is OCI” or “bot-bottle implements
-OCI for agents.”
-
-## Can bot-bottle be the turnkey product layer?
-
-Yes, if it owns substantially more than launch syntax.
-
-The turnkey promise is:
-
-> Choose a trusted role, point it at a project, and run any supported coding
-> agent with full permissions. bot-bottle builds the environment, isolates it,
-> supplies only the capabilities it needs, keeps credentials outside, mediates
-> external writes, and gives the operator one place to watch and intervene.
-
-That product has several defensible jobs:
-
-### 1. Packaging and reproducibility
-
-- provider and toolchain images;
-- pinned, verified build inputs;
-- skills and MCP configuration;
-- role/bottle composition;
-- cached startup and portable environment definitions; and
-- compatibility testing across agents and backends.
-
-### 2. Trusted policy compilation
-
-The manifest is valuable because one reviewable document compiles into:
-
-- an isolation plan;
-- gateway routes and DLP policy;
-- credential slots;
-- Git-gate repositories and identities;
-- provider configuration;
-- supervision behavior; and
-- operator-facing preflight.
-
-Sandbox Agent's runtime configuration does not replace this. The policy must
-be resolved before an untrusted guest or agent-control daemon exists.
-
-### 3. Security enforcement
-
-- dedicated-kernel isolation where available;
-- no direct guest route to the internet;
-- credentials injected outside the agent;
-- content inspection on allowed destinations;
-- Git secrets scanning and upstream-key custody;
-- fail-closed policy resolution; and
-- authoritative host-side audit.
-
-This is the strongest current differentiation from a generic
-“Sandbox Agent + Docker/E2B” assembly.
-
-### 4. Lifecycle and operations
-
-- install and host preflight;
-- image build/update;
-- start, stop, resume, cleanup, and migration;
-- concurrent named agents;
-- state recovery after crashes;
-- live supervision and policy remediation; and
-- backend selection without changing the role definition.
-
-### 5. Ecosystem and DX
-
-A product layer can support:
-
-- curated provider images;
-- signed policy/bottle packs;
-- reusable role templates;
-- skills and MCP bundles;
-- backend plugins;
-- an authenticated desktop/web/mobile operator client;
-- browser/preview integration;
-- normalized transcripts and change review; and
-- team policy distribution and compliance exports.
-
-The analogy to Docker is strongest here: users adopt the coherent workflow and
-ecosystem, not because the low-level process API is proprietary.
-
-## Business and product positioning
-
-“Turnkey wrapper” is understandable internally but weak externally. It implies
-that the hard work lives underneath and that another wrapper can replace it.
-Prefer one of:
-
-- **The policy-first runtime for coding agents**
-- **Run any coding agent with full permissions, without giving it your host or
-  credentials**
-- **A turnkey local control plane for isolated coding agents**
-- **Docker-like packaging and operations for coding agents, with the security
-  boundary outside the agent**
-
-The open/product split could resemble the container ecosystem:
-
-### Open foundation
-
-- manifest schema and composition;
-- local CLI and core orchestrator;
-- provider adapters;
-- Firecracker/Apple Container/Docker backends;
-- gateway policy format and enforcement;
-- Sandbox Agent compatibility;
-- local audit and supervision; and
-- conformance tests for providers/backends/policy.
-
-### Productizable ecosystem/DX
-
-- polished desktop and mobile clients;
-- fleet/remote-host management;
-- signed and curated role/image/policy registry;
-- team policy distribution and administrative controls;
-- durable searchable transcripts and audit exports;
-- SSO, RBAC, retention, and tamper-evident audit;
-- managed update/compatibility channels;
-- remote browser/preview relay;
-- enterprise support; and
-- optional managed build/cache infrastructure.
-
-OCI itself is not the thing Docker sells. Interoperability expands the market;
-the product captures value through reliable packaging, workflow, distribution,
-management, and trust. bot-bottle should follow that logic rather than trying
-to make its session protocol the moat.
-
-## Strategic threat from Sandbox Agent
-
-Sandbox Agent is a real threat for three reasons:
-
-1. **It can become the integration default.** A frontend or agent platform can
-   integrate one API and choose among many agents and sandbox vendors.
-2. **It can own session data and UI.** The universal event schema, Inspector,
-   React components, restoration, terminal, and computer-use APIs give it a
-   natural path toward the operator surface.
-3. **Sandbox providers can move upward.** If E2B, Daytona, BoxLite, or another
-   runtime combines Sandbox Agent with adequate network policy and credential
-   custody, it can offer much of the turnkey stack.
-
-The threat is not that its manifest syntax is better. It currently has no
-equivalent trusted policy composition. The threat is that **the ecosystem may
-standardize around its API before bot-bottle has a stable external control
-surface**. In that world bot-bottle is evaluated as one sandbox provider,
-while the SDK and its consumers own the user relationship.
-
-## Why bot-bottle can still win its layer
-
-Sandbox Agent's scope exclusions align with bot-bottle's deepest work:
-
-- it does not choose or operate the sandbox provider;
-- it does not mediate Git;
-- it does not own network policy;
-- it does not securely deliver credentials;
-- it does not durably store sessions; and
-- it cannot make guest-generated telemetry authoritative.
-
-Those are not incidental features. Together they define the trusted system
-around an untrusted coding agent. bot-bottle also has a narrower and coherent
-initial customer: a developer or small operator who wants existing agent CLIs
-to run locally with broad permissions and bounded consequences.
-
-The durable advantage is therefore:
-
-> Sandbox Agent makes agents controllable. bot-bottle makes them safe and
-> operable.
-
-That sentence remains true only if bot-bottle closes its operator-DX gaps.
-Security without a browser/preview loop, stable API, normalized session view,
-and good parallel-task UX risks becoming an invisible backend feature.
-
-## Integration options
-
-### Option A — Embed Sandbox Agent inside each bottle
-
-bot-bottle launches Sandbox Agent as the provider process supervisor and
-connects it to the host orchestrator through a bottle-scoped authenticated
-channel.
-
-**Benefits**
-
-- immediate provider-neutral session API;
-- more supported agents;
-- normalized streaming and transcripts;
-- terminal, filesystem, process, and computer-use primitives;
-- Inspector/React ecosystem; and
-- less provider-specific reverse engineering in bot-bottle.
-
-**Risks**
-
-- `0.x` API/schema churn;
-- extra binary and release-supply-chain dependency;
-- lowest-common-denominator normalization;
-- conflict with provider-native resume state;
-- an in-guest daemon is attacker-controlled after guest compromise;
-- duplicate orchestration responsibilities; and
-- upstream can move into policy/lifecycle and compete more directly.
-
-**Security rule**
-
-Treat every event and state claim from Sandbox Agent as untrusted telemetry.
-Never delegate egress authorization, credential release, bottle identity,
-authoritative audit, or Git policy to it.
-
-### Option B — Implement a Sandbox Agent-compatible endpoint
-
-bot-bottle maps the external protocol onto its existing provider adapters and
-process model without running the upstream server.
-
-**Benefits**
-
-- ecosystem compatibility with tighter component control;
-- no in-guest daemon dependency; and
-- room to preserve bot-bottle-native lifecycle semantics.
-
-**Risks**
-
-- large and continuing compatibility burden;
-- “full feature coverage” is expensive across all providers;
-- accidental protocol fork; and
-- effort diverted from policy and UX differentiation.
-
-### Option C — Define an independent bot-bottle session API
-
-Build only the control surface bot-bottle needs.
-
-**Benefits**
-
-- clean fit with the trust model and persistent named bottles;
-- no upstream dependency; and
-- deliberate support for supervision and security events.
-
-**Risks**
-
-- recreates a fast-growing open-source project;
-- no existing client ecosystem;
-- slower browser/desktop/mobile work; and
-- increases the chance that Sandbox Agent becomes the de facto standard first.
-
-### Recommendation
-
-Start with **Option A as a bounded compatibility spike**, not a product
-commitment. Do not begin with a clean-room competing protocol.
-
-The spike should answer:
-
-1. Can Claude Code, Codex, and Pi retain exact native resume behavior?
-2. Can Sandbox Agent run without receiving real provider credentials?
-3. Can its server be reached through a bottle-scoped authenticated channel
-   without exposing the orchestrator or broadening guest egress?
-4. Which permission events overlap or conflict with bot-bottle supervision?
-5. Can normalized events be stored while clearly separating untrusted
-   transcript telemetry from authoritative gateway/Git audit?
-6. Can manifest skills, MCP servers, prompt, and startup arguments compile
-   deterministically into its configuration?
-7. Does its versioning policy permit a compatibility contract bot-bottle can
-   support?
-8. What image-size, startup-time, and update burden does the binary add?
-
-If the answers are favorable, adopt it behind a bot-bottle-owned interface and
-pin/test the supported version. If not, implement the smallest compatible
-subset needed by external clients before inventing a wholly separate API.
-
-## Product roadmap implications
-
-The competitor scan and this architecture comparison reorder the likely work:
-
-1. **Provider-neutral control/session compatibility spike**
-2. **Stable authenticated external bot-bottle API**
-3. **Normalized transcript/event persistence**
-4. **Parallel-session operator UI**
-5. **Browser/preview/computer-use capability**
-6. **Policy/image/skill distribution and signing**
-7. **Remote host/fleet management**
-
-This does not mean pausing security work. It means exposing the shipped
-security work through a product surface that can compete with the SDK-plus-
-sandbox ecosystem.
-
-## Decision
-
-Treat Sandbox Agent SDK as a potentially standard **agent process-control
-layer**, not as a sandbox replacement and not as a minor complementary
-library. Position bot-bottle one layer above it:
-
-- manifests express trusted role and environment policy;
-- bot-bottle compiles and enforces that policy across host, gateway, Git, and
-  isolation backends;
-- Sandbox Agent or a compatible protocol controls the selected agent process;
-  and
-- bot-bottle owns the turnkey operator experience.
-
-The Docker analogy is strategically sound when stated as:
-
-> Sandbox Agent can be the portable task/exec protocol; bot-bottle can be the
-> opinionated engine, Compose-like policy layer, and Desktop-like operator
-> product.
-
-It is not sound when stated as:
-
-> Sandbox Agent is OCI and bot-bottle is Docker.
-
-There is no independent OCI-equivalent agent specification yet, and Sandbox
-Agent already reaches into UI/session territory. Compatibility should be
-pursued quickly, while the trusted manifest/enforcement plane and operator
-experience remain the parts bot-bottle deliberately owns.

scripts/coverage.sh

@@ -13,7 +13,7 @@
 #     are re-executed; no KVM or Docker dependency.
 #
 # Pass "critical" as the last argument in either mode to also report just the
-# critical modules (ADR 0004 target: 85%).
+# critical modules (ADR 0004 target: 90%).
 set -euo pipefail
 
 cd "$(dirname "$0")/.."
@@ -34,8 +34,8 @@ if [ "${1:-}" = "aggregate" ]; then
     "$PY" -m coverage report -m
 
     if [ "${2:-}" = "critical" ]; then
-        echo "== critical modules (ADR 0004 minimum: 85%) ==" >&2
-        "$PY" -m coverage report --include="$CRITICAL" --fail-under=85
+        echo "== critical modules (ADR 0004 minimum: 90%) ==" >&2
+        "$PY" -m coverage report --include="$CRITICAL" --fail-under=90
     fi
     exit 0
 fi
@@ -55,6 +55,6 @@ echo "== combined report ==" >&2
 "$PY" -m coverage report -m
 
 if [ "${1:-}" = "critical" ]; then
-    echo "== critical modules (ADR 0004 minimum: 85%) ==" >&2
-    "$PY" -m coverage report --include="$CRITICAL" --fail-under=85
+    echo "== critical modules (ADR 0004 minimum: 90%) ==" >&2
+    "$PY" -m coverage report --include="$CRITICAL" --fail-under=90
 fi

scripts/critical-modules.txt

@@ -1,4 +1,4 @@
-# Critical security/logic core held to the >=85% coverage bar by
+# Critical security/logic core held to the >=90% coverage bar by
 # docs/decisions/0004-coverage-policy.md.
 #
 # SINGLE SOURCE OF TRUTH: scripts/coverage.sh (the `critical` report) and

scripts/diff_coverage.py

@@ -13,8 +13,8 @@ policy.
 
 Usage:
     scripts/coverage.sh                 # produce .coverage first
-    python3 scripts/diff_coverage.py    # gate against origin/main, min 80%
-    python3 scripts/diff_coverage.py --base main --min 75
+    python3 scripts/diff_coverage.py    # gate against origin/main, min 90%
+    python3 scripts/diff_coverage.py --base main --min 85
 """
 
 from __future__ import annotations
@@ -74,7 +74,7 @@ def main() -> int:
     ap = argparse.ArgumentParser()
     ap.add_argument("--base", default="origin/main",
                     help="git ref to diff against (default: origin/main)")
-    ap.add_argument("--min", type=float, default=80.0,
+    ap.add_argument("--min", type=float, default=90.0,
                     help="minimum %% of changed executable lines covered")
     args = ap.parse_args()
 

tests/unit/test_orchestrator_gateway.py

@@ -248,88 +248,6 @@ class TestDockerGateway(unittest.TestCase):
             calls,
         )
 
-    def test_ensure_running_replaces_poisoned_ipv6_network(self) -> None:
-        # A daemon that default-enables IPv6 leaves the gateway network with a
-        # malformed fdd0::/64 gateway, so `docker network inspect` exits
-        # non-zero with a ParseAddr error (not "No such network"). `--ipv6=false`
-        # can't heal an already-poisoned network — the create just no-ops on
-        # "already exists" — so _ensure_network must force-remove and recreate
-        # it, else every later subnet read keeps failing.
-        calls: list[list[str]] = []
-
-        def fake(argv: list[str], **_kw: object) -> Mock:
-            calls.append(argv)
-            if argv[:2] == ["docker", "ps"]:
-                return _proc(stdout="")
-            if argv[:3] == ["docker", "network", "inspect"]:
-                return _proc(
-                    returncode=1,
-                    stderr='ParseAddr("fdd0:0:0:4::1/64"): unexpected character, '
-                    'want colon (at "/64")',
-                )
-            return _proc()
-
-        with patch(_RUN_DOCKER, side_effect=fake):
-            self.sc.connect_to_orchestrator(_ORCH_URL, _TOKEN)
-        self.assertIn(["docker", "rm", "--force", self.sc.name], calls)
-        self.assertIn(["docker", "network", "rm", self.sc.network], calls)
-        creates = [c for c in calls if c[:3] == ["docker", "network", "create"]]
-        self.assertEqual(
-            [[
-                "docker", "network", "create",
-                "--ipv6=false",
-                "--subnet", DEFAULT_GATEWAY_SUBNET,
-                "--label",
-                f"bot-bottle.gateway-subnet={DEFAULT_GATEWAY_SUBNET}",
-                self.sc.network,
-            ]],
-            creates,
-        )
-
-    def test_ensure_running_creates_network_when_inspect_reports_absent(self) -> None:
-        # The absent case (inspect fails with "No such network") must NOT try to
-        # remove anything — it just creates. Guards the poisoned-vs-absent split.
-        calls: list[list[str]] = []
-
-        def fake(argv: list[str], **_kw: object) -> Mock:
-            calls.append(argv)
-            if argv[:3] == ["docker", "network", "inspect"]:
-                return _proc(returncode=1, stderr="Error: No such network: x")
-            return _proc(stdout="") if argv[:2] == ["docker", "ps"] else _proc()
-
-        with patch(_RUN_DOCKER, side_effect=fake):
-            self.sc.connect_to_orchestrator(_ORCH_URL, _TOKEN)
-        self.assertNotIn(["docker", "network", "rm", self.sc.network], calls)
-        creates = [c for c in calls if c[:3] == ["docker", "network", "create"]]
-        self.assertEqual(1, len(creates))
-
-    def test_ensure_running_does_not_destroy_on_generic_inspect_error(self) -> None:
-        # A generic inspect failure (daemon hiccup, permission, timeout) is NOT
-        # evidence of a poisoned network. Only the ParseAddr poison signature may
-        # take the destructive heal path; anything else must surface as an error
-        # without tearing down a possibly-healthy shared gateway.
-        calls: list[list[str]] = []
-
-        def fake(argv: list[str], **_kw: object) -> Mock:
-            calls.append(argv)
-            if argv[:2] == ["docker", "ps"]:
-                return _proc(stdout="")
-            if argv[:3] == ["docker", "network", "inspect"]:
-                return _proc(
-                    returncode=1,
-                    stderr="Cannot connect to the Docker daemon at unix:///var/run/docker.sock",
-                )
-            return _proc()
-
-        with patch(_RUN_DOCKER, side_effect=fake):
-            with self.assertRaises(GatewayError):
-                self.sc.connect_to_orchestrator(_ORCH_URL, _TOKEN)
-        # No mutation of the shared gateway: neither the container nor the
-        # network is removed, and nothing is recreated.
-        self.assertNotIn(["docker", "network", "rm", self.sc.network], calls)
-        self.assertFalse(any(c[:3] == ["docker", "rm", "--force"] for c in calls))
-        self.assertEqual([], [c for c in calls if c[:3] == ["docker", "network", "create"]])
-
     def test_ca_cert_pem_reads_from_container(self) -> None:
         with patch(_RUN_DOCKER, return_value=_proc(stdout=_CA_PEM)) as m:
             self.assertEqual(_CA_PEM, self.sc.ca_cert_pem())