chore(sync): mirror backend .py + Dockerfile to Space (hf-sync-backend)

Automated backend sync from szl-holdings/a11oy main via hf-sync-backend.
Updated (differed from the Space): Dockerfile, szl_spaces_proxy.py, szl_spaces_surface.py
Deleted (gone from the repo + Dockerfile COPY set): (none)

Keeps the Space-built backend (serve.py + the Dockerfile-COPY'd .py
modules) identical to GitHub main so the Space never rebuilds from a
stale backend, new endpoints don't 404 there, and orphaned modules
removed from the repo don't linger in the Space tree.

Dockerfile

@@ -142,6 +142,10 @@ COPY knowledge.json ./static/knowledge.json
 # Signed-off-by: Yachay <yachay@szlholdings.ai>
 # ---------------------------------------------------------------------------
 COPY knowledge.json szl_parity_gaps.py a11oy_warhacker_obs.py serve.py a11oy_wireA_metrics.py cathedral.html a11oy_operator_organ.py a11oy_hf_assets.py szl_b2_secdata.py gates_manifest.json a11oy_code_orchestrator.py a11oy_agent_loop.py a11oy_org_rag.py a11oy_mcp_client.py szl_rag.py a11oy_code_ide.html wayra_serve.py wayra_snapshot.json wayra_digests_7d.json szl_khipu_os_routes.py ./
+# Spaces-on-a11oy.net shared modules (Dev2+3) — reverse-proxy + console surface.
+# Per-file COPY (this Dockerfile uses no `COPY . .`) or serve.py's guarded import
+# falls back and /spaces + /api/<ns>/v1/spaces/health 404. Byte-identical a11oy+killinchu.
+COPY szl_spaces_proxy.py szl_spaces_surface.py ./
 COPY szl_khipu_consensus.py szl_puriq_formulas.py ayni_os_serve.py szl_live_wires.py live_wires.html live_wires_3d.js szl_dsse.py szl_provenance.py szl_be_hardening.py szl_unay.py szl_khipu_lmdb.py szl_khipu_replicate.py szl_unay_routes.py szl_warhacker_aliases.py a11oy_v4_hickok.py szl_khipu.py szl_formulas.py a11oy_v4_formulas.py szl_anatomy_3d.py szl_anatomy_routes.py ./
 COPY _vendor_blobs.py szl_v4_fleet.py operator_shell_v4.py szl_bridge.py szl_bridge_schemas.py agent.html a11oy_bridge_cli.py szl_ken.py a11oy_formula_endpoints.py a11oy_formulas_page.py a11oy_frontier_patch.py a11oy_v4_agent.py szl_brain.py szl_wire.py szl_hub.py szl_rosie_companion.py szl_receipt_substrate.py szl_alloy_embed_fabric.py szl_ayni_quorum.py szl_agentic_loop.py ./
 COPY szl_formula_wiring.py a11oy_code_engine.py a11oy_code.py a11oy_seismic.py szl_warhacker_real.py szl_warhacker_demos.py NOTICE_warhacker_demos.txt szl_llm_registry.py szl_elite_console.py szl_alloy_models.py szl_scaling.py szl_allodial.py szl_entanglement.py szl_neuroplasticity.py szl_chain_of_title.py szl_sovereign_compute.py a11oy_active_flux_router.py ./

szl_spaces_proxy.py

@@ -0,0 +1,337 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: Apache-2.0
+# © 2026 Lutar, Stephen P. — SZL Holdings · ORCID 0009-0001-0110-4173
+"""szl_spaces_proxy.py — surface the live HF Spaces estate under a11oy.net/spaces/*.
+
+ADDITIVE, self-contained, SHARED (byte-identical in a11oy + killinchu). Founder rule:
+"all the huggingface on my a11oy.net" with NO new subdomains. This module reverse-
+proxies each live Hugging Face Space to a same-origin path:
+
+    GET/HEAD /spaces                 -> index (delegates to szl_spaces_surface tiles if
+                                        present; else a minimal honest index of the 11)
+    GET/HEAD /spaces/{name}          -> reverse-proxy of https://szlholdings-{name}.hf.space/
+    GET/HEAD /spaces/{name}/{path}   -> reverse-proxy of that Space's sub-paths/assets
+
+The proxy is a SERVER-SIDE fetch over the app's shared httpx.AsyncClient (resolved
+lazily from serve.py's module global, like szl_engine_status), NOT a browser CDN load —
+so it satisfies the 0-runtime-CDN doctrine for the same reason a11oy_hf_assets.py states
+(server-side fetch, not a browser CDN). HTML responses get a <base href="/spaces/{name}/">
+injected so the Space's root-relative assets resolve back through this proxy.
+
+HONEST DEGRADE: upstream timeout / connect error / unreachable -> a clean 502 page
+("Space <name> is starting / unreachable — open directly: <hf.space url>"). NEVER a fake
+200. Hop-by-hop headers are stripped. The proxy is an ALLOWLIST of the known Space names
+only (no open proxy); unknown names -> 404. a11oy is NOT self-proxied (would loop) and
+killinchu is served on its own host — both are listed as TILES (by szl_spaces_surface)
+linking to their canonical hosts, but are NOT in the reverse-proxy allowlist here.
+
+No auth token is forwarded to HF — these are PUBLIC Spaces.
+
+Routes are inserted at the FRONT of app.router.routes (app.router.routes[0:0] = new)
+so they win over the /api/<ns>/{path:path} Node proxy + the /{full_path:path} SPA
+catch-all (the same route-to-front idiom a11oy_hf_assets.py uses).
+
+Doctrine v11: locked-proven = EXACTLY 8 {F1,F4,F7,F11,F12,F18,F19,F22} @ c7c0ba17;
+Λ = Conjecture 1; Khipu = Conjecture 2; trust never 100%; 0 runtime CDN (server-side
+fetch); no user-visible codenames (Space names are their own honest titles); never
+commits a key; additive-only; never weakens a gate; honest 502 beats a fake 200.
+
+Signed-off-by: Stephen Lutar <stephenlutar2@gmail.com>
+Co-Authored-By: Perplexity Computer Agent <agent@perplexity.ai>
+"""
+from __future__ import annotations
+
+import sys
+from typing import Any
+
+_ORG_PREFIX = "szlholdings-"
+
+# The 11 live Spaces (all RUNNING). app URL pattern: https://szlholdings-<name>.hf.space
+# PROXY allowlist = the names we reverse-proxy under /spaces/<name>. We SKIP:
+#   - "a11oy"    : self-proxy would loop (a11oy.net IS the a11oy Space).
+#   - "killinchu": served on its own host; we link the tile to its host, never proxy it.
+# Both skipped names are still listed as TILES by szl_spaces_surface.
+ALL_SPACES = [
+    "immune", "sda", "anatomy", "cathedral", "energy", "yarqa",
+    "khipu-constellation", "llm-router-live", "hatun-mcp", "a11oy", "killinchu",
+]
+# Names we DO reverse-proxy (allowlist). Order preserved for the fallback index.
+PROXY_SPACES = [n for n in ALL_SPACES if n not in ("a11oy", "killinchu")]
+
+
+def hf_url(name: str) -> str:
+    """Canonical HF app URL for a Space name (lowercase, org-prefixed)."""
+    return f"https://{_ORG_PREFIX}{name}.hf.space"
+
+
+# Hop-by-hop headers (RFC 7230 §6.1) — never forwarded across the proxy boundary.
+_HOP_BY_HOP = {
+    "connection", "keep-alive", "proxy-authenticate", "proxy-authorization",
+    "te", "trailers", "transfer-encoding", "upgrade",
+    # content-encoding/length are recomputed by our Response; strip to avoid mismatch.
+    "content-encoding", "content-length",
+}
+
+_PROXY_TIMEOUT = 8.0       # short timeout — honest 502 beats a hung request.
+_PROXY_RETRIES = 1         # one quick retry on a transient flap before degrading.
+_MAX_BYTES = 25 * 1024 * 1024  # 25MB cap per proxied response (Spaces are light pages).
+
+
+def _honest_502(name: str) -> bytes:
+    """Clean 502 page — NEVER a fake 200. Tells the user to open the Space directly."""
+    url = hf_url(name)
+    return (
+        "<!doctype html><html lang=\"en\"><head><meta charset=\"utf-8\">"
+        "<meta name=\"viewport\" content=\"width=device-width,initial-scale=1\">"
+        "<title>Space %s — starting / unreachable</title></head>"
+        "<body style=\"margin:0;background:#0b0f14;color:#cdd6e0;"
+        "font:15px/1.6 system-ui,-apple-system,Segoe UI,Roboto,sans-serif;"
+        "display:flex;min-height:100vh;align-items:center;justify-content:center\">"
+        "<main style=\"max-width:560px;padding:2rem;text-align:center\">"
+        "<div style=\"font-size:2.2rem;margin-bottom:.4rem\">&#9889;</div>"
+        "<h1 style=\"font-size:1.25rem;margin:0 0 .6rem;color:#e7eef6\">"
+        "Space &ldquo;%s&rdquo; is starting or unreachable</h1>"
+        "<p style=\"color:#8a96a3;margin:0 0 1.2rem\">The upstream Hugging Face Space did "
+        "not respond in time. This is an honest 502 &mdash; not a faked page. "
+        "It usually means the Space is waking from sleep; try again shortly.</p>"
+        "<p><a href=\"%s\" style=\"color:#d4a444;text-decoration:none;font-weight:600\">"
+        "Open %s directly on Hugging Face &rarr;</a></p>"
+        "<p style=\"margin-top:1.4rem\"><a href=\"/spaces\" "
+        "style=\"color:#7c8794;text-decoration:none\">&larr; All Spaces</a></p>"
+        "</main></body></html>" % (name, name, url, name)
+    ).encode("utf-8")
+
+
+def _fallback_index() -> bytes:
+    """Minimal honest /spaces index — used ONLY if szl_spaces_surface (the rich tiles
+    page) is not registered. Lists every Space name with both links. 0 CDN."""
+    rows = []
+    for name in ALL_SPACES:
+        if name in ("a11oy", "killinchu"):
+            local = hf_url(name)  # own canonical host (not self-proxied here)
+            local_label = "Open on HF"
+        else:
+            local = "/spaces/%s" % name
+            local_label = "Open in a11oy.net"
+        rows.append(
+            "<li style=\"margin:.4rem 0\"><strong style=\"color:#e7eef6\">%s</strong> "
+            "&middot; <a href=\"%s\" style=\"color:#d4a444;text-decoration:none\">%s</a> "
+            "&middot; <a href=\"%s\" style=\"color:#7c8794;text-decoration:none\">Open on HF</a>"
+            "</li>" % (name, local, local_label, hf_url(name))
+        )
+    return (
+        "<!doctype html><html lang=\"en\"><head><meta charset=\"utf-8\">"
+        "<meta name=\"viewport\" content=\"width=device-width,initial-scale=1\">"
+        "<title>Spaces</title></head>"
+        "<body style=\"margin:0;background:#0b0f14;color:#cdd6e0;"
+        "font:15px/1.6 system-ui,-apple-system,Segoe UI,Roboto,sans-serif;padding:2rem\">"
+        "<main style=\"max-width:760px;margin:0 auto\">"
+        "<h1 style=\"color:#e7eef6\">Hugging Face Spaces</h1>"
+        "<p style=\"color:#8a96a3\">All live Spaces, surfaced under a11oy.net. "
+        "Server-side reverse proxy &mdash; 0 browser CDN.</p>"
+        "<ul style=\"list-style:none;padding:0\">" + "".join(rows) + "</ul>"
+        "</main></body></html>"
+    ).encode("utf-8")
+
+
+def _resolve_client() -> Any:
+    """Resolve the app's shared httpx.AsyncClient lazily from serve.py's module global
+    (same idiom as szl_engine_status) so registration order doesn't matter."""
+    try:
+        import serve as _serve  # type: ignore
+        return getattr(_serve, "_http_client", None)
+    except Exception:
+        return None
+
+
+def _rewrite_html(body: bytes, name: str) -> bytes:
+    """Inject <base href="/spaces/<name>/"> so the Space's root-relative asset URLs
+    (e.g. /assets/app.js, href="/"...) resolve back through this proxy. Idempotent:
+    if a base href for this proxy is already present, leave the body untouched."""
+    base_tag = ('<base href="/spaces/%s/">' % name).encode("utf-8")
+    if base_tag in body:
+        return body
+    low = body.lower()
+    # Prefer to place the <base> right after <head ...> so it applies to all assets.
+    h = low.find(b"<head")
+    if h != -1:
+        gt = body.find(b">", h)
+        if gt != -1:
+            return body[: gt + 1] + base_tag + body[gt + 1:]
+    # No <head> — try right after <html ...>.
+    h = low.find(b"<html")
+    if h != -1:
+        gt = body.find(b">", h)
+        if gt != -1:
+            return body[: gt + 1] + base_tag + body[gt + 1:]
+    # No usable anchor — prepend (still better than broken relative assets).
+    return base_tag + body
+
+
+async def _proxy(name: str, subpath: str, request) -> Any:
+    """Reverse-proxy one request to the named Space. Honest 502 on any upstream flap."""
+    from starlette.responses import Response
+
+    if name not in PROXY_SPACES:
+        # Not in the allowlist — either unknown, or a deliberately-skipped self/own-host
+        # Space. 404 (no open proxy). The skipped ones are reachable as tiles only.
+        return Response(content=b"Unknown or non-proxied Space.\n",
+                        status_code=404, media_type="text/plain")
+
+    client = _resolve_client()
+    if client is None:
+        return Response(content=_honest_502(name), status_code=502,
+                        media_type="text/html")
+
+    target = hf_url(name) + "/" + subpath
+    # Forward only safe request headers (drop Host so httpx sets the upstream host;
+    # drop hop-by-hop). No auth token forwarded — public Spaces.
+    fwd_headers = {
+        k: v for k, v in request.headers.items()
+        if k.lower() not in _HOP_BY_HOP and k.lower() not in ("host", "cookie")
+    }
+    method = request.method.upper()
+
+    upstream = None
+    last_exc = None
+    for _attempt in range(_PROXY_RETRIES + 1):
+        try:
+            upstream = await client.request(
+                method, target, headers=fwd_headers,
+                timeout=_PROXY_TIMEOUT, follow_redirects=True,
+            )
+            break
+        except Exception as e:  # connect error / timeout / read error -> honest degrade
+            last_exc = e
+            upstream = None
+
+    if upstream is None:
+        print("[spaces-proxy] upstream flap for %s: %r" % (name, last_exc),
+              file=sys.stderr)
+        return Response(content=_honest_502(name), status_code=502,
+                        media_type="text/html")
+
+    ct = (upstream.headers.get("content-type") or "").lower()
+    body = upstream.content or b""
+    if len(body) > _MAX_BYTES:
+        body = body[:_MAX_BYTES]
+
+    # HTML: inject <base href> so assets resolve under /spaces/<name>/.
+    if "text/html" in ct:
+        body = _rewrite_html(body, name)
+
+    out_headers = {
+        k: v for k, v in upstream.headers.items()
+        if k.lower() not in _HOP_BY_HOP
+    }
+    # HEAD must carry no body.
+    if method == "HEAD":
+        body = b""
+
+    return Response(content=body, status_code=upstream.status_code,
+                    headers=out_headers,
+                    media_type=upstream.headers.get("content-type"))
+
+
+def register(app, ns: str = "a11oy") -> str:
+    """ADDITIVE: mount the /spaces reverse-proxy routes at the FRONT of the router so
+    they beat the SPA + Node-proxy catch-alls. try/except-guarded by the caller."""
+    try:
+        from starlette.responses import Response
+    except Exception as e:  # pragma: no cover
+        return "unavailable: %r" % (e,)
+
+    n_before = len(app.router.routes)
+
+    async def _spaces_index(request):
+        # Delegate the rich tiles page to szl_spaces_surface if it owns /spaces; this
+        # fallback index only renders if that module isn't present. Idempotent: this
+        # route is inserted only once per register() and register() is guarded upstream.
+        if request.method.upper() == "HEAD":
+            return Response(content=b"", status_code=200, media_type="text/html")
+        return Response(content=_fallback_index(), status_code=200,
+                        media_type="text/html")
+
+    async def _spaces_name(request):
+        name = request.path_params.get("name", "")
+        return await _proxy(name, "", request)
+
+    async def _spaces_path(request):
+        name = request.path_params.get("name", "")
+        subpath = request.path_params.get("path", "")
+        return await _proxy(name, subpath, request)
+
+    from starlette.routing import Route
+    # NOTE: szl_spaces_surface registers its OWN richer /spaces tiles page and inserts
+    # it at the front AFTER this module (it's registered second in serve.py), so the
+    # tiles page wins over this fallback index — by design. Both are idempotent.
+    routes = [
+        Route("/spaces", _spaces_index, methods=["GET", "HEAD"]),
+        Route("/spaces/{name}", _spaces_name, methods=["GET", "HEAD"]),
+        Route("/spaces/{name}/{path:path}", _spaces_path, methods=["GET", "HEAD"]),
+    ]
+    for r in routes:
+        app.router.routes.append(r)
+
+    new = app.router.routes[n_before:]
+    del app.router.routes[n_before:]
+    app.router.routes[0:0] = new
+    print("[%s] Spaces reverse-proxy registered: /spaces + /spaces/{name} + "
+          "/spaces/{name}/{path} (%d proxied: %s) [moved %d routes to front]"
+          % (ns, len(PROXY_SPACES), ",".join(PROXY_SPACES), len(new)), file=sys.stderr)
+    return "ok: %d proxied spaces, %d routes" % (len(PROXY_SPACES), len(new))
+
+
+# ---------------------------------------------------------------------------
+# Self-test — pure stdlib + starlette TestClient; no real network. Stubs the shared
+# client to assert: allowlist enforced (unknown -> 404), honest 502 on a dead client,
+# <base href> injection, HEAD carries no body, and the fallback index lists all 11.
+# ---------------------------------------------------------------------------
+if __name__ == "__main__":
+    import ast as _ast
+    # parse-self guard
+    with open(__file__, "r", encoding="utf-8") as _fh:
+        _ast.parse(_fh.read())
+
+    # base-href injection
+    out = _rewrite_html(b"<html><head><title>x</title></head><body>hi</body></html>", "immune")
+    assert b'<base href="/spaces/immune/">' in out, "must inject base href"
+    assert _rewrite_html(out, "immune") == out, "base href injection must be idempotent"
+
+    # honest 502 content
+    p = _honest_502("sda")
+    assert b"honest 502" in p and b"szlholdings-sda.hf.space" in p, "502 must be honest + direct link"
+
+    # allowlist
+    assert "a11oy" not in PROXY_SPACES and "killinchu" not in PROXY_SPACES, "self/own-host skipped"
+    assert len(ALL_SPACES) == 11 and len(PROXY_SPACES) == 9, (len(ALL_SPACES), len(PROXY_SPACES))
+
+    # fallback index lists all 11 names
+    idx = _fallback_index()
+    for nm in ALL_SPACES:
+        assert nm.encode() in idx, "index missing %s" % nm
+
+    from starlette.applications import Starlette
+    from starlette.responses import PlainTextResponse
+    from starlette.routing import Route as _R
+    from starlette.testclient import TestClient
+
+    a = Starlette(routes=[_R("/{full_path:path}", lambda req: PlainTextResponse("SPA"))])
+    st = register(a, ns="a11oy")
+    assert st.startswith("ok:"), st
+    c = TestClient(a)
+    # /spaces fallback index resolves before the SPA catch-all and lists all names
+    r = c.get("/spaces")
+    assert r.status_code == 200 and "immune" in r.text and "killinchu" in r.text, r.status_code
+    # unknown / non-proxied name -> 404 (no open proxy); a11oy is deliberately skipped
+    assert c.get("/spaces/a11oy").status_code == 404, "a11oy must not be self-proxied"
+    assert c.get("/spaces/notreal").status_code == 404, "unknown -> 404"
+    # known name with no shared client wired -> honest 502 (never fake 200)
+    r502 = c.get("/spaces/immune")
+    assert r502.status_code == 502 and "honest 502" in r502.text, (r502.status_code, r502.text[:80])
+    # HEAD on a known name -> still 502 here (no client) but no body
+    rh = c.head("/spaces/immune")
+    assert rh.status_code == 502, rh.status_code
+
+    print("szl_spaces_proxy: ALL OK (allowlist; honest 502; base-href idempotent; "
+          "%d proxied of %d; 0 CDN server-side fetch)" % (len(PROXY_SPACES), len(ALL_SPACES)))

szl_spaces_surface.py

@@ -0,0 +1,473 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: Apache-2.0
+# © 2026 Lutar, Stephen P. — SZL Holdings · ORCID 0009-0001-0110-4173
+"""szl_spaces_surface.py — console "Spaces" surface (health API + tiles + nav).
+
+ADDITIVE, self-contained, SHARED (byte-identical in a11oy + killinchu). The console
+companion to szl_spaces_proxy: a LIVE health view of the whole HF Spaces estate plus a
+clean tiles page and ONE idempotent nav item, following the additive-injector pattern
+(a11oy_nav_wireup.py / killinchu_nav_wireup.py).
+
+ROUTES (additive, inserted at the FRONT of the router so they beat the SPA + Node-proxy
+catch-alls — same route-to-front idiom as a11oy_hf_assets.py):
+
+  GET  /api/<ns>/v1/spaces/health  -> for each Space, an HONEST status:
+        {name, title, stage, app_reachable, url, proxy_url}
+        - stage          : runtime.stage from the HF API
+                           (https://huggingface.co/api/spaces/SZLHOLDINGS/<name>),
+                           or "unknown" if that API call degrades. LABELLED as HF-API.
+        - app_reachable  : a REAL same-origin server-side probe of
+                           https://szlholdings-<name>.hf.space/ (HEAD, short timeout).
+                           true ONLY when the probe really succeeded. Never fabricated.
+        Degrade -> stage:"unknown", app_reachable:false. NEVER a faked stage/200.
+
+  GET/HEAD /spaces                 -> a clean tiles page (one card per Space: honest
+        title, live status dot fed by /health, "Open in a11oy.net" -> /spaces/<name>,
+        "Open on HF" -> hf.space url). Pure inline markup, 0 browser CDN. The status
+        dots are filled by a tiny inline fetch of the SAME-ORIGIN /health JSON (not a
+        CDN; the data is our own server-side-probed endpoint).
+
+NAV: a BaseHTTPMiddleware injector adds ONE nav item "Spaces" -> /spaces into the
+console left-nav (before <div class="side-foot">, with nav-group / nav-item fallbacks).
+Idempotent — keyed by data-attribute data-nav-spaces="hf1"; removes NOTHING from the SPA
+source; never touches /api, /v1, /assets, /static, /vendor responses. Works identically
+on the a11oy /console and killinchu /elite consoles (same sidebar markup) — which is why
+this module can be byte-identical in both apps.
+
+The /spaces probe + HF-API call are SERVER-SIDE fetches (resolve the shared httpx client
+lazily from serve.py, like szl_engine_status) — 0 runtime CDN, same justification as
+a11oy_hf_assets.py. No auth token forwarded to HF (public Spaces / public API).
+
+Doctrine v11: locked-proven = EXACTLY 8 {F1,F4,F7,F11,F12,F18,F19,F22} @ c7c0ba17;
+Λ = Conjecture 1; Khipu = Conjecture 2; trust never 100%; 0 runtime CDN; no user-visible
+codenames (Space names are their own honest titles); never commits a key; additive-only;
+honest "unknown"/false beats a fabricated stage.
+
+Signed-off-by: Stephen Lutar <stephenlutar2@gmail.com>
+Co-Authored-By: Perplexity Computer Agent <agent@perplexity.ai>
+"""
+from __future__ import annotations
+
+import sys
+import time
+from typing import Any
+
+_ORG = "SZLHOLDINGS"
+_ORG_PREFIX = "szlholdings-"
+
+# The 11 live Spaces + their honest, public titles (NOT codenames — each Space's own
+# name). a11oy + killinchu are listed as tiles linking to their own canonical hosts;
+# they are NOT reverse-proxied by szl_spaces_proxy (self / own-host).
+SPACES: list[dict[str, str]] = [
+    {"name": "immune",              "title": "Immune — Verifiable Screening"},
+    {"name": "sda",                 "title": "SDA — Space Domain Awareness"},
+    {"name": "anatomy",             "title": "Anatomy — Canonical Formula Registry"},
+    {"name": "cathedral",           "title": "Cathedral — Estate Cathedral"},
+    {"name": "energy",              "title": "Energy — Sovereign Compute"},
+    {"name": "yarqa",               "title": "Yarqa — Data Channel"},
+    {"name": "khipu-constellation", "title": "Khipu Constellation — Receipt Mesh"},
+    {"name": "llm-router-live",     "title": "LLM Router (Live)"},
+    {"name": "hatun-mcp",           "title": "Hatun — MCP Server"},
+    {"name": "a11oy",               "title": "a11oy — Brand Orchestration Layer"},
+    {"name": "killinchu",           "title": "Killinchu — Edge Console"},
+]
+# Spaces served on their OWN canonical host (not reverse-proxied here): the tile's
+# primary "open" link points at HF rather than /spaces/<name>.
+_OWN_HOST = {"a11oy", "killinchu"}
+
+_DOCTRINE = {
+    "version": "v11",
+    "lambda": "Conjecture 1",
+    "khipu": "Conjecture 2",
+    "locked_proven": ["F1", "F4", "F7", "F11", "F12", "F18", "F19", "F22"],
+    "trust_ceiling": "never 100%",
+}
+
+_PROBE_TIMEOUT = 6.0
+_HF_API_TIMEOUT = 6.0
+_HEALTH_CACHE_TTL = 20.0  # seconds — keep the tiles page snappy without re-probing 11x.
+_HEALTH_CACHE: dict[str, Any] = {"ts": 0.0, "payload": None}
+
+
+def hf_url(name: str) -> str:
+    return f"https://{_ORG_PREFIX}{name}.hf.space"
+
+
+def hf_api_url(name: str) -> str:
+    return f"https://huggingface.co/api/spaces/{_ORG}/{name}"
+
+
+def proxy_url(name: str) -> str:
+    """Where the tile's primary "open" link points. Own-host Spaces -> their HF host;
+    everyone else -> the same-origin reverse proxy at /spaces/<name>."""
+    return hf_url(name) if name in _OWN_HOST else f"/spaces/{name}"
+
+
+def _resolve_client() -> Any:
+    """Lazily resolve the app's shared httpx.AsyncClient from serve.py (same idiom as
+    szl_engine_status), so registration order doesn't matter."""
+    try:
+        import serve as _serve  # type: ignore
+        return getattr(_serve, "_http_client", None)
+    except Exception:
+        return None
+
+
+async def _probe_one(client: Any, sp: dict[str, str]) -> dict[str, Any]:
+    """HONEST per-Space status. app_reachable is a REAL HEAD probe; stage is from the
+    HF API. Any failure degrades to honest false/'unknown' — never fabricated."""
+    name = sp["name"]
+    result: dict[str, Any] = {
+        "name": name,
+        "title": sp["title"],
+        "url": hf_url(name),
+        "proxy_url": proxy_url(name),
+        "own_host": name in _OWN_HOST,
+        "stage": "unknown",         # from HF API; HF-API-labelled below
+        "stage_source": "hf-api",
+        "app_reachable": False,     # REAL probe; only true when the probe truly succeeds
+    }
+    if client is None:
+        result["note"] = "no http client; honest degrade"
+        return result
+
+    # (1) REAL same-origin liveness probe of the Space app (HEAD; fall back to tiny GET).
+    try:
+        r = await client.request("HEAD", hf_url(name) + "/",
+                                 timeout=_PROBE_TIMEOUT, follow_redirects=True)
+        result["app_reachable"] = bool(r.status_code < 500)
+        result["app_status"] = r.status_code
+    except Exception:
+        try:
+            r = await client.get(hf_url(name) + "/", timeout=_PROBE_TIMEOUT,
+                                 follow_redirects=True)
+            result["app_reachable"] = bool(r.status_code < 500)
+            result["app_status"] = r.status_code
+        except Exception as e:
+            result["app_reachable"] = False
+            result["probe_error"] = type(e).__name__
+
+    # (2) HF API runtime.stage (public API, no token). Honest "unknown" on any failure.
+    try:
+        ra = await client.get(hf_api_url(name), timeout=_HF_API_TIMEOUT,
+                              headers={"User-Agent": "szl-spaces-surface/1.0"})
+        if ra.status_code == 200:
+            data = ra.json()
+            stage = (((data or {}).get("runtime") or {}).get("stage"))
+            if isinstance(stage, str) and stage:
+                result["stage"] = stage
+        else:
+            result["stage_http"] = ra.status_code
+    except Exception as e:
+        result["stage_error"] = type(e).__name__
+
+    return result
+
+
+async def spaces_health() -> dict[str, Any]:
+    """Aggregate honest health for all 11 Spaces (short TTL cache)."""
+    now = time.monotonic()
+    if _HEALTH_CACHE["payload"] is not None and (now - _HEALTH_CACHE["ts"]) < _HEALTH_CACHE_TTL:
+        return _HEALTH_CACHE["payload"]
+
+    client = _resolve_client()
+    spaces: list[dict[str, Any]] = []
+    if client is None:
+        for sp in SPACES:
+            spaces.append({
+                "name": sp["name"], "title": sp["title"], "url": hf_url(sp["name"]),
+                "proxy_url": proxy_url(sp["name"]), "own_host": sp["name"] in _OWN_HOST,
+                "stage": "unknown", "stage_source": "hf-api", "app_reachable": False,
+                "note": "no http client; honest degrade",
+            })
+    else:
+        import asyncio as _asyncio
+        spaces = await _asyncio.gather(*[_probe_one(client, sp) for sp in SPACES])
+        spaces = list(spaces)
+
+    payload = {
+        "count": len(spaces),
+        "spaces": spaces,
+        "labels": {
+            "stage": "HF API runtime.stage (https://huggingface.co/api/spaces/SZLHOLDINGS/<name>)",
+            "app_reachable": "REAL same-origin server-side HEAD/GET probe of the Space app",
+            "degrade": "stage:'unknown' + app_reachable:false; never fabricated",
+        },
+        "note": "Server-side probed; 0 browser CDN. Honest live/unknown only.",
+        "doctrine": _DOCTRINE,
+        "fetchedAt": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+    }
+    _HEALTH_CACHE["payload"] = payload
+    _HEALTH_CACHE["ts"] = now
+    return payload
+
+
+# ---------------------------------------------------------------------------
+# Tiles page — pure inline markup, 0 CDN. Status dots are filled by a tiny inline
+# fetch of the SAME-ORIGIN /api/<ns>/v1/spaces/health (our own server-side-probed
+# endpoint, not a CDN). Cards are pre-rendered so the page is useful even with JS off.
+# ---------------------------------------------------------------------------
+def _tiles_page(ns: str) -> bytes:
+    cards = []
+    for sp in SPACES:
+        name = sp["name"]
+        title = sp["title"]
+        primary = proxy_url(name)
+        primary_label = "Open on HF" if name in _OWN_HOST else "Open in a11oy.net"
+        cards.append(
+            '<article class="sp-card" data-space="%s">'
+            '<header class="sp-head">'
+            '<span class="sp-dot" data-dot="%s" title="status">&#9679;</span>'
+            '<h2 class="sp-title">%s</h2></header>'
+            '<div class="sp-stage" data-stage="%s">stage: <span>checking&hellip;</span></div>'
+            '<div class="sp-links">'
+            '<a class="sp-open" href="%s">%s</a>'
+            '<a class="sp-hf" href="%s" rel="noopener" target="_blank">Open on HF &#8599;</a>'
+            '</div></article>'
+            % (name, name, title, name, primary, primary_label, hf_url(name))
+        )
+    html = (
+        '<!doctype html><html lang="en"><head><meta charset="utf-8">'
+        '<meta name="viewport" content="width=device-width,initial-scale=1">'
+        '<title>Spaces &middot; a11oy</title>'
+        '<style>'
+        ':root{color-scheme:dark}'
+        '*{box-sizing:border-box}'
+        'body{margin:0;background:#0b0f14;color:#cdd6e0;'
+        'font:15px/1.6 system-ui,-apple-system,Segoe UI,Roboto,sans-serif}'
+        '.sp-wrap{max-width:1100px;margin:0 auto;padding:2rem 1.25rem}'
+        '.sp-h1{color:#e7eef6;font-size:1.6rem;margin:0 0 .25rem}'
+        '.sp-sub{color:#8a96a3;margin:0 0 1.6rem}'
+        '.sp-grid{display:grid;gap:1rem;'
+        'grid-template-columns:repeat(auto-fill,minmax(260px,1fr))}'
+        '.sp-card{background:#121821;border:1px solid #1d2632;border-radius:12px;'
+        'padding:1rem 1.1rem;display:flex;flex-direction:column;gap:.5rem}'
+        '.sp-head{display:flex;align-items:center;gap:.55rem}'
+        '.sp-dot{color:#5b6675;font-size:.7rem;line-height:1}'
+        '.sp-dot.up{color:#3ad07a}.sp-dot.down{color:#e0593a}.sp-dot.unknown{color:#c9a23a}'
+        '.sp-title{font-size:1rem;margin:0;color:#e7eef6;font-weight:600}'
+        '.sp-stage{color:#7c8794;font-size:.82rem}'
+        '.sp-stage span{color:#9fb0c0}'
+        '.sp-links{margin-top:auto;display:flex;gap:.9rem;flex-wrap:wrap;padding-top:.4rem}'
+        '.sp-open{color:#d4a444;text-decoration:none;font-weight:600}'
+        '.sp-hf{color:#7c8794;text-decoration:none}'
+        '.sp-foot{color:#5b6675;font-size:.8rem;margin-top:1.6rem}'
+        '</style></head>'
+        '<body><main class="sp-wrap">'
+        '<h1 class="sp-h1">Hugging Face Spaces</h1>'
+        '<p class="sp-sub">All live Spaces, surfaced on a11oy.net &mdash; server-side '
+        'reverse proxy + honest live health. 0 browser CDN.</p>'
+        '<div class="sp-grid">' + "".join(cards) + '</div>'
+        '<p class="sp-foot">Status dot &amp; stage are filled from the same-origin '
+        '<code>/api/' + ns + '/v1/spaces/health</code> endpoint (real server-side probe '
+        '+ HF API). Honest: a grey/amber dot means starting or unknown, never a faked up.</p>'
+        '</main>'
+        '<script>'
+        '(function(){'
+        'fetch("/api/' + ns + '/v1/spaces/health").then(function(r){return r.json();})'
+        '.then(function(d){(d.spaces||[]).forEach(function(s){'
+        'var card=document.querySelector(\'[data-space="\'+s.name+\'"]\');if(!card)return;'
+        'var dot=card.querySelector(".sp-dot");'
+        'if(dot){dot.classList.remove("up","down","unknown");'
+        'dot.classList.add(s.app_reachable?"up":(s.stage&&s.stage!=="unknown"?"unknown":"down"));'
+        'dot.title=(s.app_reachable?"reachable":"unreachable")+" / stage:"+(s.stage||"unknown");}'
+        'var st=card.querySelector(".sp-stage span");'
+        'if(st){st.textContent=(s.stage||"unknown")+(s.app_reachable?" \\u00b7 reachable":" \\u00b7 unreachable");}'
+        '});}).catch(function(){});'
+        '})();'
+        '</script>'
+        '</body></html>'
+    )
+    return html.encode("utf-8")
+
+
+# ---------------------------------------------------------------------------
+# Nav injector — ONE "Spaces" nav item into the console left-nav. Same additive,
+# idempotent BaseHTTPMiddleware idiom as a11oy_nav_wireup / killinchu_nav_wireup.
+# ---------------------------------------------------------------------------
+_NAV_MARKER = b'data-nav-spaces="hf1"'
+_FOOT_ANCHOR = b'<div class="side-foot">'
+_GROUP_ANCHOR = b'<div class="nav-group">'
+_NAVITEM_ANCHOR = b'<div class="nav-item"'
+
+
+def _nav_item() -> bytes:
+    """ONE 'Spaces' nav item, mirroring the console's own nav-item markup so it inherits
+    the console styling (0 CDN, 0 codename). Globe glyph; honest label."""
+    return (
+        '<div class="nav-item" data-nav-spaces="hf1" data-wireup-path="/spaces" '
+        'onclick="location.href=\'/spaces\'" style="cursor:pointer">'
+        '<span class="ico">\U0001F310</span>Spaces</div>'
+    ).encode("utf-8")
+
+
+def _make_injector():
+    from starlette.middleware.base import BaseHTTPMiddleware
+    from starlette.responses import Response
+
+    nav_item = _nav_item()
+
+    class _SpacesNavInjector(BaseHTTPMiddleware):
+        async def dispatch(self, request, call_next):
+            resp = await call_next(request)
+            try:
+                ct = (resp.headers.get("content-type") or "").lower()
+                if "text/html" not in ct:
+                    return resp
+                p = request.url.path
+                if (p.startswith("/api/") or p.startswith("/v1/")
+                        or p.startswith("/vendor/") or p.startswith("/assets/")
+                        or p.startswith("/static/")):
+                    return resp
+                # The /spaces tiles page IS our own page; don't inject the sidebar nav
+                # into it (it has no console sidebar). Cheap guard — also keeps it idempotent.
+                if p == "/spaces" or p.startswith("/spaces/"):
+                    return resp
+
+                body = b""
+                async for chunk in resp.body_iterator:
+                    body += chunk if isinstance(chunk, (bytes, bytearray)) else str(chunk).encode()
+
+                if _NAV_MARKER not in body:
+                    if _FOOT_ANCHOR in body:
+                        body = body.replace(_FOOT_ANCHOR, nav_item + _FOOT_ANCHOR, 1)
+                    elif _NAVITEM_ANCHOR in body:
+                        # No footer found, but a nav exists -> place after the first
+                        # nav-item div so 'Spaces' still lands in the nav.
+                        start = body.find(_NAVITEM_ANCHOR)
+                        end = body.find(b"</div>", start)
+                        if end != -1:
+                            end += len(b"</div>")
+                            body = body[:end] + nav_item + body[end:]
+                    elif _GROUP_ANCHOR in body:
+                        body = body.replace(_GROUP_ANCHOR, _GROUP_ANCHOR + nav_item, 1)
+
+                # body_iterator is consumed — MUST rebuild the Response even if unchanged,
+                # else downstream sees an empty body (white screen).
+                headers = dict(resp.headers)
+                headers.pop("content-length", None)
+                return Response(content=body, status_code=resp.status_code,
+                                headers=headers, media_type="text/html")
+            except Exception:
+                return resp
+
+    return _SpacesNavInjector
+
+
+def register(app, ns: str = "a11oy") -> str:
+    """ADDITIVE: mount GET /api/<ns>/v1/spaces/health + GET/HEAD /spaces (rich tiles)
+    at the FRONT of the router (beat the SPA + Node-proxy catch-alls), and attach the
+    idempotent 'Spaces' nav injector. try/except-guarded by the caller."""
+    try:
+        from fastapi.responses import JSONResponse  # noqa: F401
+        from starlette.responses import Response, JSONResponse as _JSON
+    except Exception as e:  # pragma: no cover
+        return "unavailable: %r" % (e,)
+
+    n_before = len(app.router.routes)
+    tiles = _tiles_page(ns)
+
+    async def _health(request):
+        payload = await spaces_health()
+        return _JSON(payload)
+
+    async def _tiles(request):
+        if request.method.upper() == "HEAD":
+            return Response(content=b"", status_code=200, media_type="text/html")
+        return Response(content=tiles, status_code=200, media_type="text/html")
+
+    from starlette.routing import Route
+    routes = [
+        Route("/api/%s/v1/spaces/health" % ns, _health, methods=["GET"]),
+        # The rich tiles page OWNS /spaces (wins over szl_spaces_proxy's fallback index
+        # because this module is registered SECOND and front-inserts after it).
+        Route("/spaces", _tiles, methods=["GET", "HEAD"]),
+    ]
+    for r in routes:
+        app.router.routes.append(r)
+
+    new = app.router.routes[n_before:]
+    del app.router.routes[n_before:]
+    app.router.routes[0:0] = new
+
+    app.add_middleware(_make_injector())
+
+    print("[%s] Spaces surface registered: /api/%s/v1/spaces/health + /spaces (tiles, "
+          "%d spaces) + nav injector [moved %d routes to front]"
+          % (ns, ns, len(SPACES), len(new)), file=sys.stderr)
+    return "ok: %d spaces, health + tiles + nav, %d routes" % (len(SPACES), len(new))
+
+
+# ---------------------------------------------------------------------------
+# Self-test — pure stdlib + starlette TestClient; no real network. Stubs the shared
+# client to assert: health degrades honestly (no client -> stage unknown + reachable
+# false), tiles page lists ALL 11 names + has the health-fetch JS, nav injects exactly
+# once + is idempotent + removes nothing, /spaces is NOT nav-injected.
+# ---------------------------------------------------------------------------
+if __name__ == "__main__":
+    import ast as _ast
+    with open(__file__, "r", encoding="utf-8") as _fh:
+        _ast.parse(_fh.read())
+
+    assert len(SPACES) == 11, len(SPACES)
+    tp = _tiles_page("a11oy")
+    for sp in SPACES:
+        assert sp["name"].encode() in tp, "tiles missing %s" % sp["name"]
+        assert sp["title"].encode() in tp, "tiles missing title %s" % sp["title"]
+    assert b"/api/a11oy/v1/spaces/health" in tp, "tiles must fetch the health endpoint"
+    assert b"http://" not in tp, "tiles must be 0 CDN (no http://)"
+    # the only https in the page should be the hf.space open links (server-named, fine)
+    assert tp.count(b"https://huggingface.co") == 0, "tiles must not pull from HF CDN"
+
+    from starlette.applications import Starlette
+    from starlette.responses import HTMLResponse, PlainTextResponse
+    from starlette.routing import Route as _R
+    from starlette.testclient import TestClient
+
+    SAMPLE_CONSOLE = (
+        '<html><body><aside>'
+        '<div class="nav-group">Operate</div>'
+        '<div class="nav-item" data-view="x" onclick="go(\'x\')">'
+        '<span class="ico">+</span>Existing</div>'
+        '<div class="side-foot">footer</div>'
+        '</aside></body></html>'
+    )
+
+    async def _console(req):
+        return HTMLResponse(SAMPLE_CONSOLE)
+
+    app = Starlette(routes=[
+        _R("/console", _console),
+        _R("/{full_path:path}", lambda req: PlainTextResponse("SPA")),
+    ])
+    st = register(app, ns="a11oy")
+    assert st.startswith("ok:"), st
+    c = TestClient(app)
+
+    # health: no client wired -> honest degrade for all 11
+    h = c.get("/api/a11oy/v1/spaces/health").json()
+    assert h["count"] == 11, h["count"]
+    assert all(s["stage"] == "unknown" and s["app_reachable"] is False for s in h["spaces"]), \
+        "no client must degrade to unknown/false (never fabricated)"
+    assert h["doctrine"]["locked_proven"] == ["F1", "F4", "F7", "F11", "F12", "F18", "F19", "F22"]
+
+    # tiles page resolves + lists all names
+    t = c.get("/spaces")
+    assert t.status_code == 200 and "text/html" in t.headers["content-type"], t.status_code
+    for sp in SPACES:
+        assert sp["name"] in t.text, "tiles page missing %s" % sp["name"]
+
+    # nav injects exactly once + idempotent + removes nothing
+    p1 = c.get("/console").text
+    p2 = c.get("/console").text
+    assert p1.count('data-nav-spaces="hf1"') == 1, "nav must inject exactly once"
+    assert p2.count('data-nav-spaces="hf1"') == 1, "nav must be idempotent"
+    assert "location.href='/spaces'" in p1, "nav must link /spaces"
+    assert "Operate</div>" in p1 and "Existing</div>" in p1 and "footer</div>" in p1, \
+        "must remove nothing from the SPA source"
+    assert p1 == p2, "second console render must be byte-identical (idempotent)"
+    # the tiles page itself must NOT be nav-injected (it has no console sidebar)
+    assert 'data-nav-spaces="hf1"' not in c.get("/spaces").text, "/spaces must not be nav-injected"
+
+    print("szl_spaces_surface: ALL OK (11 spaces; honest degrade; tiles 0-CDN; nav "
+          "idempotent + additive; /spaces not self-injected)")