@bongos/core 1.17.0

package/.claude/skills/session-handoff/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: session-handoff
+description: Emit a clean, paste-ready "next-steps" prompt to start a FRESH session with — so the next session begins with tight, curated context instead of dragging the whole transcript forward. Triggers when the user says "/session-handoff", "hand off to a fresh session", "give me a handoff prompt", "wrap up context for next time", "write the next-steps prompt", "I want to continue this in a new session", or "context is getting heavy, prep a fresh start". Read-only — it composes text, it changes no state.
+---
+
+You are producing a **handoff prompt**: a single, self-contained block of text the builder will **copy and paste as the first message of a brand-new session** to continue this work with a clean, light context.
+
+This is NOT the ship handoff and NOT the session close-out:
+- `/builder-ship` records handoff **notes** into the project ledger (backward-looking, for the record).
+- `/builder-end` **closes** the current session (resolve claim + teardown).
+- **This skill** writes the **starter prompt for the NEXT session** (forward-looking, for a human to paste). It resolves nothing and ships nothing.
+
+Use it at the end of a working session, or mid-session when the context is getting heavy and you'd rather continue fresh without losing the thread.
+
+## What to produce
+
+Emit **exactly one fenced code block** (so it's trivially copy-pasteable) containing the prompt below. Write it for a reader — and a future Claude session — that has **none** of this conversation's context: be specific, name files by path, and spell out task ids as hall links, never a bare `#NNN`.
+
+Keep it **short and curated** — a prompt, not a transcript. Include only what the next session needs to act. Use these sections, dropping any that are genuinely empty:
+
+1. **Goal / where things stand** — one or two lines: the overall objective and the current state.
+2. **Done this session** — a few bullets of what actually landed, each tagged `verified-prod` | `verified-smoke` | `implemented-not-verified` so the next session trusts the right things.
+3. **Next steps** — the ordered, concrete actions to take next. Name the exact files, functions, and task ids (as hall links). Lead with the single most important one.
+4. **Manual checks to run first** — anything the next session should verify before building on this work (a test to run, a page to load, a status to confirm).
+5. **Gotchas / watch-outs** — traps you hit or foresee (a stale-tooling merge, a flaky step, a gated path, a decision still open).
+6. **Pointers** — key files, ADRs, the relevant claim/task, and where to look. A short map so the next session doesn't re-hunt.
+7. **First action** — the literal first thing to do in the fresh session, e.g. "Run `/builder-reauth` then `/builder-start`," or "Claim [#1234](<buildersOrigin>#/task/1234) into a fresh `task-1234` worktree."
+
+## How to compose it
+
+- **Ground it in this session.** Pull the "Done" + "Next steps" from what actually happened here — the claims you worked, the files you touched, the decisions you made. If you hold an active claim, name it and its status.
+- **Mirror `docs/handoff-template.md`** for the section shape, but condense: a starter prompt is a fraction of a full session log.
+- **Self-contained.** Assume the fresh session starts cold. Every reference (file, task, ADR, URL) must be resolvable without this chat.
+- **Improvable.** If the builder edits the draft, keep their changes — this is their prompt to reuse and refine, not a fixed artifact.
+
+## Constraints
+
+- **Never include secrets** — no tokens, passwords, or the CLI session bearer. If a step needs a credential, name where it lives (Settings, `~/.config/otb/…`), never the value.
+- **Task/idea/blocker ids are hall links** (`[#NNN](<buildersOrigin>#/task/NNN)` using `domains.buildersOrigin`) or plain `task NNN` — never a bare `#NNN` (it mis-autolinks to GitHub and 404s).
+- **One fenced block, copy-clean.** No prose outside the block except a one-line "here's your handoff prompt — paste it into a fresh session" lead-in.
+- Read-only: this skill composes text and changes no state. It does not claim, ship, release, or write files.
+
+## Files this skill touches
+
+- Reads (for grounding, optional): the current session context, `docs/handoff-template.md`, and — if useful — the active claim via `node scripts/gds/api.js GET /me`.
+- Writes: nothing. Its only output is the handoff prompt printed in chat.

package/.claude/skills/status/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: status
+description: Answer "what's the status of X" / "what's left for criterion Cn" in one call. Triggers when the user says "/status", "what's left for C8", "status of GDS-V3", "how far along is the memory criterion", "what tasks remain to complete X", or asks how a version/criterion is progressing. Read-only — rolls up each done-when criterion → its gating tasks → live statuses → what's blocking.
+---
+
+You are answering a project-status question. Before this skill existed, doing so meant ~10 sequential GDS calls (grep the seed file for which tasks map to a criterion, eyeball a "Gates R55–R63" sentence, then re-query each task's status). The structured criterion↔task link (`task_criteria`, migration 055) + the `/status` CLI collapse that to one call. See ADR 0025 and task #435.
+
+## What this skill does
+
+Rolls up a version's done-when criteria → gating tasks → live statuses → what's left, in one call to the public `GET /api/gds/versions/:id/progress`. Read-only and unauthenticated, so it works even before `/builder-setup`. As of task 1288 it produces a **deterministic card** (same shape every time) — your job is to render it, not to re-summarize it.
+
+## How to render it
+
+Delivery is deterministic (task 1288, same methodology as `/builder-start`). The **card-delivery hook** (`.claude/hooks/session-cards.js`) runs `status.js` for you on a `/status` (or "what's left for C8" / "status of GDS-V4") prompt — pulling any version + `Cn` out of the prompt — and injects the **finished card + a one-step directive** into your context, a block beginning `[otb card — the status card below was pre-rendered …]`.
+
+1. **Normal path — follow the injected directive.** If that `[otb card …]` block is present, do exactly what it says: `show_widget` with the fenced HTML if you have `mcp__visualize` (call `mcp__visualize__read_me` once first, silently), otherwise output the fenced markdown **verbatim**. Render **once** — don't run `status.js`, don't lead with your own headline, don't rebuild the table, don't add a recommendation or recap. The card now owns the headline, the remaining-task list, and the unattributed-tasks note (this replaces the old freeform "interpret + relay" summary).
+
+2. **Fallback — no directive present** (hook disabled/failed, or an older checkout). Run it yourself:
+   - **If you have `show_widget`**: `node scripts/gds/status.js --widget [--version ID] [Cn]` → render the HTML verbatim with `title: "status_card"` (call `read_me` once first).
+   - **No widget renderer**: `node scripts/gds/status.js [--version ID] [Cn]` → print its stdout verbatim.
+   - `Cn` is positional (C8 = the 8th criterion); `--version` defaults to the live internal version; `--json` is the machine interface; `--hook` is the envelope the hook consumes — don't render those for the user unless asked.
+
+## Constraints
+
+- **Read-only.** This skill never claims, ships, or mutates anything. If the user then wants to act on a remaining task, hand off to `/builder-claim N`.
+- **`Cn` is positional**, computed live from the criteria ordering — so it stays correct even if criteria are added or reordered. Don't hardcode a Cn→slug mapping.
+- If `--version X` returns no criteria, say so plainly (that version may not have done-when criteria seeded) rather than implying 0% done.
+
+## Files this skill touches
+
+- Calls: `GET /api/gds/versions/:id/progress` (public)
+- Runs: `scripts/gds/status.js` (`--hook` / `--widget` render the card; default text + `--json` unchanged)
+- Delivered by: `.claude/hooks/session-cards.js` (the card-delivery hook, task 1288)

package/.devcontainer/Dockerfile

@@ -0,0 +1,69 @@
+# Amazonprimea 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

@@ -0,0 +1,73 @@
+# The Example Dev Box (`.devcontainer/`)
+
+This folder is **the box defined as code** — [ADR 0031 §3](../docs/adr/<redacted>.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/<redacted>.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

@@ -0,0 +1,19 @@
+{
+  "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

@@ -0,0 +1,93 @@
+{
+  // Amazonprimea 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": "Amazonprimea 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

@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+# healthcheck.sh — image-level toolchain integrity check for the Amazonprimea
+# 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

@@ -0,0 +1,198 @@
+#!/usr/bin/env bash
+# init-firewall.sh — default-deny outbound firewall for the Amazonprimea 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
+#   - amazonprimea.com + staging ................... the GDS API (/api/gds/* CLI)   [OTB]
+#   - 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"
+  "amazonprimea.com"
+  "staging.amazonprimea.com"
+  "generativelanguage.googleapis.com"
+  "pypi.org"
+  "files.pythonhosted.org"
+)
+
+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.
+if curl -fsS --max-time 10 https://amazonprimea.com/healthz 2>/dev/null | grep -q '^ok$'; then
+  log "  ✓ GDS API (amazonprimea.com) 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."