@bongos/core 1.19.1049 → 1.19.1051

package/.devcontainer/Dockerfile

@@ -1,69 +0,0 @@
-# Example Dev Box — the OTB builder environment as code (ADR 0031 §3).
-# Base Ubuntu 24.04 ships Python 3.12 (matches CI's art-pipeline cert) + a non-root
-# `vscode` sudo user. Node 22 / gh / Claude Code arrive as version-pinned features
-# (devcontainer.json); this Dockerfile covers the OS bits features don't: firewall
-# tooling + the art pipeline's system/Python deps. Builds identically on a DO box
-# and a laptop (x64/arm64). Full design + reconciliations: ./README.md.
-
-# Pinned to the multi-arch (amd64+arm64) image-index digest, not just the mutable
-# tag, so an upstream tag mutation / supply-chain swap can't silently replace the
-# box foundation. devcontainer-lock.json pins the features; this pins the base.
-# Bump the digest deliberately when intentionally moving to a newer base.
-FROM mcr.microsoft.com/devcontainers/base:ubuntu-24.04@sha256:d94c97dd9cacf183d0a6fd12a8e87b526e9e928307674ae9c94139139c0c6eae
-
-ARG TZ="Etc/UTC"
-ENV TZ="${TZ}"
-ENV DEVCONTAINER=true
-# Persisted shell history (see the volume mount in devcontainer.json).
-ENV HISTFILE=/commandhistory/.bash_history
-
-# --- OS packages --------------------------------------------------------------
-# Firewall tooling (iptables/ipset/iproute2 + dnsutils for `dig`), jq for the
-# GitHub-meta parse, the Python 3.12 toolchain, and the sharp from-source net.
-RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \
-  && apt-get install -y --no-install-recommends \
-     iptables ipset iproute2 dnsutils \
-     jq curl ca-certificates \
-     python3 python3-pip python3-venv python3-dev \
-     build-essential pkg-config \
-  && apt-get clean && rm -rf /var/lib/apt/lists/*
-
-# --- Python venv for the art pipeline (PEP 668 safe) --------------------------
-# Ubuntu 24.04 marks the system Python "externally managed", so a global
-# `pip install` is refused. A dedicated venv on PATH gives the art pipeline a
-# clean, writable 3.12 interpreter where `python3` "just works" — matching the
-# isolated interpreter CI gets from actions/setup-python. Deps themselves are
-# installed from the repo's pinned art/pipeline/requirements.txt at first-run
-# (post-create.sh), so the set stays manifest-driven and reproducible.
-ENV OTB_VENV=/opt/otb-venv
-RUN python3 -m venv "${OTB_VENV}" \
-  && "${OTB_VENV}/bin/pip" install --no-cache-dir --upgrade pip \
-  && chown -R vscode:vscode "${OTB_VENV}"
-# Prepend the venv to PATH for every shell + lifecycle command.
-ENV PATH="${OTB_VENV}/bin:${PATH}"
-
-# --- Firewall + health scripts ------------------------------------------------
-# NB the install path: the Claude Code feature ALSO ships its own
-# /usr/local/bin/init-firewall.sh, and features install AFTER this Dockerfile —
-# so installing ours at that path would be silently overwritten by the feature's
-# (which lacks our GDS/Gemini/PyPI allow-list). We install ours as
-# otb-init-firewall.sh and point postStart at it; the feature's copy sits unused.
-COPY init-firewall.sh /usr/local/bin/otb-init-firewall.sh
-COPY healthcheck.sh   /usr/local/bin/healthcheck.sh
-RUN chmod +x /usr/local/bin/otb-init-firewall.sh /usr/local/bin/healthcheck.sh
-
-# Persisted-history dir owned by the runtime user.
-RUN mkdir -p /commandhistory && chown -R vscode:vscode /commandhistory
-
-# --- Build-time integrity assertion -------------------------------------------
-# Fail the BUILD (not some later mystery at runtime) if the toolchain the box
-# promises isn't actually present. This is half of "doctor.js as health check":
-# the image-level half, asserting the box was built right. The builder-level
-# half (session/auth/git) runs as scripts/gds/doctor.js at attach time.
-RUN /usr/local/bin/healthcheck.sh --build || \
-    (echo "BUILD FAILED: toolchain integrity check did not pass" && exit 1)
-
-# Runtime health check for the DO-box-as-service case (#598): a parked/recreated
-# box can be probed for "is the toolchain intact" without a GDS session.
-HEALTHCHECK --interval=1m --timeout=15s --start-period=30s --retries=3 \
-  CMD /usr/local/bin/healthcheck.sh || exit 1

package/.devcontainer/README.md

@@ -1,73 +0,0 @@
-# The Example Dev Box (`.devcontainer/`)
-
-This folder is **the box defined as code** — [ADR 0031 §3](../docs/adr/0031-cloud-dev-environments-for-builders.md). It is the single environment every OTB builder runs Claude Code's *worker* in, whether they reach it from Claude Desktop → SSH, from the web → Remote Control, or locally via Docker Desktop. The same spec builds and runs identically on a DigitalOcean box and on a laptop.
-
-> Recall the mental model ([ADR 0031 "mental model"](../docs/adr/0031-cloud-dev-environments-for-builders.md), and [the onboarding primer](../docs/onboarding/primer.md)): the **screen** is your device, the **brain** is Anthropic's servers, and this is the **worker** — where the repo lives and the work happens.
-
-## What's here
-
-| File | Role |
-|---|---|
-| `devcontainer.json` | The box spec: base build, version-pinned features (Node 22, GitHub CLI, Claude Code), firewall capabilities, persisted volumes, lifecycle hooks. |
-| `Dockerfile` | Ubuntu 24.04 base + the OS-level bits features don't cover: firewall tooling, the art-pipeline system deps, and a PEP-668-safe Python venv. |
-| `init-firewall.sh` | The **default-deny outbound firewall** (ADR 0031 §6). Runs at every container start. Allow-lists only the hosts the toolchain needs. |
-| `post-create.sh` | First-run provisioning: folds in `setup-builder.sh`, installs art deps, verifies the stack. |
-| `healthcheck.sh` | Image-level toolchain integrity check — the "is the box built right?" half of doctor-as-health-check. |
-
-## The toolchain it guarantees
-
-- **Node 22** (`package.json` requires `>=22`) — via the `node` devcontainer feature.
-- **Python 3.12** — native to the Ubuntu 24.04 base, installed into a venv at `/opt/otb-venv`.
-- **sharp ^0.34** — the game/art native dep; prebuilt binaries on linux x64 **and** arm64, so no compile.
-- **The five art-pipeline libs** — Pillow, numpy, scipy, scikit-learn, certifi (from the pinned `art/pipeline/requirements.txt`).
-- **Claude Code + GitHub CLI + git** — via features.
-
-## Lifecycle
-
-1. **build** — Dockerfile lays down the OS deps + venv, then asserts the toolchain (`healthcheck.sh --build`) so a broken box fails the build, not a later mystery.
-2. **postCreate** (once) — `post-create.sh`: brings up the **firewall first** (so the dependency installs below run behind default-deny — no open-egress window during provisioning), then `setup-builder.sh --no-auth --skip-keys` (toolchain check + `npm ci` + `.env.local`), then `pip install` the art deps into the venv, then verify sharp + the art libs load.
-3. **postStart** (every start) — `sudo otb-init-firewall.sh` re-applies the default-deny egress firewall (iptables state resets each container start).
-4. **postAttach** (every attach) — `node scripts/gds/doctor.js` runs the *builder* health check (session/auth/git/env). Non-fatal, so a fresh, not-yet-authed box still attaches.
-
-On first connect you finish two runtime steps the box can't do for you: authenticate the GDS CLI (`node scripts/gds/setup.js` or `/builder-setup`) and, if you run the art pipeline, drop a Google AI Studio key in `~/.config/otb/env` (a persisted volume — survives rebuilds).
-
-## The firewall allow-list
-
-Default-deny outbound. Only these egress targets are permitted (keep it tight — every addition is attack surface):
-
-| Target | Why |
-|---|---|
-| Anthropic API + telemetry | the brain (tokens), Claude Code |
-| GitHub (published meta ranges) | `git` push/pull, `gh` |
-| npm registry | `npm ci` |
-| `example.com` + `staging.` | the GDS API (`/api/gds/*` CLI) |
-| `generativelanguage.googleapis.com` | the pixel-art pipeline (Gemini) |
-| `pypi.org` + `files.pythonhosted.org` | `pip install` the art deps |
-
-The firewall comes up **before the dependency installs** (in postCreate) and is **re-applied on every start** (postStart), so there is no open-egress window during provisioning — `npm ci` and `pip` run behind the allow-list (npm/PyPI/GitHub are on it). It **fails closed** by default: if it can't apply rules or verification fails, container start fails. The one documented escape hatch is `FIREWALL_OPTIONAL=1`, for a laptop Docker host that won't grant `NET_ADMIN` — there the builder is already root of their own machine, so egress lockdown is advisory (ADR 0031 §6 "honest limit"). Using it emits a loud, greppable `SECURITY AUDIT` line in the container logs. The DO box (#598) leaves it enforcing.
-
-## Running it
-
-- **Laptop (Docker Desktop):** open the repo in VS Code → "Reopen in Container", or `devcontainer up --workspace-folder .`. Apple-silicon (arm64) and Intel (x64) both work — sharp ships prebuilt binaries for each, and `node_modules` is a container-isolated volume so the host's macOS binaries never collide with the container's Linux ones.
-- **DigitalOcean box:** the per-builder provisioning (#598) builds this same spec on the box and exposes it over SSH / `claude rc`. Nothing in this folder is DO-specific — that's the portability the ADR commits to.
-
-### Known macOS-laptop caveat (does not affect the DO box)
-
-On a macOS Docker Desktop bind mount, VirtioFS can intermittently return `EDEADLK` ("Resource deadlock avoided") when reading repo files, especially while the host is heavily accessing the same folder. The symptom seen in testing was the postCreate **art-deps `pip install` failing** to read `art/pipeline/requirements.txt` (the box otherwise built fine — Node, Python, `sharp`, the firewall, and the runtime health check all passed). post-create.sh retries and is non-fatal, so the box still provisions. If art deps don't install: rebuild the container, or switch **Docker Desktop → Settings → General → file sharing to "gRPC FUSE"**. The DO box uses a native filesystem (a real clone, no bind mount), so this never occurs there.
-
-## Deliberate reconciliations (where this differs from a naïve reading of the ADR)
-
-- **Python 3.12, not "3.10".** ADR 0031 §3 says "Python 3.10"; that's a floor. CI (`portability-smoke.yml`) certifies the art pipeline on **3.12**, so the box uses 3.12 to *reproduce* CI rather than approximate it. 3.12 satisfies the `>=3.10` requirement in `setup-builder.sh`.
-- **`sharp` "build deps" without system libvips.** The ADR says "sharp build deps." sharp ^0.34 uses prebuilt binaries with libvips **bundled**, so no compile happens on x64/arm64. We install `build-essential` + `pkg-config` as the from-source safety net the ADR intends, but deliberately do **not** install system `libvips-dev` — a mismatched system libvips is a known footgun; sharp prefers its own.
-- **Allow-list is wider than the ADR's "Anthropic, GitHub, npm".** That parenthetical describes the *Anthropic feature's* defaults. Our box legitimately needs the GDS API + Gemini + PyPI or the CLI and art pipeline break behind the firewall. The list stays minimal and each entry is justified above.
-- **Base = Ubuntu 24.04 devcontainers image** (not Anthropic's reference `node:20`) — for the Node 22 + Python 3.12 parity above and a ready-made non-root `vscode` sudo user. The Claude Code *feature* is still Anthropic's, satisfying "the Anthropic Claude Code container feature."
-
-## Out of scope (separate ADR-0031 tasks)
-
-This task is the **foundation only**. It does not provision boxes, lock builders to one box, gate by rank, or wire billing:
-
-- **#597** — move prod deploy to GitHub Actions (no builder box holds the droplet key).
-- **#598** — per-builder DO box provisioning + auto-suspend (depends on this).
-- **#599** — Desktop managed-settings + the always-on `claude rc` service.
-- **#600** — rank-gated source access via the box.
-- **#602** — cost passthrough (org-funded starter → self-fund).

package/.devcontainer/devcontainer-lock.json

@@ -1,19 +0,0 @@
-{
-  "features": {
-    "ghcr.io/anthropics/devcontainer-features/claude-code:1.0": {
-      "version": "1.0.5",
-      "resolved": "ghcr.io/anthropics/devcontainer-features/claude-code@sha256:cfc2e7d3e9fd3b9b01f8d5cb158508a884c8c0ede2e23ed10f32dea5d4ffe69a",
-      "integrity": "sha256:cfc2e7d3e9fd3b9b01f8d5cb158508a884c8c0ede2e23ed10f32dea5d4ffe69a"
-    },
-    "ghcr.io/devcontainers/features/github-cli:1": {
-      "version": "1.1.0",
-      "resolved": "ghcr.io/devcontainers/features/github-cli@sha256:d22f50b70ed75339b4eed1ba9ecde3a1791f90e88d37936517e3bace0bbad671",
-      "integrity": "sha256:d22f50b70ed75339b4eed1ba9ecde3a1791f90e88d37936517e3bace0bbad671"
-    },
-    "ghcr.io/devcontainers/features/node:1": {
-      "version": "1.7.1",
-      "resolved": "ghcr.io/devcontainers/features/node@sha256:8c0de46939b61958041700ee89e3493f3b2e4131a06dc46b4d9423427d06e5f6",
-      "integrity": "sha256:8c0de46939b61958041700ee89e3493f3b2e4131a06dc46b4d9423427d06e5f6"
-    }
-  }
-}

package/.devcontainer/devcontainer.json

@@ -1,93 +0,0 @@
-{
-  // Example Dev Box — the OTB builder environment as code (ADR 0031 §3).
-  //
-  // This is the single box spec every builder runs, reached via Claude Desktop
-  // → SSH or the web → Remote Control (ADR 0031 §1). It builds identically on a
-  // DigitalOcean box and on a laptop via Docker Desktop. The pre-distributed
-  // Desktop "managed settings" that lock a non-technical builder to exactly this
-  // box are a separate task (#599); this file is the box itself.
-  "name": "Example Dev Box",
-
-  "build": {
-    "dockerfile": "Dockerfile",
-    // Context is this .devcontainer/ folder (the default). The Dockerfile only
-    // COPYs the two scripts that live here; nothing from the repo root is needed
-    // at build time (npm ci / pip install run at postCreate against the mounted
-    // workspace), so the COPY paths stay relative to this folder.
-    "context": ".",
-    "args": {
-      // Honor the host timezone when set, else UTC.
-      "TZ": "${localEnv:TZ:Etc/UTC}"
-    }
-  },
-
-  // Node 22, the GitHub CLI, and Claude Code arrive as version-pinned features
-  // rather than hand-rolled in the Dockerfile (the idiomatic, reproducible path).
-  // The Claude Code feature also installs Anthropic's default-deny egress posture
-  // tooling; our init-firewall.sh (postStart) is the OTB-tuned allow-list on top.
-  "features": {
-    "ghcr.io/devcontainers/features/node:1": { "version": "22" },
-    "ghcr.io/devcontainers/features/github-cli:1": {},
-    "ghcr.io/anthropics/devcontainer-features/claude-code:1.0": {}
-  },
-
-  // NET_ADMIN + NET_RAW let the postStart firewall manage iptables/ipset. Without
-  // these the firewall fails closed (or warns if FIREWALL_OPTIONAL=1) — see
-  // init-firewall.sh. Docker Desktop and a DO Docker host both honor cap-add.
-  "runArgs": ["--cap-add=NET_ADMIN", "--cap-add=NET_RAW"],
-
-  // The devcontainers Ubuntu base ships a non-root `vscode` user with passwordless
-  // sudo (needed for the postStart firewall). Run as that user, not root.
-  "remoteUser": "vscode",
-
-  "containerEnv": {
-    "DEVCONTAINER": "true",
-    // Where the art-pipeline Python venv lives (the Dockerfile prepends its bin
-    // to PATH); post-create.sh and healthcheck.sh reference it.
-    "OTB_VENV": "/opt/otb-venv",
-    // A modest Node heap headroom for the dev server + art pipeline.
-    "NODE_OPTIONS": "--max-old-space-size=4096"
-  },
-
-  // Standardize the in-container repo path (matches Anthropic's reference) so
-  // docs/scripts can assume /workspace regardless of the host folder name.
-  "workspaceFolder": "/workspace",
-  "workspaceMount": "source=${localWorkspaceFolder},target=/workspace,type=bind,consistency=delegated",
-
-  // Named volumes (NOT binds — nothing secret lands in the repo or image, per
-  // ADR 0022):
-  //   - node_modules: a container-ISOLATED volume so the host's native binaries
-  //     (e.g. a macOS-built `sharp`) never leak into this linux box, and vice
-  //     versa. This is what makes "runs identically on a laptop" true — without
-  //     it, bind-mounting the repo from macOS breaks sharp in the container.
-  //   - the Claude Code login/config (so a rebuild doesn't force re-login),
-  //   - shell history (quality-of-life),
-  //   - ~/.config/otb (the per-builder Gemini key + GDS session survive rebuilds).
-  "mounts": [
-    "source=otb-node-modules-${devcontainerId},target=/workspace/node_modules,type=volume",
-    "source=otb-claude-config-${devcontainerId},target=/home/vscode/.claude,type=volume",
-    "source=otb-bashhistory-${devcontainerId},target=/commandhistory,type=volume",
-    "source=otb-config-${devcontainerId},target=/home/vscode/.config/otb,type=volume"
-  ],
-
-  // Lifecycle:
-  //   postCreate — once, after the repo is mounted: fold in setup-builder.sh,
-  //                install art deps, verify the stack (post-create.sh).
-  //   postStart  — every start: bring up the default-deny firewall.
-  //   postAttach — every attach: run the BUILDER health check (session/auth/git).
-  //                Non-fatal (|| true) so a not-yet-authed fresh box still attaches.
-  "postCreateCommand": "bash .devcontainer/post-create.sh",
-  "postStartCommand": "sudo /usr/local/bin/otb-init-firewall.sh",
-  "postAttachCommand": "node scripts/gds/doctor.js || true",
-  "waitFor": "postCreateCommand",
-
-  "customizations": {
-    "vscode": {
-      "extensions": [
-        "anthropic.claude-code",
-        "dbaeumer.vscode-eslint",
-        "esbenp.prettier-vscode"
-      ]
-    }
-  }
-}

package/.devcontainer/healthcheck.sh

@@ -1,84 +0,0 @@
-#!/usr/bin/env bash
-# healthcheck.sh — image-level toolchain integrity check for the Example
-# Dev Box (ADR 0031 §3).
-#
-# This is the IMAGE half of "doctor.js as the health check": it answers "was the
-# box built correctly?" using only what the image itself provides — no GDS
-# session, no repo checkout, no network. The BUILDER half ("is *this builder*
-# authed, hooked, and clean?") is scripts/gds/doctor.js, run at attach time.
-#
-# Two modes:
-#   --build   run as the final Dockerfile RUN step (fail the build on a bad box).
-#   (default) the runtime HEALTHCHECK / a recreated-box probe (#598).
-#
-# Both check the same stable, image-level toolchain. Repo-level facts (sharp in
-# node_modules, the art libs in the venv) are installed at first-run by
-# post-create.sh and verified there — they are intentionally NOT gated here so
-# the container never flaps "unhealthy" during provisioning.
-#
-# NOTE on ordering: Node, the GitHub CLI, and Claude Code are installed by
-# devcontainer *features*, which run AFTER the Dockerfile is built. So the
-# --build assertion can't see Node — it checks only what the Dockerfile itself
-# provides (the Python venv + firewall tooling). The Node check runs at runtime,
-# where features are present.
-
-set -uo pipefail
-
-MODE="${1:-runtime}"
-fails=0
-
-ok()   { echo "  ok   $*"; }
-bad()  { echo "  FAIL $*"; fails=$((fails + 1)); }
-
-# Node >= 22 — runtime only (feature-installed after the Dockerfile build).
-if [ "$MODE" != "--build" ]; then
-  if command -v node >/dev/null 2>&1; then
-    nver="$(node --version 2>/dev/null)"
-    nmaj="$(echo "$nver" | sed 's/^v//' | cut -d. -f1)"
-    if [[ "$nmaj" =~ ^[0-9]+$ ]] && [ "$nmaj" -ge 22 ]; then
-      ok "node $nver (>= 22)"
-    else
-      bad "node $nver found, need >= 22"
-    fi
-  else
-    bad "node not on PATH"
-  fi
-else
-  echo "  --   node check deferred to runtime (feature-installed after the Dockerfile)"
-fi
-
-# Python >= 3.12 (the venv interpreter — must be first on PATH)
-if command -v python3 >/dev/null 2>&1; then
-  pyver="$(python3 -c 'import sys; print("%d.%d" % sys.version_info[:2])' 2>/dev/null || echo "?")"
-  pymaj="${pyver%%.*}"; pymin="${pyver#*.}"
-  if [[ "$pymaj" =~ ^[0-9]+$ ]] && [[ "$pymin" =~ ^[0-9]+$ ]] \
-     && { [ "$pymaj" -gt 3 ] || { [ "$pymaj" -eq 3 ] && [ "$pymin" -ge 12 ]; }; }; then
-    ok "python ${pyver} (>= 3.12) [$(command -v python3)]"
-  else
-    bad "python ${pyver} found, need >= 3.12"
-  fi
-  # The venv must be the active interpreter so the art pipeline's deps resolve.
-  if [ -n "${OTB_VENV:-}" ] && [ "$(command -v python3)" = "${OTB_VENV}/bin/python3" ]; then
-    ok "art-pipeline venv active (${OTB_VENV})"
-  else
-    bad "expected venv python at ${OTB_VENV:-<unset>}/bin/python3, got $(command -v python3)"
-  fi
-else
-  bad "python3 not on PATH"
-fi
-
-# Firewall tooling present (the default-deny boundary depends on it).
-for tool in iptables ipset dig jq; do
-  if command -v "$tool" >/dev/null 2>&1; then
-    ok "$tool present"
-  else
-    bad "$tool missing (firewall/init would fail)"
-  fi
-done
-
-if [ "$fails" -eq 0 ]; then
-  [ "$MODE" = "--build" ] && echo "toolchain integrity: OK (build)"
-  exit 0
-fi
-echo "toolchain integrity: ${fails} problem(s)"
-exit 1

package/.devcontainer/init-firewall.sh

@@ -1,234 +0,0 @@
-#!/usr/bin/env bash
-# init-firewall.sh — default-deny outbound firewall for the Example Dev Box.
-#
-# ADR 0031 §3 + §6: the box is an org-controlled, egress-restricted surface. This
-# script flips the container to default-DROP and then allow-lists ONLY the hosts
-# the OTB toolchain legitimately needs. Everything else is blocked, so a builder
-# session (or a compromised dependency) cannot quietly exfiltrate to an arbitrary
-# host.
-#
-# Mechanism (mirrors Anthropic's reference init-firewall.sh):
-#   1. Resolve every allow-listed host to IPs WHILE egress is still open.
-#   2. Stuff them into an `ipset` (hash:net so GitHub's CIDR ranges fit).
-#   3. Flip INPUT/OUTPUT/FORWARD to DROP, then re-allow loopback, established
-#      connections, DNS, SSH, and OUTPUT to the ipset.
-#   4. Verify: a blocked host must fail; an allow-listed host must succeed.
-#
-# Allow-list (and WHY each is here — keep this tight, every addition is egress):
-#   - GitHub  (api.github.com/meta ranges) ......... git push/pull, `gh`
-#   - npm registry (registry.npmjs.org) ............ `npm ci`
-#   - Anthropic API (api.anthropic.com + telemetry)  the brain (tokens), Claude Code
-#   - THIS instance's own API host(s) .............. the GDS API (/api/gds/* CLI)
-#     (resolved from config/branding.json at runtime — task 1002757; a hardcoded
-#      founder host allow-listed someone else's server and BLOCKED the builder's own)
-#   - generativelanguage.googleapis.com ............ the pixel-art pipeline (Gemini) [OTB]
-#   - pypi.org + files.pythonhosted.org ............ `pip install` art deps          [OTB]
-#
-# Runs as root via `sudo` from the devcontainer postStartCommand. Needs the
-# NET_ADMIN + NET_RAW capabilities (granted by runArgs in devcontainer.json).
-#
-# Fail posture: FAIL-CLOSED by default. If the rules cannot be applied or the
-# verification fails, the script exits non-zero. Set FIREWALL_OPTIONAL=1 to
-# downgrade a cap/permission failure to a loud warning that still lets the
-# container boot — intended ONLY for a laptop Docker host that won't grant
-# NET_ADMIN (where the builder is already root of their own machine, so egress
-# lockdown is advisory anyway — see ADR 0031 §6 "honest limit"). The DO box
-# (#598) sets FIREWALL_OPTIONAL unset, so it always enforces.
-
-set -euo pipefail
-IFS=$'\n\t'
-
-OPTIONAL="${FIREWALL_OPTIONAL:-0}"
-
-# Hosts to allow-list by name (resolved via dig at runtime). GitHub is handled
-# separately via its published meta ranges. Keep this list minimal.
-ALLOWED_HOSTS=(
-  "registry.npmjs.org"
-  "api.anthropic.com"
-  "statsig.anthropic.com"
-  "sentry.io"
-  "generativelanguage.googleapis.com"
-  "pypi.org"
-  "files.pythonhosted.org"
-  # THIS instance's own hosts are appended below from its branding pack.
-)
-
-# Append the instance's OWN API hosts, read from config/branding.json at runtime
-# (task 1002757). Was two hardcoded founder hosts, which allow-listed someone
-# else's server and left the builder's own GDS API blocked — the devcontainer
-# then failed every /builder-* call for a reason nothing in the log explained.
-# GDS_ALLOW_HOSTS (space/comma separated) overrides for a non-standard setup.
-REPO_ROOT_FW="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
-INSTANCE_HOSTS="${GDS_ALLOW_HOSTS:-}"
-if [ -z "$INSTANCE_HOSTS" ]; then
-  INSTANCE_HOSTS="$(node -e '
-    const d = (require(process.argv[1]).branding().domains) || {};
-    const hosts = new Set();
-    // Only *_ORIGIN-shaped values yield a host, and only a real public FQDN
-    // counts: the neutral starter pack carries localhost:3000 and bare subdomain
-    // PREFIXES ("sandbox-", "term-"), none of which is an allow-listable host.
-    for (const v of Object.values(d)) {
-      if (typeof v !== "string" || !v.trim()) continue;
-      let host = null;
-      try { host = new URL(v).hostname; } catch { host = v.trim(); }
-      if (!host) continue;
-      if (!/^(?=.{1,253}$)[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$/i.test(host)) continue;
-      if (/^localhost$/i.test(host)) continue;
-      hosts.add(host.toLowerCase());
-    }
-    process.stdout.write([...hosts].join(" "));
-  ' "$REPO_ROOT_FW/src/branding" 2>/dev/null || true)"
-fi
-for h in ${INSTANCE_HOSTS//,/ }; do
-  [ -n "$h" ] && ALLOWED_HOSTS+=("$h")
-done
-
-log()  { echo "[firewall] $*"; }
-die() {
-  # Honor the documented escape hatch: a cap/permission failure on a laptop
-  # host downgrades to a warning instead of bricking container startup.
-  # The bypass is env-driven, so it can't be access-controlled from inside the
-  # script — the mitigation is a LOUD, greppable audit line so any use is
-  # visible in container logs / log aggregation. On the org DO box this must
-  # never be set; if this banner appears there, investigate.
-  if [ "$OPTIONAL" = "1" ]; then
-    log "==================== SECURITY AUDIT ===================="
-    log "egress firewall DISABLED via FIREWALL_OPTIONAL=1"
-    log "  reason: $*"
-    log "  the box is running WITHOUT default-deny egress (laptop-only escape hatch)"
-    log "======================================================="
-    exit 0
-  fi
-  log "ERROR: $*"
-  log "If this host genuinely cannot grant NET_ADMIN (e.g. a restricted laptop Docker),"
-  log "re-run with FIREWALL_OPTIONAL=1 to boot without egress lockdown."
-  exit 1
-}
-
-# Pre-flight: we must be root and have the iptables/ipset tooling + caps.
-if [ "$(id -u)" -ne 0 ]; then
-  die "must run as root (expected: sudo $0)"
-fi
-command -v iptables >/dev/null 2>&1 || die "iptables not installed"
-command -v ipset    >/dev/null 2>&1 || die "ipset not installed"
-command -v dig      >/dev/null 2>&1 || die "dig (dnsutils) not installed"
-
-# A NET_ADMIN probe: try a harmless list. If the kernel refuses, we lack the cap.
-if ! iptables -L >/dev/null 2>&1; then
-  die "cannot manage iptables (NET_ADMIN capability missing?)"
-fi
-
-log "resolving allow-list while egress is still open…"
-
-# Fresh ipset. hash:net so we can store both single IPs and CIDR ranges.
-# create -exist + flush (not destroy+create): on a manual re-run an iptables
-# OUTPUT rule may still reference the set, which makes `destroy` fail. Flushing
-# empties it in place while keeping the object valid.
-ipset create allowed-domains hash:net -exist
-ipset flush allowed-domains
-
-add_ip() {
-  # Validate it looks like an IPv4 (or CIDR) before adding, so a bad DNS answer
-  # can't inject garbage into the set.
-  local ip="$1"
-  if [[ "$ip" =~ ^[0-9]{1,3}(\.[0-9]{1,3}){3}(/[0-9]{1,2})?$ ]]; then
-    ipset add allowed-domains "$ip" 2>/dev/null || true
-  fi
-}
-
-# --- GitHub: use the published meta ranges (covers github.com, api, git, web) -
-log "  + GitHub meta ranges"
-gh_meta="$(curl -fsS --max-time 20 https://api.github.com/meta || true)"
-if [ -n "$gh_meta" ] && command -v jq >/dev/null 2>&1; then
-  # .web + .api + .git are the egress-relevant range groups.
-  while read -r cidr; do
-    [ -n "$cidr" ] && add_ip "$cidr"
-  done < <(echo "$gh_meta" | jq -r '(.web // []) + (.api // []) + (.git // []) | .[]' 2>/dev/null | grep -E '^[0-9]+\.' || true)
-else
-  # Fallback: resolve the hostnames directly if the meta API is unavailable.
-  log "    (meta API unavailable — falling back to direct resolution)"
-  for h in github.com api.github.com codeload.github.com objects.githubusercontent.com; do
-    while read -r ip; do add_ip "$ip"; done < <(dig +short +noall +answer A "$h" 2>/dev/null | grep -E '^[0-9]+\.' || true)
-  done
-fi
-
-# --- Everything else: resolve by name -----------------------------------------
-for host in "${ALLOWED_HOSTS[@]}"; do
-  log "  + $host"
-  while read -r ip; do
-    add_ip "$ip"
-  done < <(dig +short +noall +answer A "$host" 2>/dev/null | grep -E '^[0-9]+\.' || true)
-done
-
-# --- Host networking: keep the container reachable from / to its Docker host --
-# Allow the host gateway + the container's own /24 so SSH in, the dev server,
-# and DNS-to-the-Docker-resolver keep working after we flip to DROP.
-host_ip="$(ip route | awk '/default/ {print $3; exit}')"
-if [ -n "${host_ip:-}" ]; then
-  host_net="$(echo "$host_ip" | sed 's/\.[0-9]*$/.0\/24/')"
-  log "  + host network ${host_net}"
-  add_ip "$host_net"
-fi
-
-n="$(ipset list allowed-domains | grep -cE '^[0-9]+\.' || true)"
-log "allow-list built: ${n} entries"
-[ "$n" -gt 0 ] || die "allow-list is empty — refusing to flip to default-DROP (would sever everything)"
-
-log "applying default-deny policy…"
-
-# Flush prior rules so re-runs are idempotent.
-iptables -F
-iptables -X 2>/dev/null || true
-
-# Loopback — always.
-iptables -A INPUT  -i lo -j ACCEPT
-iptables -A OUTPUT -o lo -j ACCEPT
-
-# Established/related return traffic.
-iptables -A INPUT  -m state --state ESTABLISHED,RELATED -j ACCEPT
-iptables -A OUTPUT -m state --state ESTABLISHED,RELATED -j ACCEPT
-
-# DNS — keep resolution working at runtime (long-running procs re-resolve).
-iptables -A OUTPUT -p udp --dport 53 -j ACCEPT
-iptables -A OUTPUT -p tcp --dport 53 -j ACCEPT
-
-# SSH — the Desktop/Remote-Control on-ramp (ADR 0031 §1).
-iptables -A INPUT  -p tcp --dport 22 -j ACCEPT
-iptables -A OUTPUT -p tcp --dport 22 -j ACCEPT
-
-# The actual allow-list: outbound only to resolved, vetted IPs.
-iptables -A OUTPUT -m set --match-set allowed-domains dst -j ACCEPT
-
-# Default DROP for everything not explicitly allowed above.
-iptables -P INPUT   DROP
-iptables -P FORWARD DROP
-iptables -P OUTPUT  DROP
-
-log "verifying…"
-
-# A blocked host MUST fail (proves the deny is real).
-if curl -fsS --max-time 6 https://example.com >/dev/null 2>&1; then
-  die "verification FAILED: example.com is reachable but should be blocked"
-fi
-log "  ✓ blocked host (example.com) is unreachable"
-
-# An allow-listed host MUST succeed (proves we didn't sever everything).
-if ! curl -fsS --max-time 10 https://api.github.com/zen >/dev/null 2>&1; then
-  die "verification FAILED: api.github.com is unreachable but should be allowed"
-fi
-log "  ✓ allow-listed host (api.github.com) is reachable"
-
-# Our own GDS API must be reachable (the CLI depends on it). Non-fatal warn:
-# the host may be mid-deploy; the firewall correctness is already proven above.
-# The instance's OWN first API host (task 1002757 — was a founder literal, so this
-# probe reported a stranger's health as the container's connectivity).
-GDS_PROBE_HOST="$(printf '%s\n' ${INSTANCE_HOSTS//,/ } | head -n 1)"
-if [ -z "$GDS_PROBE_HOST" ]; then
-  log "  · no instance API host resolved from the branding pack — skipping the GDS reachability probe"
-elif curl -fsS --max-time 10 "https://$GDS_PROBE_HOST/healthz" 2>/dev/null | grep -q '^ok$'; then
-  log "  ✓ GDS API ($GDS_PROBE_HOST) is reachable"
-else
-  log "  ! GDS API healthz did not return ok (host may be redeploying) — allow rule is in place"
-fi
-
-log "default-deny firewall active."