fix(decoder): give the container the Canary it is supposed to run

The database mount below was one of three ways the decoder could not reach its
own oracle. The other two are here.

`run-canary` never looked in `Checked/`. It tried `Release/` then `Debug/`, and
both of those exist on this box -- an Aug 28 binary and a Jul 19 one. They boot
the game perfectly well and carry NO `audit_61` branch probe, so a probe run
against either returns zero hits that read as a finding about the game rather
than as a stale binary. Configuration is now the outer loop and location the
inner one, so a `Checked` build anywhere beats a `Release` build anywhere;
`$XENIA_BIN` still overrides everything. Measured here: `Checked` has
`audit_61_branch_probe_pcs`, `Release` and `Debug` do not.

The launcher also now says which instrumentation is missing BEFORE the run,
because the alternative is reading an empty log afterwards and guessing.

`build-canary` built `$PROJECT_DIR/xenia-canary`, which does not exist in this
container -- the source is bind-mounted at `/canary` and the launcher already
exports `XENIA_SRC=/canary`. CONTAINER-NOTES has carried that defect since
2026-08-29 with a symlink workaround and a warning to remember to delete the
symlink afterwards. It now reads `$XENIA_SRC` first, so there is nothing to
remember. Its default configuration moves Release -> Checked to match what
`run-canary` picks; the old default spent a full build on a binary nothing ran.

Two documented blockers are refuted rather than deleted, since the sequence of
wrong readings is what makes the right one checkable: the CONTAINER-NOTES
symlink dance (the warm build volume it was configured against is gone too,
removed in the 2026-09-18 cleanup, so the next build configures cleanly against
`/canary`), and `upstream-baseline.md`'s "`version.h` is never generated" --
`CMakeLists.txt` generates it at configure time now, with a stub fallback.

`decoder-loop.md` claimed the oracle was at `Linux/Release/` and that the probe
was on two side branches; both were true when written and neither is now.

Verified: five pick_bin cases against the extracted function body, and `strings`
on all three real binaries.

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

docker/decoder/bin/build-canary

@@ -10,11 +10,22 @@
 # 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]
+# `Checked` is the default, and should stay it: it is what the host builds and
+# what `run-canary` picks first, so the two agree by construction. Building
+# `Release` here instead leaves a second binary that `run-canary` will not use
+# -- hours of CPU for something nothing runs. `Checked` is optimised, with
+# assertions left in.
+#
+#   build-canary [Checked|Release|Debug]  [extra cmake --build args]
 set -euo pipefail
 
-CONFIG="${1:-Release}"; shift || true
+CONFIG="${1:-Checked}"; shift || true
-SRC="${PROJECT_DIR:-/work}/xenia-canary"
+# $XENIA_SRC FIRST. In this container the Canary source is bind-mounted at
+# `/canary`, and `$PROJECT_DIR/xenia-canary` does not exist -- so the old default
+# made this script unusable here, and the documented workaround was to symlink
+# `/canary` into the repository and remember to delete it again (CONTAINER-NOTES
+# §"The toolchain is real"). The launcher already exports the right path; read it.
+SRC="${XENIA_SRC:-${PROJECT_DIR:-/work}/xenia-canary}"
 BUILD="${XENIA_BUILD_DIR:-/sylph-home/re/canary-build}"
 JOBS="${SYLPH_JOBS:-2}"
 

docker/decoder/bin/run-canary

@@ -48,15 +48,26 @@ fi
 PROJECT_DIR="${PROJECT_DIR:-/work}"
 
 # ── Binary ───────────────────────────────────────────────────────────────────
+# `Checked` FIRST. All three configurations can be built, but `Checked` is the
+# one this project actually builds, so it is the one carrying our
+# instrumentation; the `Release/` and `Debug/` binaries beside it are months-old
+# leftovers that still run and still boot the game, which is exactly what makes
+# them dangerous -- a probe run against one reports zero hits and reads as a
+# finding about the game. Measured on this box 2026-09-21: `Checked` has
+# `audit_61_branch_probe_pcs`, `Release` (Aug 28) and `Debug` (Jul 19) do not.
 pick_bin() {
   [ -n "${XENIA_BIN:-}" ] && { echo "$XENIA_BIN"; return; }
+  # Configuration is the OUTER loop, location the inner one: a `Checked` build
+  # anywhere beats a `Release` build anywhere. The other order picks a stale
+  # container `Release` over a fresh instrumented repo `Checked`, which is the
+  # exact mistake this is here to stop.
+  for cfg in Checked Release Debug; do
     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/$cfg/xenia_canary" \
-      "${XENIA_BUILD_DIR:-/sylph-home/re/canary-build}/bin/Linux/Debug/xenia_canary" \
+        "$PROJECT_DIR/xenia-canary/build/bin/Linux/$cfg/xenia_canary"; do
-      "$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
+  done
 }
 BIN="$(pick_bin)"
 if [ -z "${BIN:-}" ]; then
@@ -64,6 +75,13 @@ if [ -z "${BIN:-}" ]; then
   exit 1
 fi
 
+# Say what is in the binary before the run, not after reading an empty log.
+# A missing probe is a build that predates it, never a quiet game.
+for sym in audit_61_branch_probe_pcs RE-DRAW; do
+  grep -aqm1 -- "$sym" "$BIN" \
+    || echo "run-canary: ⚠ $BIN has NO '$sym' -- it predates that instrumentation. Rebuild with: build-canary" >&2
+done
+
 # ── ISO ──────────────────────────────────────────────────────────────────────
 ISO="${SYLPH_ISO:-}"
 if [ -z "$ISO" ]; then

docker/decoder/sylph-decoder

@@ -122,11 +122,28 @@ docker_args() {
     # (file offset = VA - 0x82000000), which removes the need to boot the
     # emulator and scrape /dev/shm to get at it. An earlier belief that this
     # file was STALE was tested and refuted -- it is current.
-    -v "${SYLPH_XENIA_RS:-$PROJECT/xenia-rs}:/xenia-rs:ro"
     -v "${SYLPH_PE:-$PROJECT/Project Sylpheed - Arc of Deception (USA, Europe) (En,Ja).pe}:/image/sylpheed.pe:ro"
-    -e "SYLPHEED_DB=/xenia-rs/sylpheed.db"
+    # 🔴 THE DISASSEMBLY DATABASE. This used to be read from the xenia-rs clone
+    # (`SYLPHEED_DB=/xenia-rs/sylpheed.db`). That repo is retired, its directory
+    # is gone, and the mount that served it was removed -- so the variable named
+    # a path that did not exist and `zq.py` had nothing to open. The database now
+    # lives beside the repo as a build artefact; mounted at the container's repo
+    # root, which is where `zq.py` looks when `$SYLPHEED_DB` is unset.
+    #
+    # Read-only on purpose: the host owns it, DuckDB takes an exclusive lock to
+    # write, and two agents plus the human sharing one file would corrupt it.
+    # Regenerating means writing elsewhere and pointing `$SYLPHEED_DB` at it.
     -e "SYLPHEED_PE=/image/sylpheed.pe"
     -e "SYLPHEED_IMAGE_BASE=0x82000000"
+    # 🔴 EVIDENCE IS SHARED, NOT COMMITTED (issue #49). Each agent works in its
+    # OWN clone, so a gitignored capture written in one container is invisible to
+    # the other and to the human -- git used to be the transport and no longer is.
+    # One host directory, bind-mounted into both agents, is: all three see the
+    # same files live, every `docs/re/captures/...` citation resolves everywhere,
+    # and nothing can reach git history. Read-write on purpose -- showing each
+    # other a screenshot is the point.
+    -v "${SYLPH_CAPTURES:-$PROJECT/Sylpheed/docs/re/captures}:/work/docs/re/captures"
+
     # The shared exchange: transient files with provenance, outside git history.
     -v "sylpheed-exchange:/exchange"
     -e "PROJECT_DIR=/work"
@@ -268,6 +285,20 @@ docker_args() {
     echo "==> NOTE: no ISO at $_iso -- Canary has nothing to boot." >&2
   fi
 
+  # The disassembly database. `zq.py` looks at the repo root when $SYLPHEED_DB
+  # is unset, so mounting it there needs no environment variable at all -- which
+  # is what the dead `/xenia-rs/sylpheed.db` variable taught: a path in an env
+  # var and a path in a mount drift apart silently.
+  _db="${SYLPH_DB:-$PROJECT/Sylpheed/sylpheed.db}"
+  if [ -f "$_db" ]; then
+    _out+=(-v "$_db:/work/sylpheed.db:ro")
+  else
+    echo "==> NOTE: no sylpheed.db at $_db -- /sylph-dis and zq.py cannot run." >&2
+    echo "    build one:  cargo run --release -p sylpheed-xexdb --bin sylph-xexdb -- \\" >&2
+    echo "                  dis \"\$SYLPH_ISO\" --db sylpheed.db --analyze sql --quiet" >&2
+    echo "    then re-apply the RE names with tools/apply_re_symbols.sql" >&2
+  fi
+
   # ── GPU ──
   # Three distinct cases, and conflating them is how you end up believing you
   # have hardware Vulkan while actually running llvmpipe:

docker/port/sylph-port

@@ -67,6 +67,14 @@ docker_args() {
     -v "sylpheed-port-claude:/sylph-home/port/.claude"
     -v "${SYLPH_CLAUDE_HOME:-$HOME/.claude}:/sylph-home/port/.claude.seed:ro"
     -v "${SYLPH_CLAUDE_JSON:-$HOME/.claude.json}:/sylph-home/port/.claude.host.json:ro"
+    # 🔴 EVIDENCE IS SHARED, NOT COMMITTED (issue #49). Each agent works in its
+    # OWN clone, so a gitignored capture written in one container is invisible to
+    # the other and to the human -- git used to be the transport and no longer is.
+    # One host directory, bind-mounted into both agents, is: all three see the
+    # same files live, every `docs/re/captures/...` citation resolves everywhere,
+    # and nothing can reach git history. Read-write on purpose -- showing each
+    # other a screenshot is the point.
+    -v "${SYLPH_CAPTURES:-$WORKSPACE/Sylpheed/docs/re/captures}:/work/docs/re/captures"
     -v "sylpheed-exchange:/exchange"
     -e "PROJECT_DIR=/work"
     # Same guardrail as the decoder, added the same day and for its reason: the

docs/agents/CONSOLIDATION.md

@@ -1,3 +1,27 @@
+# ✅ CLOSED 2026-09-20 — every phase done, and the two human decisions taken
+
+Nothing on this page is outstanding. It is kept as the record of how the two-repo
+layout was reached; **where it describes the repository's present state it is
+now out of date on purpose**, and the notes below say how.
+
+| the page says | what is true now |
+|---|---|
+| "**Still open, for the human**: the history fork" | **Taken: full purge.** `git filter-repo` stripped 182 assets from every commit; force-pushed 2026-09-19. `main` `2a93be99` → `e16556dc`, `.git` **217 MB → 114 MB**, **0** assets anywhere in history, verified from an independent fresh clone. Backups + runbook: `~/sylph-repo-backup-2026-09-19/` |
+| "`docs/re/captures/` is 118 MB of game screenshots inside a public repository" | **Decided (#49): no game assets in the repos.** Captures live on disk, gitignored, shared between the host and both agents by bind mount; derived measurements (csv/tsv/txt/log/json/npy) stay tracked. PR #59 |
+| "all six repos are `private=False`" | Still true, and now deliberate — there is nothing game-derived in them |
+| "`ai-agent-*.md`, `scratch/`, `_voice_span.rs` — keep or drop" | `scratch/` and `_voice_span.rs` dropped in the 2026-09-18 cleanup; the `ai-agent-*.md` files are the human's and stay |
+| the four archived repos | unchanged: `Sylpheed-Godot`, `xenia-rs`, `xex2tractor` archived read-only, `Syplheed-Reborn` deleted. ⚠️ Their local clones are **gone from this machine** too, and `sylph-decoder` no longer mounts `xenia-rs` |
+
+🔴 **The one thing this page got right and nobody acted on.** It named
+`crates/sylpheed-export`'s dependency on **this repository by tag** as the hard
+blocker for a rewrite. It was not re-checked before the purge, the locked rev
+vanished, and the build broke for every clean checkout while still working on the
+machine that did the rewrite — its `~/.cargo/git` still held the old object.
+Fixed in PR #60 (re-lock) and PR #61 (path dependency, which removes the class).
+**Before any future history rewrite, grep for a dependency on the repo's own URL.**
+
+---
+
 # Consolidating six repositories into two
 
 **Set by the human, 2026-09-13.** The end state is **two** repositories:

docs/agents/CONTAINER-NOTES.md

@@ -12,13 +12,20 @@ already went wrong once.
 * **The toolchain is real.** `tools/re-capture/rebuild_canary.sh` exists because
   the old box had no cmake/ninja/clang and only runtime sonames, so it hand-
   relinked object files. **Do not use it here.** Use `build-canary`.
-  🔴 **But `build-canary` does not work in this container as it stands
+  ✅ **FIXED 2026-09-21 — `build-canary` now reads `$XENIA_SRC` first**, which the
+  launcher already sets to `/canary`, so there is no symlink to make and none to
+  forget. The two paragraphs below are kept because they are how the defect was
+  found and refuted, but **neither describes the script any more.**
+
+  🔴 ~~**`build-canary` does not work in this container as it stands
   (2026-08-29).** It builds `${PROJECT_DIR:-/work}/xenia-canary`, which **does
   not exist here** — the Canary source is at **`/canary`** (`$XENIA_SRC`). The
   warm 235 MB tree at `/sylph-home/re/canary-build` is configured with
   `CMAKE_HOME_DIRECTORY=/work/xenia-canary`, also missing, and its
   `build-Release.ninja` carries **no per-file rules** — it wants to re-run CMake
-  first, which would fail on the absent source root.
+  first, which would fail on the absent source root.~~ The warm tree is gone too:
+  every `sylph-*` volume was removed in the 2026-09-18 cleanup, so the next build
+  configures from scratch against `/canary` and caches the right source root.
 
   ✅ **The conclusion drawn from all that is REFUTED (2026-08-31).** The note went
   on to say *"any Canary change is a full reconfigure against `/canary` plus a full
@@ -38,9 +45,10 @@ already went wrong once.
   warm 235 MB tree is otherwise intact and the ninja re-run resolves its rules
   from the symlink.
 
-  ⚠️ **Remove the symlink when you are done.** `/work` is the repository, and
+  ⚠️ ~~**Remove the symlink when you are done.**~~ No longer needed — but if you
-  `xenia-canary` is not in `.gitignore`, so it shows up as untracked and can be
+  ever make one by hand, note that `/work` is the repository and `xenia-canary`
-  swept into a `git add -A`.
+  is not in `.gitignore`, so it shows up as untracked and can be swept into a
+  `git add -A`.
 * **numpy and Pillow are installed.** `entities2.py`, `flight_probe.py` and the
   image oracles work. Their absence used to look like a logic bug.
 

docs/agents/CONTAINERS-AND-AGENTS.md

@@ -88,6 +88,42 @@ sylph-agent-canary-build                         the warm 235 MB Canary build tr
 sylpheed-exchange                                agent -> agent files, read-only in
 ```
 
+**Plus one bind mount, which is not a volume on purpose** — the host's
+`Sylpheed/docs/re/captures/`, mounted read-write into both agents at
+`/work/docs/re/captures`:
+
+```
+-v "${SYLPH_CAPTURES:-<workspace>/Sylpheed/docs/re/captures}:/work/docs/re/captures"
+```
+
+🔴 **Why it has to exist.** Each agent works in its OWN clone, so before issue
+#49 the transport for evidence was *git*: commit the screenshot, the other agent
+pulls it. #49 removed that — captures are gitignored now — and without a
+replacement a capture written in one container is invisible to the other agent,
+to the human, and to `check-capture-citations`, which would call every citation
+dangling. One host directory shared by all three restores it: the same file is
+live everywhere, every `docs/re/captures/...` citation resolves, and nothing can
+reach git history. Read-write on both, because showing each other a screenshot
+is the point.
+
+Verified rather than assumed: container A wrote a `.png` there, a **separate**
+container B read it back, the host saw it, and `git status` reported **0**
+changes.
+
+⚠️ **Evidence that must cross MACHINES still cannot go this way** — a bare clone
+on the other desktop has no captures at all. Attach it to the issue or PR; that
+is the only channel that travels.
+
+⚠️ **The agent volumes were all deleted in the 2026-09-18 cleanup** and Docker
+recreates them empty on next launch. Nothing was lost — both agent clones were
+verified clean with nothing unpushed, and the exchange held only spent artefacts.
+One side effect is welcome: the empty `*-claude` volumes mean the next launch
+starts a **fresh** session, which is the documented workaround for the
+"resumes the old brief" defect below.
+
+⚠️ **`sylph-decoder` used to mount `xenia-rs` read-only. That repo is retired and
+the directory is gone**, so the mount pointed at nothing; removed.
+
 **Credentials** — three files on the host, `chmod 600`, mounted read-only:
 
 ```

docs/agents/PROTOCOL.md

@@ -129,10 +129,18 @@ exchange volume carries the working artefacts.
 | kind | where | why |
 |---|---|---|
 | code, decoded knowledge | **git** | history, review, permanence |
-| evidence cited by a finding | **git** | it is the proof |
+| evidence cited by a finding — a screenshot, a frame, a savegame | **`docs/re/captures/`, present but NEVER committed** | it is the proof, but it is game content. The directory is gitignored and shared between the host and both agents, so all three see the same file; `tools/re/check-capture-citations` fails if a citation has no file, and fails again if an asset is tracked |
+| a measurement you derived — csv, tsv, txt, log, json | **git** | our own numbers, not game content, and most findings rest on them |
+| evidence that must cross machines | **attached to the issue or PR** | captures are local-only now, so a bare clone has none of them. Attaching is the only channel that reaches the other desktop or a reviewer |
 | **evidence a human must look at** — the screenshot or film behind a `state/needs-human` item | **attached to that issue** | it travels *with* the item, a person sees it in a browser, and it cannot be orphaned from the claim it supports |
 | exploratory captures, work in progress, "look at this" | **`share`** → `/exchange` | no history; would bloat the repo forever |
 
+⚠️ **This table's first row used to say "git", and that is how 76 MB of
+screenshots accumulated** — directly above the rule forbidding exactly that. The
+two contradicted each other for months and the table won, because it was the one
+that told you what to *do*. Issue #49 settled it and the history was rewritten;
+if you find yourself reaching for `git add -f` on a capture, the answer is no.
+
 🔴 **Never commit game content.** Not sprites, not audio, not transcoded video,
 not a capture of the running game — under *any* directory name. On 2026-09-04
 this rule was live, and freshly tightened, while **545 MB of extracted disc

docs/agents/decoder-loop.md

@@ -56,11 +56,28 @@ rather than left in a document you might not reach.
 | path | what | env |
 |---|---|---|
 | `/image/sylpheed.pe` | the decompressed executable image | `SYLPHEED_PE` |
-| `/xenia-rs/sylpheed.db` | a disassembly database, 586 MB | `SYLPHEED_DB` |
+| `sylpheed.db` at the repo root | the disassembly database, 337 MB | — (`zq.py` finds it; `$SYLPHEED_DB` only to override) |
+| `/canary/build/bin/Linux/Checked/xenia_canary` | the built oracle, inside the `/canary` mount | — |
 | `/disc` | the extracted disc | `SYLPHEED_DISC` |
 | `/iso/game.iso` | the retail ISO Canary boots | `SYLPH_ISO` |
 | `/canary` | the Canary source, read-write | `XENIA_SRC` |
 
+⚠️ **The database is read-only and is NOT in git** — it is a build artefact, and
+`docs/re/captures/` is the same (issue #49). If either is missing the launcher
+says so and prints the command that builds it. Query the database with
+`python3 tools/zq.py …`, never by reading a disassembly dump.
+
+⚠️ **Take the oracle from `Checked/`, not `Release/`.** `Checked` is what this
+tree actually builds (optimised, with assertions); the `Release/` binary beside
+it is a stale August build with no `audit_61` probe in it. `strings` on the two
+is how that was found, and is how to check any binary before quoting a run from
+it.
+
+The `Checked` build carries all three instrumentations — `RE-INPUT`, `RE-DRAW`
+and the `audit_61` guest-PC branch probe (fork PR #2 brought the probe onto
+`sylpheed-re`; before it, the probe lived only on `phase-a-tracing`). Verified
+by `strings` on the binary, not assumed.
+
 **The `.pe` is a flat VA dump**: file offset = `VA - 0x82000000`. Reading
 `0x820A1630` is `seek(0xA1630)`. No XEX decrypt, no LZX, **no booted emulator** —
 dumping guest memory works but makes the whole static corpus depend on a running

docs/re/upstream-baseline.md

@@ -19,12 +19,13 @@ The instrumented branch stops at the Stage 02 briefing under a storm of
 behind `upstream/canary_experimental` (`a5a18f5c7`); our branch carries 50 of its
 own.
 
-* **`version.h` is never generated.** The build fails on
+* ~~**`version.h` is never generated.**~~ ✅ **FIXED — `CMakeLists.txt` now
-  `trace_writer.cc:17: fatal error: 'version.h' file not found`. Upstream's
+  generates it at configure time**, calling `xenia-build.py`'s
-  `xenia-build.py` writes it from git HEAD; the container's `build-canary`
+  `generate_version_h()` and falling back to a stub if that fails, so a
-  wrapper does not invoke it, and our tree only builds because a stale copy from
+  CMake-direct build no longer depends on a stale copy in the build directory.
-  an old `sylpheed-re` build sits in the build directory. Regenerated by hand in
+  It used to fail on `trace_writer.cc:17: fatal error: 'version.h' file not
-  exactly the format that script emits.
+  found`, and the fix had to exist before the 2026-09-18 cleanup deleted the
+  build volume that was carrying that stale copy.
 * **`build-canary` reports success on a failed build.** The harness recorded
   "completed (exit code 0)" while ninja had stopped with `1 error generated`.
   Only the missing binary gave it away.

tools/re/check-capture-citations

@@ -235,6 +235,21 @@ def main() -> int:
     print("  cited by a page or a tool : %d" % (len(files) - len(orphans)))
     print("  cited by nothing          : %d  (reported, not failed —" % len(orphans))
     print("                               an orphan may be evidence a page owes)")
+    # 🔴 A BARE CLONE HAS NO CAPTURES AT ALL, and that is not a defect.
+    # Since #49 the assets are never committed, so a fresh clone, a worktree or
+    # a CI checkout legitimately has none — and the naive check calls all 134
+    # citations dangling and exits 1. A gate that is red on every clean checkout
+    # is one people learn to ignore, which is how the last wrong-by-default
+    # check in this file cost a session. Distinguish "none here" from "this one
+    # is missing": with some assets present, a gap is real and still fails.
+    assets_here = sum(1 for f in files if f.lower().endswith(ASSET_SUFFIXES))
+    if assets_here == 0 and dangling:
+        print("  ⓘ no captures on this checkout: %d citations unresolved" % len(dangling))
+        print("     Expected — captures are local-only (#49) and a fresh clone has none.")
+        print("     Copy them in, or read the evidence on the issue it is attached to.")
+        print("  🔴 game assets TRACKED    : %d" % len(stowaways))
+        return 1 if stowaways else 0
+
     rc = 0
     if dangling:
         print("  🔴 cited but NOT present  : %d" % len(dangling))