.gitea/workflows/cicd-tests.yaml

@@ -410,6 +410,13 @@ jobs:
 
             backend_ready=false
             for i in $(seq 1 40); do
+              backend_running="$(docker inspect -f '{{.State.Running}}' "${BACKEND_CONTAINER}" 2>/dev/null || echo false)"
+              if [ "${backend_running}" != "true" ]; then
+                echo "❌ Backend container exited before becoming healthy"
+                dump_failure_context
+                exit 1
+              fi
+
               health_code="$(curl -sS -o /tmp/blackbox-health.json -w "%{http_code}" "http://127.0.0.1:18000/health" || true)"
               if [ "${health_code}" = "200" ]; then
                 backend_ready=true

Dockerfile.backend

@@ -34,4 +34,4 @@ COPY backend/ .
 EXPOSE 8000
 
 # Default command - can be overridden in compose for development
-CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]
+CMD ["uvicorn", "backend.main:app", "--host", "0.0.0.0", "--port", "8000"]

compose.dev.yml

@@ -22,7 +22,7 @@ services:
       - "8001:8000"
     command:
       - "uvicorn"
-      - "main:app"
+      - "backend.main:app"
       - "--host"
       - "0.0.0.0"
       - "--port"

docs/DEPLOYABLE_RUNTIME_CONTRACT.md

@@ -31,7 +31,7 @@ Excluded:
 
 - Container build source: `Dockerfile.backend`.
 - Runtime base image: `python:3.14-slim`.
-- Runtime process: `uvicorn main:app --host 0.0.0.0 --port 8000`.
+- Runtime process: `uvicorn backend.main:app --host 0.0.0.0 --port 8000`.
 - Exposed runtime port: `8000`.
 
 ### Required Runtime Dependencies
@@ -68,7 +68,7 @@ The lockfile in `backend/uv.lock` is the dependency source of truth.
 ### Backend Runtime Checklist
 
 - [ ] Runtime image built from `Dockerfile.backend`.
-- [ ] Runtime process is uvicorn serving `main:app` on `0.0.0.0:8000`.
+- [ ] Runtime process is uvicorn serving `backend.main:app` on `0.0.0.0:8000`.
 - [ ] `DATABASE_URL` is set in deployment runtime.
 - [ ] `GET /health` behavior matches contract.
 - [ ] Startup fails on runtime policy mismatch.