local-dev: stop spawned engine containers in down/clean

Backend's runtime spawns the engine container outside the compose
project, so `docker compose down` left a `galaxy-game-…` container
running. Add a `stop-engines` target that finds them by their OCI
image-title label (set in game/Dockerfile) and remove forcibly;
make `down` and `clean` depend on it. `clean` additionally wipes
the per-game state directory under /tmp/galaxy-game-state.

Add a troubleshooting note for the related symptom: when the
browser holds a keypair from a previous DB and `make clean`
recreates everything, the lobby renders "no games yet" until the
user clears site data or opens an incognito window. The dev user
keeps the same email but receives a fresh user_id, which the old
keypair cannot authenticate against.

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

tools/local-dev/Makefile

@@ -1,18 +1,23 @@
-.PHONY: help up down logs status rebuild clean psql logs-backend logs-gateway logs-mail build-engine wait
+.PHONY: help up down logs status rebuild clean psql logs-backend logs-gateway logs-mail build-engine stop-engines wait
 
 .DEFAULT_GOAL := help
 
 COMPOSE := docker compose
 REPO_ROOT := $(realpath $(CURDIR)/../..)
 ENGINE_IMAGE := galaxy-engine:local-dev
+# Label set by the engine `Dockerfile` runtime stage; used to find
+# engine containers spawned by backend's runtime that fall outside
+# `docker compose down`'s scope.
+ENGINE_LABEL := org.opencontainers.image.title=galaxy-game-engine
 
 help:
 	@echo "Local development stack for the Galaxy UI:"
 	@echo "  make up             Build (if needed) and bring up the stack, wait until healthy"
-	@echo "  make down           Stop containers, keep volumes"
+	@echo "  make down           Stop containers (incl. spawned engines), keep volumes"
 	@echo "  make rebuild        Force rebuild of backend / gateway images and bring up"
 	@echo "  make build-engine   Build the engine image $(ENGINE_IMAGE) used by the dev sandbox"
-	@echo "  make clean          Stop and wipe volumes (postgres data, game state)"
+	@echo "  make stop-engines   Stop and remove only the per-game engine containers"
+	@echo "  make clean          Stop and wipe volumes (postgres data, engines, game state)"
 	@echo "  make logs           Tail all logs"
 	@echo "  make logs-backend   Tail only the backend logs"
 	@echo "  make logs-gateway   Tail only the gateway logs"
@@ -42,11 +47,26 @@ build-engine:
 		docker build -t $(ENGINE_IMAGE) -f $(REPO_ROOT)/game/Dockerfile $(REPO_ROOT); \
 	fi
 
-down:
+down: stop-engines
 	$(COMPOSE) down
 
-clean:
+clean: stop-engines
 	$(COMPOSE) down -v
+	@if [ -d /tmp/galaxy-game-state ]; then \
+		echo "wiping /tmp/galaxy-game-state…"; \
+		docker run --rm -v /tmp/galaxy-game-state:/state alpine sh -c 'rm -rf /state/*' 2>/dev/null || rm -rf /tmp/galaxy-game-state/* 2>/dev/null || true; \
+	fi
+
+# Spawned engine containers run outside the compose project (the
+# backend's runtime creates them on demand), so `compose down` does
+# not see them. We discover them by the engine image's
+# OCI title label, set by game/Dockerfile.
+stop-engines:
+	@ids=$$(docker ps -aq --filter label=$(ENGINE_LABEL)); \
+	if [ -n "$$ids" ]; then \
+		echo "stopping engine containers…"; \
+		docker rm -f $$ids >/dev/null; \
+	fi
 
 logs:
 	$(COMPOSE) logs -f --tail=100

tools/local-dev/README.md

@@ -181,6 +181,19 @@ make status         docker compose ps
 
 ## Troubleshooting
 
+- **Lobby shows "no games yet" after `make clean && make up`** —
+  the browser still holds a keypair + device session bound to the
+  user_id from the previous DB. The new user has the same email
+  (`dev@local.test`) but a fresh user_id, so the old keypair
+  authenticates against a session row that no longer exists or
+  points at the wrong account. Open the page in an incognito
+  window, or wipe site data for `localhost:5173` (DevTools →
+  Application → Storage → Clear site data) and log in again.
+- **`make down` leaves a `galaxy-game-…` container behind** — fixed
+  in this Makefile: `make down` and `make clean` now stop spawned
+  engine containers via the `org.opencontainers.image.title=
+  galaxy-game-engine` label. To stop them by hand without touching
+  the rest of the stack, `make stop-engines`.
 - **`make up` reports a build error mentioning `pkg/cronutil`** —
   upstream module list drifted; copy any new `pkg/<name>/` line into
   the local-dev `backend.Dockerfile` / `gateway.Dockerfile` to match