fix(dispatch): gate slot forwards during swap window with structured 503

[thinmintdev]

Summary

Chat completions hitting a slot mid-swap (STARTING / WARMING) used
to return a raw 502 (port not yet bound) or 503 from
llama-server's still-loading gate — no Retry-After, no progress
context for the dashboard.

This PR adds a swap-window gate inside Dispatcher.forward: if the
target slot isn't in {READY, SERVING, IDLE}, raise a typed
SlotLoading error instead of forwarding to a port that may not be
bound or a model that may not be loaded. The error carries
retry_after_s plus a progress block (phase, requested_model,
upstream), and the error middleware now promotes retry_after_s to
a real Retry-After HTTP header on any 503 envelope so OpenAI-style
SDKs back off cleanly.

Production trace that prompted this (2026-05-28, primary swap):

02:50:26  POST /v1/chat/completions  502  dispatch.upstream_unavailable  (port 8001 dead)
02:51:24  POST /v1/chat/completions  503  (raw llama-server "still loading")
02:51:31  POST /v1/chat/completions  503  (same)
02:51:35  primary llama-server: listening on :8001
02:54:27  POST /v1/chat/completions  200  (back to normal)

After this PR, the 502/503 window returns:

HTTP/1.1 503 Service Unavailable
retry-after: 15
content-type: application/json

{"error":{"code":"slot.loading",
          "message":"slot 'primary' is starting — not ready to serve",
          "details":{"slot":"primary","state":"starting","retry_after_s":15,
                     "progress":{"phase":"starting",
                                 "requested_model":"qwen3-coder-...",
                                 "upstream":"primary"}}}}

Why this works for both audiences

• OpenAI SDKs see a textbook 503 + Retry-After: 15 and exponential-back-off-retry without help.
• The hal0 dashboard can render a "model loading…" chip from details.progress instead of a generic error toast.
• All /v1/* routes that go through the dispatcher (audio, embeddings, rerank, chat) get the gate for free — it lives at Dispatcher.forward, not in a route handler.

Files

• src/hal0/dispatcher/router.py — new SlotLoading(DispatchError) + Dispatcher._check_slot_ready_for_dispatch + _build_loading_response
• src/hal0/api/middleware/error_codes.py — promote details.retry_after_s to Retry-After header on 503 envelopes
• tests/dispatcher/test_serving_integration.py — 6 parametrized non-ready states + 3 ready states + remote-skip case
• tests/api/test_v1_audio.py — pin in-memory slot state to READY in the seed helpers (audio tests stub HTTP transport rather than starting a real slot)

Verification

• Unit tests: 1928/1928 pass, 3 skipped (pre-existing).
• LXC smoke (live):
  • OFFLINE slot + chat call → 503 slot.loading + Retry-After: 15 ✅
  • Mid-swap (state=starting) chat call → same envelope, phase=starting ✅
  • Post-swap chat call → 200 OK unchanged ✅
• CI gates: ruff check clean, ruff format --check clean.

Related

• Chat dispatcher ignores body model field — always routes to primary slot #377 — chat dispatcher always routes to legacy primary slot regardless of body model field. Orthogonal architectural issue, deferred. The swap-window gate doesn't touch routing — it only refuses to forward when the target slot is loading.

Test plan

• pytest tests/dispatcher/ tests/api/
• ruff check + ruff format --check
• LXC smoke: trigger primary swap, fire chat during load window, assert 503 + Retry-After + structured body
• LXC smoke: post-swap chat returns 200 unchanged