From 20b3c74b2c5540cb9522e23db79cd68fee55aeb8 Mon Sep 17 00:00:00 2001 From: MechaCat02 Date: Sat, 29 Aug 2026 13:05:41 +0200 Subject: [PATCH] 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.