From 01a3505b1e50ca1882388c12ad643feb09b22e2c Mon Sep 17 00:00:00 2001
From: MechaCat02 <fabian@diekaulbachs.de>
Date: Sat, 29 Aug 2026 12:52:13 +0200
Subject: [PATCH 1/4] containers: fix volume ownership and make the clone guard
 survive interruption

Two bugs, both mine, both found by starting the thing.

**Volume mount points must exist AND be owned by the agent before USER agent.**
Docker seeds a named volume from whatever the image has at that path, ownership
included, and creates a ROOT-OWNED directory when the path is absent. Either way
the agent cannot write, and the failure surfaced far from its cause: "clone
FAILED", with no permission error anywhere in sight. The port's own Dockerfile
already carried a comment explaining this trap, which I then walked into for
/work and /exchange.

**The clone guard checked for a .git directory, not a usable HEAD.** A clone
interrupted partway -- the container was removed while one ran -- leaves a .git
with no commits, and a presence check then skips the retry forever and hands the
agent an empty repository that looks like a checkout. It now verifies HEAD, and
clones via a temp directory so a partial result never lands in /work at all.

Also: the port launcher's path defaults still assumed the old repo root, so it
mounted no disc; and the stale /reborn notice is gone now that there is one
repository.

Verified running: both agents cloned 06676d3, `share` on PATH from /work/tools,
/exchange agent-owned, canary at /canary for the decoder, disc at /disc for the
port.
---
 docker/decoder/Dockerfile    |  4 ++--
 docker/decoder/entrypoint.sh | 19 +++++++++++++++----
 docker/decoder/sylph-decoder |  4 ++--
 docker/port/Dockerfile       |  4 ++--
 docker/port/entrypoint.sh    | 22 +++++++++++++++-------
 docker/port/sylph-port       |  9 ++++++---
 6 files changed, 42 insertions(+), 20 deletions(-)

diff --git a/docker/decoder/Dockerfile b/docker/decoder/Dockerfile
index 4480c4e8..0e4d3db2 100644
--- a/docker/decoder/Dockerfile
+++ b/docker/decoder/Dockerfile
@@ -92,8 +92,8 @@ RUN if getent passwd "${AGENT_UID}" >/dev/null; then \
     fi; \
     groupadd -g "${AGENT_GID}" agent \
     && useradd -m -u "${AGENT_UID}" -g "${AGENT_GID}" -s /bin/bash -d /sylph-home/re agent \
-    && mkdir -p /sylph-home/re /work \
-    && chown -R "${AGENT_UID}:${AGENT_GID}" /sylph-home \
+    && mkdir -p /sylph-home/re /work /exchange \
+    && chown -R "${AGENT_UID}:${AGENT_GID}" /sylph-home /work /exchange \
     && echo 'agent ALL=(ALL) NOPASSWD: ALL' > /etc/sudoers.d/agent
 
 COPY bin/ /usr/local/bin/
diff --git a/docker/decoder/entrypoint.sh b/docker/decoder/entrypoint.sh
index ef566023..e0b981d9 100755
--- a/docker/decoder/entrypoint.sh
+++ b/docker/decoder/entrypoint.sh
@@ -101,12 +101,23 @@ mkdir -p "$HOME/shots" "$HOME/logs"
 #
 # Cloned ONCE. Never auto-pulled: pulling under a running agent moves files out
 # from under whatever it is mid-edit, which is the same class of bug again.
-if [ ! -d /work/.git ]; then
+if ! git -C /work rev-parse --verify HEAD >/dev/null 2>&1; then
+  # Checks for a usable HEAD, not merely a .git directory. A clone interrupted
+  # partway -- the container stopped while it ran, which has happened -- leaves
+  # a .git with no commits, and a presence check would then skip the retry
+  # forever and hand the agent an empty repository.
   echo "[entrypoint] cloning ${SYLPH_REPO_URL:-https://git.mc02.dev/fabi/Sylpheed.git} into /work"
-  git clone --quiet "${SYLPH_REPO_URL:-https://git.mc02.dev/fabi/Sylpheed.git}" /work || {
-    echo "[entrypoint] clone FAILED -- the agent has no repository" >&2; }
+  _tmp=$(mktemp -d)
+  if git clone --quiet "${SYLPH_REPO_URL:-https://git.mc02.dev/fabi/Sylpheed.git}" "$_tmp/r"; then
+    find /work -mindepth 1 -maxdepth 1 -exec rm -rf {} + 2>/dev/null || true
+    mv "$_tmp/r"/.[!.]* "$_tmp/r"/* /work/ 2>/dev/null || true
+    echo "[entrypoint] /work at $(git -C /work rev-parse --short HEAD) on $(git -C /work rev-parse --abbrev-ref HEAD)"
+  else
+    echo "[entrypoint] clone FAILED -- the agent has no repository" >&2
+  fi
+  rm -rf "$_tmp"
 else
-  echo "[entrypoint] /work is at $(git -C /work rev-parse --short HEAD 2>/dev/null) on $(git -C /work rev-parse --abbrev-ref HEAD 2>/dev/null)"
+  echo "[entrypoint] /work at $(git -C /work rev-parse --short HEAD) on $(git -C /work rev-parse --abbrev-ref HEAD)"
 fi
 
 # The shared exchange, for transient files that must not enter git history.
diff --git a/docker/decoder/sylph-decoder b/docker/decoder/sylph-decoder
index a4b5ed6c..78c6c48a 100755
--- a/docker/decoder/sylph-decoder
+++ b/docker/decoder/sylph-decoder
@@ -234,9 +234,9 @@ case "${1:-}" in
     # wakeup cannot end the run. Set SYLPH_LOOP_INTERVAL= (empty) to self-pace.
     INTERVAL="${SYLPH_LOOP_INTERVAL-45m}"
     declare -a ARGS; docker_args ARGS
-    ARGS+=(-e SYLPH_AUTONOMOUS=1 -w "$PROJECT")
+    ARGS+=(-e SYLPH_AUTONOMOUS=1 -w /work)
     echo "==> loose  |  cpus=$CPUS  mem=${MEM_GB}g  shm=${SHM_GB}g"
-    echo "==> project: $PROJECT (mounted at its own path, so memory carries over)"
+    echo "==> repo:    own clone in volume sylpheed-decoder-repo -> /work"
     echo "==> pacing:  ${INTERVAL:-self-paced}"
     docker rm -f "$NAME" >/dev/null 2>&1 || true
     docker run -d -i -t "${ARGS[@]}" "$IMAGE" "/loop ${INTERVAL:+$INTERVAL }$TASK" >/dev/null
diff --git a/docker/port/Dockerfile b/docker/port/Dockerfile
index 4cce0756..a828d7aa 100644
--- a/docker/port/Dockerfile
+++ b/docker/port/Dockerfile
@@ -69,8 +69,8 @@ RUN if getent passwd "${AGENT_UID}" >/dev/null; then \
     fi; \
     groupadd -g "${AGENT_GID}" agent \
     && useradd -m -u "${AGENT_UID}" -g "${AGENT_GID}" -s /bin/bash -d /sylph-home/port agent \
-    && mkdir -p /sylph-home/port /work /reborn \
-    && chown -R "${AGENT_UID}:${AGENT_GID}" /sylph-home \
+    && mkdir -p /sylph-home/port /work /exchange /reborn \
+    && chown -R "${AGENT_UID}:${AGENT_GID}" /sylph-home /work /exchange \
     && echo 'agent ALL=(ALL) NOPASSWD: ALL' > /etc/sudoers.d/agent
 
 COPY bin/ /usr/local/bin/
diff --git a/docker/port/entrypoint.sh b/docker/port/entrypoint.sh
index 1bb97ffb..999ef4ed 100755
--- a/docker/port/entrypoint.sh
+++ b/docker/port/entrypoint.sh
@@ -20,9 +20,6 @@ if ! xdpyinfo -display "$DISPLAY" >/dev/null 2>&1; then
 fi
 echo "[entrypoint] display $DISPLAY ready ($SCREEN_GEOMETRY)"
 
-if [ -d /reborn ]; then
-  echo "[entrypoint] /reborn mounted read-only — HANDOFF.md is the contract"
-fi
 
 # Seed ~/.claude.json from the host's read-only copy, then stamp onboarding as
 # complete. Claude Code re-runs its first-run wizard whenever
@@ -54,12 +51,23 @@ chmod 600 "$HOME/.claude.json" 2>/dev/null || true
 #
 # Cloned ONCE. Never auto-pulled: pulling under a running agent moves files out
 # from under whatever it is mid-edit, which is the same class of bug again.
-if [ ! -d /work/.git ]; then
+if ! git -C /work rev-parse --verify HEAD >/dev/null 2>&1; then
+  # Checks for a usable HEAD, not merely a .git directory. A clone interrupted
+  # partway -- the container stopped while it ran, which has happened -- leaves
+  # a .git with no commits, and a presence check would then skip the retry
+  # forever and hand the agent an empty repository.
   echo "[entrypoint] cloning ${SYLPH_REPO_URL:-https://git.mc02.dev/fabi/Sylpheed.git} into /work"
-  git clone --quiet "${SYLPH_REPO_URL:-https://git.mc02.dev/fabi/Sylpheed.git}" /work || {
-    echo "[entrypoint] clone FAILED -- the agent has no repository" >&2; }
+  _tmp=$(mktemp -d)
+  if git clone --quiet "${SYLPH_REPO_URL:-https://git.mc02.dev/fabi/Sylpheed.git}" "$_tmp/r"; then
+    find /work -mindepth 1 -maxdepth 1 -exec rm -rf {} + 2>/dev/null || true
+    mv "$_tmp/r"/.[!.]* "$_tmp/r"/* /work/ 2>/dev/null || true
+    echo "[entrypoint] /work at $(git -C /work rev-parse --short HEAD) on $(git -C /work rev-parse --abbrev-ref HEAD)"
+  else
+    echo "[entrypoint] clone FAILED -- the agent has no repository" >&2
+  fi
+  rm -rf "$_tmp"
 else
-  echo "[entrypoint] /work is at $(git -C /work rev-parse --short HEAD 2>/dev/null) on $(git -C /work rev-parse --abbrev-ref HEAD 2>/dev/null)"
+  echo "[entrypoint] /work at $(git -C /work rev-parse --short HEAD) on $(git -C /work rev-parse --abbrev-ref HEAD)"
 fi
 
 # The shared exchange, for transient files that must not enter git history.
diff --git a/docker/port/sylph-port b/docker/port/sylph-port
index 04f28dd1..3a547df6 100755
--- a/docker/port/sylph-port
+++ b/docker/port/sylph-port
@@ -32,7 +32,10 @@ set -euo pipefail
 HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # The repo to mount at /work. Overridable so this script can be run from a
 # worktree -- a human editing on `main` must not repoint the agent's checkout.
-REPO="${SYLPH_PORT_REPO:-$(cd "$HERE/.." && pwd)}"
+# The checkout is now a volume the container clones into, so this is only used
+# to locate things that live BESIDE the repository -- the disc, chiefly. Three
+# levels up from docker/port/ is the workspace root.
+WORKSPACE="$(cd "$HERE/../../.." && pwd)"
 IMAGE="${SYLPH_PORT_IMAGE:-sylpheed-port:latest}"
 NAME="${SYLPH_PORT_NAME:-sylpheed-port}"
 
@@ -43,7 +46,7 @@ NAME="${SYLPH_PORT_NAME:-sylpheed-port}"
 CPUS="${SYLPH_PORT_CPUS:-3}"
 MEM_GB="${SYLPH_PORT_MEM_GB:-4}"
 
-DISC="${SYLPH_DISC:-$(cd "$REPO/../sylph_extract" 2>/dev/null && pwd || true)}"
+DISC="${SYLPH_DISC:-$(cd "$WORKSPACE/sylph_extract" 2>/dev/null && pwd || true)}"
 
 docker_args() {
   local _out=(
@@ -135,7 +138,7 @@ case "${1:-}" in
     # wake-up silently ends the loop.
     INTERVAL="${SYLPH_LOOP_INTERVAL-45m}"
     echo "==> loose  |  cpus=$CPUS  mem=${MEM_GB}g  pacing=${INTERVAL:-self}"
-    echo "==> repo:   $REPO"
+    echo "==> repo:   own clone in volume sylpheed-port-repo -> /work"
     docker run -d -i -t "${ARGS[@]}" -e SYLPH_AUTONOMOUS=1 -w /work "$IMAGE" \
       "/loop ${INTERVAL:+$INTERVAL }$TASK" >/dev/null
     echo

From 20b3c74b2c5540cb9522e23db79cd68fee55aeb8 Mon Sep 17 00:00:00 2001
From: MechaCat02 <fabian@diekaulbachs.de>
Date: Sat, 29 Aug 2026 13:05:41 +0200
Subject: [PATCH 2/4] agents: they never spoke, the decoder lost the disc, and
 both shared one state dir

Three defects, all mine, found by checking instead of assuming.

**They never exchanged a word.** SendMessage=0, ListAgents=0 across both new
sessions. PROTOCOL.md specified in detail what a message MAY and MAY NOT do and
never said how to send one or that the other agent was addressable -- they knew
that last time only because the human told them directly, and rebuilding with
fresh volumes wiped it. Policy without mechanism is prose. Now documented with
the two addresses, a worked example, and an instruction to introduce themselves
on the first iteration rather than waiting to have a question.

**The decoder lost the disc and the ISO.** They used to arrive inside the project
mount and silently stopped when /work became a clone. Silently is the word: the
disc-gated tests SELF-SKIP without SYLPHEED_DISC and report green, so a whole
test suite would have passed while measuring nothing. Both are now mounted
explicitly, the ISO at a stable path so run-canary does not depend on host
directory names.

**Both agents shared one Claude state directory.** They share the host's
~/.claude, and once both working directories became /work they resolved to the
same projects/-work/ -- two supposedly independent agents writing to one place,
which undoes the point of separate checkouts. Each now has its own volume, seeded
once from the host with credentials only, so a token refresh writes locally and
neither can corrupt the host's auth.

Also widened the pacing rule. It banned ScheduleWakeup by name; the decoder then
scheduled itself an hourly cron job -- not harmful, but the same instinct that
ended a run yesterday, through a door I had left open. Now: no self-scheduling by
any route.

Mount audit after the changes: shared and intentional are the exchange volume and
the read-only credential seed. Everything else -- repo, Claude state, cargo,
target, canary, disc, ISO -- is per agent or one-sided.
---
 docker/decoder/entrypoint.sh | 18 ++++++++++++++++++
 docker/decoder/sylph-decoder | 19 +++++++++++++++++--
 docker/port/entrypoint.sh    | 18 ++++++++++++++++++
 docker/port/sylph-port       |  3 ++-
 docs/agents/PROTOCOL.md      | 36 +++++++++++++++++++++++++++++++++---
 docs/agents/decoder-loop.md  | 11 +++++++++++
 docs/agents/port-loop.md     | 11 +++++++++++
 7 files changed, 110 insertions(+), 6 deletions(-)

diff --git a/docker/decoder/entrypoint.sh b/docker/decoder/entrypoint.sh
index e0b981d9..f14b94de 100755
--- a/docker/decoder/entrypoint.sh
+++ b/docker/decoder/entrypoint.sh
@@ -124,6 +124,24 @@ fi
 mkdir -p /exchange/files 2>/dev/null || true
 
 # ── Claude Code config ───────────────────────────────────────────────────────
+# ── Claude state: this agent's own, seeded once from the host ───────────────
+# Isolated per agent. Both working directories are /work, and Claude Code keys
+# its per-project state off the working directory -- so a SHARED ~/.claude put
+# two independent agents in the same projects/-work/ directory, which undoes the
+# point of giving them separate checkouts.
+#
+# Seeded rather than shared because credentials live in .credentials.json and a
+# token refresh must be able to write. Copying once means each agent refreshes
+# its own token and neither can corrupt the host's.
+if [ -d "$HOME/.claude.seed" ] && [ ! -s "$HOME/.claude/.credentials.json" ]; then
+  mkdir -p "$HOME/.claude"
+  cp -a "$HOME/.claude.seed/.credentials.json" "$HOME/.claude/" 2>/dev/null || true
+  for f in settings.json CLAUDE.md; do
+    [ -e "$HOME/.claude.seed/$f" ] && cp -a "$HOME/.claude.seed/$f" "$HOME/.claude/" 2>/dev/null || true
+  done
+  echo "[entrypoint] seeded ~/.claude from the host (credentials only)"
+fi
+
 # Seed ~/.claude.json from the host's read-only copy, then stamp onboarding as
 # complete. Claude Code re-runs its first-run wizard whenever
 # lastOnboardingVersion differs from the installed version — so a container with
diff --git a/docker/decoder/sylph-decoder b/docker/decoder/sylph-decoder
index 78c6c48a..655690e4 100755
--- a/docker/decoder/sylph-decoder
+++ b/docker/decoder/sylph-decoder
@@ -104,6 +104,12 @@ docker_args() {
     # and carries our instrumentation. Read-write: building probes into it is
     # real work, not a side effect.
     -v "${SYLPH_CANARY:-$HOME/RE Project Sylpheed/xenia-canary}:/canary"
+    # The disc and the ISO. These used to arrive inside the project mount and
+    # silently stopped when /work became a clone -- silently because the
+    # disc-gated tests SELF-SKIP without SYLPHEED_DISC and report green, which
+    # is the most expensive kind of missing mount.
+    -v "${SYLPH_DISC:-$PROJECT/sylph_extract}:/disc:ro"
+    -e "SYLPHEED_DISC=/disc"
     # The shared exchange: transient files with provenance, outside git history.
     -v "sylpheed-exchange:/exchange"
     -e "PROJECT_DIR=/work"
@@ -115,7 +121,8 @@ docker_args() {
     # The state dir is shared read-write: credentials live in
     # .claude/.credentials.json, so token refresh needs to write, and this is
     # also what carries the project memory across.
-    -v "${SYLPH_CLAUDE_HOME:-$HOME/.claude}:/sylph-home/re/.claude"
+    -v "sylpheed-decoder-claude:/sylph-home/re/.claude"
+    -v "${SYLPH_CLAUDE_HOME:-$HOME/.claude}:/sylph-home/re/.claude.seed:ro"
     # ~/.claude.json sits BESIDE that directory and holds `hasCompletedOnboarding`.
     # Mounted READ-ONLY at a staging path: the entrypoint copies it to
     # ~/.claude.json and stamps onboarding as done. Sharing the file directly
@@ -165,7 +172,15 @@ docker_args() {
   [ -n "${SYLPH_VULKAN:-}" ]      && _out+=(-e "SYLPH_VULKAN=$SYLPH_VULKAN")
   [ -n "${SYLPH_REMOTE:-}" ]      && _out+=(-e "SYLPH_REMOTE=$SYLPH_REMOTE")
   [ -n "${SYLPH_REMOTE_NAME:-}" ] && _out+=(-e "SYLPH_REMOTE_NAME=$SYLPH_REMOTE_NAME")
-  [ -n "${SYLPH_ISO:-}" ]         && _out+=(-e "SYLPH_ISO=$SYLPH_ISO")
+  # The ISO Canary boots. Default resolves the retail image beside the project;
+  # mounted at a stable in-container path so run-canary does not depend on the
+  # host's directory names.
+  _iso="${SYLPH_ISO:-$PROJECT/Project Sylpheed - Arc of Deception (USA, Europe) (En,Ja).iso}"
+  if [ -f "$_iso" ]; then
+    _out+=(-v "$_iso:/iso/game.iso:ro" -e "SYLPH_ISO=/iso/game.iso")
+  else
+    echo "==> NOTE: no ISO at $_iso -- Canary has nothing to boot." >&2
+  fi
 
   # ── GPU ──
   # Three distinct cases, and conflating them is how you end up believing you
diff --git a/docker/port/entrypoint.sh b/docker/port/entrypoint.sh
index 999ef4ed..0cd71feb 100755
--- a/docker/port/entrypoint.sh
+++ b/docker/port/entrypoint.sh
@@ -21,6 +21,24 @@ fi
 echo "[entrypoint] display $DISPLAY ready ($SCREEN_GEOMETRY)"
 
 
+# ── Claude state: this agent's own, seeded once from the host ───────────────
+# Isolated per agent. Both working directories are /work, and Claude Code keys
+# its per-project state off the working directory -- so a SHARED ~/.claude put
+# two independent agents in the same projects/-work/ directory, which undoes the
+# point of giving them separate checkouts.
+#
+# Seeded rather than shared because credentials live in .credentials.json and a
+# token refresh must be able to write. Copying once means each agent refreshes
+# its own token and neither can corrupt the host's.
+if [ -d "$HOME/.claude.seed" ] && [ ! -s "$HOME/.claude/.credentials.json" ]; then
+  mkdir -p "$HOME/.claude"
+  cp -a "$HOME/.claude.seed/.credentials.json" "$HOME/.claude/" 2>/dev/null || true
+  for f in settings.json CLAUDE.md; do
+    [ -e "$HOME/.claude.seed/$f" ] && cp -a "$HOME/.claude.seed/$f" "$HOME/.claude/" 2>/dev/null || true
+  done
+  echo "[entrypoint] seeded ~/.claude from the host (credentials only)"
+fi
+
 # Seed ~/.claude.json from the host's read-only copy, then stamp onboarding as
 # complete. Claude Code re-runs its first-run wizard whenever
 # lastOnboardingVersion differs from the installed version, so a container with a
diff --git a/docker/port/sylph-port b/docker/port/sylph-port
index 3a547df6..8cbca2d7 100755
--- a/docker/port/sylph-port
+++ b/docker/port/sylph-port
@@ -62,7 +62,8 @@ docker_args() {
     # CARGO_HOME on a volume, not the container overlay: without it the pinned
     # decoder source is re-fetched from the network on every fresh container.
     -v "sylpheed-port-cargo:/sylph-home/port/.cargo"
-    -v "${SYLPH_CLAUDE_HOME:-$HOME/.claude}:/sylph-home/port/.claude"
+    -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"
     -v "sylpheed-exchange:/exchange"
     -e "PROJECT_DIR=/work"
diff --git a/docs/agents/PROTOCOL.md b/docs/agents/PROTOCOL.md
index 060fbf2c..92cc2052 100644
--- a/docs/agents/PROTOCOL.md
+++ b/docs/agents/PROTOCOL.md
@@ -40,6 +40,33 @@ exists to catch, and it is why the Referee will not be allowed to interpret.
 
 Agents talk directly. Traffic is **pointers and priorities**, not content.
 
+### How, concretely
+
+This section exists because the first version of this page specified the policy
+and forgot the mechanism, and two agents then ran for hours without exchanging a
+word — each knowing exactly what a message *may* contain and not that the other
+was addressable.
+
+```
+ListAgents                      # who is reachable
+SendMessage(to: "sylpheed-agent", message: "...")    # the Decoder
+SendMessage(to: "sylpheed-port",  message: "...")    # the Port
+```
+
+Both register under those names at startup. **Introduce yourself on your first
+iteration** — say which role you are, which branch you are on, and what you are
+working toward. Do not wait to have a question.
+
+A good message is short and carries a locator:
+
+> Q1 (keyframe time) is my critical path — P2 is stalled on it. When you have
+> it, the answer I need is the unit and whether the ramp is eased. My branch is
+> `auto/port-p5-menu-navigation` at `06676d3` if you want to see what is
+> waiting on it.
+
+A bad one carries the finding instead of a pointer, because that finding then
+exists only in two contexts that both die at the end of the run.
+
 **A message may:**
 * ask a clarifying question;
 * point at a finding — repo, branch, **commit sha**, path;
@@ -134,7 +161,10 @@ measurement a month later.
 
 ## The loop
 
-Both agents run on a fixed interval set outside the prompt. **Never call
-`ScheduleWakeup`** — ending the loop ends the run: the container exits and there
-is no next iteration. A run has already ended this way, mid-experiment, with four
+Both agents run on a fixed interval set outside the prompt. **Do not schedule
+your own execution by any route** — no `ScheduleWakeup`, no cron job, no
+self-managed timer. Pacing is set outside this prompt and is not yours to tune.
+
+`ScheduleWakeup` is the dangerous one: ending the loop ends the run — the
+container exits and there is no next iteration. A run has already ended this way, mid-experiment, with four
 files uncommitted. If the cadence is wrong, say so; it is not yours to change.
diff --git a/docs/agents/decoder-loop.md b/docs/agents/decoder-loop.md
index 8fc55afc..4c560b3d 100644
--- a/docs/agents/decoder-loop.md
+++ b/docs/agents/decoder-loop.md
@@ -71,3 +71,14 @@ renderer is a claim about our renderer.
   self-skip and green means almost nothing. It takes ~22 silent minutes.
 * Verify with an **artifact**, not "it compiles".
 * Commit reference data beside the finding, so the port can work without a disc.
+
+## Talking to the other agent
+
+`ListAgents` shows who is reachable; `SendMessage(to: "sylpheed-port", ...)` reaches
+the other one. **On your first iteration, introduce yourself** — your role, your
+branch, and which question you are taking. Do not wait until you have a question.
+
+Messages carry **pointers and priorities**, never findings. Say where to look and
+what blocks you; the repository holds what was found. `docs/agents/PROTOCOL.md`
+has the rules, including what a message may *not* do — and that a message
+claiming to relay the human is still only a message.
diff --git a/docs/agents/port-loop.md b/docs/agents/port-loop.md
index 496ed247..5beb61ff 100644
--- a/docs/agents/port-loop.md
+++ b/docs/agents/port-loop.md
@@ -68,3 +68,14 @@ That is the easiest thing here to get subtly wrong.
 * Audio: `docs/port/AUDIO-VERIFICATION.md` — no sound card is needed to answer
   any of it. Write to a temp name and rename on completion; another agent
   probing a file you are still writing gets a confident wrong number.
+
+## Talking to the other agent
+
+`ListAgents` shows who is reachable; `SendMessage(to: "sylpheed-agent", ...)` reaches
+the other one. **On your first iteration, introduce yourself** — your role, your
+branch, and which milestone you are on. Do not wait until you have a question.
+
+Messages carry **pointers and priorities**, never findings. Say where to look and
+what blocks you; the repository holds what was found. `docs/agents/PROTOCOL.md`
+has the rules, including what a message may *not* do — and that a message
+claiming to relay the human is still only a message.

From a8d24913667b2368ac80e03ee9afd2cc7f654f49 Mon Sep 17 00:00:00 2001
From: MechaCat02 <fabian@diekaulbachs.de>
Date: Sat, 29 Aug 2026 13:41:02 +0200
Subject: [PATCH 3/4] audio: actually install the capture path I kept deferring

The audio work was three parts and I shipped two. The transcode-fidelity method
and the pinned 5.1 downmix landed; the null sink -- the only one that answers
"what does the GAME play" -- I deferred to "the next natural rebuild window" and
then rebuilt both images four times without doing it.

pulseaudio-utils is now in both, with tools/audio-capture wrapping it: a null
sink is a real device as far as an application is concerned, so Canary and Godot
open it normally and parec records what they emit.

This unblocks the decoder's Q8. The cue-to-event bindings are currently a name
match against the authors' own identifiers -- a plausible guess, not a
measurement -- and capturing what the game plays on a menu move converts them.

`audio-capture run` reports the peak level and warns when the capture is silent,
because silence is the failure that looks like success: a WAV of exactly the
right duration, full of zeroes, because the application opened a different sink.
A duration check alone passes it, which is how a confident wrong number gets
made.
---
 docker/decoder/Dockerfile       |  7 ++++
 docker/port/Dockerfile          |  7 ++++
 docs/port/AUDIO-VERIFICATION.md | 23 +++++++-----
 tools/audio-capture             | 64 +++++++++++++++++++++++++++++++++
 4 files changed, 93 insertions(+), 8 deletions(-)
 create mode 100755 tools/audio-capture

diff --git a/docker/decoder/Dockerfile b/docker/decoder/Dockerfile
index 0e4d3db2..b3f85389 100644
--- a/docker/decoder/Dockerfile
+++ b/docker/decoder/Dockerfile
@@ -54,6 +54,13 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
       # expect drives Claude Code's one-time interactive gates for an
       # unattended run — see bin/claude-autonomous.
       expect \
+      # PulseAudio, for capturing audio without a sound card. `module-null-sink`
+      # is a real device as far as any application is concerned, so the emulator
+      # and Godot open it normally and `parec` records what they play. Without
+      # it, "does this actually sound right" is unanswerable in a container --
+      # and the cue-to-event bindings stay a name match rather than a
+      # measurement. See docs/port/AUDIO-VERIFICATION.md.
+      pulseaudio pulseaudio-utils \
     && rm -rf /var/lib/apt/lists/*
 
 # Pin the unversioned tool names to 19 so CMake, and anything that shells out to
diff --git a/docker/port/Dockerfile b/docker/port/Dockerfile
index a828d7aa..e0893494 100644
--- a/docker/port/Dockerfile
+++ b/docker/port/Dockerfile
@@ -32,6 +32,13 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
       python3 jq ripgrep unzip file less nano tini sudo procps \
       # expect drives Claude Code's one-time interactive gates
       expect \
+      # PulseAudio, for capturing audio without a sound card. `module-null-sink`
+      # is a real device as far as any application is concerned, so the emulator
+      # and Godot open it normally and `parec` records what they play. Without
+      # it, "does this actually sound right" is unanswerable in a container --
+      # and the cue-to-event bindings stay a name match rather than a
+      # measurement. See docs/port/AUDIO-VERIFICATION.md.
+      pulseaudio pulseaudio-utils \
     && rm -rf /var/lib/apt/lists/*
 
 # ── Godot 4 ──────────────────────────────────────────────────────────────────
diff --git a/docs/port/AUDIO-VERIFICATION.md b/docs/port/AUDIO-VERIFICATION.md
index 41c80c90..6ca19b4d 100644
--- a/docs/port/AUDIO-VERIFICATION.md
+++ b/docs/port/AUDIO-VERIFICATION.md
@@ -89,18 +89,25 @@ under a dummy driver" is a weaker claim than "heard", and the difference matters
 ## 3. A virtual device, when something insists on a real one
 
 For anything that opens a device rather than a bus — the emulator, most
-obviously — a PulseAudio **null sink** is a real device that records to a file:
+obviously — a PulseAudio **null sink** is a real device that records to a file.
+`pulseaudio-utils` is in both images, and `audio-capture` wraps it:
 
 ```bash
-pactl load-module module-null-sink sink_name=cap sink_properties=device.description=cap
-PULSE_SINK=cap <the application>
-parec -d cap.monitor --file-format=wav /tmp/captured.wav
+audio-capture run /tmp/menu.wav -- run-canary        # start sink, run, record
+audio-capture start                                  # or drive it by hand
+PULSE_SINK=cap godot --path port
+audio-capture record /tmp/out.wav &
 ```
 
-This is the route to capturing what the *game* plays — the menu move and confirm
-cues behind HANDOFF Q8 — rather than what we think it should play. It needs
-`pulseaudio-utils` in the image, so it is a rebuild, not something to reach for
-mid-iteration.
+This is the route to capturing what the **game** plays — the menu move and
+confirm cues behind HANDOFF Q8 — rather than what we believe it should play.
+Those bindings are currently a name match against the authors' own identifiers;
+a capture turns them into a measurement.
+
+⚠️ `audio-capture run` reports the peak level and **warns when the result is
+silent**, because silence is the failure that looks like success: a WAV of
+exactly the right duration, full of zeroes, because the application opened a
+different sink. A duration check alone would pass it.
 
 ## What none of this establishes
 
diff --git a/tools/audio-capture b/tools/audio-capture
new file mode 100755
index 00000000..1db19f04
--- /dev/null
+++ b/tools/audio-capture
@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+# Record what an application plays, with no sound card present.
+#
+#   audio-capture start                 bring up a null sink named `cap`
+#   audio-capture record OUT.wav &      record from it until killed
+#   audio-capture run OUT.wav -- CMD…   start, run CMD, stop, leave OUT.wav
+#
+# A null sink is a real device as far as the application is concerned: the
+# emulator and Godot open it exactly as they would hardware, and its monitor
+# source is what `parec` reads. This is the difference between "the file decodes"
+# and "the game played this" -- the second is a measurement, the first is not.
+#
+# Nothing here says the audio SOUNDS right; it says what was emitted. A human
+# listening still answers something none of this does.
+set -euo pipefail
+
+SINK="${SYLPH_SINK:-cap}"
+
+ensure_daemon() {
+  pulseaudio --check 2>/dev/null || pulseaudio --start --exit-idle-time=-1 2>/dev/null || true
+  for _ in $(seq 30); do pactl info >/dev/null 2>&1 && return 0; sleep 0.2; done
+  echo "audio-capture: no PulseAudio daemon" >&2; return 1
+}
+
+case "${1:-}" in
+  start)
+    ensure_daemon
+    pactl list short sinks | grep -q "^[0-9]*[[:space:]]*$SINK[[:space:]]" \
+      || pactl load-module module-null-sink sink_name="$SINK" \
+           sink_properties=device.description="$SINK" >/dev/null
+    pactl set-default-sink "$SINK"
+    echo "audio-capture: sink '$SINK' ready; point apps at it with PULSE_SINK=$SINK"
+    ;;
+  record)
+    out="${2:?usage: audio-capture record OUT.wav}"
+    ensure_daemon
+    exec parec -d "${SINK}.monitor" --file-format=wav "$out"
+    ;;
+  run)
+    out="${2:?usage: audio-capture run OUT.wav -- COMMAND...}"; shift 2
+    [ "${1:-}" = "--" ] && shift
+    "$0" start
+    parec -d "${SINK}.monitor" --file-format=wav "$out" & rec=$!
+    # Kill the recorder on any exit path, or a failed run leaves it holding the
+    # monitor and the next capture silently records nothing.
+    trap 'kill "$rec" 2>/dev/null || true' EXIT
+    PULSE_SINK="$SINK" "$@" || true
+    sleep 1; kill "$rec" 2>/dev/null || true; wait "$rec" 2>/dev/null || true
+    trap - EXIT
+    if [ -s "$out" ]; then
+      dur=$(ffprobe -v error -show_entries format=duration -of csv=p=0 "$out" 2>/dev/null || echo "?")
+      echo "audio-capture: $out (${dur}s)"
+      # Silence is the failure that looks like success: a WAV of the right
+      # length, full of zeroes, because the app opened a different sink.
+      peak=$(ffmpeg -hide_banner -i "$out" -af astats=measure_perchannel=none -f null - 2>&1 \
+               | grep -m1 "Peak level" || true)
+      echo "            ${peak:-no level measured}"
+      case "$peak" in *"-inf"*) echo "            WARNING: silent -- did the app use this sink?" ;; esac
+    else
+      echo "audio-capture: nothing recorded" >&2; exit 1
+    fi
+    ;;
+  *) sed -n '2,12p' "$0" | sed 's/^# \{0,1\}//' ;;
+esac

From 2021eee47d48057fabd4d0dc0ce2a365ff79805d Mon Sep 17 00:00:00 2001
From: MechaCat02 <fabian@diekaulbachs.de>
Date: Sat, 29 Aug 2026 13:53:00 +0200
Subject: [PATCH 4/4] agents: merge main at the start of every iteration

Both agents read the protocol, their mission and the shared tooling from their
OWN checkout, and both work on topic branches -- so without an explicit sync
they follow whichever version of the rules existed when the branch started.

Found concretely: tools/audio-capture and two protocol revisions were on main
while the decoder worked for hours from a branch that had neither. The port had
merged on its own initiative and did have them, which is exactly the kind of
divergence nobody notices until the two disagree about what the rules say.
---
 docs/agents/decoder-loop.md | 14 ++++++++++++++
 docs/agents/port-loop.md    | 14 ++++++++++++++
 2 files changed, 28 insertions(+)

diff --git a/docs/agents/decoder-loop.md b/docs/agents/decoder-loop.md
index 4c560b3d..06a95213 100644
--- a/docs/agents/decoder-loop.md
+++ b/docs/agents/decoder-loop.md
@@ -13,6 +13,20 @@ behavioural and cannot be answered from a file, so you run the emulator.
 You do **not** build the port. If you find yourself writing GDScript or designing
 an export schema, stop and go back to the question you were answering.
 
+## Before anything else, every iteration: sync with `main`
+
+```bash
+git -C /work fetch origin && git -C /work merge --no-edit origin/main
+```
+
+You work on a topic branch, and you read the protocol, the mission and the
+shared tooling **from your own checkout** — so without this you are following
+whichever version of the rules existed when your branch started. That is not
+hypothetical: `tools/audio-capture` and two protocol revisions landed on `main`
+while one agent worked for hours from a branch that had neither.
+
+If the merge conflicts, resolve it, say so in your reply, and carry on.
+
 ## Read these first, every iteration
 
 1. `docs/agents/PROTOCOL.md` — how this team works. Non-negotiable.
diff --git a/docs/agents/port-loop.md b/docs/agents/port-loop.md
index 5beb61ff..419de7fb 100644
--- a/docs/agents/port-loop.md
+++ b/docs/agents/port-loop.md
@@ -9,6 +9,20 @@ You own **the disc → playable**: `crates/sylpheed-export`, `port/`, the asset
 tree. You do **not** reverse engineer. You have no emulator and no oracle, so a
 guess of yours is indistinguishable from a fact and will be believed later.
 
+## Before anything else, every iteration: sync with `main`
+
+```bash
+git -C /work fetch origin && git -C /work merge --no-edit origin/main
+```
+
+You work on a topic branch, and you read the protocol, the mission and the
+shared tooling **from your own checkout** — so without this you are following
+whichever version of the rules existed when your branch started. That is not
+hypothetical: `tools/audio-capture` and two protocol revisions landed on `main`
+while one agent worked for hours from a branch that had neither.
+
+If the merge conflicts, resolve it, say so in your reply, and carry on.
+
 ## Read these first, every iteration
 
 1. `docs/agents/PROTOCOL.md` — how this team works. Non-negotiable.