diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 3ebd7d5..7f79cc5 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -2,16 +2,189 @@ name: CI
 
 on:
   push:
+    branches: [main]
   pull_request:
 
 jobs:
-  bash-syntax:
-    name: bash -n
+  static:
+    name: static checks
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - name: Syntax-check shell scripts
         run: |
-          bash -n claude-box
-          bash -n entrypoint.sh
-          bash -n userns-probe.sh
+          for f in claude-box codex-box libcage.sh entrypoint-cage.sh \
+                   userns-probe.sh payload-init-claude.sh; do
+            bash -n "$f"
+          done
+          echo "parse OK"
+      - name: Cage boundary (static)
+        run: |
+          set -euo pipefail
+          scripts="claude-box codex-box libcage.sh entrypoint-cage.sh userns-probe.sh payload-init-claude.sh"
+          # The engine block exists exactly once: among the shell sources, engine_args
+          # is built only in the cage library, never in a payload wrapper.
+          hits=$(grep -ln 'engine_args+=(' $scripts || true)
+          [ "$hits" = "libcage.sh" ] \
+            || { echo "FAIL: engine_args built outside libcage.sh:"; echo "$hits"; exit 1; }
+          # Both wrappers compose the cage rather than reimplementing it.
+          for w in claude-box codex-box; do
+            grep -q 'source .*libcage.sh' "$w" \
+              || { echo "FAIL: $w does not source libcage.sh"; exit 1; }
+          done
+          # Payload Dockerfiles are FROM the shared cage base.
+          for d in Dockerfile.claude Dockerfile.codex; do
+            grep -q '^FROM cage-base' "$d" \
+              || { echo "FAIL: $d is not FROM cage-base"; exit 1; }
+          done
+          echo "static boundary OK"
+
+  acceptance:
+    name: cage acceptance (--engine none)
+    runs-on: ubuntu-latest
+    needs: static
+    steps:
+      - uses: actions/checkout@v5
+
+      # Build cage-base + both payload images through the real launchers, so the
+      # image build path itself is under test. --engine none skips the nested
+      # dockerd (the one part hosted runners can't reliably provide); every check
+      # below is independent of it.
+      - name: Warm images via the launchers
+        run: |
+          set -euo pipefail
+          mkdir -p /tmp/cbtest && cd /tmp/cbtest && git init -q
+          CLAUDE_BOX_EXEC=1 "$GITHUB_WORKSPACE/claude-box" --engine none -- true
+          CODEX_BOX_EXEC=1  "$GITHUB_WORKSPACE/codex-box"  --engine none -- true
+
+      # Part 1 — the cage base carries no harness; each payload adds only its own.
+      - name: Image boundary
+        run: |
+          set -euo pipefail
+          if docker run --rm --entrypoint sh cage-base -c 'command -v claude || command -v codex'; then
+            echo "FAIL: cage-base contains an agent harness"; exit 1
+          fi
+          docker run --rm --entrypoint sh cage-base -c '
+            for b in git gh docker dockerd-rootless.sh gosu uv; do
+              command -v "$b" >/dev/null || { echo "MISSING $b"; exit 1; }
+            done'
+          docker run --rm --entrypoint sh claude-box -c 'command -v claude >/dev/null && ! command -v codex  >/dev/null'
+          docker run --rm --entrypoint sh codex-box  -c 'command -v codex  >/dev/null && ! command -v claude >/dev/null'
+          echo "image boundary OK"
+
+      # Part 4 + headless runbook — the exit-status contract holds identically
+      # through each wrapper: harness status, signal deaths, and an in-box timeout
+      # all propagate verbatim (none of these are launcher faults).
+      - name: Exit-status contract
+        run: |
+          set -euo pipefail
+          cd /tmp/cbtest
+          check() { # <box> <exec-var> <want> <cmd...>
+            local box="$1" var="$2" want="$3"; shift 3
+            local got=0
+            env "$var=1" "$GITHUB_WORKSPACE/$box" --engine none -- "$@" >/dev/null 2>&1 || got=$?
+            [ "$got" = "$want" ] \
+              || { echo "FAIL: $box '$*' exited $got, want $want"; exit 1; }
+            echo "OK: $box '$*' -> $got"
+          }
+          for pair in "claude-box:CLAUDE_BOX_EXEC" "codex-box:CODEX_BOX_EXEC"; do
+            box="${pair%%:*}"; var="${pair##*:}"
+            check "$box" "$var" 0   bash -c 'exit 0'
+            check "$box" "$var" 7   bash -c 'exit 7'
+            check "$box" "$var" 130 bash -c 'kill -INT $$'    # SIGINT
+            check "$box" "$var" 143 bash -c 'kill -TERM $$'   # SIGTERM
+            check "$box" "$var" 137 bash -c 'kill -KILL $$'   # SIGKILL
+            check "$box" "$var" 124 timeout 1 sleep 5         # in-box timeout
+          done
+          # stdin round-trips through the cage (proves -i gating).
+          out=$(printf 'PING\n' | env CLAUDE_BOX_EXEC=1 "$GITHUB_WORKSPACE/claude-box" --engine none -- cat)
+          [ "$out" = "PING" ] || { echo "FAIL: stdin round-trip returned '$out'"; exit 1; }
+          echo "exit contract OK"
+
+      # Part 3 — a mounted host socket is refused before the harness ever runs.
+      # The mount array must be passed via .env.<label> (the launcher sources it
+      # in-process; bash cannot export an array across exec).
+      - name: Host socket refused
+        run: |
+          set -euo pipefail
+          cd /tmp/cbtest
+          for pair in "claude-box:CLAUDE_BOX_EXEC" "codex-box:CODEX_BOX_EXEC"; do
+            box="${pair%%:*}"; var="${pair##*:}"
+            printf '%s_EXTRA_MOUNTS=("/var/run/docker.sock:/var/run/docker.sock")\n' \
+              "${var%_EXEC}" > ".env.${box}"
+            rc=0
+            env "$var=1" "$GITHUB_WORKSPACE/$box" --engine none -- true >out.txt 2>err.txt || rc=$?
+            rm -f ".env.${box}"
+            grep -q 'FATAL: /var/run/docker.sock is mounted from the host' err.txt \
+              || { echo "FAIL: $box did not refuse a mounted host socket"; cat err.txt; exit 1; }
+            [ "$rc" != 0 ] \
+              || { echo "FAIL: $box exited 0 with a host socket mounted"; exit 1; }
+            echo "OK: $box refused host socket (exit $rc)"
+          done
+          echo "socket refusal OK"
+
+      # Headless runbook — a launcher fault emits a distinct exit code and a
+      # machine-readable stderr line, even with the nested engine disabled. A
+      # create-time failure (a mount docker rejects) is docker 125, remapped to 126.
+      - name: Launcher fault line
+        run: |
+          set -euo pipefail
+          cd /tmp/cbtest
+          printf 'CLAUDE_BOX_EXTRA_MOUNTS=("/tmp:/tmp:bogusmode")\n' > .env.claude-box
+          rc=0
+          CLAUDE_BOX_EXEC=1 "$GITHUB_WORKSPACE/claude-box" --engine none -- true >/dev/null 2>err.txt || rc=$?
+          rm -f .env.claude-box
+          [ "$rc" = 126 ] || { echo "FAIL: want exit 126, got $rc"; cat err.txt; exit 1; }
+          grep -q 'fault=engine-start-failed' err.txt \
+            || { echo "FAIL: missing fault=engine-start-failed line"; cat err.txt; exit 1; }
+          echo "fault line OK (exit $rc)"
+
+      # Headless runbook — redirected stdout carries only the payload's output:
+      # no CR, no cage/launcher log lines (those go to stderr), no stderr leak.
+      - name: Stream cleanliness
+        run: |
+          set -euo pipefail
+          cd /tmp/cbtest
+          CLAUDE_BOX_EXEC=1 "$GITHUB_WORKSPACE/claude-box" --engine none \
+            -- bash -c 'printf "hello\n"' >out.txt 2>/dev/null
+          [ "$(cat out.txt)" = "hello" ] || { echo "FAIL: stdout not exactly hello:"; cat -A out.txt; exit 1; }
+          [ "$(wc -l < out.txt)" -eq 1 ] || { echo "FAIL: unexpected line count"; exit 1; }
+          if grep -q $'\r' out.txt; then echo "FAIL: CR in stdout"; exit 1; fi
+          if grep -qE '\[cage\]|\[claude-box\]' out.txt; then echo "FAIL: log line leaked to stdout"; exit 1; fi
+          echo "stream cleanliness OK"
+
+      # Headless runbook — the state dump is opt-in via CLAUDE_BOX_DEBUG (-> CAGE_DEBUG);
+      # off by default, and it lists the state mount but never cats secrets.
+      - name: Debug dump opt-in
+        run: |
+          set -euo pipefail
+          cd /tmp/cbtest
+          CLAUDE_BOX_EXEC=1 "$GITHUB_WORKSPACE/claude-box" --engine none -- true >/dev/null 2>off.txt
+          CLAUDE_BOX_DEBUG=1 CLAUDE_BOX_EXEC=1 "$GITHUB_WORKSPACE/claude-box" --engine none -- true >/dev/null 2>on.txt
+          [ "$(grep -c 'state mount' off.txt)" -eq 0 ] || { echo "FAIL: dump present without debug"; exit 1; }
+          [ "$(grep -c 'state mount' on.txt)" -ge 1 ] || { echo "FAIL: dump absent with debug"; cat on.txt; exit 1; }
+          echo "debug dump opt-in OK"
+
+      # Headless runbook — an invalid --name is rejected before anything starts,
+      # and a box started headless is addressable via the --name-file handle.
+      - name: Box name handle + validation
+        run: |
+          set -euo pipefail
+          cd /tmp/cbtest
+          rc=0
+          CLAUDE_BOX_EXEC=1 "$GITHUB_WORKSPACE/claude-box" --name 'a b/c' --engine none -- true >/dev/null 2>err.txt || rc=$?
+          [ "$rc" = 1 ] || { echo "FAIL: invalid --name exited $rc, want 1"; cat err.txt; exit 1; }
+          grep -q 'invalid container name' err.txt || { echo "FAIL: missing invalid-name message"; cat err.txt; exit 1; }
+          echo "OK: invalid --name rejected"
+          h="$(mktemp)"; name="cbci-$$"
+          CLAUDE_BOX_EXEC=1 "$GITHUB_WORKSPACE/claude-box" --engine none --name "$name" --name-file "$h" \
+            -- sleep 120 >/dev/null 2>&1 &
+          launcher=$!
+          for _ in $(seq 1 150); do [ -s "$h" ] && break; sleep 0.2; done
+          [ "$(cat "$h")" = "$name" ] || { echo "FAIL: name-file not published"; kill "$launcher" 2>/dev/null || true; exit 1; }
+          for _ in $(seq 1 150); do docker inspect "$name" >/dev/null 2>&1 && break; sleep 0.2; done
+          docker exec "$name" true || { echo "FAIL: cannot exec into named box"; docker stop "$name" 2>/dev/null || true; exit 1; }
+          docker stop "$name" >/dev/null
+          wait "$launcher" 2>/dev/null || true
+          [ ! -e "$h" ] || { echo "FAIL: name-file not cleaned on exit"; exit 1; }
+          echo "name handle + validation OK"
diff --git a/.gitignore b/.gitignore
index bf4c1a9..c39fb94 100644
--- a/.gitignore
+++ b/.gitignore
@@ -4,3 +4,5 @@
 .faff
 .faffrc.local.yaml
 .env.*
+
+docs/superpowers
diff --git a/Dockerfile b/Dockerfile.cage
similarity index 64%
rename from Dockerfile
rename to Dockerfile.cage
index 69d621d..368098d 100644
--- a/Dockerfile
+++ b/Dockerfile.cage
@@ -1,11 +1,16 @@
 FROM node:22-bookworm-slim
 
-# System deps + GitHub CLI + a full nested container engine (ADR-0041
-# decision 3): the cage gets its OWN dockerd — rootless by default, rootful
-# under sysbox / privileged dind — never a mounted host socket. docker-ce
-# brings dockerd; docker-ce-rootless-extras brings dockerd-rootless.sh +
-# rootlesskit; uidmap/slirp4netns/fuse-overlayfs/iproute2/iptables are the
-# rootless engine's userns, networking, and storage tooling.
+# cage-base — the payload-free box: host-isolation tooling and a full nested
+# container engine (ADR-0041 decision 3), with NO agent harness baked in. A
+# payload image (claude-box, codex-box) does `FROM cage-base` and adds its own
+# harness. Nothing Claude-specific lives here: no claude-code, no ugrep
+# grep-shadow, no bun — those moved to the Claude payload layer.
+#
+# The cage gets its OWN dockerd — rootless by default, rootful under sysbox /
+# privileged dind — never a mounted host socket. docker-ce brings dockerd;
+# docker-ce-rootless-extras brings dockerd-rootless.sh + rootlesskit;
+# uidmap/slirp4netns/fuse-overlayfs/iproute2/iptables are the rootless engine's
+# userns, networking, and storage tooling.
 RUN apt-get update && apt-get install -y --no-install-recommends \
     git curl ca-certificates gnupg unzip jq openssh-client socat \
     python3 python3-pip python3-venv \
@@ -26,7 +31,8 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
 
 # Chromium runtime libs so Playwright (installed per-project in venvs) can launch
 # its bundled browser without needing root at runtime. Browser binary itself is
-# not baked in — `playwright install chromium` fetches it on demand.
+# not baked in — `playwright install chromium` fetches it on demand. Generic
+# capability, not Claude's, so it belongs in the cage.
 RUN apt-get update && apt-get install -y --no-install-recommends \
     libnss3 libnspr4 libdbus-1-3 libatk1.0-0 libatk-bridge2.0-0 libcups2 \
     libxcomposite1 libxdamage1 libxfixes3 libxrandr2 libgbm1 libasound2 \
@@ -34,7 +40,7 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
     && rm -rf /var/lib/apt/lists/*
 
 # AWS CLI v2 — official bundled installer (arch-aware). Netlify CLI ships via
-# npm below; flyctl via its official install script.
+# npm below; flyctl via its official install script. Generic deploy CLIs.
 RUN case "$(dpkg --print-architecture)" in \
         amd64) awscli_arch=x86_64 ;; \
         arm64) awscli_arch=aarch64 ;; \
@@ -58,9 +64,6 @@ RUN npm install -g netlify-cli wrangler \
 # the official Astral image so we don't curl-pipe-sh.
 COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /usr/local/bin/
 
-# Bun (required for Claude Code plugins — claude-hud, etc.)
-RUN curl -fsSL https://bun.sh/install | BUN_INSTALL=/usr/local bash
-
 # Yarn Berry (for Node.js projects using Yarn 4)
 RUN corepack enable && corepack prepare yarn@4.13.0 --activate
 
@@ -71,29 +74,8 @@ RUN curl -fsSL "https://github.com/tianon/gosu/releases/download/1.17/gosu-$(dpk
     && chmod +x /usr/local/bin/gosu \
     && gosu nobody true
 
-# ugrep + shadow grep with it. Claude Code on the host transparently redirects
-# `grep` to ugrep (via a shell function) so patterns can use ugrep extensions
-# like `\t` in -E regex. Subprocesses spawned by Claude Code (e.g. statusLine
-# commands from plugins like claude-hud) don't inherit that shell function, so
-# in the container we install ugrep system-wide and put a `grep` symlink on
-# /usr/local/bin (which precedes /usr/bin on PATH) — anything resolving `grep`
-# via PATH gets ugrep, while scripts that hardcode /usr/bin/grep still hit the
-# stock GNU grep.
-RUN apt-get update && apt-get install -y --no-install-recommends ugrep \
-    && ln -sf /usr/bin/ugrep /usr/local/bin/grep \
-    && rm -rf /var/lib/apt/lists/*
-
-# Claude Code
-RUN npm install -g @anthropic-ai/claude-code \
-    && npm cache clean --force
-
-COPY entrypoint.sh /usr/local/bin/claude-box-entrypoint.sh
+COPY entrypoint-cage.sh /usr/local/bin/cage-entrypoint.sh
 COPY userns-probe.sh /usr/local/bin/claude-box-userns-probe
-RUN chmod +x /usr/local/bin/claude-box-entrypoint.sh /usr/local/bin/claude-box-userns-probe
-
-# Bake the claude-box theme into the image so it's available regardless of
-# host mounts or virtiofs cache state. The entrypoint copies it into the
-# user's themes dir at startup.
-COPY claude-box-theme.json /usr/local/share/claude-box-theme.json
+RUN chmod +x /usr/local/bin/cage-entrypoint.sh /usr/local/bin/claude-box-userns-probe
 
-ENTRYPOINT ["/usr/local/bin/claude-box-entrypoint.sh"]
+ENTRYPOINT ["/usr/local/bin/cage-entrypoint.sh"]
diff --git a/Dockerfile.claude b/Dockerfile.claude
new file mode 100644
index 0000000..5908623
--- /dev/null
+++ b/Dockerfile.claude
@@ -0,0 +1,33 @@
+FROM cage-base
+
+# claude-box payload: Claude Code on top of the payload-free cage, plus the two
+# Claude-specific tools that used to live in the monolith image.
+
+# ugrep + shadow grep with it. Claude Code on the host transparently redirects
+# `grep` to ugrep (via a shell function) so patterns can use ugrep extensions
+# like `\t` in -E regex. Subprocesses spawned by Claude Code (e.g. statusLine
+# commands from plugins like claude-hud) don't inherit that shell function, so
+# in the container we install ugrep system-wide and put a `grep` symlink on
+# /usr/local/bin (which precedes /usr/bin on PATH) — anything resolving `grep`
+# via PATH gets ugrep, while scripts that hardcode /usr/bin/grep still hit the
+# stock GNU grep. This is a Claude convention, so it lives here, not in cage-base.
+RUN apt-get update && apt-get install -y --no-install-recommends ugrep \
+    && ln -sf /usr/bin/ugrep /usr/local/bin/grep \
+    && rm -rf /var/lib/apt/lists/*
+
+# Bun (required for Claude Code plugins — claude-hud, etc.)
+RUN curl -fsSL https://bun.sh/install | BUN_INSTALL=/usr/local bash
+
+# Claude Code
+RUN npm install -g @anthropic-ai/claude-code \
+    && npm cache clean --force
+
+# Bake the claude-box theme into the image so it's available regardless of host
+# mounts or virtiofs cache state. The payload-init hook copies it into the user's
+# themes dir at startup.
+COPY claude-box-theme.json /usr/local/share/claude-box-theme.json
+
+# Payload-init hook: the cage entrypoint runs this (as root, before the engine)
+# for Claude-specific prep — theme install and stale-dir cleanup.
+COPY payload-init-claude.sh /usr/local/share/cage/payload-init
+RUN chmod +x /usr/local/share/cage/payload-init
diff --git a/Dockerfile.codex b/Dockerfile.codex
new file mode 100644
index 0000000..5f1b016
--- /dev/null
+++ b/Dockerfile.codex
@@ -0,0 +1,9 @@
+FROM cage-base
+
+# codex-box payload: the OpenAI Codex CLI on top of the payload-free cage.
+# Nothing else is added — the cage already carries git, gh, the nested engine,
+# and the generic dev tooling. Auth is a persisted ~/.codex login synced by the
+# launcher; the harness runs with --dangerously-bypass-approvals-and-sandbox
+# because the cage is the isolation boundary.
+RUN npm install -g @openai/codex \
+    && npm cache clean --force
diff --git a/README.md b/README.md
index a8c9b33..4855474 100644
--- a/README.md
+++ b/README.md
@@ -19,6 +19,37 @@ claude-box bridges that gap. It wires up the bind-mounts, credential extraction,
 - `settings.json` is synced on first run (stripping sandbox/hooks, rewriting macOS-specific paths)
 - A **nested container engine** runs inside the box (rootless dockerd by default), so `docker` / `docker compose` work in-session without ever exposing the host's docker socket
 
+## Architecture: the cage
+
+claude-box is one payload on a shared **cage**. The cage is the isolation
+boundary: it owns the outer container, its security posture, the bounded nested
+engine, uid mapping, the ssh / colima relays, the image build, the exit-status
+contract, and the `docker run` assembly. It knows nothing about which harness
+runs inside it. A payload owns one thing: which harness command runs, and which
+host state it syncs.
+
+- `libcage.sh` — the cage, as a sourced shell library. The engine block, the
+  userns probe ladder, env forwarding, and the `docker run` invocation live here
+  exactly once.
+- `Dockerfile.cage` builds `cage-base`: git, gh, the nested docker engine, and
+  the generic dev tooling, with **no agent harness**. `entrypoint-cage.sh` is its
+  entrypoint (create the host user, start the engine, wire the relays, then exec
+  whatever command the launcher hands it).
+- A payload is a thin wrapper plus a Dockerfile `FROM cage-base`. `claude-box` +
+  `Dockerfile.claude` add Claude Code; `codex-box` + `Dockerfile.codex` add the
+  OpenAI Codex CLI. Each wrapper sets a handful of `BOX_*` variables and may
+  define `box_stage` / `box_sync_back` hooks for its own state, then calls
+  `cage_run "$@"`.
+
+A second payload, **codex-box**, ships alongside claude-box and runs the Codex
+CLI in the same cage (`codex-box` on your `PATH`; state persists in
+`~/.codex-box/state/`, auth from a persisted `codex login`). It exists partly to
+keep the boundary honest: anything Claude-specific that leaks into the cage would
+break Codex.
+
+To verify the boundary and the nested engine, run
+[docs/cage-engine-acceptance.md](docs/cage-engine-acceptance.md).
+
 ## Requirements
 
 - Docker Desktop (or Docker Engine on Linux)
@@ -33,7 +64,7 @@ ln -sf ~/claude-box/claude-box /usr/local/bin/claude-box
 chmod +x ~/claude-box/claude-box
 ```
 
-The image builds automatically on first run (and rebuilds when the Dockerfile changes).
+The images build automatically on first run: a shared `cage-base` first, then the `claude-box` payload image on top of it. Either rebuilds when its own inputs change (see [Architecture](#architecture-the-cage)).
 
 ## Usage
 
@@ -203,7 +234,7 @@ rm -rf ~/.claude-box/state/
 claude-box --upgrade
 ```
 
-This runs `git pull --ff-only` on the install dir and exits. The image rebuilds automatically on the next regular run when the Dockerfile or entrypoint changed.
+This runs `git pull --ff-only` on the install dir and exits. The images rebuild automatically on the next regular run: `cage-base` when `Dockerfile.cage`, `entrypoint-cage.sh`, or `userns-probe.sh` changed, and the `claude-box` payload image when `Dockerfile.claude`, its `payload-init-claude.sh`, the theme, or `cage-base` itself changed.
 
 On startup, claude-box does a backgrounded `git fetch` against the install dir at most once every 24 hours. When the check finds you're behind upstream, the next launch prints a single hint line:
 
diff --git a/claude-box b/claude-box
index 41a4326..adc399e 100755
--- a/claude-box
+++ b/claude-box
@@ -1,987 +1,254 @@
 #!/usr/bin/env bash
-# claude-box — run Claude Code in Docker with --dangerously-skip-permissions
+# claude-box — run Claude Code in the cage (see libcage.sh) with
+# --dangerously-skip-permissions.
 #
 # Mounts the project dir at its exact host path so skill symlinks resolve.
 # Persists Claude Code state (settings, conversations) in ~/.claude-box/state/
-# across runs — delete that dir to reset.
-# Syncs ~/.claude skills, plugins, hooks, and .mcp.json into the
-# container so your local setup is always reflected.
-# Sessions for the current project are written to ~/.claude/projects/<slug>/
-# on the host so they're resumable from host Claude as well as future
-# claude-box runs in the same project. Session-keyed satellite state (todos,
-# shell env, pastes, plans, file-history) is also shared so resume preserves
-# more than just the transcript.
+# across runs — delete that dir to reset. Syncs ~/.claude skills, plugins, hooks,
+# and .mcp.json into the container. Sessions for the current project are shared
+# with the host's ~/.claude/projects/<slug>/ so they're resumable from host
+# Claude too, along with session-keyed satellite state (todos, shell env, pastes,
+# plans, file-history).
 #
 # Always runs in the current directory (the project root). cd into your project
 # first, then:
 #   claude-box                  # interactive session
 #   claude-box -c               # continue most recent session here
-#   claude-box --resume         # pick a session to resume (interactive picker)
+#   claude-box --resume         # interactive session picker
 #   claude-box -r <id>          # resume a specific session by ID
 #   claude-box -p "..."         # non-interactive prompt (pipe-friendly)
 #
-# Every argument is passed straight through to claude, so `claude-box --model
-# sonnet`, `claude-box --mcp-config ...`, etc. all work. Use `--` to force
-# everything after it to claude, so a claude flag that shares a name with a
-# claude-box flag can still be passed, e.g. `claude-box -- --engine foo` sends
-# `--engine foo` to claude, not claude-box.
+# Every argument is passed straight through to claude. Use `--` to force
+# everything after it to claude.
 #
 # claude-box-specific flags (consumed before claude sees them; position-free):
-#   --no-ssh                    # skip ~/.ssh mount and SSH_AUTH_SOCK forwarding
-#                                 (signing/git-over-ssh disabled inside container)
-#   --upgrade                   # git pull the claude-box install dir and exit
-#                                 (next run rebuilds the image if needed)
-#   --ollama <model>            # point Claude Code at an Ollama server's
+#   --ollama <model>            # route Claude Code at an Ollama server's
 #                                 Anthropic-compatible API (base URL from
-#                                 OLLAMA_HOST, e.g. a Tailscale peer)
-#   --engine <mode>             # nested container engine posture (ADR-0041):
-#                                 auto (default: sysbox if the host runtime
-#                                 has it, else rootless), sysbox, rootless,
-#                                 privileged-dind (named weaker posture),
-#                                 none. The host docker socket is NEVER
-#                                 mounted into the box.
+#                                 OLLAMA_HOST)
+# plus the cage-generic flags (see libcage.sh / README):
+#   --no-ssh / --upgrade / --engine <mode> / --name <name> / --name-file <path>
 #
 # Installation:
 #   git clone https://github.com/shftwst/claude-box ~/claude-box
 #   ln -sf ~/claude-box/claude-box /usr/local/bin/claude-box
-#   # or add ~/claude-box to PATH
-#
-# Exit status (so `claude-box -p …` composes in scripts, CI, and one-shots):
-#   0        the harness (claude) succeeded
-#   1–124    the harness's own exit code, verbatim
-#   125      launcher fault — image missing
-#   126      launcher fault — engine start failed
-#   127      launcher fault — harness not executable
-#   128+     signal deaths, verbatim
-# Every launcher fault also prints `claude-box: fault=<reason> detail="…"` to
-# stderr (unconditionally, even headless), so a caller testing only zero-vs-
-# nonzero keeps working while one needing precision can parse fault=. 125–127
-# follow docker run's own daemon/invoke/not-found vocabulary. A redirected
-# stdout carries only the harness's output — no CRLF, no [entrypoint] lines,
-# nothing from stderr — because a PTY is allocated only when both stdout and
-# stderr are terminals.
-#
-# Addressing a headless box:
-#   --name <name>       set the container name (default claude-box-<project>-<pid>).
-#                       Must match docker's charset [a-zA-Z0-9][a-zA-Z0-9_.-]*.
-#   --name-file <path>  write the resolved name to <path> just before launch and
-#                       remove it on exit. A supervisor polls <path>, reads the
-#                       name, then `docker stop`/`docker exec` the box.
-# Launcher warnings (rootless-userns unsupported, apparmor/SSH-relay failures)
-# print as `[claude-box] WARNING: …` on stderr unconditionally, so a headless
-# caller sees them; informational progress lines stay quiet unless stderr is a tty.
 
 set -euo pipefail
 
-# Progress logs to stderr, gated on a tty so piped/non-interactive runs stay
-# clean. Must never return nonzero: a bare top-level `log` under set -e would
-# otherwise kill the script whenever stderr isn't a tty.
-log() { [[ ! -t 2 ]] || printf '[claude-box] %s\n' "$*" >&2; }
-
-# Machine-readable launcher-fault line. UNLIKE log(), this is unconditional on
-# the tty: a headless caller relies on it to disambiguate the exit code (see the
-# exit-status contract in the header), so it must reach captured stderr whether
-# or not stderr is a terminal. fault=<reason> is the stable field; detail="…" is
-# human context. Never returns nonzero, so a bare `fault` can't trip set -e.
-fault() { printf 'claude-box: fault=%s detail="%s"\n' "$1" "${2:-}" >&2; return 0; }
-
-# Machine-facing WARNING line. Like fault(), UNCONDITIONAL on the tty: a headless
-# caller (CI, a supervisor) relies on these to explain why a rootless engine or
-# SSH relay didn't come up, which log() would silently drop when stderr is not a
-# terminal. Goes to stderr, so a redirected stdout still carries only the
-# harness's output. Interactive runs print the identical line (warn() ignores the
-# tty), so headless and interactive stderr match verbatim.
-warn() { printf '[claude-box] WARNING: %s\n' "$*" >&2; }
-
-# Background-check the install dir against its upstream. Detached so the parent
-# never waits and silent on every failure mode (not a repo, no upstream,
-# offline, fetch fails) — those skips don't touch $UPDATE_CHECK_FILE so we
-# retry next launch instead of going dark for 24h on a transient blip.
-check_for_update_in_background() {
-  (
-    cd "$CLAUDE_BOX_DIR" || exit 0
-    git rev-parse --abbrev-ref '@{u}' >/dev/null 2>&1 || exit 0
-    git fetch --quiet 2>/dev/null || exit 0
-    if [[ $(git rev-list --count HEAD..@{u} 2>/dev/null || echo 0) -gt 0 ]]; then
-      touch "$UPDATE_AVAILABLE_FILE"
-    else
-      rm -f "$UPDATE_AVAILABLE_FILE"
-    fi
-    touch "$UPDATE_CHECK_FILE"
-  ) >/dev/null 2>&1 &
-  disown 2>/dev/null || true
-}
-
-# Pull claude-box's own flags out of "$@" before anything else looks at args,
-# so the project-dir positional and the claude-flag passthrough stay clean.
-# A literal `--` ends claude-box option parsing: everything after it goes to
-# claude verbatim, so a claude flag that happens to share a name with a
-# claude-box flag (--no-ssh, --upgrade, --ollama, --engine) can still be passed.
-NO_SSH=0
-UPGRADE=0
-OLLAMA_MODEL=""
-ENGINE_MODE=""
-BOX_NAME=""
-NAME_FILE=""
-declare -a _passthrough=()
-while [[ $# -gt 0 ]]; do
-  case "$1" in
-    --) shift; _passthrough+=("$@"); break ;;
-    --no-ssh) NO_SSH=1 ;;
-    --upgrade) UPGRADE=1 ;;
-    --ollama)
-      shift
-      OLLAMA_MODEL="${1:-}"
-      [[ -n "$OLLAMA_MODEL" ]] || { printf '[claude-box] --ollama requires a model name\n' >&2; exit 1; }
-      ;;
-    --ollama=*) OLLAMA_MODEL="${1#*=}" ;;
-    --engine)
-      shift
-      ENGINE_MODE="${1:-}"
-      [[ -n "$ENGINE_MODE" ]] || { printf '[claude-box] --engine requires a mode (auto|sysbox|rootless|privileged-dind|none)\n' >&2; exit 1; }
-      ;;
-    --engine=*) ENGINE_MODE="${1#*=}" ;;
-    --name)
-      shift
-      BOX_NAME="${1:-}"
-      [[ -n "$BOX_NAME" ]] || { printf '[claude-box] --name requires a container name\n' >&2; exit 1; }
-      ;;
-    --name=*) BOX_NAME="${1#*=}" ;;
-    --name-file)
-      shift
-      NAME_FILE="${1:-}"
-      [[ -n "$NAME_FILE" ]] || { printf '[claude-box] --name-file requires a path\n' >&2; exit 1; }
-      ;;
-    --name-file=*) NAME_FILE="${1#*=}" ;;
-    *) _passthrough+=("$1") ;;
-  esac
-  shift
-done
-set -- "${_passthrough[@]+"${_passthrough[@]}"}"
-
-# A caller-supplied box name must satisfy docker's container-name charset; reject
-# early (before any docker call) with a precise message rather than letting
-# `docker run --name` fail obscurely mid-launch. Pre-flight usage error, so
-# exit 1 like the sibling flags, not the run-time fault()/125-127 path.
-if [[ -n "$BOX_NAME" && ! "$BOX_NAME" =~ ^[a-zA-Z0-9][a-zA-Z0-9_.-]*$ ]]; then
-  printf '[claude-box] --name: invalid container name (allowed: [a-zA-Z0-9][a-zA-Z0-9_.-]*)\n' >&2
-  exit 1
-fi
-
-# There's no project-dir positional: claude-box always runs in the current
-# directory (the project root). Every remaining arg goes straight to claude.
-declare -a CLAUDE_ARGS=("$@")
-
-# Resolve symlinks so installs via `ln -sf ~/claude-box/claude-box /usr/local/bin/`
-# (or homebrew's /opt/homebrew/bin) still find the Dockerfile in the repo dir.
+# Resolve symlinks so an install via `ln -sf` still finds the repo dir.
 _self="${BASH_SOURCE[0]}"
 while [[ -L "$_self" ]]; do
   _link=$(readlink "$_self")
   [[ "$_link" = /* ]] && _self="$_link" || _self="$(dirname "$_self")/$_link"
 done
-CLAUDE_BOX_DIR="$(cd "$(dirname "$_self")" && pwd)"
-
-UPDATE_CHECK_FILE="${HOME}/.claude-box/.last-update-check"
-UPDATE_AVAILABLE_FILE="${HOME}/.claude-box/.update-available"
-mkdir -p "${HOME}/.claude-box"
-
-# --upgrade: pull latest claude-box and exit. Next regular run picks up any
-# Dockerfile/entrypoint changes via the mtime-vs-BUILT_MARKER check below.
-# Uses --ff-only so a dirty install dir errors out instead of silently merging.
-if [[ $UPGRADE -eq 1 ]]; then
-  log "upgrading claude-box at ${CLAUDE_BOX_DIR}..."
-  if git -C "$CLAUDE_BOX_DIR" pull --ff-only; then
-    rm -f "$UPDATE_AVAILABLE_FILE"
-    touch "$UPDATE_CHECK_FILE"
-    exit 0
-  else
-    exit $?
-  fi
-fi
-
-# Show cached update hint (zero-latency: just a file-existence check).
-[[ -e "$UPDATE_AVAILABLE_FILE" ]] && \
-  log "update available — run 'claude-box --upgrade' to pull latest"
-
-# If our cached check is missing or >24h old, kick off a fresh check in the
-# background. `find -mtime -1` is portable across BSD (macOS) and GNU find.
-if [[ ! -f "$UPDATE_CHECK_FILE" ]] || \
-   [[ -z "$(find "$UPDATE_CHECK_FILE" -mtime -1 2>/dev/null)" ]]; then
-  check_for_update_in_background
-fi
-
-PROJECT_DIR="$(pwd)"
-
-# Refuse to launch from $HOME (or any ancestor of it). PROJECT_DIR is
-# bind-mounted into the container, so launching from home would mount your
-# entire home directory into the box — a huge attack surface and a lot of
-# virtiofs traffic — and make ${HOME} a virtiofs mount root the entrypoint
-# can't chown (which used to kill the container outright). Runs before any
-# trap/launch, so a bare exit here is clean.
-_home="$(cd "$HOME" 2>/dev/null && pwd)"
-if [[ -n "$_home" && ( "$PROJECT_DIR" == "$_home" || "$_home" == "$PROJECT_DIR"/* ) ]]; then
-  printf '[claude-box] refusing to launch from %s\n' "$PROJECT_DIR" >&2
-  printf '[claude-box] this would bind-mount your entire home directory (%s) into the box.\n' "$_home" >&2
-  printf '[claude-box] cd into a specific project directory and run claude-box from there.\n' >&2
-  exit 1
-fi
+BOX_SRC_DIR="$(cd "$(dirname "$_self")" && pwd)"
 
 CLAUDE_HOME="${HOME}/.claude"
-IMAGE="claude-box"
-DOCKERFILE="${CLAUDE_BOX_DIR}/Dockerfile"
-ENTRYPOINT_SH="${CLAUDE_BOX_DIR}/entrypoint.sh"
-USERNS_PROBE_SH="${CLAUDE_BOX_DIR}/userns-probe.sh"
-BUILT_MARKER="${HOME}/.claude-box/.built"
 
-# A caller-supplied --name wins; otherwise the default stays unique per launcher
-# via the PID, so concurrent boxes never collide.
-CONTAINER_NAME="${BOX_NAME:-claude-box-$(basename "$PROJECT_DIR")-$$}"
+# --- cage config ---
+BOX_LABEL="claude-box"
+BOX_IMAGE="claude-box"
+BOX_DOCKERFILE="${BOX_SRC_DIR}/Dockerfile.claude"
+BOX_STATE_DIR="${HOME}/.claude-box/state"
+BOX_STATE_MOUNT="${CLAUDE_HOME}"
+BOX_ENV_PREFIX="CLAUDE_BOX"
+BOX_FORWARD_VARS=(ANTHROPIC_API_KEY LINEAR_API_KEY)
+BOX_PAYLOAD_CMD=(claude --dangerously-skip-permissions)
+# Extra files Dockerfile.claude COPYs, so editing them forces an image rebuild.
+BOX_BUILD_INPUTS=("${BOX_SRC_DIR}/payload-init-claude.sh" "${BOX_SRC_DIR}/claude-box-theme.json")
 
-# Build the image if it doesn't exist or any build input has changed. Includes
-# entrypoint.sh because it's COPYed into the image, so changes there need a
-# rebuild even when the Dockerfile itself is unchanged.
-needs_build=0
-if ! docker image inspect "$IMAGE" &>/dev/null; then
-  needs_build=1
-elif [[ "$DOCKERFILE" -nt "$BUILT_MARKER" || "$ENTRYPOINT_SH" -nt "$BUILT_MARKER" \
-        || "$USERNS_PROBE_SH" -nt "$BUILT_MARKER" ]]; then
-  needs_build=1
-fi
-if [[ $needs_build -eq 1 ]]; then
-  log "building image..."
-  if ! docker build -f "$DOCKERFILE" -t "$IMAGE" "$CLAUDE_BOX_DIR"; then
-    fault image-missing "docker build failed for image '${IMAGE}'"
-    exit 125
-  fi
-  mkdir -p "$(dirname "$BUILT_MARKER")"
-  touch "$BUILT_MARKER"
-fi
-
-# The image must exist before we run. If inspect still can't see it — a build
-# skipped as unneeded but the image was removed out-of-band, or a build that
-# produced nothing — that's an image-missing launcher fault (125), caught here
-# (before the container ever launches) so runtime 125s can mean engine failure.
-if ! docker image inspect "$IMAGE" >/dev/null 2>&1; then
-  fault image-missing "image '${IMAGE}' is not present (build it or check the docker daemon)"
-  exit 125
-fi
+OLLAMA_MODEL=""
 
-# Persistent state dir — preserves settings, conversation history, etc. across
-# runs so Claude Code doesn't re-run setup on every launch. Delete to reset.
-STATE_DIR="${HOME}/.claude-box/state"
-mkdir -p "$STATE_DIR"
-chmod 777 "$STATE_DIR"
+# shellcheck source=libcage.sh
+source "${BOX_SRC_DIR}/libcage.sh"
 
-_SSH_RELAY_PID=""
-cleanup() {
-  if [[ -n "$_SSH_RELAY_PID" ]]; then
-    kill "$_SSH_RELAY_PID" 2>/dev/null || true
-    wait "$_SSH_RELAY_PID" 2>/dev/null || true
-  fi
-  # The published handle is only valid while the box lives (the container is
-  # --rm), so remove it on exit rather than leave a name pointing at nothing.
-  [[ -n "$NAME_FILE" ]] && rm -f "$NAME_FILE"
+# --- wrapper flag: --ollama <model> ---
+box_parse_arg() {
+  case "$1" in
+    --ollama)
+      OLLAMA_MODEL="${2:-}"
+      [[ -n "$OLLAMA_MODEL" ]] || { printf '[claude-box] --ollama requires a model name\n' >&2; exit 1; }
+      _CONSUMED=2; return 0 ;;
+    --ollama=*) OLLAMA_MODEL="${1#*=}"; _CONSUMED=1; return 0 ;;
+  esac
+  return 1
 }
 
-# Flush sessions, credentials, and satellite state from the container back to the
-# host, write any refreshed token back to the Keychain, and print the resume
-# hint. Runs from the EXIT trap (and via the signal traps below), so a DROPPED
-# session — terminal/SSH close, sleep, kill — flushes to the host's native Claude
-# dir and gets the Colima virtiofs coherence pass exactly like a clean exit,
-# instead of stranding the transcript in the state dir. The helper container
-# works over the state volume, so it doesn't need the (already --rm'd) session
-# container. Guarded to run at most once, and only if the container was launched.
-_LAUNCHED=0
-_SYNCED=0
-sync_back() {
-  [[ "${_LAUNCHED:-0}" == 1 && "${_SYNCED:-0}" == 0 ]] || return 0
-  _SYNCED=1
-  set +euo pipefail
-
-  # Never copy out from a container that's still writing to the state volume. On
-  # a headless run no PTY absorbs the signal, so a supervisor's SIGINT/TERM/HUP
-  # can reach this launcher and fire the EXIT trap while the session container is
-  # still live — snapshotting half-flushed state. Stop it (with a short grace so
-  # the harness can flush) and wait before touching the volume. On a clean exit
-  # the container has already `--rm`'d itself, so `docker inspect` misses and
-  # this is a fast no-op — the interactive -it path routed the signal to the
-  # container, not here, so it too arrives with the container already gone.
-  if docker inspect "$CONTAINER_NAME" >/dev/null 2>&1; then
-    docker stop -t 2 "$CONTAINER_NAME" >/dev/null 2>&1 || true
-  fi
-
-  _state_proj="${STATE_DIR}/projects/${PROJECT_SLUG}"
-
-  # On Colima, files written by the container may not be visible on the host due
-  # to virtiofs caching. Copy them out through Docker's I/O path via a helper
-  # container — the host can't see them directly.
-  if [[ "${DOCKER_HOST:-}" == */.colima/* ]]; then
-    log "syncing state back from colima..."
-    _cid=$(docker create --entrypoint sleep -v "${STATE_DIR}:/_state:rw" "${IMAGE}" 1 2>/dev/null)
-    if [[ -n "$_cid" ]]; then
-      # Sessions, .claude.json, credentials, and satellite state (tasks, todos, etc.)
-      docker cp "${_cid}:/_state/projects/${PROJECT_SLUG}/." "${_state_proj}/" 2>/dev/null || true
-      docker cp "${_cid}:/_state/.claude.json" "${STATE_DIR}/.claude.json" 2>/dev/null || true
-      docker cp "${_cid}:/_state/.credentials.json" "${STATE_DIR}/.credentials.json" 2>/dev/null || true
-      for _sat in tasks session-env shell-snapshots paste-cache plans file-history; do
-        docker cp "${_cid}:/_state/${_sat}/." "${STATE_DIR}/${_sat}/" 2>/dev/null || true
-      done
-      docker rm -f "$_cid" >/dev/null 2>&1 || true
-    fi
-  fi
+# Echoes a claudeAiOauth credential's expiresAt (epoch ms) from stdin, else 0.
+_cred_expiry() {
+  node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{try{const j=JSON.parse(s);process.stdout.write(String((j.claudeAiOauth&&j.claudeAiOauth.expiresAt)||0))}catch{process.stdout.write("0")}})' 2>/dev/null || printf 0
+}
 
-  # Write an in-box token refresh back to the macOS Keychain so host Claude — and
-  # the next launch's seed — pick it up instead of re-seeding a now-rotated (dead)
-  # refresh token, the usual cause of intermittent logouts. Newer-wins by
-  # expiresAt so a concurrent host refresh isn't clobbered. Only updates an
-  # existing Keychain item (never creates a duplicate) and only for a real
-  # claudeAiOauth token.
-  if command -v security >/dev/null 2>&1 \
-     && [[ -s "${STATE_DIR}/.credentials.json" ]] \
-     && grep -q '"claudeAiOauth"' "${STATE_DIR}/.credentials.json" 2>/dev/null; then
-    _state_exp=$(_cred_expiry < "${STATE_DIR}/.credentials.json")
-    _kc_exp=0
-    if _kc_now=$(security find-generic-password -s "Claude Code-credentials" -w 2>/dev/null) \
-       && [[ "$_kc_now" == *claudeAiOauth* ]]; then
-      _kc_exp=$(printf '%s' "$_kc_now" | _cred_expiry)
-    fi
-    _kc_acct=$(security find-generic-password -s "Claude Code-credentials" 2>/dev/null \
-      | sed -n 's/^[[:space:]]*"acct"<blob>="\(.*\)"$/\1/p')
-    if [[ -n "$_kc_acct" && "${_state_exp:-0}" -gt "${_kc_exp:-0}" ]]; then
-      security add-generic-password -U -s "Claude Code-credentials" -a "$_kc_acct" \
-        -w "$(cat "${STATE_DIR}/.credentials.json")" 2>/dev/null \
-        && log "synced refreshed Claude token back to Keychain" || true
-    fi
+# --- box_stage: everything Claude-specific, run after the cage builds its
+# generic mounts and before the (generic) colima flush. Appends to env_args /
+# override_mounts (cage globals), stages files into STATE_DIR / RELAY_DIR, and
+# sets HOST_PROJECT_SESSIONS for box_sync_back.
+box_stage() {
+  local STATE_CLAUDE_JSON="${STATE_DIR}/.claude.json"
+
+  # claude-code: skip its npm self-install on startup.
+  env_args+=(-e "SKIP_NPM_PACKAGES_INSTALL=1")
+
+  # --ollama <model>: route Claude Code at an Ollama server's Anthropic-compatible
+  # API. Base URL from OLLAMA_HOST (scheme optional). ANTHROPIC_AUTH_TOKEN is a
+  # dummy Ollama ignores but Claude Code requires non-empty. Both main and
+  # small/fast models point at the same model.
+  if [[ -n "$OLLAMA_MODEL" ]]; then
+    local _ollama_url="${OLLAMA_HOST:-localhost:11434}"
+    [[ "$_ollama_url" == http://* || "$_ollama_url" == https://* ]] || _ollama_url="http://${_ollama_url}"
+    env_args+=(
+      -e "ANTHROPIC_BASE_URL=${_ollama_url}"
+      -e "ANTHROPIC_AUTH_TOKEN=ollama"
+      -e "ANTHROPIC_MODEL=${OLLAMA_MODEL}"
+      -e "ANTHROPIC_SMALL_FAST_MODEL=${OLLAMA_MODEL}"
+    )
+    log "ollama mode: ${_ollama_url} (model: ${OLLAMA_MODEL})"
   fi
 
-  # Copy sessions to the host's Claude project dir for cross-tool resumability.
-  # Preserve mtimes (-p): the resume hint below picks the just-closed session by
-  # newest mtime, and a plain cp stamps every file with the copy time — which
-  # collapses all sessions to one timestamp and makes the pick arbitrary (it
-  # falls back to glob/alphabetical order, reporting a stale unrelated session).
-  cp -pf "${_state_proj}/"*.jsonl "$HOST_PROJECT_SESSIONS/" 2>/dev/null
-  cp -prf "${_state_proj}/"*/ "$HOST_PROJECT_SESSIONS/" 2>/dev/null
-
-  # Resume hint: the just-closed session is the newest transcript by mtime. Scan
-  # both the synced state dir (authoritative on Colima — docker cp keeps real
-  # mtimes) and the host dir (where the live override-mount writes on other
-  # runtimes) so whichever holds the real session wins even if one copy missed —
-  # that double source is also why the hint still prints on a fresh project when
-  # only one of the two dirs got populated. Skip agent-*.jsonl: those are
-  # subagent sidechains, not resumable sessions.
-  _latest=""
-  for f in "${_state_proj}/"*.jsonl "${HOST_PROJECT_SESSIONS}/"*.jsonl; do
-    [[ -f "$f" ]] || continue
-    case "${f##*/}" in agent-*) continue ;; esac
-    [[ -z "$_latest" || "$f" -nt "$_latest" ]] && _latest="$f"
+  # Concatenate CLAUDE.md: global base -> parent dirs -> project (project wins).
+  # Written into the state dir so it's part of the main volume mount.
+  : > "${STATE_DIR}/CLAUDE.md"
+  [[ -f "${CLAUDE_HOME}/CLAUDE.md" ]] && cat "${CLAUDE_HOME}/CLAUDE.md" >> "${STATE_DIR}/CLAUDE.md"
+  local claude_files=() current="$PROJECT_DIR" i f
+  while [[ "$current" != "/" ]]; do
+    [[ -f "$current/CLAUDE.md" ]] && claude_files+=("$current/CLAUDE.md")
+    current="$(dirname "$current")"
+  done
+  for (( i=${#claude_files[@]}-1; i>=0; i-- )); do
+    f="${claude_files[$i]}"
+    printf '\n<!-- %s -->\n' "$f" >> "${STATE_DIR}/CLAUDE.md"
+    cat "$f" >> "${STATE_DIR}/CLAUDE.md"
   done
-  if [[ -n "$_latest" ]]; then
-    _id=$(basename "$_latest" .jsonl)
-    _resume_cmd="claude-box -r ${_id}"
-    printf '[claude-box] to resume: %s\n' "$_resume_cmd" >&2
-    # Also persist the hint: a dropped session (terminal/SSH closed) runs this
-    # trap with a stderr that's already gone, so the line above is computed and
-    # lost. Stash it so the next launch in this project can surface it.
-    printf '%s\n' "$_resume_cmd" > "${_state_proj}/.last-resume" 2>/dev/null || true
-  fi
-}
-
-# Run sync_back on any exit, and convert a closed terminal (HUP), kill (TERM), or
-# Ctrl-C during the sync phase (INT) into a graceful exit so it still fires. A
-# pending signal trap runs the instant `docker run` returns, so sync_back must
-# already be defined by then — hence it lives here, above the run. During the
-# interactive `docker run -it` the PTY is in raw mode, so the user's in-Claude
-# Ctrl-C goes to the container, not to this launcher. On a HEADLESS run there's
-# no PTY, so a supervisor's signal lands here while the container may still be
-# live; sync_back stops the container before copying out (see its guard), so the
-# copy-out never races a running container regardless of the signal path.
-trap 'sync_back; cleanup' EXIT
-trap 'exit' INT TERM HUP
-
-# Per-project overrides: source ${PROJECT_DIR}/.env.claude-box if present so
-# each project can supply its own values (e.g. a project-specific LINEAR_API_KEY)
-# without having to re-export them in the calling shell. Sourced BEFORE
-# FORWARD_VARS is built so the file can also extend CLAUDE_BOX_EXTRA_VARS.
-# Values here win over whatever's in the host shell. set -a auto-exports each
-# assignment so plain KEY=value lines work without needing `export`.
-PROJECT_ENV_FILE="${PROJECT_DIR}/.env.claude-box"
-if [[ -f "$PROJECT_ENV_FILE" ]]; then
-  set -a
-  # shellcheck disable=SC1090
-  source "$PROJECT_ENV_FILE"
-  set +a
-fi
-
-# Nested container engine posture (ADR-0041 decision 3). The box gets its own
-# engine INSIDE the cage so its authority is bounded by the cage; the host
-# docker socket is never mounted (the entrypoint refuses to start if one is).
-# Ladder: sysbox (best — rootful engine bounded by the sysbox runtime) →
-# rootless dind (default — unprivileged dockerd in a nested userns; needs
-# seccomp/apparmor unconfined on the OUTER container to allow userns + mounts,
-# but adds no capabilities and stays non-privileged) → privileged-dind (the
-# named weaker posture, explicit opt-in only) → none.
-# CLI --engine wins; else CLAUDE_BOX_ENGINE_MODE (env or .env.claude-box);
-# else auto.
-ENGINE_MODE="${ENGINE_MODE:-${CLAUDE_BOX_ENGINE_MODE:-auto}}"
-_host_docker_caps=""
-if [[ "$ENGINE_MODE" != "none" ]]; then
-  # One docker info call answers both: is sysbox-runc a host runtime, and
-  # does the host enforce apparmor (only then is apparmor=unconfined valid —
-  # passing it on a non-apparmor host errors at container create).
-  _host_docker_caps="$(docker info --format '{{.SecurityOptions}} {{range $k, $v := .Runtimes}}{{$k}} {{end}}' 2>/dev/null || true)"
-fi
-case "$ENGINE_MODE" in
-  auto)
-    if [[ "$_host_docker_caps" == *sysbox-runc* ]]; then ENGINE=sysbox; else ENGINE=rootless; fi
-    ;;
-  sysbox)
-    if [[ "$_host_docker_caps" != *sysbox-runc* ]]; then
-      fault engine-start-failed "--engine sysbox: host docker has no sysbox-runc runtime (install sysbox first)"
-      exit 126
-    fi
-    ENGINE=sysbox
-    ;;
-  rootless|privileged-dind|none) ENGINE="$ENGINE_MODE" ;;
-  *)
-    printf '[claude-box] unknown --engine mode: %s (want auto|sysbox|rootless|privileged-dind|none)\n' "$ENGINE_MODE" >&2
-    exit 1
-    ;;
-esac
-
-# Per-docker-host slug for cache files: probe results are properties of the
-# docker host (VM), so a Colima↔Docker-Desktop switch must not reuse them.
-_dh_slug="$(printf '%s' "${DOCKER_HOST:-default}" | tr -c 'a-zA-Z0-9' '_')"
 
-# Probe whether the host daemon can map a device node into containers; cached
-# per docker host. /dev/fuse backs fuse-overlayfs (the storage fallback on
-# kernels without rootless-overlay2); /dev/net/tun backs slirp4netns (the
-# rootless engine's network). A missing tun device means the rootless engine
-# can't network — surfaced by the entrypoint's ready check.
-_probe_device() {
-  local dev="$1" cache="${HOME}/.claude-box/.device-probe-${1//\//_}-${_dh_slug}"
-  if [[ ! -f "$cache" ]]; then
-    if docker run --rm --entrypoint true --device "$dev" "$IMAGE" >/dev/null 2>&1; then
-      echo yes > "$cache"
-    else
-      echo no > "$cache"
-    fi
+  # Concatenate AGENTS.md the same way into the cage relay (the entrypoint copies
+  # it to ~/.agents/AGENTS.md). Skip if the cage couldn't provide a writable relay.
+  if [[ -n "$RELAY_DIR" ]]; then
+    : > "${RELAY_DIR}/AGENTS.md"
+    [[ -f "${HOME}/.agents/AGENTS.md" ]] && cat "${HOME}/.agents/AGENTS.md" >> "${RELAY_DIR}/AGENTS.md"
+    local agents_files=()
+    current="$PROJECT_DIR"
+    while [[ "$current" != "/" ]]; do
+      [[ -f "$current/AGENTS.md" ]] && agents_files+=("$current/AGENTS.md")
+      current="$(dirname "$current")"
+    done
+    for (( i=${#agents_files[@]}-1; i>=0; i-- )); do
+      f="${agents_files[$i]}"
+      printf '\n<!-- %s -->\n' "$f" >> "${RELAY_DIR}/AGENTS.md"
+      cat "$f" >> "${RELAY_DIR}/AGENTS.md"
+    done
   fi
-  [[ "$(cat "$cache" 2>/dev/null)" == yes ]]
-}
-
-# AppArmor profile granting the cage CAPABLE user namespaces. Ubuntu-lineage
-# kernels (Colima VMs, Ubuntu 23.10+) set apparmor_restrict_unprivileged_userns:
-# an unconfined unprivileged process may create a userns but is stripped of
-# capabilities inside it, which kills rootlesskit. The blessed fix is a profile
-# carrying the `userns,` permission; flags=(unconfined) means it confines
-# nothing else. Loaded via the host's own apparmor_parser (guaranteed present
-# when apparmor is enforced — dockerd needs it for docker-default) through a
-# privileged one-shot helper that nsenters the host mount namespace. That
-# helper is launcher-side HOST-altitude setup by the human-run wrapper — the
-# cage itself never gets this authority.
-_USERNS_PROFILE='abi <abi/4.0>,
-include <tunables/global>
-profile claude-box-engine flags=(unconfined) {
-  userns,
-}'
-
-# Idempotent, ~300ms. Re-run each launch when needed: loaded profiles do not
-# survive a docker-host (VM) reboot.
-_load_userns_profile() {
-  printf '%s\n' "$_USERNS_PROFILE" | docker run --rm -i --privileged --pid=host \
-    --entrypoint nsenter "$IMAGE" -t 1 -m -- sh -c \
-    'cat > /run/claude-box-engine.profile && apparmor_parser -Kr /run/claude-box-engine.profile' \
-    >/dev/null 2>&1
-}
 
-# Run the baked-in userns probe (unshare + parent-side newuidmap, i.e. what
-# rootlesskit does at boot) under candidate security options.
-_userns_probe() {
-  docker run --rm --entrypoint /usr/local/bin/claude-box-userns-probe \
-    --security-opt seccomp=unconfined "$@" "$IMAGE" >/dev/null 2>&1
-}
-
-# Pick the WEAKEST relaxation set that yields a capable nested userns:
-#   plain        seccomp=unconfined (+ apparmor=unconfined on apparmor hosts)
-#   profile      + the claude-box-engine apparmor profile (userns permission)
-#   profile-cap  + CAP_SYS_ADMIN in the bounding set (Ubuntu-restricted kernels
-#                need it for setuid newuidmap's parent-side map write; latent —
-#                unprivileged cage processes only reach it via those helpers)
-#   cap          SYS_ADMIN alone (restricted kernel, no apparmor mediation)
-# Cached per docker host; "unsupported" is never cached so a host fix is
-# picked up on the next launch. Delete ~/.claude-box/.userns-strategy-* to
-# force a re-probe.
-_resolve_userns_strategy() {
-  local cache="${HOME}/.claude-box/.userns-strategy-${_dh_slug}" s="" aa=()
-  if [[ -s "$cache" ]]; then
-    cat "$cache"
-    return 0
-  fi
-  [[ "$_host_docker_caps" == *apparmor* ]] && aa=(--security-opt apparmor=unconfined)
-  if _userns_probe ${aa[@]+"${aa[@]}"}; then
-    s="plain"
-  elif [[ "$_host_docker_caps" == *apparmor* ]] && _load_userns_profile; then
-    if _userns_probe --security-opt apparmor=claude-box-engine; then
-      s="profile"
-    elif _userns_probe --security-opt apparmor=claude-box-engine --cap-add SYS_ADMIN; then
-      s="profile-cap"
-    fi
-  fi
-  if [[ -z "$s" ]] && _userns_probe ${aa[@]+"${aa[@]}"} --cap-add SYS_ADMIN; then
-    s="cap"
+  # Extract gh CLI token and forward it as GH_TOKEN (cage forwards GH_TOKEN if
+  # already set; this covers the keychain-backed macOS case). Harmless duplicate
+  # of the cage's own gh fetch, kept for parity with the monolith.
+  # (No-op here: the cage already fetched GH_TOKEN before box_stage.)
+
+  # Per-project session sharing: bind-mount just this project's session dir so
+  # sessions started in claude-box are resumable from host Claude and vice versa.
+  # PROJECT_SLUG is set by the cage. HOST_PROJECT_SESSIONS is global for sync-back.
+  HOST_PROJECT_SESSIONS="${CLAUDE_HOME}/projects/${PROJECT_SLUG}"
+  mkdir -p "$HOST_PROJECT_SESSIONS"
+  mkdir -p "${STATE_DIR}/projects/${PROJECT_SLUG}"
+
+  # Surface the previous run's resume hint if the last session was dropped.
+  local _last_resume_file="${STATE_DIR}/projects/${PROJECT_SLUG}/.last-resume"
+  if [[ -s "$_last_resume_file" ]]; then
+    log "last session: $(cat "$_last_resume_file")"
+    rm -f "$_last_resume_file" 2>/dev/null || true
   fi
-  if [[ -n "$s" ]]; then
-    echo "$s" > "$cache"
-    echo "$s"
-  else
-    echo "unsupported"
+  if [[ "${DOCKER_HOST:-}" != */.colima/* ]]; then
+    override_mounts+=(-v "${HOST_PROJECT_SESSIONS}:${HOST_PROJECT_SESSIONS}")
   fi
-}
-
-engine_args=()
-case "$ENGINE" in
-  sysbox)
-    # Sysbox provisions the inner engine's storage and devices itself; the
-    # data-root volume below would defeat its uid-shifting, so pass none.
-    engine_args+=(--runtime sysbox-runc -e "CLAUDE_BOX_ENGINE=rootful" --init)
-    log "engine: sysbox (rootful nested dockerd, bounded by sysbox-runc)"
-    ;;
-  rootless)
-    # The anonymous volume at the data root keeps the nested engine's storage
-    # off the container overlayfs (overlay-on-overlay is rejected) — --rm
-    # removes it with the container, so engine state is per-session.
-    # systempaths=unconfined unmasks /proc inside the cage: rootlesskit must
-    # write net.ipv4.ip_forward in its OWN detached netns through /proc/sys,
-    # which docker bind-mounts read-only in every non-privileged container.
-    engine_args+=(
-      --security-opt seccomp=unconfined
-      --security-opt systempaths=unconfined
-      -e "CLAUDE_BOX_ENGINE=rootless"
-      -v /var/lib/claude-box-engine
-      --init
-    )
-    _userns_strategy="$(_resolve_userns_strategy)"
-    case "$_userns_strategy" in
-      plain)
-        [[ "$_host_docker_caps" == *apparmor* ]] && engine_args+=(--security-opt apparmor=unconfined)
-        ;;
-      profile|profile-cap)
-        _load_userns_profile || warn "apparmor profile load failed: engine may not start"
-        engine_args+=(--security-opt apparmor=claude-box-engine)
-        [[ "$_userns_strategy" == profile-cap ]] && engine_args+=(--cap-add SYS_ADMIN)
-        ;;
-      cap)
-        engine_args+=(--cap-add SYS_ADMIN)
-        ;;
-      unsupported)
-        warn "this docker host cannot give an unprivileged user a capable user"
-        warn "namespace, so the rootless nested engine will likely fail to start."
-        warn "consider sysbox, or '--engine privileged-dind' (ADR-0041's named"
-        warn "weaker posture), or '--engine none'."
-        [[ "$_host_docker_caps" == *apparmor* ]] && engine_args+=(--security-opt apparmor=unconfined)
-        ;;
-    esac
-    _probe_device /dev/net/tun && engine_args+=(--device /dev/net/tun)
-    _probe_device /dev/fuse && engine_args+=(--device /dev/fuse)
-    log "engine: rootless nested dockerd (userns strategy: ${_userns_strategy})"
-    ;;
-  privileged-dind)
-    warn "--engine privileged-dind is ADR-0041's named weaker posture:"
-    warn "a privileged cage weakens host isolation. Prefer sysbox or rootless."
-    engine_args+=(--privileged -e "CLAUDE_BOX_ENGINE=rootful" -v /var/lib/docker --init)
-    ;;
-  none)
-    engine_args+=(-e "CLAUDE_BOX_ENGINE=none")
-    log "engine: none (no container engine inside the box)"
-    ;;
-esac
-
-# Env vars to forward into the container.
-# Add project-specific vars by setting CLAUDE_BOX_EXTRA_VARS, either in your
-# shell before invoking or inside the project's .env.claude-box:
-#   CLAUDE_BOX_EXTRA_VARS=(TURSO_AUTH_TOKEN MY_API_KEY) claude-box
-# Forward TERM + COLORFGBG only if the host shell has them set — don't synthesize
-# defaults. Claude Code's theme auto-detect works correctly when the container
-# inherits exactly what iTerm2 (or whatever terminal) provides, and synthesizing
-# values has surprising side effects.
-# Specifically, do NOT set COLORTERM=truecolor in the docker run env — even
-# though the terminal supports it, forcing it in the container causes Claude
-# Code's palette derivation to pick a broken combo (white-on-white prompt and
-# response text). Let the terminal advertise its own capabilities through
-# whatever vars iTerm2 already exports.
-FORWARD_VARS=(
-  ANTHROPIC_API_KEY
-  GITHUB_TOKEN
-  GITHUB_PERSONAL_ACCESS_TOKEN
-  LINEAR_API_KEY
-  TERM
-  COLORFGBG
-  CLAUDE_BOX_DEBUG   # opt-in entrypoint state dump (off by default)
-  CLAUDE_BOX_EXEC    # acceptance hook: exec the args as a raw command, not claude
-  "${CLAUDE_BOX_EXTRA_VARS[@]+"${CLAUDE_BOX_EXTRA_VARS[@]}"}"
-)
-
-env_args=()
-for var in "${FORWARD_VARS[@]}"; do
-  [[ -n "${!var:-}" ]] && env_args+=(-e "${var}=${!var}")
-done
-
-# --ollama <model>: route Claude Code at an Ollama server's Anthropic-compatible
-# API (mirrors `ollama launch claude --model X`). The base URL comes from
-# OLLAMA_HOST so it follows wherever that already points — a Tailscale peer, a
-# LAN box, or localhost — all reachable from the container over the normal
-# bridge network (no host networking needed). OLLAMA_HOST may omit the scheme
-# (Ollama's own convention), so add http:// when absent. ANTHROPIC_AUTH_TOKEN is
-# a dummy Ollama ignores but Claude Code requires to be non-empty. Both the main
-# and small/fast models point at the same model so background calls don't fall
-# back to a claude-* name the server doesn't have.
-if [[ -n "$OLLAMA_MODEL" ]]; then
-  _ollama_url="${OLLAMA_HOST:-localhost:11434}"
-  [[ "$_ollama_url" == http://* || "$_ollama_url" == https://* ]] || _ollama_url="http://${_ollama_url}"
-  env_args+=(
-    -e "ANTHROPIC_BASE_URL=${_ollama_url}"
-    -e "ANTHROPIC_AUTH_TOKEN=ollama"
-    -e "ANTHROPIC_MODEL=${OLLAMA_MODEL}"
-    -e "ANTHROPIC_SMALL_FAST_MODEL=${OLLAMA_MODEL}"
-  )
-  log "ollama mode: ${_ollama_url} (model: ${OLLAMA_MODEL})"
-fi
-
-# Concatenate CLAUDE.md files: global base → parent dirs → project (project wins).
-# Written directly into the state dir so it's part of the main volume mount —
-# no separate bind mount that could fail on Colima when virtiofs hasn't synced.
-: > "${STATE_DIR}/CLAUDE.md"
-
-if [[ -f "${CLAUDE_HOME}/CLAUDE.md" ]]; then
-  cat "${CLAUDE_HOME}/CLAUDE.md" >> "${STATE_DIR}/CLAUDE.md"
-fi
 
-declare -a claude_files=()
-current="$PROJECT_DIR"
-while [[ "$current" != "/" ]]; do
-  [[ -f "$current/CLAUDE.md" ]] && claude_files+=("$current/CLAUDE.md")
-  current="$(dirname "$current")"
-done
-
-for (( i=${#claude_files[@]}-1; i>=0; i-- )); do
-  f="${claude_files[$i]}"
-  printf '\n<!-- %s -->\n' "$f" >> "${STATE_DIR}/CLAUDE.md"
-  cat "$f" >> "${STATE_DIR}/CLAUDE.md"
-done
-
-# Concatenate AGENTS.md the same way: global ~/.agents/AGENTS.md → parent dirs →
-# project (project wins). The user's CLAUDE.md tells Claude to read
-# ~/.agents/AGENTS.md, and projects carry their own AGENTS.md, so the box needs
-# the merged view — not just the global file. Staged in the state dir (the one
-# reliably-synced mount) for the entrypoint to copy out to ~/.agents/AGENTS.md.
-mkdir -p "${STATE_DIR}/.agents"
-: > "${STATE_DIR}/.agents/AGENTS.md"
-
-if [[ -f "${HOME}/.agents/AGENTS.md" ]]; then
-  cat "${HOME}/.agents/AGENTS.md" >> "${STATE_DIR}/.agents/AGENTS.md"
-fi
-
-declare -a agents_files=()
-current="$PROJECT_DIR"
-while [[ "$current" != "/" ]]; do
-  [[ -f "$current/AGENTS.md" ]] && agents_files+=("$current/AGENTS.md")
-  current="$(dirname "$current")"
-done
-
-for (( i=${#agents_files[@]}-1; i>=0; i-- )); do
-  f="${agents_files[$i]}"
-  printf '\n<!-- %s -->\n' "$f" >> "${STATE_DIR}/.agents/AGENTS.md"
-  cat "$f" >> "${STATE_DIR}/.agents/AGENTS.md"
-done
-
-# Specific ~/.claude entries to bind-mount on top of the state volume.
-# Pre-create the mount-point directories/files as host-user-owned so Docker
-# doesn't create them as root (which would leave root-owned paths in STATE_DIR
-# that the cleanup trap can't delete).
-# Extract gh CLI token from the host (keychain-backed on macOS) and forward it
-# as GH_TOKEN so `gh` works inside the container without re-authing.
-if [[ -z "${GH_TOKEN:-}" ]]; then
-  log "fetching gh auth token..."
-  GH_TOKEN=$(gh auth token 2>/dev/null) && env_args+=(-e "GH_TOKEN=${GH_TOKEN}") || true
-fi
-
-declare -a override_mounts=()
-
-# Mount SSH keys + forward ssh-agent so git-over-SSH and signing work inside
-# the container. Agent forwarding means the host's already-unlocked key is used
-# directly — no passphrase prompt per commit. Skipped if --no-ssh was passed.
-#
-# macOS socket paths vary by runtime:
-#   - Docker Desktop: can't bind-mount /private/tmp/com.apple.launchd.* sockets
-#     but exposes a magic /run/host-services/ssh-auth.sock proxy.
-#   - Colima: virtiofs can't expose Unix sockets at all. We relay the host agent
-#     over TCP (Python on host → socat in container) so the container gets a
-#     working SSH_AUTH_SOCK without needing the VM to see the socket file.
-#   - OrbStack: full macOS filesystem access, all paths work directly.
-# 1Password's socket (~/.1password/agent.sock) is under $HOME and works everywhere.
-if [[ $NO_SSH -eq 0 ]]; then
-  [[ -d "${HOME}/.ssh" ]] && override_mounts+=(-v "${HOME}/.ssh:${HOME}/.ssh:ro")
-  if [[ -n "${SSH_AUTH_SOCK:-}" && -S "$SSH_AUTH_SOCK" ]]; then
-    if [[ "${DOCKER_HOST:-}" == */.colima/* ]]; then
-      # Colima: start a TCP relay on the host that proxies to the agent socket.
-      # The container's entrypoint converts it back to a Unix socket via socat.
-      # We write the port to a temp file instead of capturing stdout via $()
-      # because $(cmd &) hangs waiting for the pipe to drain and $! inside $()
-      # doesn't propagate to the parent shell.
-      _relay_port_file=$(mktemp /tmp/claude-box-relay.XXXXXX)
-      python3 -c "
-import socket, sys, threading, signal, os
-src = '${SSH_AUTH_SOCK}'
-server = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
-server.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
-server.bind(('127.0.0.1', 0))
-port = server.getsockname()[1]
-with open('${_relay_port_file}', 'w') as f:
-    f.write(str(port))
-server.listen(8)
-signal.signal(signal.SIGTERM, lambda *_: sys.exit(0))
-def relay(a, b):
-    try:
-        while d := a.recv(4096): b.sendall(d)
-    except: pass
-    finally: a.close(); b.close()
-while True:
-    c, _ = server.accept()
-    u = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
-    u.connect(src)
-    threading.Thread(target=relay, args=(c, u), daemon=True).start()
-    threading.Thread(target=relay, args=(u, c), daemon=True).start()
-" &
-      _SSH_RELAY_PID=$!
-      # Poll until the relay writes its port (up to 3 s). A fixed sleep raced
-      # against Python startup — if the read beat the write, the container got
-      # an empty CLAUDE_BOX_SSH_RELAY_PORT and no SSH_AUTH_SOCK.
-      _RELAY_PORT=""
-      for _i in $(seq 1 30); do
-        [[ -s "$_relay_port_file" ]] && { _RELAY_PORT=$(<"$_relay_port_file"); break; }
-        sleep 0.1
-      done
-      rm -f "$_relay_port_file"
-      if [[ -z "$_RELAY_PORT" ]]; then
-        warn "SSH agent relay failed to start: signing will not work"
-        kill "$_SSH_RELAY_PID" 2>/dev/null || true
-        _SSH_RELAY_PID=""
-      else
-        env_args+=(-e "CLAUDE_BOX_SSH_RELAY_PORT=${_RELAY_PORT}")
-        env_args+=(--add-host "host.docker.internal:host-gateway")
-      fi
-    elif [[ "$SSH_AUTH_SOCK" == /private/tmp/com.apple.launchd.* ]]; then
-      # Docker Desktop can't mount launchd sockets — use its built-in proxy
-      override_mounts+=(-v "/run/host-services/ssh-auth.sock:/run/host-services/ssh-auth.sock")
-      env_args+=(-e "SSH_AUTH_SOCK=/run/host-services/ssh-auth.sock")
-    else
-      # OrbStack and Linux: mount the socket directly
-      override_mounts+=(-v "${SSH_AUTH_SOCK}:${SSH_AUTH_SOCK}")
-      env_args+=(-e "SSH_AUTH_SOCK=${SSH_AUTH_SOCK}")
+  # Session-keyed satellite state (todos, shell env, pastes, plans, file-history).
+  local entry
+  for entry in tasks session-env shell-snapshots paste-cache plans file-history; do
+    mkdir -p "${CLAUDE_HOME}/${entry}"
+    if [[ "${DOCKER_HOST:-}" != */.colima/* ]]; then
+      override_mounts+=(-v "${CLAUDE_HOME}/${entry}:${CLAUDE_HOME}/${entry}")
     fi
-  fi
-else
-  log "ssh disabled (--no-ssh): no key mount, no agent forwarding"
-fi
+  done
 
-# Mount host ~/.gitconfig read-only so user name/email, aliases, signing config,
-# etc. carry into the container. On Colima, copy into state dir instead (virtiofs
-# can't see single host files reliably for bind mounts).
-if [[ -f "${HOME}/.gitconfig" ]]; then
-  if [[ "${DOCKER_HOST:-}" == */.colima/* ]]; then
-    cp -f "${HOME}/.gitconfig" "${STATE_DIR}/.gitconfig" 2>/dev/null || true
+  # On non-Colima runtimes, overlay-mount host ~/.claude entries on top of the
+  # state dir so the container reflects the host's current setup. On Colima these
+  # mounts silently fail (virtiofs can't see host dirs), so sync into the state
+  # dir instead (below), before the cage's flush.
+  if [[ "${DOCKER_HOST:-}" != */.colima/* ]]; then
+    for entry in plugins skills hooks .mcp.json; do
+      if [[ -e "${CLAUDE_HOME}/${entry}" ]]; then
+        if [[ -d "${CLAUDE_HOME}/${entry}" ]]; then mkdir -p "${STATE_DIR}/${entry}"; else touch "${STATE_DIR}/${entry}"; fi
+        override_mounts+=(-v "${CLAUDE_HOME}/${entry}:${CLAUDE_HOME}/${entry}:rw")
+      fi
+    done
+    # Symlinked skills point outside ~/.claude; mount their target parent dirs rw
+    # so those paths resolve inside the container.
+    log "resolving skill symlinks..."
+    local dir target
+    while IFS= read -r dir; do
+      [[ -d "$dir" ]] && override_mounts+=(-v "${dir}:${dir}:rw")
+    done < <(
+      find "${CLAUDE_HOME}/skills" -maxdepth 1 -type l 2>/dev/null \
+        | while IFS= read -r link; do target=$(readlink "$link" 2>/dev/null) && dirname "$target"; done \
+        | sort -u
+    )
   else
-    override_mounts+=(-v "${HOME}/.gitconfig:${HOME}/.gitconfig:ro")
+    log "resolving skill symlinks..."
   fi
-fi
-
-# Share XDG cache (pip wheels, npm/yarn tarballs, playwright browsers, etc.) so
-# first-run downloads survive container exit and are shared across boxes.
-# mkdir -p so Docker doesn't create a root-owned dir on a host without ~/.cache.
-mkdir -p "${HOME}/.cache"
-override_mounts+=(-v "${HOME}/.cache:${HOME}/.cache")
 
-# Share ~/.local/bin so tools installed inside the box (pip/uv --user, etc.)
-# survive container exit. The entrypoint puts this on PATH. mkdir -p so Docker
-# doesn't create a root-owned dir when the host has no ~/.local/bin yet.
-mkdir -p "${HOME}/.local/bin"
-override_mounts+=(-v "${HOME}/.local/bin:${HOME}/.local/bin")
-
-# Per-project session sharing: bind-mount just this project's session dir from
-# the host so sessions started in claude-box are resumable from host Claude
-# (and vice versa). Scoped to the current project so other projects' history
-# stays isolated in the state volume. Claude encodes project paths by replacing
-# `/` with `-`; we mirror that to find the matching subdir.
-PROJECT_SLUG="${PROJECT_DIR//\//-}"
-HOST_PROJECT_SESSIONS="${CLAUDE_HOME}/projects/${PROJECT_SLUG}"
-mkdir -p "$HOST_PROJECT_SESSIONS"
-mkdir -p "${STATE_DIR}/projects/${PROJECT_SLUG}"
-
-# Surface the previous run's resume hint if the last session was dropped — its
-# stderr was gone when sync_back printed, so the line never reached the user.
-# Show it once, then clear it so it doesn't linger across future launches.
-_last_resume_file="${STATE_DIR}/projects/${PROJECT_SLUG}/.last-resume"
-if [[ -s "$_last_resume_file" ]]; then
-  log "last session: $(cat "$_last_resume_file")"
-  rm -f "$_last_resume_file" 2>/dev/null || true
-fi
-# On Colima, skip the override mount — the freshly-created host dir isn't
-# visible to the VM, so Docker creates an empty ephemeral directory instead.
-# Sessions fall through to the state dir's projects folder, and we sync them
-# back to the host after docker exits.
-if [[ "${DOCKER_HOST:-}" != */.colima/* ]]; then
-  override_mounts+=(-v "${HOST_PROJECT_SESSIONS}:${HOST_PROJECT_SESSIONS}")
-fi
-
-# Session-keyed satellite state. Each of these dirs holds one entry per session
-# UUID (todos, shell env snapshots, pastes, plan-mode drafts, file-edit
-# history). Sharing them with the host means a session started in claude-box
-# resumes in host Claude — and vice versa — with full fidelity, not just the
-# conversation transcript. Trade-off: because entries are keyed by session UUID
-# (not project), the container can see satellite state for sessions from other
-# projects. No corruption risk; UUIDs don't collide. mkdir -p so a fresh host
-# without these dirs doesn't end up with root-owned mount points.
-for entry in tasks session-env shell-snapshots paste-cache plans file-history; do
-  mkdir -p "${CLAUDE_HOME}/${entry}"
-  # On Colima, skip these override mounts — virtiofs can't see the host dirs.
-  # The state dir already has these paths and they'll be synced back after exit.
-  if [[ "${DOCKER_HOST:-}" != */.colima/* ]]; then
-    override_mounts+=(-v "${CLAUDE_HOME}/${entry}:${CLAUDE_HOME}/${entry}")
+  # Sync Claude OAuth credentials into the state dir, newer-wins by expiresAt. On
+  # macOS the canonical source is the Keychain ("Claude Code-credentials");
+  # ~/.claude/.credentials.json often holds only MCP OAuth state, so trusting the
+  # file by existence would overwrite a good state token with garbage.
+  log "reading Claude credentials..."
+  local _state_cred="${STATE_DIR}/.credentials.json" _state_exp=0 KEYCHAIN_CRED _kc_exp
+  if [[ -s "$_state_cred" ]] && grep -q '"claudeAiOauth"' "$_state_cred" 2>/dev/null; then
+    _state_exp=$(_cred_expiry < "$_state_cred")
   fi
-done
-
-# Per-project extra mounts. Set CLAUDE_BOX_EXTRA_MOUNTS in .env.claude-box (or
-# the calling shell) to an array of host:container[:opts] specs, e.g.:
-#   CLAUDE_BOX_EXTRA_MOUNTS=("$HOME/.aws:$HOME/.aws:ro" "/data:/data")
-for spec in "${CLAUDE_BOX_EXTRA_MOUNTS[@]+"${CLAUDE_BOX_EXTRA_MOUNTS[@]}"}"; do
-  override_mounts+=(-v "$spec")
-done
-
-# On non-Colima runtimes, overlay-mount host ~/.claude entries on top
-# of the state dir so the container always reflects the host's current setup.
-# On Colima, these mounts silently fail (virtiofs can't see the host dirs), so
-# we skip them here and sync into the state dir later via host-side cp + flush.
-if [[ "${DOCKER_HOST:-}" != */.colima/* ]]; then
-  for entry in plugins skills hooks .mcp.json; do
-    if [[ -e "${CLAUDE_HOME}/${entry}" ]]; then
-      if [[ -d "${CLAUDE_HOME}/${entry}" ]]; then
-        mkdir -p "${STATE_DIR}/${entry}"
-      else
-        touch "${STATE_DIR}/${entry}"
-      fi
-      override_mounts+=(-v "${CLAUDE_HOME}/${entry}:${CLAUDE_HOME}/${entry}:rw")
+  if KEYCHAIN_CRED=$(security find-generic-password -s "Claude Code-credentials" -w 2>/dev/null) \
+     && [[ "$KEYCHAIN_CRED" == *claudeAiOauth* ]]; then
+    _kc_exp=$(printf '%s' "$KEYCHAIN_CRED" | _cred_expiry)
+    if [[ "${_kc_exp:-0}" -ge "${_state_exp:-0}" ]]; then
+      printf '%s\n' "$KEYCHAIN_CRED" > "$_state_cred"
     fi
-  done
-
-  # Symlinked skills point to absolute paths outside ~/.claude (e.g. other repos).
-  # Collect the unique parent dirs of all symlink targets and mount them rw
-  # so those paths resolve inside the container and skills can be developed.
-  log "resolving skill symlinks..."
-  while IFS= read -r dir; do
-    [[ -d "$dir" ]] && override_mounts+=(-v "${dir}:${dir}:rw")
-  done < <(
-    find "${CLAUDE_HOME}/skills" -maxdepth 1 -type l 2>/dev/null \
-      | while IFS= read -r link; do
-          target=$(readlink "$link" 2>/dev/null) && dirname "$target"
-        done \
-      | sort -u
-  )
-else
-  log "resolving skill symlinks..."
-fi
-# Sync Claude OAuth credentials into the state dir, newer-wins. On macOS the
-# canonical source is the Keychain ("Claude Code-credentials");
-# ~/.claude/.credentials.json on macOS often holds only MCP OAuth state (no
-# claudeAiOauth block), so trusting the file by existence alone overwrites a
-# good state-dir token with garbage. The state token may also be FRESHER than
-# the Keychain — an in-box /login or token refresh from a previous run (written
-# back to the Keychain on exit, below). Access-token expiresAt is the recency
-# proxy: whichever side refreshed most recently has the larger value, so we only
-# overwrite the state token when the incoming copy is at least as new. If
-# neither source yields a token, leave the state file alone.
-#
-# Echoes a claudeAiOauth credential's expiresAt (epoch ms) from stdin, else 0.
-_cred_expiry() {
-  node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{try{const j=JSON.parse(s);process.stdout.write(String((j.claudeAiOauth&&j.claudeAiOauth.expiresAt)||0))}catch{process.stdout.write("0")}})' 2>/dev/null || printf 0
-}
-log "reading Claude credentials..."
-_state_cred="${STATE_DIR}/.credentials.json"
-_state_exp=0
-if [[ -s "$_state_cred" ]] && grep -q '"claudeAiOauth"' "$_state_cred" 2>/dev/null; then
-  _state_exp=$(_cred_expiry < "$_state_cred")
-fi
-if KEYCHAIN_CRED=$(security find-generic-password -s "Claude Code-credentials" -w 2>/dev/null) \
-   && [[ "$KEYCHAIN_CRED" == *claudeAiOauth* ]]; then
-  _kc_exp=$(printf '%s' "$KEYCHAIN_CRED" | _cred_expiry)
-  if [[ "${_kc_exp:-0}" -ge "${_state_exp:-0}" ]]; then
-    printf '%s\n' "$KEYCHAIN_CRED" > "$_state_cred"
+  elif [[ "${_state_exp:-0}" -eq 0 ]] && [[ -f "${CLAUDE_HOME}/.credentials.json" ]] \
+       && grep -q '"claudeAiOauth"' "${CLAUDE_HOME}/.credentials.json" 2>/dev/null; then
+    cp -f "${CLAUDE_HOME}/.credentials.json" "$_state_cred"
   fi
-elif [[ "${_state_exp:-0}" -eq 0 ]] && [[ -f "${CLAUDE_HOME}/.credentials.json" ]] \
-     && grep -q '"claudeAiOauth"' "${CLAUDE_HOME}/.credentials.json" 2>/dev/null; then
-  cp -f "${CLAUDE_HOME}/.credentials.json" "$_state_cred"
-fi
 
-# Prefer a long-lived OAuth token (from `claude setup-token`) over the rotating
-# subscription refresh token whenever one is available. Claude Code uses the
-# setup-token as-is and never refreshes it, so any number of concurrent boxes can
-# share it safely. The rotating refresh token can't be shared: two boxes refresh
-# it independently, the auth server sees the single-use token spent twice, and
-# revokes the whole lineage — silently logging every box out. CLAUDE_CODE_OAUTH_TOKEN
-# outranks the mounted .credentials.json OAuth block in Claude's auth precedence,
-# so the shared credential mount stays in place — both as the fallback below and
-# to keep /login propagation working — while the env token, when present, is what
-# actually authenticates.
-#
-# Source order: an already-exported CLAUDE_CODE_OAUTH_TOKEN wins; otherwise pull it
-# from a Keychain item the user creates once with the token `claude setup-token`
-# prints:
-#   security add-generic-password -U -s "Claude Code-oauth-token" -a "$USER" -w "<token>"
-# When neither yields a token we inject nothing and fall through to the rotating
-# credential above — single-box behaviour is unchanged.
-if [[ -z "$OLLAMA_MODEL" ]]; then
-  _claude_oauth_token="${CLAUDE_CODE_OAUTH_TOKEN:-}"
-  if [[ -z "$_claude_oauth_token" ]] && command -v security >/dev/null 2>&1; then
-    _claude_oauth_token=$(security find-generic-password -s "Claude Code-oauth-token" -w 2>/dev/null || true)
-  fi
-  if [[ -n "$_claude_oauth_token" ]]; then
-    env_args+=(-e "CLAUDE_CODE_OAUTH_TOKEN=${_claude_oauth_token}")
-    log "using static OAuth token (concurrency-safe; refresh disabled)"
+  # Prefer a long-lived OAuth token (claude setup-token) over the rotating
+  # subscription refresh token so concurrent boxes don't revoke each other's
+  # lineage. Skipped in ollama mode. Env token outranks the mounted credential.
+  if [[ -z "$OLLAMA_MODEL" ]]; then
+    local _claude_oauth_token="${CLAUDE_CODE_OAUTH_TOKEN:-}"
+    if [[ -z "$_claude_oauth_token" ]] && command -v security >/dev/null 2>&1; then
+      _claude_oauth_token=$(security find-generic-password -s "Claude Code-oauth-token" -w 2>/dev/null || true)
+    fi
+    if [[ -n "$_claude_oauth_token" ]]; then
+      env_args+=(-e "CLAUDE_CODE_OAUTH_TOKEN=${_claude_oauth_token}")
+      log "using static OAuth token (concurrency-safe; refresh disabled)"
+    fi
   fi
-fi
-
-# Sync host config files into the state dir.
-# Only syncs when the host file is newer (first run, or after host update).
-# Claude Code then reads/writes the state-dir copies, keeping container state
-# independent of the host after the initial seed.
 
-_sync_js="${TMPDIR:-/tmp}/claude-box-sync.$$.js"
-cat > "$_sync_js" <<'JSEOF'
+  # Settings surgery: seed settings.json / .claude.json into the state dir (host
+  # newer-wins), stripping sandbox/hooks, rewriting the macOS bun path to the
+  # container path, forcing the claude-box theme, and pre-accepting the bypass
+  # dialog. statusline mode refreshes the HUD every launch.
+  local _sync_js="${TMPDIR:-/tmp}/claude-box-sync.$$.js"
+  cat > "$_sync_js" <<'JSEOF'
 const fs = require('fs');
 const [,, mode, src, dst] = process.argv;
 const s = JSON.parse(fs.readFileSync(src, 'utf8'));
 if (mode === 'passthrough') {
-  // Pre-accept the bypass permissions dialog so --dangerously-skip-permissions
-  // doesn't prompt every run.
   s.bypassPermissionsModeAccepted = true;
 }
 if (mode === 'settings') {
   delete s.sandbox;
   delete s.hooks;
-  // Rewrite macOS bun path to container path so plugins like claude-hud work.
   if (s.statusLine && s.statusLine.command) {
     s.statusLine.command = s.statusLine.command.replace(/\/opt\/homebrew\/bin\/bun/g, '/usr/local/bin/bun');
   }
-  // Use the claude-box theme so the container is visually distinct from host Claude.
   s.theme = 'custom:claude-box';
 }
 if (mode === 'statusline') {
-  // Refresh ONLY the host's statusLine (the HUD) + theme into the existing state
-  // copy, bun path rewritten — merging into, not replacing, the box's settings.
-  // Runs every launch (bypassing the -nt seed guard) so a host statusLine still
-  // reaches the box after Claude has rewritten the box's settings.json and made
-  // it "newer" than the host. Mirrors the host: sets it when present, removes it
-  // when absent. Bails without writing if the state file is unreadable, so a
-  // transient parse error can't nuke the box's settings.
   let cur;
   try { cur = JSON.parse(fs.readFileSync(dst, 'utf8')); } catch { process.exit(0); }
   if (s.statusLine) {
@@ -998,181 +265,120 @@ if (mode === 'statusline') {
 fs.writeFileSync(dst, JSON.stringify(s, null, 2));
 JSEOF
 
-HOST_SETTINGS="${CLAUDE_HOME}/settings.json"
-STATE_SETTINGS="${STATE_DIR}/settings.json"
-if [[ -f "$HOST_SETTINGS" ]] && { [[ ! -f "$STATE_SETTINGS" ]] || [[ "$HOST_SETTINGS" -nt "$STATE_SETTINGS" ]]; }; then
-  node "$_sync_js" settings "$HOST_SETTINGS" "$STATE_SETTINGS"
-fi
-
-# The HUD (statusLine) is host-derived presentation config, so refresh it from
-# the host on EVERY launch — not just on the -nt seed above. Claude rewrites the
-# box's settings.json during a session (theme/model/config), making the state
-# copy permanently "newer" than the host; without this, a host statusLine added
-# or changed afterwards never reaches the box and the HUD silently disappears.
-if [[ -f "$HOST_SETTINGS" && -f "$STATE_SETTINGS" ]]; then
-  node "$_sync_js" statusline "$HOST_SETTINGS" "$STATE_SETTINGS"
-fi
-
-HOST_CLAUDE_JSON="${HOME}/.claude.json"
-STATE_CLAUDE_JSON="${STATE_DIR}/.claude.json"
-if [[ -f "$HOST_CLAUDE_JSON" ]] && { [[ ! -f "$STATE_CLAUDE_JSON" ]] || [[ "$HOST_CLAUDE_JSON" -nt "$STATE_CLAUDE_JSON" ]]; }; then
-  node "$_sync_js" passthrough "$HOST_CLAUDE_JSON" "$STATE_CLAUDE_JSON"
-fi
-
-rm -f "$_sync_js"
+  local HOST_SETTINGS="${CLAUDE_HOME}/settings.json" STATE_SETTINGS="${STATE_DIR}/settings.json"
+  if [[ -f "$HOST_SETTINGS" ]] && { [[ ! -f "$STATE_SETTINGS" ]] || [[ "$HOST_SETTINGS" -nt "$STATE_SETTINGS" ]]; }; then
+    node "$_sync_js" settings "$HOST_SETTINGS" "$STATE_SETTINGS"
+  fi
+  if [[ -f "$HOST_SETTINGS" && -f "$STATE_SETTINGS" ]]; then
+    node "$_sync_js" statusline "$HOST_SETTINGS" "$STATE_SETTINGS"
+  fi
+  local HOST_CLAUDE_JSON="${HOME}/.claude.json"
+  if [[ -f "$HOST_CLAUDE_JSON" ]] && { [[ ! -f "$STATE_CLAUDE_JSON" ]] || [[ "$HOST_CLAUDE_JSON" -nt "$STATE_CLAUDE_JSON" ]]; }; then
+    node "$_sync_js" passthrough "$HOST_CLAUDE_JSON" "$STATE_CLAUDE_JSON"
+  fi
+  rm -f "$_sync_js"
+
+  # Ensure all bind-mount source files exist as actual files (Docker auto-creates
+  # missing sources as root-owned dirs, which persists and breaks later runs).
+  local _f
+  for _f in "$STATE_CLAUDE_JSON" "${STATE_DIR}/CLAUDE.md" "${STATE_DIR}/settings.json" \
+            "${STATE_DIR}/.credentials.json"; do
+    [[ -d "$_f" ]] && rm -rf "$_f"
+    [[ ! -f "$_f" ]] && touch "$_f"
+  done
 
-# Ensure all bind-mount source files exist as actual files. Docker auto-creates
-# nonexistent sources as root-owned directories, which persists in the state dir
-# and breaks subsequent runs (especially on Colima).
-for _f in "$STATE_CLAUDE_JSON" "${STATE_DIR}/CLAUDE.md" "${STATE_DIR}/settings.json" \
-          "${STATE_DIR}/.credentials.json"; do
-  [[ -d "$_f" ]] && rm -rf "$_f"
-  [[ ! -f "$_f" ]] && touch "$_f"
-done
+  # On Colima, host overlay mounts fail, so sync host ~/.claude config + seed
+  # sessions into the state dir here; the cage's flush (after box_stage) carries
+  # it all into the VM.
+  if [[ "${DOCKER_HOST:-}" == */.colima/* ]]; then
+    log "syncing host config for colima..."
+    local _sync_entry
+    for _sync_entry in plugins skills hooks; do
+      if [[ -d "${CLAUDE_HOME}/${_sync_entry}" ]]; then
+        mkdir -p "${STATE_DIR}/${_sync_entry}"
+        rsync -aL --delete "${CLAUDE_HOME}/${_sync_entry}/" "${STATE_DIR}/${_sync_entry}/" 2>/dev/null || \
+          cp -rfL "${CLAUDE_HOME}/${_sync_entry}/." "${STATE_DIR}/${_sync_entry}/" 2>/dev/null || true
+      fi
+    done
+    [[ -f "${CLAUDE_HOME}/.mcp.json" ]] && cp -f "${CLAUDE_HOME}/.mcp.json" "${STATE_DIR}/.mcp.json" 2>/dev/null || true
 
-# Colima's virtiofs cache may not expose freshly-written host files to the VM
-# in time for bind mounts. Flush volatile state files through Docker's I/O path
-# by tar-piping them into a lightweight container that writes to the same volume,
-# warming the VM's filesystem cache. Other runtimes skip this — they share the
-# full host filesystem without caching issues.
-if [[ "${DOCKER_HOST:-}" == */.colima/* ]]; then
-  # Sync host ~/.claude entries (plugins, skills, hooks, .mcp.json) into the
-  # state dir. Overlay mounts from the host fail on Colima (virtiofs can't see
-  # host-written dirs), so everything must be in the state dir volume.
-  log "syncing host config for colima..."
-  for _sync_entry in plugins skills hooks; do
-    if [[ -d "${CLAUDE_HOME}/${_sync_entry}" ]]; then
-      mkdir -p "${STATE_DIR}/${_sync_entry}"
-      rsync -aL --delete "${CLAUDE_HOME}/${_sync_entry}/" "${STATE_DIR}/${_sync_entry}/" 2>/dev/null || \
-        cp -rfL "${CLAUDE_HOME}/${_sync_entry}/." "${STATE_DIR}/${_sync_entry}/" 2>/dev/null || true
+    log "seeding host sessions for colima..."
+    if [[ -d "$HOST_PROJECT_SESSIONS" ]]; then
+      rsync -au "${HOST_PROJECT_SESSIONS}/" "${STATE_DIR}/projects/${PROJECT_SLUG}/" 2>/dev/null || \
+        cp -ru "${HOST_PROJECT_SESSIONS}/." "${STATE_DIR}/projects/${PROJECT_SLUG}/" 2>/dev/null || true
     fi
-  done
-  [[ -f "${CLAUDE_HOME}/.mcp.json" ]] && cp -f "${CLAUDE_HOME}/.mcp.json" "${STATE_DIR}/.mcp.json" 2>/dev/null || true
-
-  # Inbound session seeding (host -> state). The live override mounts for the
-  # project sessions dir and the satellite-state dirs are skipped on Colima, and
-  # the post-exit sync only copies state -> host. Without this, a session that
-  # exists on the host — created by host Claude, by a prior box run, or copied
-  # in by hand — is invisible inside the box. Seed newer-wins (no --delete, so
-  # it unions rather than mirrors) so an in-box-newer session isn't clobbered by
-  # a stale host copy; the flush below carries the result into the VM.
-  log "seeding host sessions for colima..."
-  if [[ -d "$HOST_PROJECT_SESSIONS" ]]; then
-    rsync -au "${HOST_PROJECT_SESSIONS}/" "${STATE_DIR}/projects/${PROJECT_SLUG}/" 2>/dev/null || \
-      cp -ru "${HOST_PROJECT_SESSIONS}/." "${STATE_DIR}/projects/${PROJECT_SLUG}/" 2>/dev/null || true
+    local _seed_sat
+    for _seed_sat in tasks session-env shell-snapshots paste-cache plans file-history; do
+      if [[ -d "${CLAUDE_HOME}/${_seed_sat}" ]]; then
+        mkdir -p "${STATE_DIR}/${_seed_sat}"
+        rsync -au "${CLAUDE_HOME}/${_seed_sat}/" "${STATE_DIR}/${_seed_sat}/" 2>/dev/null || \
+          cp -ru "${CLAUDE_HOME}/${_seed_sat}/." "${STATE_DIR}/${_seed_sat}/" 2>/dev/null || true
+      fi
+    done
   fi
-  for _seed_sat in tasks session-env shell-snapshots paste-cache plans file-history; do
-    if [[ -d "${CLAUDE_HOME}/${_seed_sat}" ]]; then
-      mkdir -p "${STATE_DIR}/${_seed_sat}"
-      rsync -au "${CLAUDE_HOME}/${_seed_sat}/" "${STATE_DIR}/${_seed_sat}/" 2>/dev/null || \
-        cp -ru "${CLAUDE_HOME}/${_seed_sat}/." "${STATE_DIR}/${_seed_sat}/" 2>/dev/null || true
-    fi
-  done
-
-  # Flush the entire state dir through Docker I/O so the VM sees everything —
-  # both the files we just synced and the volatile files (credentials, settings).
-  log "flushing state for colima..."
-  tar --no-xattrs -cf - -C "${STATE_DIR}" . 2>/dev/null \
-    | docker run --rm -i --entrypoint tar -v "${STATE_DIR}:/_state" "${IMAGE}" --no-same-owner -xf - -C /_state 2>/dev/null || true
-fi
 
-# Mount .claude.json (main state) into the container at the home dir level
-override_mounts+=(-v "${STATE_CLAUDE_JSON}:${HOME}/.claude.json")
+  # Mount .claude.json (main state) at the home dir level.
+  override_mounts+=(-v "${STATE_CLAUDE_JSON}:${HOME}/.claude.json")
+}
 
-# Set the terminal tab/window title to the project name so it's obvious which
-# box this tab belongs to (otherwise it just shows "bash" or "docker"). OSC 0
-# sets both icon name and window title — supported by iTerm2, Terminal.app,
-# gnome-terminal, kitty, alacritty, tmux, etc. Gated on stderr being a tty so
-# piped/non-interactive runs don't leak escape codes. The parent shell's
-# prompt hook normally restores its own title after we exit.
-if [[ -t 2 ]]; then
-  printf '\e]0;claude-box: %s\a' "$(basename "$PROJECT_DIR")" >&2
-fi
+# --- box_sync_back: flush sessions, credentials, and satellite state back to the
+# host, write a refreshed token back to the Keychain, and print the resume hint.
+# Runs from the cage's EXIT trap after the container has stopped; on colima the
+# cage created _CID over the state volume for docker cp.
+box_sync_back() {
+  local _state_proj="${STATE_DIR}/projects/${PROJECT_SLUG}"
 
-# Compose docker's -i/-t independently from the actual fd shapes.
-#
-# -t (allocate a PTY): only when BOTH stdout and stderr are real terminals.
-# Claude Code's Ink TUI needs a PTY on stdout for color + layout, but a PTY also
-# applies CRLF translation and merges the container's stderr into stdout. So if
-# stdout alone is redirected (`claude-box -p … > out.txt`), gating on any-of-
-# three would still allocate a PTY and corrupt the capture with \r\n and stray
-# [entrypoint] lines. Requiring both stdout and stderr to be ttys means a PTY is
-# used only for genuinely interactive runs, and any redirection drops it.
-#
-# -i (attach stdin): only when something is actually connected to stdin — a
-# terminal, a pipe, or a redirected file. Passing -i unconditionally makes a
-# supervisor that launches us with stdin at /dev/null hand Claude an immediate
-# EOF (interactive Claude then exits at once); omitting -i there leaves stdin
-# unattached, which is correct for a no-stdin invocation.
-TTY_FLAGS=()
-if [[ -t 0 || -p /dev/stdin || -f /dev/stdin || -S /dev/stdin ]]; then
-  TTY_FLAGS+=(-i)
-fi
-if [[ -t 1 && -t 2 ]]; then
-  TTY_FLAGS+=(-t)
-fi
+  if [[ -n "$_CID" ]]; then
+    # Colima: copy out through Docker's I/O path (the host can't see it directly).
+    log "syncing state back from colima..."
+    docker cp "${_CID}:/_state/projects/${PROJECT_SLUG}/." "${_state_proj}/" 2>/dev/null || true
+    docker cp "${_CID}:/_state/.claude.json" "${STATE_DIR}/.claude.json" 2>/dev/null || true
+    docker cp "${_CID}:/_state/.credentials.json" "${STATE_DIR}/.credentials.json" 2>/dev/null || true
+    local _sat
+    for _sat in tasks session-env shell-snapshots paste-cache plans file-history; do
+      docker cp "${_CID}:/_state/${_sat}/." "${STATE_DIR}/${_sat}/" 2>/dev/null || true
+    done
+  fi
 
-# Mount order matters: state volume first, then specific overrides shadow it
-# for the paths that need to reflect the host (settings, skills, CLAUDE.md).
-# Entrypoint runs as root, creates a hostuser for HOST_UID, then drops to it.
-log "starting container..."
-_LAUNCHED=1
-_rc=0
+  # Write an in-box token refresh back to the macOS Keychain, newer-wins by
+  # expiresAt. Only updates an existing item, only for a real claudeAiOauth token.
+  if command -v security >/dev/null 2>&1 \
+     && [[ -s "${STATE_DIR}/.credentials.json" ]] \
+     && grep -q '"claudeAiOauth"' "${STATE_DIR}/.credentials.json" 2>/dev/null; then
+    local _state_exp _kc_exp=0 _kc_now _kc_acct
+    _state_exp=$(_cred_expiry < "${STATE_DIR}/.credentials.json")
+    if _kc_now=$(security find-generic-password -s "Claude Code-credentials" -w 2>/dev/null) \
+       && [[ "$_kc_now" == *claudeAiOauth* ]]; then
+      _kc_exp=$(printf '%s' "$_kc_now" | _cred_expiry)
+    fi
+    _kc_acct=$(security find-generic-password -s "Claude Code-credentials" 2>/dev/null \
+      | sed -n 's/^[[:space:]]*"acct"<blob>="\(.*\)"$/\1/p')
+    if [[ -n "$_kc_acct" && "${_state_exp:-0}" -gt "${_kc_exp:-0}" ]]; then
+      security add-generic-password -U -s "Claude Code-credentials" -a "$_kc_acct" \
+        -w "$(cat "${STATE_DIR}/.credentials.json")" 2>/dev/null \
+        && log "synced refreshed Claude token back to Keychain" || true
+    fi
+  fi
 
-# Publish the box's name for a headless caller to address (docker stop/exec).
-# Written HERE — just before the container exists and inside the EXIT-trap
-# coverage (trap set above with sync_back/cleanup) — so the file's lifetime
-# matches the box's: cleanup() removes it on exit, and the container is --rm so a
-# post-exit handle would be dead anyway. A caller that only passes --name-file
-# polls for this file to appear, then reads the name.
-if [[ -n "$NAME_FILE" ]]; then
-  printf '%s\n' "$CONTAINER_NAME" > "$NAME_FILE" \
-    || warn "--name-file: could not write ${NAME_FILE}"
-fi
+  # Copy sessions to the host's Claude project dir for cross-tool resumability,
+  # preserving mtimes so the resume hint picks the just-closed session correctly.
+  cp -pf "${_state_proj}/"*.jsonl "$HOST_PROJECT_SESSIONS/" 2>/dev/null
+  cp -prf "${_state_proj}/"*/ "$HOST_PROJECT_SESSIONS/" 2>/dev/null
 
-docker run --rm "${TTY_FLAGS[@]}" \
-  --name "$CONTAINER_NAME" \
-  -e "HOST_UID=$(id -u)" \
-  -e "HOST_GID=$(id -g)" \
-  -e "HOME=${HOME}" \
-  -e "SKIP_NPM_PACKAGES_INSTALL=1" \
-  -e "GIT_CONFIG_COUNT=3" \
-  -e "GIT_CONFIG_KEY_0=safe.directory" \
-  -e "GIT_CONFIG_VALUE_0=*" \
-  -e "GIT_CONFIG_KEY_1=url.https://github.com/.insteadOf" \
-  -e "GIT_CONFIG_VALUE_1=git@github.com:" \
-  -e "GIT_CONFIG_KEY_2=credential.helper" \
-  -e "GIT_CONFIG_VALUE_2=!gh auth git-credential" \
-  -v "${PROJECT_DIR}:${PROJECT_DIR}" \
-  -v "${STATE_DIR}:${CLAUDE_HOME}" \
-  ${override_mounts[@]+"${override_mounts[@]}"} \
-  ${engine_args[@]+"${engine_args[@]}"} \
-  ${env_args[@]+"${env_args[@]}"} \
-  -w "${PROJECT_DIR}" \
-  "$IMAGE" \
-  --dangerously-skip-permissions ${CLAUDE_ARGS[@]+"${CLAUDE_ARGS[@]}"} || _rc=$?
+  # Resume hint: newest transcript by mtime across the state dir and host dir,
+  # skipping agent-*.jsonl subagent sidechains.
+  local _latest="" f _id _resume_cmd
+  for f in "${_state_proj}/"*.jsonl "${HOST_PROJECT_SESSIONS}/"*.jsonl; do
+    [[ -f "$f" ]] || continue
+    case "${f##*/}" in agent-*) continue ;; esac
+    [[ -z "$_latest" || "$f" -nt "$_latest" ]] && _latest="$f"
+  done
+  if [[ -n "$_latest" ]]; then
+    _id=$(basename "$_latest" .jsonl)
+    _resume_cmd="claude-box -r ${_id}"
+    printf '[claude-box] to resume: %s\n' "$_resume_cmd" >&2
+    printf '%s\n' "$_resume_cmd" > "${_state_proj}/.last-resume" 2>/dev/null || true
+  fi
+}
 
-# The session/credential flush + resume hint run from the EXIT trap (sync_back,
-# defined above), so they fire on a dropped session too — not just a clean exit.
-#
-# Map docker run's status to the launcher's exit contract (see header). The
-# harness's own codes pass through verbatim (0, 1–124 and signal deaths 128+);
-# docker's container-lifecycle band becomes a distinguishable launcher fault
-# with a machine-readable reason on stderr. Image-missing was already caught
-# pre-run as 125, so a 125 HERE means the container failed to start with the
-# image present — an engine/runtime rejection (bad posture, denied privileged /
-# security-opt, missing runtime). 126/127 mean docker could not exec the harness
-# (claude not executable / not found). The rare harness that itself exits in
-# 125–127 is misattributed by the code alone — the fault= line, present only on
-# a real launcher fault, is what actually disambiguates.
-case "$_rc" in
-  125)
-    fault engine-start-failed "docker could not create/start the container (check --engine posture and host runtime)"
-    _rc=126
-    ;;
-  126|127)
-    fault harness-not-executable "the container could not exec the harness (claude not found or not executable)"
-    _rc=127
-    ;;
-esac
-exit "$_rc"
+cage_run "$@"
diff --git a/codex-box b/codex-box
new file mode 100755
index 0000000..ad95bff
--- /dev/null
+++ b/codex-box
@@ -0,0 +1,220 @@
+#!/usr/bin/env bash
+# codex-box — run the OpenAI Codex CLI in the cage (see libcage.sh).
+#
+# Mounts the project dir at its exact host path so tooling resolves. Persists
+# Codex state (~/.codex: auth.json, config.toml, sessions) in ~/.codex-box/state
+# across runs — delete that dir to reset. Authenticates from a persisted
+# `codex login`: log in once on the host, and the box reuses it; an in-box login
+# or token refresh is synced back to the host on exit.
+#
+# Always runs in the current directory (the project root). cd into your project
+# first, then:
+#   codex-box                     # interactive session
+#   codex-box "fix the flaky test"# start with a prompt
+#   codex-box resume --last       # any codex subcommand/flags pass through
+#
+# Every argument is passed straight through to codex. Use `--` to force
+# everything after it to codex (e.g. `codex-box -- --engine foo`).
+#
+# codex-box-specific flags (consumed before codex sees them; position-free):
+#   --no-ssh / --upgrade / --engine <mode> / --name <name> / --name-file <path>
+# — identical to claude-box; see libcage.sh and the README.
+#
+# Installation:
+#   ln -sf ~/claude-box/codex-box /usr/local/bin/codex-box
+
+set -euo pipefail
+
+# Resolve symlinks so an install via `ln -sf` still finds the repo dir.
+_self="${BASH_SOURCE[0]}"
+while [[ -L "$_self" ]]; do
+  _link=$(readlink "$_self")
+  [[ "$_link" = /* ]] && _self="$_link" || _self="$(dirname "$_self")/$_link"
+done
+BOX_SRC_DIR="$(cd "$(dirname "$_self")" && pwd)"
+
+# --- cage config ---
+BOX_LABEL="codex-box"
+BOX_IMAGE="codex-box"
+BOX_DOCKERFILE="${BOX_SRC_DIR}/Dockerfile.codex"
+BOX_STATE_DIR="${HOME}/.codex-box/state"
+BOX_STATE_MOUNT="${HOME}/.codex"
+BOX_ENV_PREFIX="CODEX_BOX"
+BOX_FORWARD_VARS=(OPENAI_API_KEY)
+# The cage is the isolation boundary, so Codex runs with its own sandbox and
+# approval friction off (its analogue of claude's --dangerously-skip-permissions).
+# mcp_oauth_credentials_store=file forces MCP OAuth logins (e.g. the Linear
+# remote MCP) into ${CODEX_HOME}/.credentials.json instead of the OS keyring, so
+# they live under ~/.codex = the persisted, host-seeded state volume. A macOS
+# Keychain token can't cross into a Linux box; a file one seeds straight in.
+BOX_PAYLOAD_CMD=(codex --dangerously-bypass-approvals-and-sandbox -c 'mcp_oauth_credentials_store="file"')
+
+# shellcheck source=libcage.sh
+source "${BOX_SRC_DIR}/libcage.sh"
+
+# --- payload hooks ---
+
+# Extract every "Codex MCP Credentials" Keychain entry (macOS) and rewrite it as
+# ${STATE_DIR}/.credentials.json in the file format the box reads. The Keychain
+# stores a StoredOAuthTokens JSON keyed by the store key (== the Keychain account
+# name); the file wants a BTreeMap<store_key, FallbackTokenEntry> with the token
+# flattened out. So we key by the account verbatim and transform the shape.
+# All-or-nothing best effort: any failure leaves the seeded file untouched and
+# the launch proceeds. macOS-only (guards on `security`); no-op elsewhere.
+_codex_seed_mcp_from_keychain() {
+  command -v security >/dev/null 2>&1 || return 0
+  command -v node     >/dev/null 2>&1 || return 0
+
+  # Read the Keychain ONCE. Every read triggers a macOS access prompt, so once
+  # the box has a seeded .credentials.json we leave it alone: Codex refreshes the
+  # file's tokens itself in file mode via the stored refresh_token, so it stays
+  # valid without touching the Keychain again. Force a fresh read (e.g. after a
+  # host re-login) with CODEX_BOX_RESEED_MCP=1, or by deleting the state file:
+  #   rm ~/.codex-box/state/.credentials.json
+  local reseed_var="${BOX_ENV_PREFIX}_RESEED_MCP"
+  if [[ -s "${STATE_DIR}/.credentials.json" && -z "${!reseed_var:-}" ]]; then
+    return 0
+  fi
+
+  local svc="Codex MCP Credentials" accts a pw stream=""
+
+  # Account names come from dump-keychain (attributes only; no access prompt).
+  accts=$(security dump-keychain 2>/dev/null | awk -v S="$svc" '
+    /^keychain: /   { if (svce==S && acct!="") print acct; acct=""; svce="" }
+    /"acct"<blob>=/ { l=$0; sub(/.*"acct"<blob>="/,"",l); sub(/"$/,"",l); acct=l }
+    /"svce"<blob>=/ { l=$0; sub(/.*"svce"<blob>="/,"",l); sub(/"$/,"",l); svce=l }
+    END             { if (svce==S && acct!="") print acct }
+  ')
+  # Fallback to the single primary item if the dump yielded nothing.
+  if [ -z "$accts" ]; then
+    accts=$(security find-generic-password -s "$svc" -g 2>&1 \
+      | sed -n 's/^[[:space:]]*"acct"<blob>="\(.*\)"$/\1/p' | head -1)
+  fi
+  [ -n "$accts" ] || return 0
+
+  # Read each item's password (the StoredOAuthTokens JSON). This is the step that
+  # may pop a one-time Keychain access prompt per item (click Always Allow).
+  while IFS= read -r a; do
+    [ -n "$a" ] || continue
+    pw=$(security find-generic-password -s "$svc" -a "$a" -w 2>/dev/null) || continue
+    [ -n "$pw" ] || continue
+    stream+="${a}"$'\n'"${pw}"$'\n'
+  done <<< "$accts"
+  [ -n "$stream" ] || return 0
+
+  # PID-based temp name (not mktemp): BSD mktemp on macOS rejects a suffix after
+  # the X's, and this matches how the monolith stages its sync helper.
+  local xform="${TMPDIR:-/tmp}/codex-kc.$$.js"
+  cat > "$xform" <<'JSEOF'
+// stdin: alternating lines of  account\nStoredOAuthTokens-JSON\n ...
+// stdout: { "<account>": FallbackTokenEntry } for the file store.
+const fs = require('fs');
+let buf = ''; try { buf = fs.readFileSync(0, 'utf8'); } catch { process.exit(1); }
+const lines = buf.split('\n');
+const out = {};
+for (let i = 0; i + 1 < lines.length; i += 2) {
+  const acct = lines[i], raw = lines[i + 1];
+  if (!acct || !raw) continue;
+  let s; try { s = JSON.parse(raw); } catch { continue; }
+  const tr = s.token_response || {};              // WrappedOAuthTokenResponse is transparent
+  const access = tr.access_token;
+  if (!access) continue;
+  const refresh = (tr.refresh_token != null) ? tr.refresh_token : null;
+  const scopes = tr.scope ? String(tr.scope).trim().split(/\s+/).filter(Boolean) : [];
+  let expires_at = null;
+  if (s.expires_at != null) expires_at = s.expires_at;
+  else if (tr.expires_in != null) expires_at = Date.now() + Number(tr.expires_in) * 1000;
+  const sep = (acct.length >= 17) ? acct[acct.length - 17] : '|';   // ':' => executor-owned
+  const entry = {
+    server_name: s.server_name,
+    server_url: s.url,
+    client_id: s.client_id,
+    access_token: access,
+    expires_at: expires_at,
+    refresh_token: refresh,
+    scopes: scopes,
+  };
+  if (sep === ':') entry.executor_owned = true;
+  out[acct] = entry;
+}
+if (Object.keys(out).length === 0) process.exit(1);
+process.stdout.write(JSON.stringify(out, null, 2));
+JSEOF
+
+  local tmp="${STATE_DIR}/.credentials.json.tmp"
+  if printf '%s' "$stream" | node "$xform" > "$tmp" 2>/dev/null && [ -s "$tmp" ]; then
+    mv -f "$tmp" "${STATE_DIR}/.credentials.json"
+    log "seeded MCP logins from Keychain into .credentials.json"
+  else
+    rm -f "$tmp"
+  fi
+  rm -f "$xform"
+}
+
+# Seed the host's ~/.codex (login, config, sessions) into the state dir so a
+# host `codex login` is reused in the box; newer-wins (no --delete) so an
+# in-box-newer login isn't clobbered by a stale host copy. Also build the merged
+# AGENTS.md into the cage relay — Codex reads AGENTS.md natively.
+box_stage() {
+  # Seed login/config from the host, but NEVER Codex's local runtime database.
+  # logs_*.sqlite is kept open (WAL) by a running host codex, so copying it
+  # in-flight yields a torn file ("file is not a database"), which the box then
+  # rebuilds on every startup. The box keeps its OWN sqlite in the state dir
+  # across runs; only auth.json / config.toml / profiles come from the host.
+  if [[ -d "${HOME}/.codex" ]]; then
+    log "seeding ~/.codex login/config..."
+    if command -v rsync >/dev/null 2>&1; then
+      rsync -au --exclude='*.sqlite' --exclude='*.sqlite-wal' --exclude='*.sqlite-shm' \
+        --exclude='db-backups/' "${HOME}/.codex/" "${STATE_DIR}/" 2>/dev/null || true
+    else
+      # Minimal fallback (no rsync): just the config/auth files, never the DB.
+      local f
+      for f in auth.json config.toml; do
+        [[ -f "${HOME}/.codex/${f}" ]] && cp -pf "${HOME}/.codex/${f}" "${STATE_DIR}/${f}" 2>/dev/null || true
+      done
+      cp -pf "${HOME}/.codex/"*.config.toml "${STATE_DIR}/" 2>/dev/null || true
+    fi
+  fi
+
+  # Lift MCP OAuth logins (Linear, etc.) out of the macOS Keychain into the
+  # file the box reads. Standard Codex stores them under Keychain service
+  # "Codex MCP Credentials" (Auto mode), which a Linux box can't read; the box
+  # is forced to file mode, so seed ${CODEX_HOME}/.credentials.json from the
+  # Keychain here — no re-login. Mirrors claude-box's Keychain credential lift.
+  _codex_seed_mcp_from_keychain
+
+  # Merged AGENTS.md: global ~/.agents/AGENTS.md -> parent dirs -> project.
+  # Skip if the cage couldn't provide a writable relay dir (see cage_stage_gitconfig).
+  [[ -n "$RELAY_DIR" ]] || return 0
+  : > "${RELAY_DIR}/AGENTS.md"
+  [[ -f "${HOME}/.agents/AGENTS.md" ]] && cat "${HOME}/.agents/AGENTS.md" >> "${RELAY_DIR}/AGENTS.md"
+  local agents_files=()
+  local current="$PROJECT_DIR"
+  while [[ "$current" != "/" ]]; do
+    [[ -f "$current/AGENTS.md" ]] && agents_files+=("$current/AGENTS.md")
+    current="$(dirname "$current")"
+  done
+  local i f
+  for (( i=${#agents_files[@]}-1; i>=0; i-- )); do
+    f="${agents_files[$i]}"
+    printf '\n<!-- %s -->\n' "$f" >> "${RELAY_DIR}/AGENTS.md"
+    cat "$f" >> "${RELAY_DIR}/AGENTS.md"
+  done
+}
+
+# Sync the refreshed account login back to the host so host codex and the next
+# box run pick it up. Only auth.json (the ChatGPT OAuth / API-key state), which
+# is a real file on the host. MCP logins are intentionally NOT pushed back: the
+# host stores those in the Keychain (Auto mode) and ignores a file copy, and the
+# box re-seeds them from the Keychain every launch, so a pushed-back
+# .credentials.json would only be an inert, stale artifact on the host.
+box_sync_back() {
+  cage_cp_out "auth.json"
+  if [[ -s "${STATE_DIR}/auth.json" ]]; then
+    mkdir -p "${HOME}/.codex"
+    cp -pf "${STATE_DIR}/auth.json" "${HOME}/.codex/auth.json" 2>/dev/null || true
+    log "synced ~/.codex/auth.json back to host"
+  fi
+}
+
+cage_run "$@"
diff --git a/docs/cage-engine-acceptance.md b/docs/cage-engine-acceptance.md
new file mode 100644
index 0000000..9f7a290
--- /dev/null
+++ b/docs/cage-engine-acceptance.md
@@ -0,0 +1,215 @@
+# Runbook: cage / payload acceptance
+
+Proves the extraction: the cage (`libcage.sh` + `Dockerfile.cage` +
+`entrypoint-cage.sh`) owns host isolation and the nested engine exactly once,
+carries no agent harness, and runs an arbitrary payload. Two payloads,
+`claude-box` and `codex-box`, compose that one cage without duplicating it.
+
+Maps to the ticket's acceptance:
+
+- the engine block exists exactly once (Part 0)
+- the cage base image has no harness baked in (Part 1)
+- each payload composes the cage and adds only its own harness (Part 1)
+- the bounded nested engine runs inside the box, host socket never mounted (Part 2, 3)
+- the generic exec / exit-status contract holds through the cage, per payload (Part 4)
+
+## Prerequisites
+
+- A **real docker host** (Docker Desktop / OrbStack / Colima / rootless). Run
+  these on the host, not inside a box.
+- `claude-box` and `codex-box` from this branch on `PATH`.
+- A throwaway project dir that is **not** `$HOME` (the launcher refuses `$HOME`
+  and its ancestors):
+  ```sh
+  mkdir -p /tmp/cbtest && cd /tmp/cbtest && git init -q
+  ```
+- The **first run of each box builds images**: `cage-base` first, then the
+  payload image `FROM cage-base`. Warm both once and ignore their output:
+  ```sh
+  CLAUDE_BOX_EXEC=1 claude-box -- true >/dev/null 2>&1 || true
+  CODEX_BOX_EXEC=1  codex-box  -- true >/dev/null 2>&1 || true
+  ```
+- No harness auth is needed anywhere in this runbook: every in-box command uses
+  the generic exec hook (`CLAUDE_BOX_EXEC` / `CODEX_BOX_EXEC`), which replaces the
+  harness with a bare command run as the host user inside the cage.
+
+The exec hook is the seam under test. `CLAUDE_BOX_EXEC=1 claude-box -- <cmd…>`
+(or `CODEX_BOX_EXEC=1 codex-box -- <cmd…>`) runs `<cmd…>` as the in-box command
+instead of the harness, so a check can inspect the cage from the inside.
+
+---
+
+## Part 0: The engine block exists once (static, no docker)
+
+The cage's security posture and nested-engine assembly live in exactly one file.
+No payload wrapper rebuilds them.
+
+```sh
+# The ENGINE case and engine_args construction are only in libcage.sh:
+grep -rln 'engine_args+=(' .            # expect: ./libcage.sh   (one line, nothing else)
+
+# The payload wrappers source the cage; they do not re-implement it:
+grep -n 'source .*libcage.sh' claude-box codex-box   # expect: one match each
+
+# Parse-check the whole set:
+for f in claude-box codex-box libcage.sh entrypoint-cage.sh userns-probe.sh \
+         payload-init-claude.sh; do bash -n "$f" && echo "parse OK: $f"; done
+```
+
+PASS: `engine_args+=(` appears only in `libcage.sh`; both wrappers source it;
+every script parses.
+
+---
+
+## Part 1: The cage base carries no harness; each payload adds its own
+
+The base image is payload-free. Each payload image is `FROM cage-base` and adds
+exactly one harness.
+
+```sh
+# Payloads compose the cage base:
+grep -H '^FROM' Dockerfile.claude Dockerfile.codex
+# expect: Dockerfile.claude:FROM cage-base
+#         Dockerfile.codex:FROM cage-base
+
+# cage-base has NO agent harness on PATH:
+docker run --rm --entrypoint sh cage-base -c \
+  'command -v claude; command -v codex; echo "exit=$?"'
+# expect: no path printed for either; the final `command -v` returns non-zero
+
+# cage-base DOES carry the shared tooling (the cage's job):
+docker run --rm --entrypoint sh cage-base -c \
+  'for b in git gh docker dockerd-rootless.sh gosu uv; do command -v "$b" >/dev/null \
+   && echo "have $b" || echo "MISSING $b"; done'
+# expect: have git / gh / docker / dockerd-rootless.sh / gosu / uv
+
+# Each payload adds only its own harness on top of the same base:
+docker run --rm --entrypoint sh claude-box -c 'command -v claude && ! command -v codex && echo CLAUDE_ONLY'
+docker run --rm --entrypoint sh codex-box  -c 'command -v codex  && ! command -v claude && echo CODEX_ONLY'
+```
+
+PASS: `cage-base` resolves neither `claude` nor `codex` but carries the shared
+tooling; `claude-box` has `claude` and not `codex`; `codex-box` has `codex` and
+not `claude`. The boundary is clean in both directions.
+
+---
+
+## Part 2: The bounded nested engine runs inside the box
+
+The four checks the README promises, run inside each box via the exec hook. The
+default posture (`--engine auto`) resolves to `sysbox` if the host offers the
+`sysbox-runc` runtime, else `rootless`. These expectations are for the
+**rootless** default (the typical Docker Desktop / OrbStack case); the sysbox /
+rootful notes follow each check.
+
+```sh
+cd /tmp/cbtest
+
+# 1. The nested daemon reports itself, and (rootless) advertises name=rootless:
+CLAUDE_BOX_EXEC=1 claude-box -- bash -c 'docker info --format "{{.SecurityOptions}}"'
+#   rootless  -> contains  name=rootless
+#   sysbox / privileged-dind -> rootful daemon; name=rootless absent (expected)
+
+# 2. No host socket leaked in. Under rootless the daemon's own socket lives under
+#    XDG_RUNTIME_DIR, and /var/run/docker.sock is absent:
+CLAUDE_BOX_EXEC=1 claude-box -- bash -c '
+  test ! -S /var/run/docker.sock && echo "no /var/run/docker.sock (rootless OK)"
+  echo "DOCKER_HOST=$DOCKER_HOST"'
+#   rootless -> "no /var/run/docker.sock", DOCKER_HOST under /run/user/<uid>/
+#   rootful  -> /var/run/docker.sock present but owned by the NESTED daemon,
+#               created in-box (never a host mount)
+
+# 3. The nested engine is real: it pulls and runs a container end to end:
+CLAUDE_BOX_EXEC=1 claude-box -- bash -c 'docker run --rm hello-world' | grep -q 'Hello from Docker' \
+  && echo "NESTED ENGINE RUNS CONTAINERS"
+
+# 4. The same holds for the codex payload (same cage, same engine):
+CODEX_BOX_EXEC=1 codex-box -- bash -c 'docker info --format "{{.SecurityOptions}}"'
+```
+
+PASS: `docker info` answers inside both boxes; under the rootless default it
+contains `name=rootless` and `/var/run/docker.sock` is absent; `hello-world`
+runs to completion. Under `--engine sysbox` or `--engine privileged-dind` the
+daemon is rootful (no `name=rootless`) and `/var/run/docker.sock` is the nested
+daemon's own, created in-box.
+
+To force a specific posture: `--engine rootless|sysbox|privileged-dind|none`.
+With `--engine none` every `docker …` inside the box fails to connect; that is
+the expected result, not a fault.
+
+---
+
+## Part 3: A mounted host socket is refused (both payloads)
+
+The cage voids its own isolation if a host docker socket is present, so the
+entrypoint refuses to start when one is mounted. This is the cage's guarantee,
+so it must hold for every payload.
+
+Mount your host's real socket at the in-box path `/var/run/docker.sock`. Use
+whichever host socket exists:
+
+```sh
+cd /tmp/cbtest
+# Docker Desktop / rootful host:
+SOCK=/var/run/docker.sock
+# Rootless host: SOCK="${XDG_RUNTIME_DIR}/docker.sock"  (e.g. /run/user/$(id -u)/docker.sock)
+
+CLAUDE_BOX_EXTRA_MOUNTS=("${SOCK}:/var/run/docker.sock") \
+  CLAUDE_BOX_EXEC=1 claude-box -- true 2>err.txt; echo "exit=$?"
+grep -q 'FATAL: /var/run/docker.sock is mounted from the host' err.txt && echo "CLAUDE REFUSED"
+
+CODEX_BOX_EXTRA_MOUNTS=("${SOCK}:/var/run/docker.sock") \
+  CODEX_BOX_EXEC=1 codex-box -- true 2>err.txt; echo "exit=$?"
+grep -q 'FATAL: /var/run/docker.sock is mounted from the host' err.txt && echo "CODEX REFUSED"
+```
+
+PASS: both boxes print the `FATAL: /var/run/docker.sock is mounted from the host`
+refusal and exit non-zero without ever reaching the harness. The refusal lives in
+`entrypoint-cage.sh` (shared), so adding a third payload inherits it for free.
+
+---
+
+## Part 4: The generic exec / exit-status contract holds per payload
+
+The exit-status contract is the cage's, exercised through each wrapper. The
+harness's status propagates verbatim; a launcher fault maps to its own code. (The
+exhaustive exit-mapping matrix is in
+[runbook-headless-exit.md](runbook-headless-exit.md); here we only confirm the
+seam is wired identically for both payloads.)
+
+```sh
+cd /tmp/cbtest
+
+for box in "claude-box:CLAUDE_BOX_EXEC" "codex-box:CODEX_BOX_EXEC"; do
+  name="${box%%:*}"; var="${box##*:}"
+  env "$var=1" "$name" -- bash -c 'exit 0'   ; echo "$name success -> $?  (expect 0)"
+  env "$var=1" "$name" -- bash -c 'exit 7'   ; echo "$name status  -> $?  (expect 7)"
+  env "$var=1" "$name" -- bash -c 'kill -INT $$'; echo "$name signal -> $?  (expect 130)"
+done
+
+# The passthrough round-trips stdin (proves -i gating) for both:
+printf 'PING\n' | CLAUDE_BOX_EXEC=1 claude-box -- cat   # expect: PING
+printf 'PING\n' | CODEX_BOX_EXEC=1  codex-box  -- cat   # expect: PING
+```
+
+PASS: each box returns `0`, `7`, `130` verbatim with no `fault=` line (these are
+harness statuses, not launcher faults), and round-trips the pipe. Identical
+behaviour across both payloads confirms the contract lives in the cage, not the
+wrapper.
+
+---
+
+## Results checklist
+
+| # | Criterion | Expected |
+|---|---|---|
+| 0 | engine block exists once | `engine_args+=(` only in `libcage.sh`; both wrappers source it |
+| 1 | cage base is harness-free | `cage-base` resolves neither `claude` nor `codex` |
+| 1 | cage base carries shared tooling | `git`/`gh`/`docker`/`dockerd-rootless.sh`/`gosu`/`uv` present |
+| 1 | payloads compose the cage | each is `FROM cage-base`; adds only its own harness |
+| 2 | nested engine reports itself | `docker info` answers in both boxes |
+| 2 | rootless posture | `SecurityOptions` contains `name=rootless`; no `/var/run/docker.sock` |
+| 2 | nested engine runs containers | `hello-world` completes in-box |
+| 3 | host socket refused | both boxes print the FATAL refusal, exit non-zero, never reach the harness |
+| 4 | exit status per payload | `0` / `7` / `130` verbatim, no `fault=` line, both payloads |
+| 4 | stdin round-trip per payload | `PING` echoes back for both |
diff --git a/docs/runbook-headless-exit.md b/docs/runbook-headless-exit.md
index 31bd6a9..37cbf2f 100644
--- a/docs/runbook-headless-exit.md
+++ b/docs/runbook-headless-exit.md
@@ -14,8 +14,8 @@ acceptance criteria.
   ```sh
   mkdir -p /tmp/cbtest && cd /tmp/cbtest && git init -q
   ```
-- The **first run rebuilds the image** (entrypoint.sh changed → mtime triggers a
-  rebuild). Warm it once and ignore its output:
+- The **first run builds images** (`cage-base`, then the `claude-box` payload
+  image). Warm them once and ignore the output:
   ```sh
   claude-box -- --version >/dev/null 2>&1 || true
   ```
@@ -25,14 +25,14 @@ acceptance criteria.
 Two test hooks (both forwarded into the box by this branch):
 - `CLAUDE_BOX_EXEC=1 claude-box -- <cmd…>` runs `<cmd…>` as the in-box harness
   instead of `claude`, so you can make the harness exit with any status.
-- `CLAUDE_BOX_DEBUG=1` opts into the entrypoint's state dump.
+- `CLAUDE_BOX_DEBUG=1` opts into the cage's state dump.
 
 ---
 
 ## Part 0 — Static checks (no docker)
 
 ```sh
-bash -n claude-box && bash -n entrypoint.sh && echo "parse OK"
+bash -n claude-box && bash -n libcage.sh && bash -n entrypoint-cage.sh && echo "parse OK"
 ```
 
 Exit-code mapping, in isolation (this is the authoritative check for the 127
@@ -90,7 +90,7 @@ Break the build in a throwaway copy of the repo so the real one is untouched
 ```sh
 REPO=~/src/claude-box            # adjust
 cp -r "$REPO" /tmp/cb-broken
-printf '\nRUN exit 1\n' >> /tmp/cb-broken/Dockerfile
+printf '\nRUN exit 1\n' >> /tmp/cb-broken/Dockerfile.claude
 docker rmi -f claude-box >/dev/null 2>&1 || true
 
 cd /tmp/cbtest
@@ -155,7 +155,7 @@ the tty-gated `log()` would have dropped it; `fault()` does not.
 
 ## Part 3 — Streams & TTY
 
-### 3a. Redirected stdout is clean: no CRLF, no `[entrypoint]`, nothing from stderr
+### 3a. Redirected stdout is clean: no CRLF, no `[cage]`, nothing from stderr
 
 Run from an **interactive terminal** (stdout → file, stderr → terminal):
 
@@ -165,7 +165,7 @@ CLAUDE_BOX_EXEC=1 claude-box -- bash -c 'printf "hello\n"' > out.txt
 
 od -c out.txt | head -1                       # expect: h e l l o \n   (no \r)
 printf 'CR count:        '; grep -c $'\r' out.txt          # expect 0
-printf 'entrypoint lines: '; grep -c '\[entrypoint\]' out.txt   # expect 0
+printf 'cage log lines:  '; grep -c '\[cage\]' out.txt   # expect 0
 printf 'line count:      '; wc -l < out.txt   # expect 1
 ```
 
@@ -173,10 +173,10 @@ Real-harness variant (needs auth):
 
 ```sh
 claude-box -p 'reply with exactly: hello' > out2.txt
-grep -c $'\r' out2.txt ; grep -c '\[entrypoint\]' out2.txt   # both 0
+grep -c $'\r' out2.txt ; grep -c '\[cage\]' out2.txt   # both 0
 ```
 
-PASS: `out.txt` is exactly `hello\n`; no `\r`, no `[entrypoint]` lines, no stderr
+PASS: `out.txt` is exactly `hello\n`; no `\r`, no `[cage]` lines, no stderr
 content leaked into the file.
 
 ### 3b. `-i` only when stdin is connected
@@ -205,12 +205,13 @@ cd /tmp/cbtest
 CLAUDE_BOX_EXEC=1 claude-box -- true </dev/null 2>off.txt
 CLAUDE_BOX_DEBUG=1 CLAUDE_BOX_EXEC=1 claude-box -- true </dev/null 2>on.txt
 
-printf 'default dump lines: '; grep -c '.credentials.json:' off.txt   # expect 0
-printf 'debug dump lines:   '; grep -c '.credentials.json:' on.txt    # expect >=1
+printf 'default dump lines: '; grep -c 'state mount' off.txt   # expect 0
+printf 'debug dump lines:   '; grep -c 'state mount' on.txt    # expect >=1
 ```
 
-PASS: no credential/`.claude.json` dump by default; present under
-`CLAUDE_BOX_DEBUG=1`.
+PASS: no dump by default; the `[cage] state mount (…)` listing appears only under
+`CLAUDE_BOX_DEBUG=1`. The cage dump lists the state mount and, unlike the old
+monolith, never cats credential file contents.
 
 ---
 
@@ -302,7 +303,7 @@ with `[claude-box] --name: invalid container name` and starts nothing.
 | 2b | engine start failed | exit 126 + `fault=engine-start-failed` | PASS
 | 2c | harness not executable | mapping check `126/127→127`; live `fault=harness-not-executable` |
 | 2d | fault line, fully headless | line present in captured stderr |
-| 3a | redirected stdout | no `\r`, no `[entrypoint]`, no stderr leak |
+| 3a | redirected stdout | no `\r`, no `[cage]`, no stderr leak |
 | 3b | `-i` gating | pipe round-trips; no-stdin run doesn't hang (≠124) |
 | 3c | debug dump | absent by default; present with `CLAUDE_BOX_DEBUG=1` |
 | 4 | SIGINT headless | launcher exits; no live/lingering container |
diff --git a/docs/superpowers/plans/2026-08-09-headless-diagnostics-and-handle.md b/docs/superpowers/plans/2026-08-09-headless-diagnostics-and-handle.md
deleted file mode 100644
index 79c8ec7..0000000
--- a/docs/superpowers/plans/2026-08-09-headless-diagnostics-and-handle.md
+++ /dev/null
@@ -1,322 +0,0 @@
-# Headless Diagnostics and Addressable Box Handle Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Make `claude-box` warnings survive a non-terminal stderr, and give a headless caller an addressable handle (`--name` / `--name-file`) on the box it started.
-
-**Architecture:** Add a `warn()` helper (unconditional on the tty, like the existing `fault()`) and route the four genuine launcher warnings through it. Add `--name` / `--name-file` as claude-box's own flags in the existing option loop; `--name` overrides the default PID-based container name, `--name-file` publishes the resolved name to a path just before launch and removes it on exit.
-
-**Tech Stack:** POSIX-ish bash (the `claude-box` launcher), docker CLI. No unit-test framework in this repo — gates are `bash -n` and the manual runbook (`docs/runbook-headless-exit.md`).
-
-## Global Constraints
-
-- No em dashes in code comments or docs copy; use commas/colons or split sentences. (Repo AGENTS.md rule.)
-- Never use `log()` for anything that must reach a headless caller — `log()` is tty-gated by design. Use `warn()` (warnings) or `fault()` (launcher faults).
-- Warnings and faults go to **stderr**, never stdout — the exit-status work guarantees a redirected stdout carries only the harness's output.
-- claude-box's own flags are parsed in the loop at `claude-box:107-127` and stripped from `"$@"` before forwarding to `claude`; the `--` escape hatch forwards a same-named claude flag verbatim.
-- Docker container-name charset: `^[a-zA-Z0-9][a-zA-Z0-9_.-]*$`.
-- Match sibling-flag conventions: bad flag usage prints `[claude-box] <msg>` to stderr and `exit 1` (see `--ollama` / `--engine`).
-- After every edit: `bash -n claude-box && bash -n entrypoint.sh` must pass.
-
----
-
-### Task 1: `warn()` channel — warnings survive headless
-
-**Files:**
-- Modify: `claude-box:71-77` (add `warn()` after `fault()`), `claude-box:523`, `claude-box:531-534`, `claude-box:543-544`, `claude-box:720`
-
-**Interfaces:**
-- Produces: `warn <text>` — prints `[claude-box] WARNING: <text>` to stderr unconditionally (used by later routing and by `--name-file` in Task 3).
-
-- [ ] **Step 1: Baseline check — confirm warnings are currently tty-gated**
-
-Run: `grep -n 'log "WARNING\|log "warning' claude-box`
-Expected: four regions match (523, 531-534, 543-544, 720) — all routed through the tty-gated `log()`.
-
-- [ ] **Step 2: Add the `warn()` helper**
-
-Immediately after the `fault()` definition (ends at `claude-box:77`), add:
-
-```sh
-# Machine-facing WARNING line. Like fault(), UNCONDITIONAL on the tty: a headless
-# caller (CI, a supervisor) relies on these to explain why a rootless engine or
-# SSH relay didn't come up, which log() would silently drop when stderr is not a
-# terminal. Goes to stderr, so a redirected stdout still carries only the
-# harness's output. Interactive runs print the identical line (warn() ignores the
-# tty), so headless and interactive stderr match verbatim.
-warn() { printf '[claude-box] WARNING: %s\n' "$*" >&2; }
-```
-
-- [ ] **Step 3: Route the userns-unsupported block through `warn()`**
-
-At `claude-box:531-534`, replace the four `log "WARNING: …"` lines (drop the now-redundant `WARNING:` prefix, `warn()` adds it):
-
-```sh
-        warn "this docker host cannot give an unprivileged user a capable user"
-        warn "namespace, so the rootless nested engine will likely fail to start."
-        warn "consider sysbox, or '--engine privileged-dind' (ADR-0041's named"
-        warn "weaker posture), or '--engine none'."
-```
-
-- [ ] **Step 4: Route the remaining three warning sites through `warn()`**
-
-- `claude-box:523`: `_load_userns_profile || warn "apparmor profile load failed — engine may not start"`
-- `claude-box:543-544`:
-  ```sh
-    warn "--engine privileged-dind is ADR-0041's named weaker posture:"
-    warn "a privileged cage weakens host isolation. Prefer sysbox or rootless."
-  ```
-  (Note: the original line 543 ends with an em dash; the replacement uses a colon per the no-em-dash rule.)
-- `claude-box:720`: `warn "SSH agent relay failed to start — signing will not work"` becomes `warn "SSH agent relay failed to start: signing will not work"` (drop `warning:` prefix and the em dash).
-
-- [ ] **Step 5: Verify no genuine warning still uses `log()`, and parse is clean**
-
-Run: `grep -n 'log "WARNING\|log "warning' claude-box; bash -n claude-box && echo "parse OK"`
-Expected: the grep prints nothing (all four routed), `parse OK`.
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add claude-box
-git commit -m "feat: route launcher warnings through an unconditional warn()"
-```
-
----
-
-### Task 2: `--name` flag — caller-supplied container name
-
-**Files:**
-- Modify: `claude-box:102-128` (declare `BOX_NAME`, parse `--name`, validate after loop), `claude-box:195` (resolve `CONTAINER_NAME`)
-
-**Interfaces:**
-- Consumes: nothing from Task 1.
-- Produces: `BOX_NAME` (string, empty when `--name` absent); `CONTAINER_NAME` now resolves from it (consumed by Task 3's name-file write, already used at `claude-box:263-264`, `1076`).
-
-- [ ] **Step 1: Declare `BOX_NAME` and parse `--name` in the option loop**
-
-At `claude-box:102-106`, add `BOX_NAME=""` alongside `NO_SSH=0` etc. In the `case` at `claude-box:108-125`, add before the `*)` catch-all:
-
-```sh
-    --name)
-      shift
-      BOX_NAME="${1:-}"
-      [[ -n "$BOX_NAME" ]] || { printf '[claude-box] --name requires a container name\n' >&2; exit 1; }
-      ;;
-    --name=*) BOX_NAME="${1#*=}" ;;
-```
-
-- [ ] **Step 2: Validate the name after the loop**
-
-Immediately after the loop's `set -- "${_passthrough[@]+"${_passthrough[@]}"}"` (`claude-box:128`), add:
-
-```sh
-# A caller-supplied box name must satisfy docker's container-name charset;
-# reject early (before any docker call) with a precise message rather than
-# letting `docker run --name` fail obscurely mid-launch. Pre-flight usage error,
-# so exit 1 like the sibling flags, not the run-time fault()/125-127 path.
-if [[ -n "$BOX_NAME" && ! "$BOX_NAME" =~ ^[a-zA-Z0-9][a-zA-Z0-9_.-]*$ ]]; then
-  printf '[claude-box] --name: invalid container name (allowed: [a-zA-Z0-9][a-zA-Z0-9_.-]*)\n' >&2
-  exit 1
-fi
-```
-
-- [ ] **Step 3: Resolve `CONTAINER_NAME` from `BOX_NAME`**
-
-At `claude-box:195`, replace:
-
-```sh
-CONTAINER_NAME="claude-box-$(basename "$PROJECT_DIR")-$$"
-```
-
-with:
-
-```sh
-# A caller-supplied --name wins; otherwise the default stays unique per launcher
-# via the PID, so concurrent boxes never collide.
-CONTAINER_NAME="${BOX_NAME:-claude-box-$(basename "$PROJECT_DIR")-$$}"
-```
-
-- [ ] **Step 4: Behavioral test — a bad `--name` is rejected before docker**
-
-Run:
-```bash
-bash -n claude-box && \
-( cd "$(mktemp -d)" && git init -q && "$OLDPWD/claude-box" --name 'a b/c' >/dev/null 2>err.txt; echo "exit=$?"; cat err.txt )
-```
-Expected: `exit=1` and stderr contains `[claude-box] --name: invalid container name`. No docker build or run happens (the reject is in the option loop, well before `claude-box:206`).
-
-- [ ] **Step 5: Behavioral test — the empty-value form is rejected**
-
-Run: `( cd "$(mktemp -d)" && git init -q && "$OLDPWD/claude-box" --name >/dev/null 2>err.txt; echo "exit=$?"; grep -q 'requires a container name' err.txt && echo MSG_OK )`
-Expected: `exit=1`, `MSG_OK`.
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add claude-box
-git commit -m "feat: add --name to set the box's container name"
-```
-
----
-
-### Task 3: `--name-file` flag — publish the resolved name for a headless caller
-
-**Files:**
-- Modify: `claude-box:102-125` (declare `NAME_FILE`, parse `--name-file`), `claude-box:233-238` (`cleanup()` removes the file), `claude-box:1073` region (write the file just before `docker run`)
-
-**Interfaces:**
-- Consumes: `CONTAINER_NAME` (Task 2), `warn()` (Task 1).
-- Produces: `NAME_FILE` (string, empty when absent). No later task depends on it.
-
-- [ ] **Step 1: Declare `NAME_FILE` and parse `--name-file`**
-
-At `claude-box:102-106`, add `NAME_FILE=""`. In the `case`, add before `*)`:
-
-```sh
-    --name-file)
-      shift
-      NAME_FILE="${1:-}"
-      [[ -n "$NAME_FILE" ]] || { printf '[claude-box] --name-file requires a path\n' >&2; exit 1; }
-      ;;
-    --name-file=*) NAME_FILE="${1#*=}" ;;
-```
-
-- [ ] **Step 2: Write the resolved name just before `docker run`**
-
-At the `_LAUNCHED=1` line (`claude-box:1073`), immediately after it and before the `docker run` invocation, add:
-
-```sh
-# Publish the box's name for a headless caller to address (docker stop/exec).
-# Written HERE — just before the container exists and inside the EXIT-trap
-# coverage (trap set at the sync_back/cleanup line above) — so the file's
-# lifetime matches the box's: cleanup() removes it on exit, and the container is
-# --rm so a post-exit handle would be dead anyway. A caller that only passes
-# --name-file polls for this file to appear, then reads the name.
-if [[ -n "$NAME_FILE" ]]; then
-  printf '%s\n' "$CONTAINER_NAME" > "$NAME_FILE" \
-    || warn "--name-file: could not write ${NAME_FILE}"
-fi
-```
-
-- [ ] **Step 3: Remove the file in `cleanup()`**
-
-In `cleanup()` (`claude-box:233-238`), add before the closing `}`:
-
-```sh
-  [[ -n "$NAME_FILE" ]] && rm -f "$NAME_FILE"
-```
-
-- [ ] **Step 4: Behavioral test — `--name-file` parses and the empty form is rejected**
-
-Run: `bash -n claude-box && ( cd "$(mktemp -d)" && git init -q && "$OLDPWD/claude-box" --name-file >/dev/null 2>err.txt; echo "exit=$?"; grep -q 'requires a path' err.txt && echo MSG_OK )`
-Expected: `parse OK` (implied by no error), `exit=1`, `MSG_OK`.
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add claude-box
-git commit -m "feat: add --name-file to publish the box name for headless callers"
-```
-
----
-
-### Task 4: Documentation — header block, runbook, README
-
-**Files:**
-- Modify: `claude-box` header comment (the exit-status contract block, ~`claude-box:45-62`), `docs/runbook-headless-exit.md`, `README` (the flag/usage list)
-
-**Interfaces:**
-- Consumes: the behaviors from Tasks 1-3. Produces: no code.
-
-- [ ] **Step 1: Document the two flags in the claude-box header block**
-
-In the header comment block that already documents the exit-status contract, add a short section:
-
-```sh
-# Addressing a headless box:
-#   --name <name>       set the container name (default: claude-box-<project>-<pid>).
-#                       Must match docker's charset [a-zA-Z0-9][a-zA-Z0-9_.-]*.
-#   --name-file <path>  write the resolved name to <path> just before launch and
-#                       remove it on exit. A supervisor polls <path>, reads the
-#                       name, then `docker stop`/`docker exec` the box.
-```
-
-- [ ] **Step 2: Add a "warnings survive headless" part to the runbook**
-
-Append to `docs/runbook-headless-exit.md` a part that asserts warn() output is tty-independent, e.g.:
-
-```markdown
-## Part 4 — Warnings survive a non-terminal stderr
-
-Warnings must reach captured stderr headless, identically to an interactive run.
-Force the userns-unsupported path (or any warn() site) and capture stderr:
-
-```sh
-# On a host whose userns probe resolves `unsupported`, or with the strategy
-# cache primed to it: rm -f ~/.claude-box/.userns-strategy-*; echo unsupported > ~/.claude-box/.userns-strategy-<docker-host-slug>
-claude-box --engine rootless -- --version >out.txt 2>err.txt || true
-grep -q '\[claude-box\] WARNING: this docker host cannot' err.txt && echo "WARN_HEADLESS_OK"
-```
-
-Expected: `WARN_HEADLESS_OK`. The same line appears on an interactive run's terminal.
-```
-
-- [ ] **Step 3: Add a "start headless → read name → stop" part to the runbook**
-
-Append a part that exercises the handle via the existing `CLAUDE_BOX_EXEC` hook:
-
-```markdown
-## Part 5 — Address a box started headless
-
-```sh
-h="$(mktemp)"
-CLAUDE_BOX_EXEC=1 claude-box --name-file "$h" -- sleep 300 >/dev/null 2>&1 &
-launcher=$!
-# Poll for the launcher to publish the name (it appears just before the box starts).
-for i in $(seq 1 100); do [ -s "$h" ] && break; sleep 0.1; done
-name="$(cat "$h")"; echo "handle=$name"
-docker exec "$name" true && echo "EXEC_OK"
-docker stop "$name" >/dev/null && echo "STOP_OK"
-wait "$launcher" 2>/dev/null
-[ -e "$h" ] || echo "NAME_FILE_CLEANED"
-```
-
-Expected: `handle=…`, `EXEC_OK`, `STOP_OK`, `NAME_FILE_CLEANED`.
-```
-
-- [ ] **Step 4: Add both flags to the README usage/flag list**
-
-In `README` where `--no-ssh` / `--engine` / `--ollama` are listed, add:
-
-```markdown
-- `--name <name>` — name the box's container (default `claude-box-<project>-<pid>`); lets a caller address it with `docker stop`/`docker exec`.
-- `--name-file <path>` — write the resolved container name to `<path>` just before launch (removed on exit), so a headless supervisor can discover and stop the box.
-```
-
-- [ ] **Step 5: Verify docs reference real behavior and commit**
-
-Run: `grep -n 'name-file\|--name ' README docs/runbook-headless-exit.md claude-box | head`
-Expected: matches in all three files.
-
-```bash
-git add claude-box README docs/runbook-headless-exit.md
-git commit -m "docs: document --name/--name-file and headless-warning acceptance"
-```
-
----
-
-## Self-Review
-
-**Spec coverage:**
-- Goal 1 (warnings survive headless) → Task 1 + runbook Part 4 (Task 4 Step 2). ✓
-- Goal 2 (addressable handle) → Task 2 (`--name`) + Task 3 (`--name-file`) + runbook Part 5 (Task 4 Step 3). ✓
-- Spec §1 warn() + four sites → Task 1. ✓
-- Spec §2 `--name` parse/validate/resolve → Task 2; `--name-file` write/cleanup/unwritable→warn → Task 3. ✓
-- Spec §3 docs (header, runbook, README) → Task 4. ✓
-- Spec §4 acceptance (bash -n, diagnostics, handle, `--name` validation) → per-task `bash -n` + Task 2 Steps 4-5 + Task 4 Parts 4-5. ✓
-
-**Placeholder scan:** No TBD/TODO; every code step shows exact old→new text. ✓
-
-**Type/name consistency:** `warn` (Task 1) used in Tasks 3-4. `BOX_NAME` → `CONTAINER_NAME` (Task 2) consumed by Task 3's write and the existing `docker run --name`. `NAME_FILE` declared/parsed (Task 3 Step 1), written (Step 2), removed (Step 3). Consistent. ✓
-
-**Note on testing:** Tasks 1 and 3's docker-dependent behavior (warn on a real unsupported host; the name-file write/cleanup during an actual run) is verified through the runbook, since the repo has no docker-free way to exercise a launch. Tasks 2's validation and the empty-value rejections ARE exercised docker-free because they reject inside the option loop before any docker call.
diff --git a/docs/superpowers/specs/2026-08-09-headless-diagnostics-and-handle-design.md b/docs/superpowers/specs/2026-08-09-headless-diagnostics-and-handle-design.md
deleted file mode 100644
index 1f232bb..0000000
--- a/docs/superpowers/specs/2026-08-09-headless-diagnostics-and-handle-design.md
+++ /dev/null
@@ -1,155 +0,0 @@
-# Headless diagnostics and an addressable box handle
-
-## Problem
-
-Two gaps make `claude-box` hard to drive from a script, CI job, or supervisor —
-exactly the callers the recent headless exit-status work was meant to serve.
-
-1. **Diagnostics vanish when stderr is not a terminal.** The launcher's `log()`
-   is `[[ ! -t 2 ]] || printf …` — every line it emits is suppressed unless
-   stderr is a tty. Headless, that discards the warnings that matter most:
-   - the userns-unsupported block (`claude-box:531-534`) — "this docker host
-     cannot give an unprivileged user a capable user namespace, so the rootless
-     nested engine will likely fail to start";
-   - the apparmor-profile-load failure (`claude-box:523`);
-   - the privileged-dind weaker-posture notice (`claude-box:543-544`);
-   - the SSH-agent-relay failure (`claude-box:720`).
-
-   So a rootless engine that fails to come up does so with no launcher-side
-   explanation — the one thing a CI log exists to provide.
-
-2. **A headless caller has no handle on the box it started.** `CONTAINER_NAME`
-   (`claude-box:195`) embeds the launcher's PID and is passed to
-   `docker run --name`, but a caller has no supported way to learn it, so it
-   cannot `docker stop` or `docker exec` the box it launched.
-
-## Goals
-
-- A warning printed on an interactive run also reaches captured stderr on a
-  headless run, verbatim.
-- A caller can start a box headless, obtain its container name from a documented
-  place, and `docker stop` / `docker exec` it.
-
-## Non-goals (YAGNI)
-
-- No `docker ps` parsing or name-guessing.
-- No handle for the *inner* nested engine — only the outer session container.
-- No structured/JSON status output.
-- No new exit codes; the existing contract (0 / 1-124 / 125-127 / 128+) stands.
-
-## Design
-
-### 1. `warn()` — diagnostics unconditional on the tty
-
-Add a sibling to the existing `fault()` helper:
-
-```sh
-warn() { printf '[claude-box] WARNING: %s\n' "$*" >&2; }
-```
-
-- **Unconditional on the tty**, like `fault()`. It must reach captured stderr
-  whether or not stderr is a terminal.
-- **Writes to stderr**, so the clean-stdout capture contract from the
-  exit-status work is preserved — a redirected stdout still carries only the
-  harness's output.
-
-Route the four genuine warnings through `warn()`, dropping their now-redundant
-inline `WARNING:` / `warning:` prefixes:
-
-| Site | Current | Becomes |
-| --- | --- | --- |
-| `claude-box:531-534` | 4× `log "WARNING: …"` (userns unsupported) | 4× `warn "…"` |
-| `claude-box:523` | `log "WARNING: apparmor profile load failed …"` | `warn "apparmor profile load failed …"` |
-| `claude-box:543-544` | 2× `log "WARNING: --engine privileged-dind …"` | 2× `warn "--engine privileged-dind …"` |
-| `claude-box:720` | `log "warning: SSH agent relay failed …"` | `warn "SSH agent relay failed …"` |
-
-Informational `log()` calls (`building image…`, `starting container…`, the
-`engine:` / userns-strategy lines) stay tty-gated, so a headless capture gets
-warnings only, not progress noise.
-
-Because `warn()` also prints on a tty, an interactive run and a headless run
-emit the **identical** warning text — that is precisely the acceptance check.
-Interactive output is otherwise unchanged.
-
-### 2. Addressable handle — `--name` and `--name-file`
-
-Both are claude-box's own flags, parsed in the existing option loop
-(`claude-box:107-127`) alongside `--ollama` / `--engine`, matching their
-`--flag value` and `--flag=value` shapes. They are stripped from `"$@"` before
-the remainder is forwarded to `claude`. The existing `--` escape hatch
-(`claude-box:99-101`) already covers the unlikely day `claude` grows its own
-`--name`: `claude-box -- --name foo` forwards it verbatim.
-
-**`--name <name>` / `--name=<name>`** — caller-supplied container name.
-
-- Default is unchanged: `claude-box-$(basename "$PROJECT_DIR")-$$` (still unique
-  across concurrent boxes via the PID).
-- Resolution at `claude-box:195` becomes:
-  `CONTAINER_NAME="${_cli_name:-claude-box-$(basename "$PROJECT_DIR")-$$}"`
-  where `_cli_name` is the parsed flag value (empty when not given).
-- Validated against docker's container-name charset
-  `^[a-zA-Z0-9][a-zA-Z0-9_.-]*$`. On a bad value:
-  `printf '[claude-box] --name: invalid container name (allowed: [a-zA-Z0-9][a-zA-Z0-9_.-]*)\n' >&2; exit 1`
-  — matching how `--ollama` / `--engine` reject bad args (plain `[claude-box]`
-  message, `exit 1`, already headless-safe). This pre-flight usage error
-  deliberately uses `exit 1` rather than the run-time `fault()` / 125-127 path,
-  consistent with its sibling flags.
-
-**`--name-file <path>` / `--name-file=<path>`** — where to publish the resolved
-name.
-
-- Write the resolved `CONTAINER_NAME` (caller-supplied or auto) to `<path>`
-  **just before `docker run`** (the `_LAUNCHED=1` region, ~`claude-box:1073`):
-  `printf '%s\n' "$CONTAINER_NAME" > "$_name_file"`.
-  - This point is chosen so the file appears exactly when the container is about
-    to exist, and it is inside the EXIT-trap coverage (the trap is installed at
-    `claude-box:352`, before the run). Writing earlier (e.g. at arg-parse time)
-    would publish a handle before any container exists, and — on an early
-    `exit 125` from the pre-run image checks, which run before the trap is set —
-    would strand a stale file.
-- Remove it in `cleanup()` (`claude-box:233`): the container is `--rm`, so once
-  the box exits the name addresses nothing; the file's lifetime matches the
-  box's.
-- If `<path>` is unwritable: `warn "--name-file: could not write <path>"` and
-  continue. Losing the handle does not justify failing the run.
-
-**How the two compose.** `--name` is for a caller that wants to choose the
-handle (it already knows the name; no read-back needed). `--name-file` is for a
-caller that wants the launcher to own uniqueness and then read the auto-name
-back. Supplying both is allowed and simply writes the caller's chosen name to
-the file. A caller that only sets `--name-file` polls for the file to appear,
-reads the name, then stops/execs the box.
-
-### 3. Documentation
-
-- **claude-box header block** — document `--name` and `--name-file` next to the
-  exit-status contract.
-- **`docs/runbook-headless-exit.md`** — add two parts: (a) *warnings survive
-  headless* — force the userns-unsupported path and assert the warning is in
-  captured stderr; (b) *start headless → read name → stop* — launch with
-  `--name-file`, poll for it, `docker stop` the box.
-- **README** — add both flags to the flag/usage list.
-
-## Testing / acceptance
-
-- `bash -n claude-box && bash -n entrypoint.sh` parses clean (the repo's static
-  gate).
-- **Diagnostics (goal 1):** on a host where the userns probe resolves
-  `unsupported`, a headless run's captured stderr contains the same
-  `[claude-box] WARNING: this docker host cannot …` line an interactive run
-  prints. (The runbook forces this path; where a real unsupported host isn't
-  available, the assertion is that `warn()` output is tty-independent.)
-- **Handle (goal 2):** using the existing `CLAUDE_BOX_EXEC` hook to hold a box
-  open, `--name-file /tmp/h` publishes the name, a poll reads it, and
-  `docker stop "$(cat /tmp/h)"` stops the box; the file is gone afterward.
-- **`--name` validation:** a bad `--name 'a b/c'` exits 1 with the
-  `[claude-box] --name: invalid …` message and starts no container; a valid
-  `--name my-box` is the container's name under `docker ps`.
-
-## Files touched
-
-- `claude-box` — `warn()` helper; four warning sites re-routed; `--name` /
-  `--name-file` parsing, validation, resolution, name-file write, cleanup;
-  header-block docs.
-- `docs/runbook-headless-exit.md` — two new acceptance parts.
-- `README` — two new flags.
diff --git a/entrypoint-cage.sh b/entrypoint-cage.sh
new file mode 100755
index 0000000..f50b5ed
--- /dev/null
+++ b/entrypoint-cage.sh
@@ -0,0 +1,186 @@
+#!/bin/bash
+# cage-entrypoint — the payload-free entrypoint shared by every box.
+#
+# Creates a passwd/group entry for the host UID (interactive harnesses such as
+# Claude Code and Codex silently exit when getpwuid() returns nothing), starts
+# the bounded nested engine, wires the ssh relays, then execs whatever command
+# the launcher handed it as the host user. The command IS the payload (e.g.
+# `claude --dangerously-skip-permissions …` or
+# `codex --dangerously-bypass-approvals-and-sandbox …`); this file knows nothing
+# about which harness it is.
+#
+# Env contract (all set by libcage.sh):
+#   HOST_UID / HOST_GID / HOME   the host user to become
+#   CAGE_STATE_MOUNT             the payload's state dir inside the box, chowned
+#                                to the host user (e.g. ~/.claude, ~/.codex)
+#   CAGE_ENGINE                  rootless | rootful | none
+#   CAGE_SSH_RELAY_PORT          colima TCP->unix ssh-agent relay port (optional)
+#   CAGE_DEBUG                   opt-in state dump (optional)
+
+set -e
+
+HOST_UID="${HOST_UID:-1000}"
+HOST_GID="${HOST_GID:-1000}"
+HOST_HOME="${HOME:-/home/hostuser}"
+USERNAME="hostuser"
+
+# Put the user's local bin on PATH. The payload is exec'd directly (no login
+# shell sources a profile), so child processes inherit PATH from this env.
+export PATH="${HOST_HOME}/.local/bin:${PATH}"
+
+# Neutral host->box file relay. The launcher stages host files under a
+# cage-owned .cage-relay/ inside the state mount (payload-independent: the name
+# is the cage's, not any harness's config file), so the relay rides the same
+# state volume the colima flush already carries. Copy them to the paths the tools
+# expect. Clean up a stale dir if Docker created one at a target.
+_RELAY="${CAGE_STATE_MOUNT:-${HOME}/.cage}/.cage-relay"
+if [ -f "${_RELAY}/gitconfig" ]; then
+  [ -d "${HOME}/.gitconfig" ] && rm -rf "${HOME}/.gitconfig"
+  cp -f "${_RELAY}/gitconfig" "${HOME}/.gitconfig" 2>/dev/null || true
+fi
+if [ -s "${_RELAY}/AGENTS.md" ]; then
+  [ -d "${HOME}/.agents/AGENTS.md" ] && rm -rf "${HOME}/.agents/AGENTS.md"
+  mkdir -p "${HOME}/.agents"
+  cp -f "${_RELAY}/AGENTS.md" "${HOME}/.agents/AGENTS.md" 2>/dev/null || true
+fi
+
+echo "[cage] starting..." >&2
+if [ "$(id -u)" = "0" ] && [ "${HOST_UID}" != "0" ]; then
+  echo "[cage] creating user UID=${HOST_UID} GID=${HOST_GID}..." >&2
+  # Create group if it doesn't already exist
+  if ! getent group "${HOST_GID}" >/dev/null 2>&1; then
+    groupadd -g "${HOST_GID}" "${USERNAME}"
+  fi
+
+  # Create user if it doesn't already exist.
+  # --non-unique allows UIDs outside the distro's 1000-60000 range (e.g. macOS UID 501).
+  if ! getent passwd "${HOST_UID}" >/dev/null 2>&1; then
+    useradd --non-unique -u "${HOST_UID}" -g "${HOST_GID}" -d "${HOST_HOME}" -s /bin/bash -M "${USERNAME}" 2>/dev/null
+  fi
+
+  # Ensure home dir exists and is owned by the host user. Tolerate a chown
+  # failure (|| true): when a box is launched from ${HOME} itself the wrapper
+  # bind-mounts PROJECT_DIR (== ${HOME}) into the container, so ${HOME} is a
+  # virtiofs mount root and chowning it returns EPERM, which under `set -e` would
+  # abort the entrypoint and kill the container. Skipping it is safe: a virtiofs
+  # home already maps to the host UID.
+  mkdir -p "${HOST_HOME}"
+  chown "${HOST_UID}:${HOST_GID}" "${HOST_HOME}" 2>/dev/null || true
+
+  # Fix ownership on the payload's state tree. The init-container flush and
+  # Docker-created mount points leave root-owned entries that cause EACCES when
+  # the harness tries to write sessions, config, etc.
+  if [ -n "${CAGE_STATE_MOUNT:-}" ]; then
+    [ -d "${CAGE_STATE_MOUNT}" ] && chown -R "${HOST_UID}:${HOST_GID}" "${CAGE_STATE_MOUNT}" 2>/dev/null || true
+  fi
+
+  # Payload-specific prep, if the payload image shipped a hook. Runs as root,
+  # before the engine starts, with the same env this script sees. cage-base
+  # ships none; claude-box drops a theme install + stale-dir cleanup here.
+  if [ -x /usr/local/share/cage/payload-init ]; then
+    /usr/local/share/cage/payload-init || true
+  fi
+
+  # ---- Nested container engine (ADR-0041 decision 3) ----
+  # A mounted host socket is never acceptable: it is root-equivalent control of
+  # the host, so the cage would not be host-isolated at all. Any socket present
+  # this early can only have been mounted in from outside — refuse to start.
+  if [ -S /var/run/docker.sock ]; then
+    echo "[cage] FATAL: /var/run/docker.sock is mounted from the host." >&2
+    echo "[cage] ADR-0041 (decision 3): a mounted host docker socket voids the cage's" >&2
+    echo "[cage] host isolation. Remove the mount (check *_EXTRA_MOUNTS)." >&2
+    exit 1
+  fi
+
+  # CAGE_ENGINE is set by the launcher: rootless (default), rootful (sysbox or
+  # privileged dind — identical in here), or none. The engine's data root must
+  # NOT be the container's overlayfs (overlay-on-overlay is rejected), so the
+  # launcher mounts an anonymous volume at the data-root path.
+  ENGINE="${CAGE_ENGINE:-none}"
+  ENGINE_LOG="/tmp/cage-engine.log"
+  case "$ENGINE" in
+    rootless)
+      grep -q "^${USERNAME}:" /etc/subuid 2>/dev/null || echo "${USERNAME}:100000:65536" >> /etc/subuid
+      grep -q "^${USERNAME}:" /etc/subgid 2>/dev/null || echo "${USERNAME}:100000:65536" >> /etc/subgid
+      export XDG_RUNTIME_DIR="/run/user/${HOST_UID}"
+      mkdir -p "$XDG_RUNTIME_DIR" /var/lib/claude-box-engine
+      chown "${HOST_UID}:${HOST_GID}" "$XDG_RUNTIME_DIR" /var/lib/claude-box-engine
+      chmod 700 "$XDG_RUNTIME_DIR"
+      echo "[cage] starting rootless nested engine..." >&2
+      gosu "${USERNAME}" env XDG_RUNTIME_DIR="${XDG_RUNTIME_DIR}" HOME="${HOST_HOME}" PATH="${PATH}" \
+        DOCKERD_ROOTLESS_ROOTLESSKIT_NET=slirp4netns \
+        DOCKERD_ROOTLESS_ROOTLESSKIT_PORT_DRIVER=builtin \
+        dockerd-rootless.sh --data-root /var/lib/claude-box-engine \
+        >"$ENGINE_LOG" 2>&1 &
+      export DOCKER_HOST="unix://${XDG_RUNTIME_DIR}/docker.sock"
+      ;;
+    rootful)
+      echo "[cage] starting rootful nested engine..." >&2
+      dockerd >"$ENGINE_LOG" 2>&1 &
+      usermod -aG docker "${USERNAME}" 2>/dev/null || true
+      export DOCKER_HOST="unix:///var/run/docker.sock"
+      ;;
+    *)
+      ;;
+  esac
+
+  # Block until the engine answers (bounded): the first thing a session does may
+  # be a docker command, and racing the daemon start loses. On failure, warn
+  # loudly and continue WITHOUT an engine — never fall back to any other socket.
+  if [ -n "${DOCKER_HOST:-}" ]; then
+    _engine_ok=0
+    for _i in $(seq 1 80); do
+      if gosu "${USERNAME}" env DOCKER_HOST="${DOCKER_HOST}" docker version >/dev/null 2>&1; then
+        _engine_ok=1
+        break
+      fi
+      sleep 0.25
+    done
+    if [ "$_engine_ok" = 1 ]; then
+      echo "[cage] nested engine ready (${ENGINE}) at ${DOCKER_HOST}" >&2
+    else
+      echo "[cage] WARNING: nested engine (${ENGINE}) not ready after 20s — continuing without one." >&2
+      echo "[cage] engine log tail (${ENGINE_LOG}):" >&2
+      tail -n 20 "$ENGINE_LOG" >&2 2>/dev/null || true
+      unset DOCKER_HOST
+    fi
+  fi
+
+  # Docker Desktop forwards the host ssh-agent at /run/host-services/ssh-auth.sock
+  # but the socket inside the container is root-owned. Chown it to the host user
+  # so signing/git-over-ssh works without escalation. Silently ignore if absent.
+  if [ -S /run/host-services/ssh-auth.sock ]; then
+    chown "${HOST_UID}:${HOST_GID}" /run/host-services/ssh-auth.sock || true
+  fi
+
+  # Colima TCP->Unix socket relay. The host-side Python relay exposes the SSH
+  # agent on a TCP port; socat converts it back to a Unix socket inside the
+  # container so SSH_AUTH_SOCK works normally.
+  if [ -n "${CAGE_SSH_RELAY_PORT:-}" ]; then
+    echo "[cage] wiring ssh relay..." >&2
+    CONTAINER_SSH_SOCK="/tmp/ssh-agent.sock"
+    rm -f "$CONTAINER_SSH_SOCK"
+    gosu "${USERNAME}" socat \
+      UNIX-LISTEN:"${CONTAINER_SSH_SOCK}",fork,mode=600 \
+      TCP:host.docker.internal:"${CAGE_SSH_RELAY_PORT}" &
+    export SSH_AUTH_SOCK="$CONTAINER_SSH_SOCK"
+    sleep 0.2
+  fi
+
+  # State dump is opt-in (CAGE_DEBUG), on stderr. Generic: lists the state mount.
+  if [ -n "${CAGE_DEBUG:-}" ]; then
+    echo "[cage] HOME=${HOME}" >&2
+    echo "[cage] state mount (${CAGE_STATE_MOUNT:-<unset>}):" >&2
+    ls -la "${CAGE_STATE_MOUNT}" >&2 2>/dev/null || echo "(missing)" >&2
+    echo >&2
+  fi
+
+  # gosu does a direct exec as the user — no shell wrapper, proper TTY + signal
+  # inheritance for an interactive UI. "$@" is the payload command the launcher
+  # supplied; the cage never names a harness of its own.
+  echo "[cage] exec: $*" >&2
+  exec gosu "${USERNAME}" "$@"
+fi
+
+# Already running as the right user (or root was requested).
+exec "$@"
diff --git a/entrypoint.sh b/entrypoint.sh
deleted file mode 100644
index a5a0817..0000000
--- a/entrypoint.sh
+++ /dev/null
@@ -1,223 +0,0 @@
-#!/bin/bash
-# Entrypoint for claude-box.
-# Creates a passwd/group entry for the host UID so Claude Code can resolve
-# the user (it silently exits when getpwuid() returns nothing).
-# Must run as root first; drops to the host user immediately after.
-
-set -e
-
-HOST_UID="${HOST_UID:-1000}"
-HOST_GID="${HOST_GID:-1000}"
-HOST_HOME="${HOME:-/home/hostuser}"
-USERNAME="hostuser"
-
-# Put the user's local bin on PATH. claude is exec'd directly (no login shell
-# sources a profile), so child processes inherit PATH from this env. Covers
-# pip/uv --user installs and anything else dropped in ~/.local/bin.
-export PATH="${HOST_HOME}/.local/bin:${PATH}"
-
-# Clean up stale directories that Docker auto-creates when a bind-mount source
-# doesn't exist. On Colima this is common because virtiofs cache delays can make
-# freshly-written host files invisible to the VM at mount time. These root-owned
-# directories persist in the state volume and shadow the real files on subsequent
-# runs, so we remove them unconditionally at startup.
-# Only clean paths inside the state volume (${HOME}/.claude/). Paths like
-# ${HOME}/.claude.json are separate bind mounts and can't be removed.
-for _stale in "${HOME}/.claude/CLAUDE.md" "${HOME}/.claude/.credentials.json" \
-              "${HOME}/.claude/.claude.json" "${HOME}/.claude/settings.json"; do
-  [ -d "$_stale" ] && rm -rf "$_stale"
-done
-
-# Install the baked-in claude-box theme so the container is visually distinct.
-mkdir -p "${HOME}/.claude/themes"
-cp -f /usr/local/share/claude-box-theme.json "${HOME}/.claude/themes/claude-box.json" 2>/dev/null || true
-
-# If .gitconfig was synced into the state dir (Colima), copy it to $HOME.
-# Also clean up stale directory if Docker created one at $HOME/.gitconfig.
-[ -d "${HOME}/.gitconfig" ] && rm -rf "${HOME}/.gitconfig"
-[ -f "${HOME}/.claude/.gitconfig" ] && cp -f "${HOME}/.claude/.gitconfig" "${HOME}/.gitconfig" 2>/dev/null || true
-
-# claude-box concatenates all AGENTS.md files (global + parents + project) into
-# the state dir; copy the merged result out to the ~/.agents/AGENTS.md path the
-# global CLAUDE.md tells Claude to read. Clean up a stale dir if Docker created
-# one at the file's target.
-[ -d "${HOME}/.agents/AGENTS.md" ] && rm -rf "${HOME}/.agents/AGENTS.md"
-if [ -s "${HOME}/.claude/.agents/AGENTS.md" ]; then
-  mkdir -p "${HOME}/.agents"
-  cp -f "${HOME}/.claude/.agents/AGENTS.md" "${HOME}/.agents/AGENTS.md" 2>/dev/null || true
-fi
-
-echo "[entrypoint] starting..." >&2
-if [ "$(id -u)" = "0" ] && [ "${HOST_UID}" != "0" ]; then
-  echo "[entrypoint] creating user UID=${HOST_UID} GID=${HOST_GID}..." >&2
-  # Create group if it doesn't already exist
-  if ! getent group "${HOST_GID}" >/dev/null 2>&1; then
-    groupadd -g "${HOST_GID}" "${USERNAME}"
-  fi
-
-  # Create user if it doesn't already exist.
-  # --non-unique allows UIDs outside the distro's 1000-60000 range (e.g. macOS UID 501).
-  if ! getent passwd "${HOST_UID}" >/dev/null 2>&1; then
-    useradd --non-unique -u "${HOST_UID}" -g "${HOST_GID}" -d "${HOST_HOME}" -s /bin/bash -M "${USERNAME}" 2>/dev/null
-  fi
-
-  # Ensure home dir exists and is owned by the host user. Tolerate a chown
-  # failure (|| true): when claude-box is launched from ${HOME} itself, the
-  # wrapper bind-mounts PROJECT_DIR (== ${HOME}) into the container, so ${HOME}
-  # is a virtiofs mount root rather than a plain container-local dir — and
-  # chowning a virtiofs mount root returns EPERM, which under `set -e` aborts
-  # the entrypoint and kills the container before claude ever starts. The
-  # .claude and ssh-socket chowns below already tolerate this; the home chown
-  # must too. Skipping it is safe: a virtiofs home already maps to the host UID,
-  # and the per-path .claude chown below still fixes the dirs claude writes to.
-  mkdir -p "${HOST_HOME}"
-  chown "${HOST_UID}:${HOST_GID}" "${HOST_HOME}" 2>/dev/null || true
-
-  # Fix ownership on the entire .claude tree. The init container flush and
-  # Docker-created mount points leave root-owned entries that cause EACCES
-  # when Claude Code tries to write sessions, shell env, etc.
-  chown -R "${HOST_UID}:${HOST_GID}" "${HOME}/.claude" 2>/dev/null || true
-
-  # ---- Nested container engine (ADR-0041 decision 3) ----
-  # The cage runs its OWN engine, bounded by the cage. A mounted host socket is
-  # never acceptable: it is root-equivalent control of the host (any process
-  # could start a privileged container and mount the host fs), so the cage
-  # would not be host-isolated at all. Any socket present this early can only
-  # have been mounted in from outside — refuse to start.
-  if [ -S /var/run/docker.sock ]; then
-    echo "[entrypoint] FATAL: /var/run/docker.sock is mounted from the host." >&2
-    echo "[entrypoint] ADR-0041 (decision 3): a mounted host docker socket voids the cage's" >&2
-    echo "[entrypoint] host isolation. Remove the mount (check CLAUDE_BOX_EXTRA_MOUNTS)." >&2
-    exit 1
-  fi
-
-  # CLAUDE_BOX_ENGINE is set by the launcher: rootless (default), rootful
-  # (sysbox or privileged dind — identical in here), or none. The engine's
-  # data root must NOT be the container's overlayfs (overlay-on-overlay is
-  # rejected by the kernel), so the launcher mounts an anonymous volume at
-  # the data-root path for the posture it selected.
-  ENGINE="${CLAUDE_BOX_ENGINE:-none}"
-  ENGINE_LOG="/tmp/claude-box-engine.log"
-  case "$ENGINE" in
-    rootless)
-      # dockerd-rootless (rootlesskit) as the unprivileged host user: the
-      # daemon holds no capabilities in the cage's user namespace, only in
-      # the nested one it creates — authority bounded by the cage. Needs
-      # subuid/subgid ranges for the userns and a private runtime dir.
-      grep -q "^${USERNAME}:" /etc/subuid 2>/dev/null || echo "${USERNAME}:100000:65536" >> /etc/subuid
-      grep -q "^${USERNAME}:" /etc/subgid 2>/dev/null || echo "${USERNAME}:100000:65536" >> /etc/subgid
-      export XDG_RUNTIME_DIR="/run/user/${HOST_UID}"
-      mkdir -p "$XDG_RUNTIME_DIR" /var/lib/claude-box-engine
-      chown "${HOST_UID}:${HOST_GID}" "$XDG_RUNTIME_DIR" /var/lib/claude-box-engine
-      chmod 700 "$XDG_RUNTIME_DIR"
-      echo "[entrypoint] starting rootless nested engine..." >&2
-      gosu "${USERNAME}" env XDG_RUNTIME_DIR="${XDG_RUNTIME_DIR}" HOME="${HOST_HOME}" PATH="${PATH}" \
-        DOCKERD_ROOTLESS_ROOTLESSKIT_NET=slirp4netns \
-        DOCKERD_ROOTLESS_ROOTLESSKIT_PORT_DRIVER=builtin \
-        dockerd-rootless.sh --data-root /var/lib/claude-box-engine \
-        >"$ENGINE_LOG" 2>&1 &
-      export DOCKER_HOST="unix://${XDG_RUNTIME_DIR}/docker.sock"
-      ;;
-    rootful)
-      # Rootful dockerd inside the cage — reached via sysbox (engine bounded
-      # by the sysbox runtime) or --privileged (ADR-0041's named weaker
-      # posture). Default data root /var/lib/docker: sysbox provisions that
-      # exact path itself, and the privileged posture gets an anonymous
-      # volume there from the launcher. The socket it creates is the NESTED
-      # daemon's, not the host's (a host socket was refused above). hostuser
-      # reaches it via the docker group; gosu applies supplementary groups
-      # at exec.
-      echo "[entrypoint] starting rootful nested engine..." >&2
-      dockerd >"$ENGINE_LOG" 2>&1 &
-      usermod -aG docker "${USERNAME}" 2>/dev/null || true
-      export DOCKER_HOST="unix:///var/run/docker.sock"
-      ;;
-    *)
-      ;;
-  esac
-
-  # Block until the engine answers (bounded): the very first thing a session
-  # does may be a docker command, and racing the daemon start loses. On
-  # failure, warn loudly and continue WITHOUT an engine — never fall back to
-  # any other socket; the ambient DOCKER_HOST is the single authority.
-  if [ -n "${DOCKER_HOST:-}" ]; then
-    _engine_ok=0
-    for _i in $(seq 1 80); do
-      if gosu "${USERNAME}" env DOCKER_HOST="${DOCKER_HOST}" docker version >/dev/null 2>&1; then
-        _engine_ok=1
-        break
-      fi
-      sleep 0.25
-    done
-    if [ "$_engine_ok" = 1 ]; then
-      echo "[entrypoint] nested engine ready (${ENGINE}) at ${DOCKER_HOST}" >&2
-    else
-      echo "[entrypoint] WARNING: nested engine (${ENGINE}) not ready after 20s — continuing without one." >&2
-      echo "[entrypoint] engine log tail (${ENGINE_LOG}):" >&2
-      tail -n 20 "$ENGINE_LOG" >&2 2>/dev/null || true
-      unset DOCKER_HOST
-    fi
-  fi
-
-  # Docker Desktop forwards the host ssh-agent at /run/host-services/ssh-auth.sock
-  # but the socket inside the container is root-owned. Chown it to the host user
-  # so signing/git-over-ssh works without escalation. Silently ignore if absent
-  # (Linux Docker / no agent forwarded / --no-ssh).
-  if [ -S /run/host-services/ssh-auth.sock ]; then
-    chown "${HOST_UID}:${HOST_GID}" /run/host-services/ssh-auth.sock || true
-  fi
-
-  # Colima TCP→Unix socket relay. The host-side Python relay exposes the SSH
-  # agent on a TCP port; socat converts it back to a Unix socket inside the
-  # container so SSH_AUTH_SOCK works normally for git signing and SSH auth.
-  echo "[entrypoint] checking ssh relay..." >&2
-  if [ -n "${CLAUDE_BOX_SSH_RELAY_PORT:-}" ]; then
-    CONTAINER_SSH_SOCK="/tmp/ssh-agent.sock"
-    rm -f "$CONTAINER_SSH_SOCK"
-    gosu "${USERNAME}" socat \
-      UNIX-LISTEN:"${CONTAINER_SSH_SOCK}",fork,mode=600 \
-      TCP:host.docker.internal:"${CLAUDE_BOX_SSH_RELAY_PORT}" &
-    export SSH_AUTH_SOCK="$CONTAINER_SSH_SOCK"
-    sleep 0.2
-  fi
-
-  # gosu does a direct exec as the user — no shell wrapper, proper TTY + signal
-  # inheritance for Claude Code's interactive UI.
-  #
-  # State dump is opt-in (CLAUDE_BOX_DEBUG=1), and stays on stderr. It's off by
-  # default because it's noisy and mildly sensitive: it lists ~/.claude, reports
-  # the credential file's byte count, and prints the first 200 bytes of
-  # .claude.json — none of which a headless caller wants merged into its logs.
-  if [ -n "${CLAUDE_BOX_DEBUG:-}" ]; then
-    echo "[entrypoint] HOME=${HOME}" >&2
-    echo "[entrypoint] .claude contents:" >&2
-    ls -la "${HOME}/.claude/" >&2 2>/dev/null || echo "(missing)" >&2
-    echo "[entrypoint] .credentials.json:" >&2
-    if [ -f "${HOME}/.claude/.credentials.json" ]; then
-      echo "present ($(wc -c < "${HOME}/.claude/.credentials.json") bytes)" >&2
-    else
-      echo "(missing)" >&2
-    fi
-    echo >&2
-    echo "[entrypoint] .claude.json:" >&2
-    head -c 200 "${HOME}/.claude.json" >&2 2>/dev/null || echo "(missing)" >&2
-    echo >&2
-  fi
-  # Debug/acceptance hook: CLAUDE_BOX_EXEC=1 execs the args as a raw command
-  # instead of claude — used to run docs/cage-engine-acceptance.md in-cage
-  # non-interactively (e.g. `CLAUDE_BOX_EXEC=1 ... bash -c 'docker info'`).
-  if [ -n "${CLAUDE_BOX_EXEC:-}" ]; then
-    # The launcher always prepends claude's --dangerously-skip-permissions; drop
-    # a single leading one so EXEC runs the bare command that follows (this is
-    # what makes `CLAUDE_BOX_EXEC=1 claude-box -- bash -c 'exit 7'` exit 7,
-    # exercising the launcher's exit-status propagation end to end).
-    [ "${1:-}" = "--dangerously-skip-permissions" ] && shift
-    echo "[entrypoint] exec (CLAUDE_BOX_EXEC): $*" >&2
-    exec gosu "${USERNAME}" "$@"
-  fi
-  echo "[entrypoint] launching claude $*" >&2
-  exec gosu "${USERNAME}" claude "$@"
-fi
-
-# Already running as the right user (or root was requested)
-exec claude "$@"
diff --git a/libcage.sh b/libcage.sh
new file mode 100644
index 0000000..fda1d9d
--- /dev/null
+++ b/libcage.sh
@@ -0,0 +1,572 @@
+#!/usr/bin/env bash
+# libcage.sh — the cage, once. Sourced by a thin per-payload wrapper
+# (claude-box, codex-box). The cage owns the outer container, its security
+# posture, the bounded nested engine, the ssh/colima relays, uid mapping, the
+# image build, the exit-status contract, and the docker run assembly. The
+# payload owns which harness command runs and which host state it syncs.
+#
+# A wrapper sets these before calling cage_run "$@":
+#   BOX_LABEL         short name, e.g. claude-box / codex-box (logs, .env file)
+#   BOX_SRC_DIR       dir holding Dockerfile.cage, entrypoint-cage.sh,
+#                     userns-probe.sh, and the payload Dockerfile
+#   BOX_IMAGE         payload image tag, e.g. claude-box
+#   BOX_DOCKERFILE    payload Dockerfile path (FROM cage-base)
+#   BOX_STATE_DIR     host state dir, e.g. ~/.claude-box/state
+#   BOX_STATE_MOUNT   where the state dir mounts in-box, e.g. $HOME/.claude
+#   BOX_ENV_PREFIX    env-knob prefix, e.g. CLAUDE_BOX / CODEX_BOX. Drives
+#                     ${PREFIX}_EXTRA_VARS / _EXTRA_MOUNTS / _ENGINE_MODE /
+#                     _DEBUG / _EXEC so each wrapper keeps its own interface.
+#   BOX_FORWARD_VARS  array of extra env var names to forward (payload creds)
+#   BOX_PAYLOAD_CMD   array: the harness argv the entrypoint execs (the wrapper
+#                     appends the user's passthrough args to it)
+#
+# A wrapper MAY define these hooks (all optional):
+#   box_parse_arg "$@"   handle a wrapper-specific flag. Set _CONSUMED to the
+#                        number of args eaten and return 0; return non-zero to
+#                        let the cage treat "$1" as a passthrough arg.
+#   box_stage            after the generic mounts are built: append to
+#                        override_mounts / env_args, stage relay files, seed
+#                        state. Sees STATE_DIR, PROJECT_DIR, PROJECT_SLUG, etc.
+#   box_sync_back        from the EXIT trap after the container stops: copy
+#                        payload state back to the host. Use cage_cp_out for the
+#                        colima path.
+
+# ---------------------------------------------------------------------------
+# Logging — identical contract to the monolith.
+# log(): tty-gated progress. Must never return nonzero under set -e.
+log()   { [[ ! -t 2 ]] || printf '[%s] %s\n' "${BOX_LABEL:-cage}" "$*" >&2; }
+# fault(): machine-readable launcher fault, UNCONDITIONAL on the tty.
+fault() { printf '%s: fault=%s detail="%s"\n' "${BOX_LABEL:-cage}" "$1" "${2:-}" >&2; return 0; }
+# warn(): machine-facing warning, UNCONDITIONAL on the tty.
+warn()  { printf '[%s] WARNING: %s\n' "${BOX_LABEL:-cage}" "$*" >&2; }
+
+# Fixed cage image the probes/helpers run against (payload-independent).
+CAGE_IMAGE="cage-base"
+
+# ---------------------------------------------------------------------------
+# Update check — background, silent on every failure mode.
+_cage_check_update_bg() {
+  (
+    cd "$BOX_SRC_DIR" || exit 0
+    git rev-parse --abbrev-ref '@{u}' >/dev/null 2>&1 || exit 0
+    git fetch --quiet 2>/dev/null || exit 0
+    if [[ $(git rev-list --count HEAD..@{u} 2>/dev/null || echo 0) -gt 0 ]]; then
+      touch "$UPDATE_AVAILABLE_FILE"
+    else
+      rm -f "$UPDATE_AVAILABLE_FILE"
+    fi
+    touch "$UPDATE_CHECK_FILE"
+  ) >/dev/null 2>&1 &
+  disown 2>/dev/null || true
+}
+
+# ---------------------------------------------------------------------------
+# Argument parsing. Generic cage flags (position-free, stripped before the
+# harness sees them); a literal -- ends cage parsing. Unknown args go to the
+# wrapper's box_parse_arg hook, then to the harness passthrough.
+NO_SSH=0
+UPGRADE=0
+ENGINE_MODE=""
+BOX_NAME=""
+NAME_FILE=""
+declare -a _passthrough=()
+cage_parse_args() {
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --) shift; _passthrough+=("$@"); break ;;
+      --no-ssh) NO_SSH=1 ;;
+      --upgrade) UPGRADE=1 ;;
+      --engine)
+        shift; ENGINE_MODE="${1:-}"
+        [[ -n "$ENGINE_MODE" ]] || { printf '[%s] --engine requires a mode (auto|sysbox|rootless|privileged-dind|none)\n' "$BOX_LABEL" >&2; exit 1; } ;;
+      --engine=*) ENGINE_MODE="${1#*=}" ;;
+      --name)
+        shift; BOX_NAME="${1:-}"
+        [[ -n "$BOX_NAME" ]] || { printf '[%s] --name requires a container name\n' "$BOX_LABEL" >&2; exit 1; } ;;
+      --name=*) BOX_NAME="${1#*=}" ;;
+      --name-file)
+        shift; NAME_FILE="${1:-}"
+        [[ -n "$NAME_FILE" ]] || { printf '[%s] --name-file requires a path\n' "$BOX_LABEL" >&2; exit 1; } ;;
+      --name-file=*) NAME_FILE="${1#*=}" ;;
+      *)
+        _CONSUMED=0
+        if declare -F box_parse_arg >/dev/null && box_parse_arg "$@"; then
+          shift "$(( _CONSUMED > 0 ? _CONSUMED - 1 : 0 ))"
+        else
+          _passthrough+=("$1")
+        fi ;;
+    esac
+    shift
+  done
+}
+
+# ---------------------------------------------------------------------------
+# Engine posture: probes, apparmor profile, userns ladder. Ported verbatim from
+# the monolith; the only change is that helper containers run CAGE_IMAGE.
+_dh_slug=""
+_host_docker_caps=""
+
+_probe_device() {
+  local dev="$1" cache="${HOME}/.claude-box/.device-probe-${1//\//_}-${_dh_slug}"
+  if [[ ! -f "$cache" ]]; then
+    if docker run --rm --entrypoint true --device "$dev" "$CAGE_IMAGE" >/dev/null 2>&1; then
+      echo yes > "$cache"
+    else
+      echo no > "$cache"
+    fi
+  fi
+  [[ "$(cat "$cache" 2>/dev/null)" == yes ]]
+}
+
+_USERNS_PROFILE='abi <abi/4.0>,
+include <tunables/global>
+profile claude-box-engine flags=(unconfined) {
+  userns,
+}'
+
+_load_userns_profile() {
+  printf '%s\n' "$_USERNS_PROFILE" | docker run --rm -i --privileged --pid=host \
+    --entrypoint nsenter "$CAGE_IMAGE" -t 1 -m -- sh -c \
+    'cat > /run/claude-box-engine.profile && apparmor_parser -Kr /run/claude-box-engine.profile' \
+    >/dev/null 2>&1
+}
+
+_userns_probe() {
+  docker run --rm --entrypoint /usr/local/bin/claude-box-userns-probe \
+    --security-opt seccomp=unconfined "$@" "$CAGE_IMAGE" >/dev/null 2>&1
+}
+
+_resolve_userns_strategy() {
+  local cache="${HOME}/.claude-box/.userns-strategy-${_dh_slug}" s="" aa=()
+  if [[ -s "$cache" ]]; then cat "$cache"; return 0; fi
+  [[ "$_host_docker_caps" == *apparmor* ]] && aa=(--security-opt apparmor=unconfined)
+  if _userns_probe ${aa[@]+"${aa[@]}"}; then
+    s="plain"
+  elif [[ "$_host_docker_caps" == *apparmor* ]] && _load_userns_profile; then
+    if _userns_probe --security-opt apparmor=claude-box-engine; then
+      s="profile"
+    elif _userns_probe --security-opt apparmor=claude-box-engine --cap-add SYS_ADMIN; then
+      s="profile-cap"
+    fi
+  fi
+  if [[ -z "$s" ]] && _userns_probe ${aa[@]+"${aa[@]}"} --cap-add SYS_ADMIN; then
+    s="cap"
+  fi
+  if [[ -n "$s" ]]; then echo "$s" > "$cache"; echo "$s"; else echo "unsupported"; fi
+}
+
+# Resolve ENGINE from ENGINE_MODE (CLI) / ${PREFIX}_ENGINE_MODE / auto, then
+# build engine_args. Sets globals ENGINE and engine_args.
+cage_resolve_engine() {
+  local envmode_var="${BOX_ENV_PREFIX}_ENGINE_MODE"
+  ENGINE_MODE="${ENGINE_MODE:-${!envmode_var:-auto}}"
+  _host_docker_caps=""
+  if [[ "$ENGINE_MODE" != "none" ]]; then
+    _host_docker_caps="$(docker info --format '{{.SecurityOptions}} {{range $k, $v := .Runtimes}}{{$k}} {{end}}' 2>/dev/null || true)"
+  fi
+  case "$ENGINE_MODE" in
+    auto)
+      if [[ "$_host_docker_caps" == *sysbox-runc* ]]; then ENGINE=sysbox; else ENGINE=rootless; fi ;;
+    sysbox)
+      if [[ "$_host_docker_caps" != *sysbox-runc* ]]; then
+        fault engine-start-failed "--engine sysbox: host docker has no sysbox-runc runtime (install sysbox first)"
+        exit 126
+      fi
+      ENGINE=sysbox ;;
+    rootless|privileged-dind|none) ENGINE="$ENGINE_MODE" ;;
+    *)
+      printf '[%s] unknown --engine mode: %s (want auto|sysbox|rootless|privileged-dind|none)\n' "$BOX_LABEL" "$ENGINE_MODE" >&2
+      exit 1 ;;
+  esac
+
+  _dh_slug="$(printf '%s' "${DOCKER_HOST:-default}" | tr -c 'a-zA-Z0-9' '_')"
+  engine_args=()
+  case "$ENGINE" in
+    sysbox)
+      engine_args+=(--runtime sysbox-runc -e "CAGE_ENGINE=rootful" --init)
+      log "engine: sysbox (rootful nested dockerd, bounded by sysbox-runc)" ;;
+    rootless)
+      engine_args+=(
+        --security-opt seccomp=unconfined
+        --security-opt systempaths=unconfined
+        -e "CAGE_ENGINE=rootless"
+        -v /var/lib/claude-box-engine
+        --init
+      )
+      local strat; strat="$(_resolve_userns_strategy)"
+      case "$strat" in
+        plain)
+          [[ "$_host_docker_caps" == *apparmor* ]] && engine_args+=(--security-opt apparmor=unconfined) ;;
+        profile|profile-cap)
+          _load_userns_profile || warn "apparmor profile load failed: engine may not start"
+          engine_args+=(--security-opt apparmor=claude-box-engine)
+          [[ "$strat" == profile-cap ]] && engine_args+=(--cap-add SYS_ADMIN) ;;
+        cap)
+          engine_args+=(--cap-add SYS_ADMIN) ;;
+        unsupported)
+          warn "this docker host cannot give an unprivileged user a capable user"
+          warn "namespace, so the rootless nested engine will likely fail to start."
+          warn "consider sysbox, or '--engine privileged-dind' (ADR-0041's named"
+          warn "weaker posture), or '--engine none'."
+          [[ "$_host_docker_caps" == *apparmor* ]] && engine_args+=(--security-opt apparmor=unconfined) ;;
+      esac
+      _probe_device /dev/net/tun && engine_args+=(--device /dev/net/tun)
+      _probe_device /dev/fuse && engine_args+=(--device /dev/fuse)
+      log "engine: rootless nested dockerd (userns strategy: ${strat})" ;;
+    privileged-dind)
+      warn "--engine privileged-dind is ADR-0041's named weaker posture:"
+      warn "a privileged cage weakens host isolation. Prefer sysbox or rootless."
+      engine_args+=(--privileged -e "CAGE_ENGINE=rootful" -v /var/lib/docker --init) ;;
+    none)
+      # --init here too, so all four postures agree: tini reaps zombies and
+      # forwards signals uniformly even without a nested engine.
+      engine_args+=(-e "CAGE_ENGINE=none" --init)
+      log "engine: none (no container engine inside the box)" ;;
+  esac
+}
+
+# ---------------------------------------------------------------------------
+# SSH mounts + colima ssh-agent relay. Ported verbatim; appends to
+# override_mounts / env_args and sets _SSH_RELAY_PID.
+_SSH_RELAY_PID=""
+cage_setup_ssh() {
+  if [[ $NO_SSH -ne 0 ]]; then
+    log "ssh disabled (--no-ssh): no key mount, no agent forwarding"
+    return 0
+  fi
+  [[ -d "${HOME}/.ssh" ]] && override_mounts+=(-v "${HOME}/.ssh:${HOME}/.ssh:ro")
+  [[ -n "${SSH_AUTH_SOCK:-}" && -S "$SSH_AUTH_SOCK" ]] || return 0
+  if [[ "${DOCKER_HOST:-}" == */.colima/* ]]; then
+    local relay_port_file; relay_port_file=$(mktemp /tmp/claude-box-relay.XXXXXX)
+    python3 -c "
+import socket, sys, threading, signal, os
+src = '${SSH_AUTH_SOCK}'
+server = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+server.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+server.bind(('127.0.0.1', 0))
+port = server.getsockname()[1]
+with open('${relay_port_file}', 'w') as f:
+    f.write(str(port))
+server.listen(8)
+signal.signal(signal.SIGTERM, lambda *_: sys.exit(0))
+def relay(a, b):
+    try:
+        while d := a.recv(4096): b.sendall(d)
+    except: pass
+    finally: a.close(); b.close()
+while True:
+    c, _ = server.accept()
+    u = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+    u.connect(src)
+    threading.Thread(target=relay, args=(c, u), daemon=True).start()
+    threading.Thread(target=relay, args=(u, c), daemon=True).start()
+" &
+    _SSH_RELAY_PID=$!
+    local port="" i
+    for i in $(seq 1 30); do
+      [[ -s "$relay_port_file" ]] && { port=$(<"$relay_port_file"); break; }
+      sleep 0.1
+    done
+    rm -f "$relay_port_file"
+    if [[ -z "$port" ]]; then
+      warn "SSH agent relay failed to start: signing will not work"
+      kill "$_SSH_RELAY_PID" 2>/dev/null || true
+      _SSH_RELAY_PID=""
+    else
+      env_args+=(-e "CAGE_SSH_RELAY_PORT=${port}")
+      env_args+=(--add-host "host.docker.internal:host-gateway")
+    fi
+  elif [[ "$SSH_AUTH_SOCK" == /private/tmp/com.apple.launchd.* ]]; then
+    override_mounts+=(-v "/run/host-services/ssh-auth.sock:/run/host-services/ssh-auth.sock")
+    env_args+=(-e "SSH_AUTH_SOCK=/run/host-services/ssh-auth.sock")
+  else
+    override_mounts+=(-v "${SSH_AUTH_SOCK}:${SSH_AUTH_SOCK}")
+    env_args+=(-e "SSH_AUTH_SOCK=${SSH_AUTH_SOCK}")
+  fi
+}
+
+# ---------------------------------------------------------------------------
+# Generic relay staging: host gitconfig into the cage-owned relay dir under the
+# state volume, where entrypoint-cage.sh copies it to ~/.gitconfig. The AGENTS.md
+# merge is a payload concern (the payload writes ${RELAY_DIR}/AGENTS.md in box_stage).
+RELAY_DIR=""
+cage_stage_gitconfig() {
+  RELAY_DIR="${STATE_DIR}/.cage-relay"
+  mkdir -p "$RELAY_DIR" 2>/dev/null || true
+  # If a prior run left the relay dir owned by a subuid the host user can't write
+  # (rootless-engine uid mapping), skip the relay rather than abort the launch.
+  # entrypoint-cage.sh tolerates missing relay files; box_stage checks RELAY_DIR.
+  if [[ ! -w "$RELAY_DIR" ]]; then
+    warn "relay dir not writable (${RELAY_DIR}); skipping host->box gitconfig/AGENTS.md relay"
+    RELAY_DIR=""
+    return 0
+  fi
+  [[ -f "${HOME}/.gitconfig" ]] && cp -f "${HOME}/.gitconfig" "${RELAY_DIR}/gitconfig" 2>/dev/null || true
+}
+
+# ---------------------------------------------------------------------------
+# Colima helpers, used by cage_sync_back / box_sync_back.
+_CID=""
+# cage_cp_out <rel-under-state>: on colima pull the path out of the state volume
+# through docker I/O; elsewhere the host already sees the bind-mounted state dir.
+cage_cp_out() {
+  [[ -n "$_CID" ]] || return 0
+  docker cp "${_CID}:/_state/${1}" "${STATE_DIR}/${1}" 2>/dev/null || true
+}
+
+# Flush the whole state dir into the colima VM through docker I/O so the VM sees
+# freshly-written host files at mount time. No-op off colima.
+cage_flush_state_to_vm() {
+  [[ "${DOCKER_HOST:-}" == */.colima/* ]] || return 0
+  log "flushing state for colima..."
+  tar --no-xattrs -cf - -C "${STATE_DIR}" . 2>/dev/null \
+    | docker run --rm -i --entrypoint tar -v "${STATE_DIR}:/_state" "${CAGE_IMAGE}" --no-same-owner -xf - -C /_state 2>/dev/null || true
+}
+
+_LAUNCHED=0
+_SYNCED=0
+cage_sync_back() {
+  [[ "${_LAUNCHED:-0}" == 1 && "${_SYNCED:-0}" == 0 ]] || return 0
+  _SYNCED=1
+  set +euo pipefail
+  # Never copy out from a container still writing to the state volume.
+  if docker inspect "$CONTAINER_NAME" >/dev/null 2>&1; then
+    docker stop -t 2 "$CONTAINER_NAME" >/dev/null 2>&1 || true
+  fi
+  _CID=""
+  if [[ "${DOCKER_HOST:-}" == */.colima/* ]]; then
+    _CID=$(docker create --entrypoint sleep -v "${STATE_DIR}:/_state:rw" "${CAGE_IMAGE}" 1 2>/dev/null)
+  fi
+  declare -F box_sync_back >/dev/null && box_sync_back
+  [[ -n "$_CID" ]] && docker rm -f "$_CID" >/dev/null 2>&1 || true
+}
+
+cage_cleanup() {
+  if [[ -n "$_SSH_RELAY_PID" ]]; then
+    kill "$_SSH_RELAY_PID" 2>/dev/null || true
+    wait "$_SSH_RELAY_PID" 2>/dev/null || true
+  fi
+  [[ -n "$NAME_FILE" ]] && rm -f "$NAME_FILE"
+}
+
+# ---------------------------------------------------------------------------
+# Image build: cage-base first (from its own inputs), then the payload image.
+cage_build_images() {
+  local cage_df="${BOX_SRC_DIR}/Dockerfile.cage"
+  local cage_entry="${BOX_SRC_DIR}/entrypoint-cage.sh"
+  local probe="${BOX_SRC_DIR}/userns-probe.sh"
+  local cage_marker="${HOME}/.claude-box/.built-cage"
+
+  local need=0
+  if ! docker image inspect "$CAGE_IMAGE" &>/dev/null; then need=1
+  elif [[ "$cage_df" -nt "$cage_marker" || "$cage_entry" -nt "$cage_marker" || "$probe" -nt "$cage_marker" ]]; then need=1; fi
+  if [[ $need -eq 1 ]]; then
+    log "building cage-base image..."
+    if ! docker build -f "$cage_df" -t "$CAGE_IMAGE" "$BOX_SRC_DIR"; then
+      fault image-missing "docker build failed for image '${CAGE_IMAGE}'"
+      exit 125
+    fi
+    mkdir -p "$(dirname "$cage_marker")"; touch "$cage_marker"
+  fi
+
+  local marker="${HOME}/.claude-box/.built-${BOX_LABEL}"
+  need=0
+  if ! docker image inspect "$BOX_IMAGE" &>/dev/null; then need=1
+  elif [[ "$BOX_DOCKERFILE" -nt "$marker" || "$cage_marker" -nt "$marker" ]]; then need=1
+  else
+    # Extra build inputs the payload Dockerfile COPYs (payload-init, theme, ...):
+    # a change to any must force a rebuild too, since the Dockerfile itself is
+    # unchanged. BOX_BUILD_INPUTS is a wrapper-set array of absolute paths.
+    local _in
+    for _in in "${BOX_BUILD_INPUTS[@]+"${BOX_BUILD_INPUTS[@]}"}"; do
+      [[ "$_in" -nt "$marker" ]] && { need=1; break; }
+    done
+  fi
+  if [[ $need -eq 1 ]]; then
+    log "building ${BOX_LABEL} image..."
+    if ! docker build -f "$BOX_DOCKERFILE" -t "$BOX_IMAGE" "$BOX_SRC_DIR"; then
+      fault image-missing "docker build failed for image '${BOX_IMAGE}'"
+      exit 125
+    fi
+    mkdir -p "$(dirname "$marker")"; touch "$marker"
+  fi
+
+  if ! docker image inspect "$BOX_IMAGE" >/dev/null 2>&1; then
+    fault image-missing "image '${BOX_IMAGE}' is not present (build it or check the docker daemon)"
+    exit 125
+  fi
+}
+
+# ---------------------------------------------------------------------------
+# Main entry.
+cage_run() {
+  cage_parse_args "$@"
+  set -- "${_passthrough[@]+"${_passthrough[@]}"}"
+
+  if [[ -n "$BOX_NAME" && ! "$BOX_NAME" =~ ^[a-zA-Z0-9][a-zA-Z0-9_.-]*$ ]]; then
+    printf '[%s] --name: invalid container name (allowed: [a-zA-Z0-9][a-zA-Z0-9_.-]*)\n' "$BOX_LABEL" >&2
+    exit 1
+  fi
+
+  # Plain assignment: inside a function an unqualified assignment is global,
+  # which is what we want, and it stays bash-3.2-safe (no `declare -g`).
+  HARNESS_ARGS=("$@")
+
+  mkdir -p "${HOME}/.claude-box"
+  UPDATE_CHECK_FILE="${HOME}/.claude-box/.last-update-check-${BOX_LABEL}"
+  UPDATE_AVAILABLE_FILE="${HOME}/.claude-box/.update-available-${BOX_LABEL}"
+
+  if [[ $UPGRADE -eq 1 ]]; then
+    log "upgrading ${BOX_LABEL} at ${BOX_SRC_DIR}..."
+    if git -C "$BOX_SRC_DIR" pull --ff-only; then
+      rm -f "$UPDATE_AVAILABLE_FILE"; touch "$UPDATE_CHECK_FILE"; exit 0
+    else
+      exit $?
+    fi
+  fi
+  [[ -e "$UPDATE_AVAILABLE_FILE" ]] && log "update available — run '${BOX_LABEL} --upgrade' to pull latest"
+  if [[ ! -f "$UPDATE_CHECK_FILE" ]] || [[ -z "$(find "$UPDATE_CHECK_FILE" -mtime -1 2>/dev/null)" ]]; then
+    _cage_check_update_bg
+  fi
+
+  PROJECT_DIR="$(pwd)"
+  local home_real; home_real="$(cd "$HOME" 2>/dev/null && pwd)"
+  if [[ -n "$home_real" && ( "$PROJECT_DIR" == "$home_real" || "$home_real" == "$PROJECT_DIR"/* ) ]]; then
+    printf '[%s] refusing to launch from %s\n' "$BOX_LABEL" "$PROJECT_DIR" >&2
+    printf '[%s] this would bind-mount your entire home directory (%s) into the box.\n' "$BOX_LABEL" "$home_real" >&2
+    printf '[%s] cd into a specific project directory and run %s from there.\n' "$BOX_LABEL" "$BOX_LABEL" >&2
+    exit 1
+  fi
+
+  cage_build_images
+
+  STATE_DIR="$BOX_STATE_DIR"
+  mkdir -p "$STATE_DIR"
+  # 777 lets the in-box user (any uid) write to the state volume. Tolerate a
+  # failure: after a prior run the entrypoint's chown can leave the dir owned by
+  # a subuid the host user can't chmod (rootless-engine uid mapping) — it stays
+  # writable regardless, so this is not worth aborting the launch for.
+  chmod 777 "$STATE_DIR" 2>/dev/null || true
+
+  CONTAINER_NAME="${BOX_NAME:-${BOX_LABEL}-$(basename "$PROJECT_DIR")-$$}"
+
+  trap 'cage_sync_back; cage_cleanup' EXIT
+  trap 'exit' INT TERM HUP
+
+  # Per-project overrides from ${PROJECT_DIR}/.env.<label>.
+  local proj_env="${PROJECT_DIR}/.env.${BOX_LABEL}"
+  if [[ -f "$proj_env" ]]; then
+    set -a; # shellcheck disable=SC1090
+    source "$proj_env"; set +a
+  fi
+
+  cage_resolve_engine
+
+  # Env forwarding: generic base + the payload's extras + the wrapper's
+  # ${PREFIX}_EXTRA_VARS. TERM/COLORFGBG only when set (never synthesize).
+  local extra_vars_name="${BOX_ENV_PREFIX}_EXTRA_VARS"
+  local FORWARD_VARS
+  FORWARD_VARS=(
+    GITHUB_TOKEN GITHUB_PERSONAL_ACCESS_TOKEN TERM COLORFGBG
+    "${BOX_FORWARD_VARS[@]+"${BOX_FORWARD_VARS[@]}"}"
+  )
+  # Append the array named by $extra_vars_name (dynamic name). bash 3.2 has no
+  # namerefs, so indirect via eval, guarded so an unset var is a no-op under set -u.
+  if eval "[ -n \"\${${extra_vars_name}[*]+x}\" ]" 2>/dev/null; then
+    eval "FORWARD_VARS+=( \"\${${extra_vars_name}[@]}\" )"
+  fi
+  env_args=()
+  local var
+  for var in "${FORWARD_VARS[@]}"; do
+    [[ -n "${!var:-}" ]] && env_args+=(-e "${var}=${!var}")
+  done
+  # ${PREFIX}_DEBUG -> generic CAGE_DEBUG the entrypoint reads.
+  local dbg_var="${BOX_ENV_PREFIX}_DEBUG"
+  [[ -n "${!dbg_var:-}" ]] && env_args+=(-e "CAGE_DEBUG=1")
+
+  # ${PREFIX}_EXEC: run the passthrough args as a bare command instead of the
+  # payload (the generic form of the old CLAUDE_BOX_EXEC acceptance hook).
+  local exec_var="${BOX_ENV_PREFIX}_EXEC"
+  # BOX_PAYLOAD_CMD is the base harness argv (e.g. `claude --dangerously-skip-
+  # permissions`); the cage appends the user's passthrough args. The exec hook
+  # replaces the whole command with the bare passthrough args.
+  declare -a PAYLOAD_CMD
+  if [[ -n "${!exec_var:-}" ]]; then
+    PAYLOAD_CMD=("${HARNESS_ARGS[@]+"${HARNESS_ARGS[@]}"}")
+    log "exec hook (${exec_var}): running passthrough args as the in-box command"
+  else
+    PAYLOAD_CMD=("${BOX_PAYLOAD_CMD[@]}" "${HARNESS_ARGS[@]+"${HARNESS_ARGS[@]}"}")
+  fi
+
+  # gh token so `gh` works in-box without re-auth.
+  if [[ -z "${GH_TOKEN:-}" ]]; then
+    log "fetching gh auth token..."
+    GH_TOKEN=$(gh auth token 2>/dev/null) && env_args+=(-e "GH_TOKEN=${GH_TOKEN}") || true
+  fi
+
+  override_mounts=()
+  cage_setup_ssh
+  cage_stage_gitconfig
+
+  # Share XDG cache and ~/.local/bin across boxes (generic).
+  mkdir -p "${HOME}/.cache"; override_mounts+=(-v "${HOME}/.cache:${HOME}/.cache")
+  mkdir -p "${HOME}/.local/bin"; override_mounts+=(-v "${HOME}/.local/bin:${HOME}/.local/bin")
+
+  PROJECT_SLUG="${PROJECT_DIR//\//-}"
+
+  # Per-project extra mounts from ${PREFIX}_EXTRA_MOUNTS (dynamic name; indirect
+  # via eval for bash 3.2, guarded so an unset var is a no-op under set -u).
+  local extra_mounts_name="${BOX_ENV_PREFIX}_EXTRA_MOUNTS"
+  local spec
+  if eval "[ -n \"\${${extra_mounts_name}[*]+x}\" ]" 2>/dev/null; then
+    eval "for spec in \"\${${extra_mounts_name}[@]}\"; do override_mounts+=( -v \"\$spec\" ); done"
+  fi
+
+  # Payload staging: its own mounts, relay files (AGENTS.md), state seeding.
+  declare -F box_stage >/dev/null && box_stage
+
+  cage_flush_state_to_vm
+
+  # Terminal title.
+  [[ -t 2 ]] && printf '\e]0;%s: %s\a' "$BOX_LABEL" "$(basename "$PROJECT_DIR")" >&2
+
+  TTY_FLAGS=()
+  if [[ -t 0 || -p /dev/stdin || -f /dev/stdin || -S /dev/stdin ]]; then TTY_FLAGS+=(-i); fi
+  if [[ -t 1 && -t 2 ]]; then TTY_FLAGS+=(-t); fi
+
+  log "starting container..."
+  _LAUNCHED=1
+  local rc=0
+
+  if [[ -n "$NAME_FILE" ]]; then
+    printf '%s\n' "$CONTAINER_NAME" > "$NAME_FILE" || warn "--name-file: could not write ${NAME_FILE}"
+  fi
+
+  docker run --rm "${TTY_FLAGS[@]}" \
+    --name "$CONTAINER_NAME" \
+    -e "HOST_UID=$(id -u)" \
+    -e "HOST_GID=$(id -g)" \
+    -e "HOME=${HOME}" \
+    -e "CAGE_STATE_MOUNT=${BOX_STATE_MOUNT}" \
+    -e "GIT_CONFIG_COUNT=3" \
+    -e "GIT_CONFIG_KEY_0=safe.directory" \
+    -e "GIT_CONFIG_VALUE_0=*" \
+    -e "GIT_CONFIG_KEY_1=url.https://github.com/.insteadOf" \
+    -e "GIT_CONFIG_VALUE_1=git@github.com:" \
+    -e "GIT_CONFIG_KEY_2=credential.helper" \
+    -e "GIT_CONFIG_VALUE_2=!gh auth git-credential" \
+    -v "${PROJECT_DIR}:${PROJECT_DIR}" \
+    -v "${STATE_DIR}:${BOX_STATE_MOUNT}" \
+    ${override_mounts[@]+"${override_mounts[@]}"} \
+    ${engine_args[@]+"${engine_args[@]}"} \
+    ${env_args[@]+"${env_args[@]}"} \
+    -w "${PROJECT_DIR}" \
+    "$BOX_IMAGE" \
+    "${PAYLOAD_CMD[@]}" || rc=$?
+
+  case "$rc" in
+    125) fault engine-start-failed "docker could not create/start the container (check --engine posture and host runtime)"; rc=126 ;;
+    126|127) fault harness-not-executable "the container could not exec the harness (not found or not executable)"; rc=127 ;;
+  esac
+  exit "$rc"
+}
diff --git a/payload-init-claude.sh b/payload-init-claude.sh
new file mode 100644
index 0000000..c5054e5
--- /dev/null
+++ b/payload-init-claude.sh
@@ -0,0 +1,20 @@
+#!/bin/bash
+# Claude payload-init — run by the cage entrypoint (as root, before the engine)
+# for Claude-specific in-box prep the generic cage doesn't do. HOME and
+# CAGE_STATE_MOUNT (== ${HOME}/.claude) are already set.
+set -e
+
+# Clean up stale directories that Docker auto-creates when a bind-mount source
+# doesn't exist. On Colima this is common because virtiofs cache delays can make
+# freshly-written host files invisible to the VM at mount time. These root-owned
+# directories persist in the state volume and shadow the real files on subsequent
+# runs, so remove them at startup. Only paths inside the state volume
+# (${HOME}/.claude); ${HOME}/.claude.json is a separate bind mount.
+for _stale in "${HOME}/.claude/CLAUDE.md" "${HOME}/.claude/.credentials.json" \
+              "${HOME}/.claude/.claude.json" "${HOME}/.claude/settings.json"; do
+  [ -d "$_stale" ] && rm -rf "$_stale"
+done
+
+# Install the baked-in claude-box theme so the container is visually distinct.
+mkdir -p "${HOME}/.claude/themes"
+cp -f /usr/local/share/claude-box-theme.json "${HOME}/.claude/themes/claude-box.json" 2>/dev/null || true