docker: a container the autonomous RE agent can be turned loose in

Builds and runs both halves of the project -- Canary as the oracle, Reborn as
the port -- plus the dynamic-RE toolkit. Claude Code runs with
--dangerously-skip-permissions as an unprivileged `agent` user, because that
flag is refused under root.

Capped at half the machine, computed at launch: --cpus nproc/2, --memory half
of MemTotal with --memory-swap equal to it (no swap escape hatch -- a swapping
build thrashes the host, which is the failure the cap exists to prevent), and
build parallelism derived INSIDE the container from available memory rather
than core count, since a full-parallel build of this tree has OOM-killed the
host outright.

Three things the old box got wrong are fixed rather than reproduced: a real
toolchain (so rebuild_canary.sh's hand-relinking is obsolete), numpy and Pillow
(whose absence silently disabled every image oracle and looked like a logic
bug), and a display owned by PID 1 (so Xvfb no longer "dies on its own every
few minutes" -- it was being reaped because nothing owned it).

Verified end to end, not by inspection: the image builds, sylph-doctor is green,
`build-canary` links xenia_canary inside the container, and that binary then
runs -- guest memory and the JIT code cache appear in /dev/shm within 4 s,
1 205 log lines, gmem.py reads guest RAM, pad.py drives the file pad, and
screenshot captures the display.

Five environment defects found and fixed on the way, each of which fails in a
way that points somewhere else entirely:

  * /dev/shm is `noexec` under Docker. Xenia maps its JIT code cache out of an
    shm file, so it died with "Unable to allocate code cache generated code
    storage / Cannot initalize processor" -- which reads as an address-space
    clash, not a mount flag. Now `--tmpfs /dev/shm:rw,exec`.
  * An unknown xenia flag HANGS rather than errors: ParseLaunchArguments calls
    ShowSimpleMessageBox before logging is initialised, and that SDL dialog
    blocks on XIfEvent forever. `--audio` (which the RE notes recommend) is not
    a cvar in this tree; the symptom was a 10x10 window and an empty log.
  * Named volumes come up root-owned unless their mount point exists in the
    image, so the first cmake configure failed on pkgRedirects.
  * Ubuntu 24.04 ships its own uid-1000 account, colliding with the host user.
  * Ubuntu's spirv-opt has no --canonicalize-ids, so the shader step dies ~500
    objects in; the launcher mounts the host's LunarG SDK instead of baking one
    in, which also keeps shader output byte-identical to a host build.

Known limits, stated rather than papered over: on an NVIDIA host without the
NVIDIA Container Toolkit there is no hardware Vulkan (/dev/dri alone does
nothing for NVIDIA), and under lavapipe the emulator runs correctly but was not
observed to reach a rendered frame within a couple of minutes. gdb needs `sudo`
inside the container because the host's yama ptrace_scope outranks SYS_PTRACE.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

docker/agent/bin/build-canary

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+# Configure + build Xenia Canary inside the container.
+#
+# The build directory is $XENIA_BUILD_DIR (outside the bind-mounted repo) on
+# purpose. The host builds this same tree, and CMake caches an absolute compiler
+# path and a generator: sharing repo/build between host and container makes each
+# one reconfigure and relink everything the other just did.
+#
+# Parallelism comes from $SYLPH_JOBS, which the entrypoint derives from
+# AVAILABLE MEMORY as well as core count — a full-parallel build of this tree
+# has OOM-killed the host outright.
+#
+#   build-canary [Release|Debug]  [extra cmake --build args]
+set -euo pipefail
+
+CONFIG="${1:-Release}"; shift || true
+SRC="${PROJECT_DIR:-/work}/xenia-canary"
+BUILD="${XENIA_BUILD_DIR:-/sylph-home/re/canary-build}"
+JOBS="${SYLPH_JOBS:-2}"
+
+[ -d "$SRC" ] || { echo "build-canary: no source at $SRC" >&2; exit 1; }
+
+# Submodules: this tree has drifted before, and a checkout that changes a
+# gitlink fails silently into a half-built third_party. Report rather than fix,
+# because one submodule here carries an in-tree cmake build whose untracked
+# artifacts block an update.
+if ! git -C "$SRC" submodule status --recursive 2>/dev/null | grep -qv '^ '; then
+  :
+else
+  echo "build-canary: note — submodules are not all at their recorded commits:" >&2
+  git -C "$SRC" submodule status 2>/dev/null | grep -v '^ ' | sed 's/^/  /' >&2
+fi
+
+if [ ! -f "$BUILD/CMakeCache.txt" ]; then
+  echo "==> configuring $BUILD ($CONFIG, Ninja Multi-Config, clang $(clang --version | head -1 | grep -oE '[0-9]+\.[0-9]+\.[0-9]+'))"
+  cmake -S "$SRC" -B "$BUILD" -G "Ninja Multi-Config" \
+    -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ \
+    -DXENIA_BUILD_TESTS=OFF -DXENIA_BUILD_MISC=OFF \
+    -DXENIA_ENABLE_LTO=OFF
+fi
+
+echo "==> building $CONFIG with -j$JOBS"
+cmake --build "$BUILD" --config "$CONFIG" --parallel "$JOBS" --target xenia_canary "$@"
+
+BIN="$BUILD/bin/Linux/$CONFIG/xenia_canary"
+if [ -x "$BIN" ]; then
+  echo "==> $BIN"
+  echo "    run it with:  run-canary"
+else
+  echo "build-canary: target did not produce $BIN" >&2
+  exit 1
+fi

docker/agent/bin/build-reborn

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+# Build / test Sylpheed Reborn inside the container.
+#
+# CARGO_TARGET_DIR points outside the bind-mounted repo (see the Dockerfile), so
+# this never fights the host's incremental state.
+#
+#   build-reborn                 cargo build --workspace
+#   build-reborn test            cargo test --workspace, disc tests enabled
+#   build-reborn ci              fmt + clippy + test
+#   build-reborn <cargo args...>
+set -euo pipefail
+
+SRC="${PROJECT_DIR:-/work}/Syplheed-Reborn"
+JOBS="${SYLPH_JOBS:-2}"
+cd "$SRC"
+
+# The disc-gated integration tests self-skip when this is unset, and a green run
+# then means almost nothing — point them at the extracted disc if it is there.
+if [ -z "${SYLPHEED_DISC:-}" ]; then
+  for c in "${PROJECT_DIR:-/work}/sylph_extract" "$SRC/../sylph_extract"; do
+    [ -d "$c/dat" ] && { export SYLPHEED_DISC="$(readlink -f "$c")"; break; }
+  done
+fi
+[ -n "${SYLPHEED_DISC:-}" ] && export SYLPHEED_RES3D="$SYLPHEED_DISC/hidden/resource3d"
+if [ -z "${SYLPHEED_ISO:-}" ]; then
+  iso="$(find "${PROJECT_DIR:-/work}" -maxdepth 2 -iname '*.iso' -print -quit 2>/dev/null || true)"
+  [ -n "$iso" ] && export SYLPHEED_ISO="$iso"
+fi
+echo "==> SYLPHEED_DISC=${SYLPHEED_DISC:-<unset — disc tests will SKIP>}" >&2
+
+export CARGO_BUILD_JOBS="$JOBS"
+
+case "${1:-build}" in
+  build) shift || true; exec cargo build --workspace "$@" ;;
+  test)  shift || true; exec cargo test  --workspace "$@" ;;
+  ci)
+    cargo fmt --all -- --check
+    cargo clippy --workspace -- -D warnings
+    cargo test --workspace
+    # NOTE: `just ci` also checks wasm32. That leg does not build, and not for
+    # any reason in this crate: the workspace pins tokio with features=["full"],
+    # which pulls mio, which refuses to compile for wasm32. Left out here rather
+    # than reported as a failure of the change under test.
+    echo "==> native CI green (wasm leg skipped — see the note in this script)"
+    ;;
+  *) exec cargo "$@" ;;
+esac

docker/agent/bin/run-canary

@@ -0,0 +1,99 @@
+#!/usr/bin/env bash
+# Launch Xenia Canary with the settings this title actually needs.
+#
+# Four of these are not preferences — they are measured requirements, and every
+# one of them cost a debugging session before it was pinned down:
+#
+#   --apu=sdl + SDL_AUDIODRIVER=dummy
+#       There is no PulseAudio here, so `--apu=nop` looks like the safe muted
+#       choice. It is not: the log then fills with "CreateDriver failed for
+#       index=0", the guest never gets past the intro movie, and the window
+#       stays black for 8+ minutes. The SDL driver against a dummy device is
+#       both silent AND lets the title advance.
+#
+#   NO --audio flag
+#       The RE notes say "--audio --apu=sdl". `--audio` is NOT a cvar in this
+#       tree, and an unknown argument is not a friendly error: xenia calls
+#       ShowSimpleMessageBox from ParseLaunchArguments, BEFORE logging is
+#       initialised, and that SDL dialog blocks on XIfEvent forever. Headless,
+#       the symptom is a 10x10 window, an empty log, and no guest memory —
+#       which reads like a hang deep in the emulator rather than a typo.
+#       If this ever appears to hang at startup, suspect a bad flag first.
+#
+#   --hid=file --pad_file=...
+#       The old vgamepad path made its device through /dev/uinput, which is NOT
+#       namespaced — a pad created inside a container registers with the HOST's
+#       input stack and every scripted press leaks to the user's desktop. This
+#       driver reads a text file instead. Drive it with tools/re-capture/pad.py.
+#       Trap worth remembering: 360 menus poll XamInputGetKeystrokeEx, not
+#       GetState, so a stubbed GetKeystroke looks like a completely dead pad.
+#
+#   one instance at a time
+#       Two emulators (or ours + canary) at once perturbs both and the box.
+#       Enforced with a lockfile rather than left to discipline.
+#
+# Usage:  run-canary [extra xenia flags...]
+#   ISO from $SYLPH_ISO, else the first *.iso under $PROJECT_DIR.
+#   Binary from $XENIA_BIN, else the container build, else the repo build.
+set -u
+
+LOCK=/tmp/xenia-canary.lock
+exec 9>"$LOCK"
+if ! flock -n 9; then
+  echo "run-canary: an emulator is already running (lock $LOCK)." >&2
+  echo "  Only one at a time — kill it first:  pkill -x xenia_canary" >&2
+  exit 1
+fi
+
+PROJECT_DIR="${PROJECT_DIR:-/work}"
+
+# ── Binary ───────────────────────────────────────────────────────────────────
+pick_bin() {
+  [ -n "${XENIA_BIN:-}" ] && { echo "$XENIA_BIN"; return; }
+  for c in \
+      "${XENIA_BUILD_DIR:-/sylph-home/re/canary-build}/bin/Linux/Release/xenia_canary" \
+      "${XENIA_BUILD_DIR:-/sylph-home/re/canary-build}/bin/Linux/Debug/xenia_canary" \
+      "$PROJECT_DIR/xenia-canary/build/bin/Linux/Release/xenia_canary" \
+      "$PROJECT_DIR/xenia-canary/build/bin/Linux/Debug/xenia_canary"; do
+    [ -x "$c" ] && { echo "$c"; return; }
+  done
+}
+BIN="$(pick_bin)"
+if [ -z "${BIN:-}" ]; then
+  echo "run-canary: no xenia_canary binary found. Build one with:  build-canary" >&2
+  exit 1
+fi
+
+# ── ISO ──────────────────────────────────────────────────────────────────────
+ISO="${SYLPH_ISO:-}"
+if [ -z "$ISO" ]; then
+  # Prefer a REAL file over a symlink and take the largest: the tree carries
+  # `xenia-rs/sylpheed.iso` as a symlink to the retail image, and a symlink has
+  # already cost a session once (Wine could not resolve it -> "path invalid").
+  ISO="$(find "$PROJECT_DIR" -maxdepth 2 -type f -iname '*.iso' -printf '%s\t%p\n' 2>/dev/null \
+         | sort -rn | head -1 | cut -f2-)"
+fi
+if [ -z "$ISO" ] || [ ! -f "$ISO" ]; then
+  echo "run-canary: no ISO. Set SYLPH_ISO=/path/to/game.iso" >&2
+  exit 1
+fi
+ISO="$(readlink -f "$ISO")"
+
+export SDL_AUDIODRIVER="${SDL_AUDIODRIVER:-dummy}"
+export DISPLAY="${DISPLAY:-:98}"
+PAD="${XENIA_PAD_FILE:-/tmp/xenia_pad.txt}"
+: > "$PAD"
+
+# Guest memory is backed by /dev/shm; a stale file from a killed run confuses
+# the memory readers (gmem.py finds two candidates and picks the dead one).
+rm -f /dev/shm/xenia_memory_* /dev/shm/xenia_code_cache_* 2>/dev/null || true
+
+echo "run-canary: $BIN" >&2
+echo "       iso: $ISO" >&2
+echo "       pad: $PAD   display: $DISPLAY   shm: $(df -h /dev/shm | awk 'NR==2{print $2}')" >&2
+
+exec "$BIN" "$ISO" \
+  --apu=sdl \
+  --hid=file --pad_file="$PAD" \
+  --mute=true \
+  "$@"

docker/agent/bin/screenshot

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# Raw full-root PNG grab of the headless display.
+#
+# This is deliberately the *uncropped* root window, because
+# `tools/re-capture/bin/screenshot` is a wrapper that calls this one as its raw
+# grabber and then crops to the game surface — xenia's window is a GTK window
+# whose menu bar pushes the 1280x720 game image down ~25 px, and every pixel
+# oracle in the toolkit was measured against the bare game image. That wrapper
+# directory is first on PATH, so scripts calling `screenshot` get the cropped
+# game surface and this stays the honest raw grab underneath it.
+#
+#   screenshot [out.png]     default: $HOME/shots/shot-NNNN.png
+set -u
+
+OUT="${1:-}"
+if [ -z "$OUT" ]; then
+  dir="${HOME:-/tmp}/shots"; mkdir -p "$dir"
+  n_file="$dir/.counter"
+  n=$(( $(cat "$n_file" 2>/dev/null || echo 0) + 1 )); echo "$n" > "$n_file"
+  OUT="$dir/shot-$(printf '%04d' "$n").png"
+fi
+mkdir -p "$(dirname "$OUT")"
+
+if ! xdpyinfo >/dev/null 2>&1; then
+  echo "screenshot: no display on ${DISPLAY:-<unset>}" >&2
+  exit 1
+fi
+
+# ImageMagick first. `import` talks X11 directly and captures a window that is
+# mid-redraw without tearing the way a video grabber can.
+if command -v import >/dev/null 2>&1 && import -silent -window root "$OUT" 2>/dev/null; then
+  echo "$OUT"; exit 0
+fi
+
+# Fallback: ffmpeg's x11grab. Needs an explicit size, so read it off the server
+# rather than assuming the geometry.
+if command -v ffmpeg >/dev/null 2>&1; then
+  size=$(xdpyinfo | awk '/dimensions:/{print $2; exit}')
+  if ffmpeg -loglevel error -y -f x11grab -draw_mouse 0 \
+            -video_size "$size" -i "$DISPLAY" -frames:v 1 "$OUT" 2>/dev/null; then
+    echo "$OUT"; exit 0
+  fi
+fi
+
+# Last resort: xwd, which is always present with x11-utils.
+if command -v xwd >/dev/null 2>&1 && command -v convert >/dev/null 2>&1; then
+  xwd -root -silent | convert xwd:- "$OUT" && { echo "$OUT"; exit 0; }
+fi
+
+echo "screenshot: no working capture backend" >&2
+exit 1

docker/agent/bin/sylph-doctor

@@ -0,0 +1,88 @@
+#!/usr/bin/env bash
+# Prove the container can actually do the four things it exists for, before an
+# unattended agent spends an hour discovering otherwise.
+#
+# Every check here stands for a failure that has already happened once: a
+# display that was not there, a missing numpy that looked like a logic bug, a
+# /dev/shm too small for guest memory, a Vulkan stack with no ICD.
+set -u
+fail=0
+ok()   { printf '  \033[32m✔\033[0m %s\n' "$*"; }
+bad()  { printf '  \033[31m✖\033[0m %s\n' "$*"; fail=$((fail+1)); }
+warn() { printf '  \033[33m!\033[0m %s\n' "$*"; }
+
+echo "── resources ──"
+# nproc shows the HOST's cores: --cpus is a quota, not a mask. Report both so
+# "12 cpus" is never mistaken for 12 cpus' worth of throughput.
+quota="unlimited"
+if [ -r /sys/fs/cgroup/cpu.max ]; then
+  read -r q p < /sys/fs/cgroup/cpu.max
+  [ "$q" != max ] && quota="$(( q / p )) (quota)"
+fi
+echo "  cpus: $(nproc) visible, $quota"
+if [ -r /sys/fs/cgroup/memory.max ]; then
+  m=$(cat /sys/fs/cgroup/memory.max)
+  [ "$m" = max ] && warn "memory: UNLIMITED — the half-the-box cap is not applied" \
+                 || ok "memory cap: $(( m / 1024 / 1024 / 1024 )) GiB"
+fi
+shm=$(df -BM /dev/shm | awk 'NR==2{print $2}' | tr -d M)
+# Guest memory for a 512 MB console plus the code cache does not fit in
+# Docker's 64 MB default, and the symptom is an mmap error, not a disk-full one.
+[ "${shm:-0}" -ge 512 ] && ok "/dev/shm: ${shm} MiB" || bad "/dev/shm only ${shm:-?} MiB — need >=512; pass --shm-size"
+
+echo "── toolchain ──"
+for t in clang clang++ cmake ninja cargo rustc python3 node claude; do
+  command -v "$t" >/dev/null && ok "$t  ($("$t" --version 2>/dev/null | head -1))" || bad "$t missing"
+done
+
+echo "── python (dynamic RE) ──"
+# numpy and PIL missing is the specific hole that silently disabled entities2.py
+# and every image oracle in the toolkit.
+for m in numpy PIL duckdb; do
+  python3 -c "import $m" 2>/dev/null && ok "python: $m" || bad "python: $m MISSING"
+done
+
+echo "── display ──"
+if xdpyinfo >/dev/null 2>&1; then
+  ok "display $DISPLAY  ($(xdpyinfo | awk '/dimensions:/{print $2; exit}'))"
+  pgrep -x openbox >/dev/null && ok "openbox running" || warn "no window manager — window geometry oracles will misread"
+  out=$(screenshot /tmp/_doctor.png 2>&1) && [ -s /tmp/_doctor.png ] \
+    && ok "screenshot works -> $(identify -format '%wx%h' /tmp/_doctor.png 2>/dev/null || echo ok)" \
+    || bad "screenshot failed: $out"
+  rm -f /tmp/_doctor.png
+else
+  bad "no display on ${DISPLAY:-<unset>}"
+fi
+
+echo "── vulkan ──"
+if command -v vulkaninfo >/dev/null 2>&1; then
+  dev=$(vulkaninfo --summary 2>/dev/null | grep -m3 -E 'deviceName' | sed 's/^ *//')
+  [ -n "$dev" ] && { ok "Vulkan devices:"; echo "$dev" | sed 's/^/      /'; } \
+                || bad "vulkaninfo found no device (ICD missing?)"
+else
+  bad "vulkaninfo missing"
+fi
+# Judge by what enumerated, not by whether a device node is present: an NVIDIA
+# card needs the NVIDIA Container Toolkit, and /dev/dri alone does nothing.
+case "${dev:-}" in
+  *llvmpipe*|*lavapipe*)
+    warn "SOFTWARE Vulkan only — correct but slow."
+    command -v nvidia-smi >/dev/null 2>&1 \
+      && warn "  host has an NVIDIA GPU: install nvidia-container-toolkit for hardware" ;;
+  "") ;;
+  *)  ok "hardware Vulkan" ;;
+esac
+
+echo "── project ──"
+[ -d /work/xenia-canary ]    && ok "/work/xenia-canary"    || bad "/work/xenia-canary not mounted"
+[ -d /work/Syplheed-Reborn ] && ok "/work/Syplheed-Reborn" || bad "/work/Syplheed-Reborn not mounted"
+iso=$(find /work -maxdepth 2 -type f -iname '*.iso' -printf '%s\t%p\n' 2>/dev/null | sort -rn | head -1 | cut -f2-)
+[ -n "$iso" ] && ok "ISO: $iso" || warn "no ISO under /work — run-canary needs SYLPH_ISO"
+[ -d /work/sylph_extract/dat ] && ok "extracted disc (disc-gated tests will run)" \
+                               || warn "no extracted disc — Reborn disc tests will SKIP"
+[ -w /sylph-home/re/.claude ] && ok "~/.claude writable (token refresh works)" \
+                              || warn "~/.claude not writable — Claude Code may fail to refresh auth"
+
+echo
+[ "$fail" -eq 0 ] && { echo "all good."; exit 0; }
+echo "$fail check(s) failed."; exit 1