local-dev: prune broken engines on rebuild + document one-time bake

`make rebuild` runs `compose build --no-cache backend gateway` plus
a fresh `up -d --wait`. It must therefore also reap any engine
container whose bind-mount source went away during host downtime,
otherwise the new backend image boots into a stack with the same
orphan that triggered the heal flow in the first place.

Also extend the troubleshooting note: pulling the heal-cycle fix
requires one explicit `make rebuild` so the backend image picks up
the pre-bootstrap reconciler tick. Without that, `make up` runs
the new Makefile target but the legacy backend cannot follow
through, and the developer is left staring at a `cancelled`
sandbox with no running replacement.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Ilia Denisov
2026-05-10 22:40:27 +02:00
parent edc9709bd6
commit ff53cc0ad3
2 changed files with 14 additions and 1 deletions
+1 -1
View File
@@ -36,7 +36,7 @@ help:
up: build-engine prune-broken-engines up: build-engine prune-broken-engines
$(COMPOSE) up -d --wait $(COMPOSE) up -d --wait
rebuild: build-engine rebuild: build-engine prune-broken-engines
$(COMPOSE) build --no-cache backend gateway $(COMPOSE) build --no-cache backend gateway
$(COMPOSE) up -d --wait $(COMPOSE) up -d --wait
+13
View File
@@ -239,6 +239,19 @@ make status docker compose ps
the cancelled tile and provisions a fresh sandbox with a brand the cancelled tile and provisions a fresh sandbox with a brand
new state directory. To run the cleanup by hand without restarting new state directory. To run the cleanup by hand without restarting
the rest of the stack, `make prune-broken-engines`. the rest of the stack, `make prune-broken-engines`.
The cycle relies on the backend image carrying the pre-bootstrap
reconciler tick (`backend/cmd/backend/main.go`). `make up` reuses
the cached image, so after pulling this commit the first time you
must `make rebuild` once to bake the fix in. Future `make up`
cycles will heal in one shot.
If after the heal cycle the lobby still shows only a `cancelled`
sandbox tile and no running game, the running backend image
predates the pre-bootstrap reconciler tick — the periodic ticker
cancels the orphan after bootstrap has already returned, leaving
the lobby in the half-baked state. `make rebuild` recreates the
image and then `make up` lands a fresh sandbox.
- **`make up` reports a build error mentioning `pkg/cronutil`** — - **`make up` reports a build error mentioning `pkg/cronutil`** —
upstream module list drifted; copy any new `pkg/<name>/` line into upstream module list drifted; copy any new `pkg/<name>/` line into
the local-dev `backend.Dockerfile` / `gateway.Dockerfile` to match the local-dev `backend.Dockerfile` / `gateway.Dockerfile` to match