agents-city 0.3.0-beta.21

package/bin/test-serve.py

@@ -0,0 +1,1057 @@
+#!/usr/bin/env python3
+"""The personal-city Hall server.
+
+    ./bin/test-serve.py
+
+It is the only process in this project that both listens on a socket and writes
+to disk, so its unhappy paths are security: no run token means no response, and a
+foreign origin cannot drive it. The happy path pins one owner seat, several local
+cities, symmetric roads and city-scoped writes.
+
+The server runs in-process on an ephemeral port. No browser, no network beyond
+loopback, and every city it writes lands in a temporary directory.
+"""
+
+import json
+import os
+import shutil
+import sys
+import tempfile
+import threading
+import urllib.error
+import urllib.parse
+import urllib.request
+
+AQUI = os.path.dirname(os.path.abspath(__file__))
+RAIZ = os.path.dirname(AQUI)
+sys.path.insert(0, os.path.join(RAIZ, "plugin", "scripts"))
+sys.path.insert(0, AQUI)
+import serve  # noqa: E402
+import card  # noqa: E402
+
+from testlib import comprueba, afirma, resumen  # noqa: E402
+
+
+def pide(puerto, ruta, con_pase=True, metodo="GET", cuerpo=None, cabeceras=None):
+    """One request against the test server. Returns (status, body-bytes)."""
+    url = f"http://127.0.0.1:{puerto}{ruta}"
+    if con_pase:
+        url += ("&" if "?" in ruta else "?") + "PASE=" + serve.PASE
+    req = urllib.request.Request(
+        url, method=metodo, data=json.dumps(cuerpo).encode() if cuerpo is not None else None
+    )
+    for k, v in (cabeceras or {}).items():
+        req.add_header(k, v)
+    try:
+        with urllib.request.urlopen(req, timeout=30) as r:
+            return r.status, r.read()
+    except urllib.error.HTTPError as e:
+        return e.code, e.read()
+
+
+def main():
+    print()
+    destino = tempfile.mkdtemp()
+    serve.DESTINO = os.path.join(destino, "ciudad")
+
+    servidor = serve.Servidor(("127.0.0.1", 0), serve.Manejador)
+    puerto = servidor.server_port
+    hilo = threading.Thread(target=servidor.serve_forever, daemon=True)
+    hilo.start()
+
+    # The hall reads whatever city AGENTS_CITY_DATA points at; give it one of its
+    # own so this suite never touches the caller's, and an empty disk index so
+    # /api/misrepos cannot wander off crawling the real home directory.
+    hallDatos = tempfile.mkdtemp()
+    appDatos = tempfile.mkdtemp()
+    arbitraryDatos = tempfile.mkdtemp()
+    # The suite must never write into the caller's real city registry.
+    serve.cities.REGISTRO = os.path.join(tempfile.mkdtemp(), "cities")
+    os.environ["AGENTS_CITY_DATA"] = hallDatos
+    os.environ["AGENTS_CITY_HOME"] = appDatos
+    os.environ["AGENTS_CITY_USER"] = "halltest"
+    os.environ["CITY_SEARCH_IN"] = tempfile.mkdtemp()
+    os.environ["XDG_CACHE_HOME"] = tempfile.mkdtemp()
+
+    try:
+        # ── the doors that must be closed ──────────────────────────────────
+        print("  what must be refused")
+        st, _ = pide(puerto, "/", con_pase=False)
+        comprueba("· no token: nothing, not even the page", st, 403)
+        st, _ = pide(puerto, "/?PASE=wrong-token-entirely", con_pase=False)
+        comprueba("· a wrong token is the same as none", st, 403)
+        st, _ = pide(puerto, "/api/estado", con_pase=False)
+        comprueba("· the API refuses without it too", st, 403)
+        st, _ = pide(puerto, "/api/ficha", con_pase=False, metodo="POST", cuerpo={})
+        comprueba("· and above all the endpoint that writes to disk", st, 403)
+        # This server writes files: a page from any other origin must not drive it.
+        st, _ = pide(puerto, "/api/estado", cabeceras={"Origin": "http://evil.example"})
+        comprueba("· a foreign Origin is refused even with the token", st, 403)
+        st, _ = pide(puerto, "/api/estado", cabeceras={"Origin": f"http://127.0.0.1:{puerto}"})
+        comprueba("· our own origin is not", st, 200)
+        st, _ = pide(puerto, "/api/no-such-thing")
+        comprueba("· an unknown route is a 404, not a stack trace", st, 404)
+        # The demo's remote control must never touch a real city: a replay on a
+        # real bus would be publishing fiction as committee history.
+        st, _ = pide(puerto, "/api/demo", metodo="POST", cuerpo={"action": "restart"})
+        comprueba("· the demo replay refuses any city that is not the demo", st, 403)
+        st, cuerpo = pide(puerto, "/api/estado?city=" + urllib.parse.quote(arbitraryDatos, safe=""))
+        estado_seguro = json.loads(cuerpo)
+        afirma(
+            "· a crafted city path cannot turn an arbitrary folder into a city",
+            st == 200
+            and estado_seguro["datos"] == os.path.realpath(hallDatos)
+            and not os.path.exists(os.path.join(arbitraryDatos, "city.yml")),
+        )
+        st, cuerpo = pide(
+            puerto, "/api/roads", metodo="POST", cuerpo=None, cabeceras={"Content-Length": "0"}
+        )
+        afirma("· an empty POST body is handled, not a crash", st in (200, 400), f"status {st}")
+
+        # ── the happy path: the Hall and its role catalogue ─────────────────
+        print("  what must work")
+        st, cuerpo = pide(puerto, "/")
+        comprueba("· the page is served", st, 200)
+        afirma(
+            "· with the run token injected, not the placeholder",
+            serve.PASE.encode() in cuerpo and b"__PASE__" not in cuerpo,
+        )
+
+        st, cuerpo = pide(puerto, "/api/roles?kind=product")
+        rolesR = json.loads(cuerpo)["roles"]
+        comprueba("· the product city offers its ten roles, including blank", len(rolesR), 10)
+        afirma(
+            "· with the trade read from the role files",
+            any(r["trade"] == "Architect" for r in rolesR),
+        )
+        afirma(
+            "· blank is visible but carries no invented trade",
+            any(r["id"] == "blank" and r["trade"] == "No preset" for r in rolesR),
+            str(rolesR),
+        )
+        st, cuerpo = pide(puerto, "/api/domains")
+        dominios = json.loads(cuerpo)["domains"]
+        afirma(
+            "· the Hall gets the same domain-first catalogue as the terminal",
+            st == 200
+            and dominios[0]["id"] == "software"
+            and any(d["id"] == "healthcare" for d in dominios),
+            str(dominios),
+        )
+        roles_salud = json.loads(pide(puerto, "/api/roles?domain=healthcare")[1])["roles"]
+        afirma(
+            "· selecting medicine replaces the software role grid",
+            roles_salud[0]["id"] == "clinical-director"
+            and not any(r["id"] == "dev" for r in roles_salud),
+            str(roles_salud),
+        )
+        roles_agente = json.loads(pide(puerto, "/api/roles?scope=agent")[1])["roles"]
+        ids_agente = {r["id"] for r in roles_agente}
+        afirma(
+            "· a repo agent can adopt a role outside the city domain",
+            {"blank", "seo", "po", "data-engineer"} <= ids_agente
+            and any("marketing" in r["domains"] for r in roles_agente if r["id"] == "seo"),
+            str(roles_agente),
+        )
+
+        # ── the town hall ───────────────────────────────────────────────────
+        print("  the town hall")
+        st, cuerpo = pide(puerto, "/")
+        afirma(
+            "· / serves the hall, token injected",
+            st == 200 and b"town hall" in cuerpo and b"__PASE__" not in cuerpo,
+        )
+        afirma(
+            "· the spectator panel is a moderated conversation with avatars and quiet work",
+            b"A moderated conversation over the WebSocket bus" in cuerpo
+            and b'id="liveWorkToggle"' in cuerpo
+            and b'id="liveContext"' in cuerpo
+            and b".liveAvatar" in cuerpo,
+            cuerpo[:500].decode(errors="replace"),
+        )
+        map_html = open(os.path.join(RAIZ, "city", "web", "index.html")).read()
+        hall_source = open(os.path.join(RAIZ, "city", "web", "src", "hall.ts")).read()
+        speech_source = open(os.path.join(RAIZ, "city", "web", "src", "game-speech.ts")).read()
+        afirma(
+            "· the city owns the whole central canvas; persistent HUD stays in sidebars",
+            '<main aria-label="City map"></main>' in map_html
+            and map_html.index('id="cinta"') < map_html.index('<main aria-label="City map"')
+            and map_html.index('id="mandos"') < map_html.index('<main aria-label="City map"')
+            and map_html.index('id="peli"') < map_html.index('<main aria-label="City map"')
+            and map_html.index('id="ficha"') > map_html.index('<aside id="avisos"')
+            and "#cinta{position:absolute" not in map_html
+            and "#peli{position:absolute" not in map_html,
+        )
+        afirma(
+            "· the Hall embeds only the canvas and forwards the same live WebSocket event",
+            "let SECCION = 'mapa'" in hall_source
+            and "mapUrl.searchParams.set('embed', '1')" in hall_source
+            and "mapUrl.searchParams.set('parent_origin', location.origin)" in hall_source
+            and "MAP_ACTIVITY_PROTOCOL" in hall_source
+            and "enviaActividadAlMapa(event)" in hall_source,
+        )
+        afirma(
+            "· game speech is anchored to a real actor and starts with its recipient",
+            "speech.target.getBounds()" in speech_source
+            and "`Para ${speechRecipient(event)}:`" in speech_source
+            and "compactSpeech(event.summary)" in speech_source,
+        )
+        st, cuerpo = pide(puerto, "/hall.js")
+        if st == 200:
+            afirma(
+                "· the hall code is served, typed and built",
+                b"town hall" in cuerpo or len(cuerpo) > 1000,
+            )
+        else:
+            afirma(
+                "· an unbuilt hall says how to build it, not just 404",
+                st == 404 and b"npm" in cuerpo,
+                f"{st}: {cuerpo[:120]!r}",
+            )
+        # And the unbuilt branch, deterministically.
+        js_real = serve.HALL_JS
+        serve.HALL_JS = "/definitely/not/built/hall.js"
+        st, cuerpo = pide(puerto, "/hall.js")
+        afirma(
+            "· missing build is a 404 with the build command",
+            st == 404 and b"npm run build" in cuerpo,
+            f"{st}: {cuerpo[:120]!r}",
+        )
+        serve.HALL_JS = js_real
+
+        st, cuerpo = pide(puerto, "/wizard")
+        afirma("· the v1 multiple-person wizard is retired", st == 404 and b"retired" in cuerpo)
+        st, _ = pide(puerto, "/api/escribe", metodo="POST", cuerpo={})
+        comprueba("· its multiple-person write endpoint is retired too", st, 404)
+
+        st, cuerpo = pide(puerto, "/api/estado")
+        estado = json.loads(cuerpo)
+        comprueba("· estado answers for an empty city", st, 200)
+        comprueba(
+            "· with no cards, no houses, no districts",
+            (estado["tarjetas"], estado["parcelas"], estado["unidades"]),
+            ([], [], []),
+        )
+        comprueba("· and no invented committee history", estado["deliberations"], [])
+        afirma("· and it knows who is asking", bool(estado["yo"]), repr(estado["yo"]))
+        owner, address = estado["yo"], estado["address"]
+        afirma(
+            "· its public road invitation contains no credential",
+            estado["invitation"]["address"] == address
+            and estado["invitation"]["domain"] == "software"
+            and not any("token" in k.lower() for k in estado["invitation"]),
+        )
+
+        # Committee acts are read-only local state in the Hall.
+        act_id = "delib_20260826120000_abcd1234"
+        act_dir = os.path.join(hallDatos, "deliberations", act_id)
+        os.makedirs(act_dir)
+        open(os.path.join(act_dir, "ACT.md"), "w").write("# Ship?\n")
+        open(os.path.join(act_dir, "state.json"), "w").write(
+            json.dumps(
+                {
+                    "schema": "agents-city/deliberation@1",
+                    "id": act_id,
+                    "status": "verifying",
+                    "updatedAt": "2026-08-26T12:00:00Z",
+                    "brief": {
+                        "question": "Ship?",
+                        "desiredOutcome": "A verified answer",
+                        "participants": ["api", "web"],
+                    },
+                    "positions": {"api": {}},
+                    "progress": {"revision": 2},
+                    "decisions": [
+                        {
+                            "outcome": "Ship after replay",
+                            "verifier": "ops",
+                            "decisiveContributors": ["api"],
+                        }
+                    ],
+                }
+            )
+        )
+        acts = json.loads(pide(puerto, "/api/estado")[1])["deliberations"]
+        afirma(
+            "· the Hall shows durable committee progress without mutating it",
+            len(acts) == 1
+            and acts[0]["id"] == act_id
+            and acts[0]["received"] == 1
+            and acts[0]["verifier"] == "ops"
+            and acts[0]["contributors"] == ["api"],
+            str(acts),
+        )
+
+        # A seat written through the hall is the same card as everywhere else.
+        st, cuerpo = pide(
+            puerto,
+            "/api/ficha",
+            metodo="POST",
+            cuerpo={
+                "user": "Ana.López@x.com",
+                "domain": "healthcare",
+                "role": "clinical-director",
+                "repos": ["api"],
+                "repo_roles": {"api": "seo"},
+                "objetivo": {
+                    "title": "One goal",
+                    "signal": "s",
+                    "command": "",
+                    "baseline": "0",
+                    "target": "1",
+                    "by": "Q3",
+                },
+            },
+        )
+        r = json.loads(cuerpo)
+        comprueba("· a card is written through the hall", st, 200)
+        comprueba("· body.user cannot create a second person in the city", r["user"], owner)
+        c = card.lee(os.path.join(hallDatos, f"{owner}.md"))
+        comprueba(
+            "· and reads back through the shared reader",
+            (c["agent"], c["role"], c["repos"], c["repo_roles"]),
+            (address, "clinical-director", ["api"], {"api": "seo"}),
+        )
+        estado_salud = json.loads(pide(puerto, "/api/estado")[1])
+        afirma(
+            "· domain and role knowledge land transparently in the city",
+            estado_salud["domain"] == "healthcare"
+            and os.path.isfile(os.path.join(hallDatos, "domains", "healthcare.md"))
+            and os.path.isfile(os.path.join(hallDatos, "roles", "clinical-director.md"))
+            and os.path.isfile(os.path.join(hallDatos, "roles", "seo.md")),
+        )
+        afirma(
+            "· the live capability view exposes the repo agent role",
+            estado_salud["skills"]["api"]["role"] == "seo",
+            str(estado_salud["skills"]),
+        )
+        comprueba(
+            "· roads can route by public domain and seat role",
+            (estado_salud["invitation"]["domain"], estado_salud["invitation"]["role"]),
+            ("healthcare", "clinical-director"),
+        )
+        comprueba(
+            "· an empty command is manual, not an empty string to run", c["objetivo"]["command"], ""
+        )
+
+        st, cuerpo = pide(
+            puerto,
+            "/api/ficha",
+            metodo="POST",
+            cuerpo={
+                "domain": "healthcare",
+                "role": "clinical-director",
+                "repos": ["api"],
+                "repo_roles": [],
+            },
+        )
+        afirma(
+            "· malformed repo-role mappings are a visible 400",
+            st == 400 and "repo_roles must be an object" in json.loads(cuerpo)["error"],
+            cuerpo.decode(),
+        )
+
+        # A goal with no title is no goal, not a goal called nothing.
+        pide(
+            puerto,
+            "/api/ficha",
+            metodo="POST",
+            cuerpo={
+                "user": "bo@x.com",
+                "domain": "healthcare",
+                "role": "clinical-director",
+                "repos": [],
+                "objetivo": {"title": "   "},
+            },
+        )
+        comprueba(
+            "· a blank goal title means no goal",
+            card.lee(os.path.join(hallDatos, f"{owner}.md"))["objetivo"],
+            None,
+        )
+
+        # Districts: the wrong shape is a 400 the page can show, the right one
+        # round-trips through the shared reader.
+        st, _ = pide(puerto, "/api/unidades", metodo="POST", cuerpo={"unidades": "banking"})
+        comprueba("· districts as a string is a 400, not a crash", st, 400)
+        st, _ = pide(
+            puerto, "/api/unidades", metodo="POST", cuerpo={"unidades": [{"name": "no id"}]}
+        )
+        comprueba("· a district with no id, likewise", st, 400)
+        st, cuerpo = pide(
+            puerto,
+            "/api/unidades",
+            metodo="POST",
+            cuerpo={"unidades": [{"id": "Banca Digital", "name": "Banca", "color": "#3FB8A0"}]},
+        )
+        r = json.loads(cuerpo)
+        comprueba("· a real district is written and cleaned", st, 200)
+        comprueba(
+            "· id slugged, colour lowered",
+            (r["unidades"][0]["id"], r["unidades"][0]["color"]),
+            ("banca-digital", "3fb8a0"),
+        )
+
+        # Houses: same deal.
+        st, _ = pide(puerto, "/api/parcelas", metodo="POST", cuerpo={"repos": ["x"]})
+        comprueba("· houses as a list is a 400", st, 400)
+        st, cuerpo = pide(
+            puerto,
+            "/api/parcelas",
+            metodo="POST",
+            cuerpo={
+                "repos": {
+                    "api": [
+                        {"ruta": "src/**", "unidad": "banca-digital", "nombre": "api · src"},
+                        {"ruta": "", "unidad": "none", "nombre": "api · rest"},
+                    ]
+                },
+                "lab": ["lab-x"],
+            },
+        )
+        r = json.loads(cuerpo)
+        comprueba(
+            "· a split repo round-trips through the shared reader",
+            [(p["id"], p["unidad"]) for p in r["parcelas"]],
+            [("api:src/**", "banca-digital"), ("api", "none")],
+        )
+        # And estado now reflects all of it — the page repaints from this.
+        estado = json.loads(pide(puerto, "/api/estado")[1])
+        comprueba(
+            "· estado sees one seat, two houses, one district",
+            (
+                len(estado["tarjetas"]),
+                len(estado["parcelas"]),
+                len(estado["unidades"]),
+                estado["lab"],
+            ),
+            (1, 2, 1, ["lab-x"]),
+        )
+
+        # ── several cities and their roads through one hall ────────────────
+        st, cuerpo = pide(puerto, "/api/ciudades", metodo="POST", cuerpo={"name": "Otra"})
+        creada = json.loads(cuerpo)
+        afirma(
+            "· the hall creates another city below the same user",
+            st == 200 and creada.get("address") == "halltest/otra",
+            str(creada),
+        )
+        otra = creada["city"]
+        est1 = json.loads(pide(puerto, "/api/estado")[1])
+        est2 = json.loads(pide(puerto, "/api/estado?city=" + otra)[1])
+        comprueba(
+            "· ?city= switches which city the hall manages",
+            (est1["datos"] != est2["datos"], os.path.realpath(otra) == est2["datos"]),
+            (True, True),
+        )
+        afirma(
+            "· the session name follows the city, so attach commands are right",
+            est2["sesion"].endswith("-otra") and not est1["sesion"].endswith("-otra"),
+            f"{est1['sesion']} / {est2['sesion']}",
+        )
+        afirma(
+            "· and the switcher gets the list with the current one marked",
+            any(c["actual"] for c in est2["ciudades"]),
+        )
+        st, cuerpo = pide(
+            puerto,
+            "/api/roads",
+            metodo="POST",
+            cuerpo={"action": "connect", "target": est2["city_id"]},
+        )
+        r = json.loads(cuerpo)
+        afirma(
+            "· opening a local road writes the current endpoint",
+            st == 200 and r["roads"][0]["address"] == "halltest/otra",
+            str(r),
+        )
+        otra_estado = json.loads(pide(puerto, "/api/estado?city=" + otra)[1])
+        afirma(
+            "· and the other endpoint is symmetric",
+            otra_estado["roads"][0]["id"] == est1["city_id"],
+            str(otra_estado["roads"]),
+        )
+        st, cuerpo = pide(
+            puerto,
+            "/api/roads",
+            metodo="POST",
+            cuerpo={"action": "disconnect", "target": est2["city_id"]},
+        )
+        afirma(
+            "· closing it removes both endpoints",
+            st == 200
+            and json.loads(cuerpo)["roads"] == []
+            and json.loads(pide(puerto, "/api/estado?city=" + otra)[1])["roads"] == [],
+        )
+        # A write follows the same request's city — never the default's.
+        pide(
+            puerto,
+            "/api/unidades?city=" + otra,
+            metodo="POST",
+            cuerpo={"unidades": [{"id": "u1", "name": "U1", "color": "aabbcc"}]},
+        )
+        afirma(
+            "· a save lands in the requested city, not the default",
+            os.path.exists(os.path.join(otra, "units.yml"))
+            and "u1" in open(os.path.join(otra, "units.yml")).read(),
+        )
+        afirma(
+            "· and the default city was not touched by it",
+            not os.path.exists(os.path.join(hallDatos, "units.yml"))
+            or "u1" not in open(os.path.join(hallDatos, "units.yml")).read(),
+        )
+        shutil.rmtree(otra)
+
+        # ── the demo's remote control ────────────────────────────────────────
+        print("  the demo's remote control")
+        # Which story a demo replays comes from its city.yml domain AS WRITTEN.
+        # The registry normalises unknown domains to software, which is exactly
+        # how the clinic once replayed Aurora's night instead of its own
+        # morning — this is that bug's tombstone.
+        comprueba(
+            "· each packaged demo city replays its own domain's story",
+            [
+                serve.historia_del_demo(os.path.join(RAIZ, "demo", d))
+                for d in ("city", "clinica", "despacho")
+            ],
+            ["software", "medicina", "legal"],
+        )
+        comprueba(
+            "· a demo with an unknown or missing domain falls back to software",
+            serve.historia_del_demo(tempfile.mkdtemp()),
+            "software",
+        )
+        # The control verbs, against a city dressed as a demo. `restart` is NOT
+        # exercised live on purpose: it spawns the real storyteller against the
+        # real bus; its story choice and its 403 on real cities are covered.
+        with open(os.path.join(hallDatos, "city.yml"), "w", encoding="utf-8") as f:
+            f.write("id: city_demo_test_v1\nname: Test Demo\nslug: test-demo\nowner: halltest\n")
+        st, _ = pide(puerto, "/api/demo", metodo="POST", cuerpo={"action": "volar"})
+        comprueba("· an unknown control verb is a 400, not a surprise", st, 400)
+        st, cuerpo_demo = pide(puerto, "/api/demo", metodo="POST", cuerpo={"action": "status"})
+        estado_demo = json.loads(cuerpo_demo)
+        afirma(
+            "· status answers honestly when nothing is playing",
+            st == 200 and estado_demo.get("ok") and not estado_demo.get("running"),
+            str(estado_demo),
+        )
+        st, cuerpo_demo = pide(puerto, "/api/demo", metodo="POST", cuerpo={"action": "pause"})
+        estado_demo = json.loads(cuerpo_demo)
+        afirma(
+            "· pausing silence is a safe no-op, never a crash",
+            st == 200 and not estado_demo.get("running") and not estado_demo.get("paused"),
+            str(estado_demo),
+        )
+        os.unlink(os.path.join(hallDatos, "city.yml"))
+
+        # ── the agents' character sheets ─────────────────────────────────────
+        print("  the agents' character sheets")
+        # An agents-first card: a knowledge agent with its workspace on disk,
+        # so discovery, growth and the engine keys all have something real.
+        taller = os.path.join(hallDatos, "agents", "notas")
+        os.makedirs(taller, exist_ok=True)
+        open(os.path.join(taller, "apuntes.md"), "w").write("# notas\n")
+        with open(os.path.join(hallDatos, "halltest.md"), "w", encoding="utf-8") as f:
+            f.write(
+                "---\n"
+                "user: halltest\nname: Hall Test\nrole: cpto\nagent: halltest/seat\n"
+                "agents: [notas]\nkind.notas: knowledge\nrole.notas: apuntes\n"
+                "runs.notas: claude\nmodel.notas: opus\neffort.notas: high\n"
+                "goals_defined: true\n---\n"
+            )
+        st, cuerpo = pide(puerto, "/api/estado")
+        estado = json.loads(cuerpo)
+        hoja = next((x for x in estado.get("agents", []) if x["name"] == "notas"), None)
+        afirma(
+            "· the sheet carries kind, engine and growth — all read, none invented",
+            st == 200
+            and hoja is not None
+            and hoja["kind"] == "knowledge"
+            and hoja["runtime"] == "claude"
+            and hoja["model"] == "opus"
+            and hoja["effort"] == "high"
+            and hoja["growth"]["floors"] >= 1,
+            str(hoja),
+        )
+        afirma(
+            "· an agents-first agent is discovered with a face and a skills entry",
+            "notas" in estado.get("avatars", {}) and "notas" in estado.get("skills", {}),
+            str(sorted(estado.get("skills", {}).keys())),
+        )
+        st, cuerpo = pide(
+            puerto, "/api/agente", metodo="POST", cuerpo={"agent": "notas", "model": "haiku"}
+        )
+        respuesta = json.loads(cuerpo)
+        carta = open(os.path.join(hallDatos, "halltest.md"), encoding="utf-8").read()
+        afirma(
+            "· happy: tuning the engine persists to the card key the launcher reads",
+            st == 200 and respuesta["agent"]["model"] == "haiku" and "model.notas: haiku" in carta,
+            carta,
+        )
+        st, cuerpo = pide(
+            puerto, "/api/agente", metodo="POST", cuerpo={"agent": "notas", "model": ""}
+        )
+        carta = open(os.path.join(hallDatos, "halltest.md"), encoding="utf-8").read()
+        afirma(
+            "· happy: an empty value removes the key — back to the owner's default",
+            st == 200 and "model.notas" not in carta,
+            carta,
+        )
+        st, _ = pide(
+            puerto, "/api/agente", metodo="POST", cuerpo={"agent": "nadie", "model": "opus"}
+        )
+        comprueba("· non-happy: an unknown agent is a 404, never a write", st, 404)
+        st, _ = pide(
+            puerto, "/api/agente", metodo="POST", cuerpo={"agent": "notas", "effort": "turbo"}
+        )
+        comprueba("· non-happy: an invented effort level is refused", st, 400)
+        st, _ = pide(
+            puerto,
+            "/api/agente",
+            metodo="POST",
+            cuerpo={"agent": "notas", "model": "opus; rm -rf /"},
+        )
+        comprueba("· non-happy: a model value is an alias, never a shell fragment", st, 400)
+        st, cuerpo = pide(
+            puerto, "/api/agente", metodo="POST", cuerpo={"agent": "notas", "runtime": "codex"}
+        )
+        carta = open(os.path.join(hallDatos, "halltest.md"), encoding="utf-8").read()
+        afirma(
+            "· happy: the provider is a card key too",
+            st == 200 and "runs.notas: codex" in carta,
+            carta,
+        )
+        st, _ = pide(
+            puerto,
+            "/api/agente",
+            metodo="POST",
+            cuerpo={"agent": "notas", "runtime": "terminal:sh"},
+        )
+        comprueba("· non-happy: the web never plants a terminal command", st, 400)
+        st, cuerpo = pide(
+            puerto, "/api/agente", metodo="POST", cuerpo={"agent": "notas", "avatar": "abc123"}
+        )
+        cara_nueva = json.loads(cuerpo)["agent"]["avatar"]
+        st2, cuerpo2 = pide(
+            puerto, "/api/agente", metodo="POST", cuerpo={"agent": "notas", "avatar": ""}
+        )
+        afirma(
+            "· happy: a face reroll is a seed on the card, and clearing it restores the classic",
+            st == 200
+            and st2 == 200
+            and cara_nueva != json.loads(cuerpo2)["agent"]["avatar"],
+            "",
+        )
+        st, _ = pide(
+            puerto, "/api/agente", metodo="POST", cuerpo={"agent": "notas", "avatar": "MAL$SEED"}
+        )
+        comprueba("· non-happy: an avatar seed is short and plain", st, 400)
+        # A 400 must never be an answer that already mutated the card: the
+        # handler once wrote field-by-field, so a valid model landed before an
+        # invalid effort was refused.
+        pide(puerto, "/api/agente", metodo="POST", cuerpo={"agent": "notas", "model": "sonnet"})
+        st, _ = pide(
+            puerto,
+            "/api/agente",
+            metodo="POST",
+            cuerpo={"agent": "notas", "model": "haiku", "effort": "turbo"},
+        )
+        carta = open(os.path.join(hallDatos, "halltest.md"), encoding="utf-8").read()
+        afirma(
+            "· non-happy: a refused edit leaves the whole card untouched",
+            st == 400 and "model.notas: sonnet" in carta and "haiku" not in carta,
+            carta,
+        )
+        pide(puerto, "/api/agente", metodo="POST", cuerpo={"agent": "notas", "model": ""})
+
+        # ── instructions and skills, into the agent's own home ──────────────
+        print("  instructions and skills, written only into the agent's own home")
+        st, cuerpo = pide(puerto, "/api/instrucciones?agent=notas&file=CLAUDE.md")
+        antes = json.loads(cuerpo)
+        afirma(
+            "· happy: a missing instruction file reads honestly as absent, with its reader",
+            st == 200 and antes["exists"] is False and antes["reader"] == "claude",
+            str(antes),
+        )
+        st, _ = pide(
+            puerto,
+            "/api/instrucciones",
+            metodo="POST",
+            cuerpo={"agent": "notas", "file": "CLAUDE.md", "content": "# Notas\nSé breve.\n"},
+        )
+        st2, cuerpo = pide(puerto, "/api/instrucciones?agent=notas&file=CLAUDE.md")
+        despues = json.loads(cuerpo)
+        afirma(
+            "· happy: written atomically into the workspace and read back verbatim",
+            st == 200 and st2 == 200 and despues["exists"] and "Sé breve." in despues["content"],
+            str(despues),
+        )
+        st, _ = pide(puerto, "/api/instrucciones?agent=notas&file=HACK.md")
+        comprueba("· non-happy: only CLAUDE.md and AGENTS.md exist here", st, 400)
+        # A latin-1 CLAUDE.md once escaped the handler as a UnicodeDecodeError
+        # and dropped the connection; and `exists: false` would be worse — the
+        # editor would save over what it could not read.
+        with open(os.path.join(taller, "CLAUDE.md"), "wb") as f:
+            f.write("Triaje: café\n".encode("latin-1"))
+        st, cuerpo = pide(puerto, "/api/instrucciones?agent=notas&file=CLAUDE.md")
+        afirma(
+            "· non-happy: a non-UTF-8 file is a JSON refusal, never a dropped connection",
+            st == 409 and "not UTF-8" in json.loads(cuerpo).get("error", ""),
+            cuerpo.decode(errors="replace"),
+        )
+        pide(
+            puerto,
+            "/api/instrucciones",
+            metodo="POST",
+            cuerpo={"agent": "notas", "file": "CLAUDE.md", "content": "# Notas\nSé breve.\n"},
+        )
+        st, _ = pide(
+            puerto,
+            "/api/instrucciones",
+            metodo="POST",
+            cuerpo={"agent": "nadie", "file": "CLAUDE.md", "content": "x"},
+        )
+        comprueba("· non-happy: an unknown agent gets no file", st, 404)
+
+        import base64 as _b64
+        import io as _io
+        import zipfile as _zip
+
+        def zipea(entradas, enlace=None):
+            crudo = _io.BytesIO()
+            with _zip.ZipFile(crudo, "w") as z:
+                for nombre, contenido in entradas:
+                    z.writestr(nombre, contenido)
+                if enlace:
+                    info = _zip.ZipInfo(enlace)
+                    info.external_attr = (0o120777 << 16)
+                    z.writestr(info, "/etc/passwd")
+            return _b64.b64encode(crudo.getvalue()).decode()
+
+        bueno = zipea([("mi-skill/SKILL.md", "---\nname: mi-skill\n---\nhola"),
+                       ("mi-skill/extra.md", "más")])
+        st, cuerpo = pide(
+            puerto, "/api/skill", metodo="POST", cuerpo={"agent": "notas", "zip": bueno}
+        )
+        st2, cuerpo2 = pide(puerto, "/api/estado")
+        skills_notas = json.loads(cuerpo2)["skills"].get("notas", {}).get("skills", [])
+        afirma(
+            "· happy: an uploaded skill lands in the agent's home and is discovered live",
+            st == 200 and any(s["name"] == "mi-skill" for s in skills_notas),
+            str(skills_notas),
+        )
+        st, _ = pide(
+            puerto, "/api/skill", metodo="POST", cuerpo={"agent": "notas", "zip": bueno}
+        )
+        comprueba("· non-happy: installing over an existing skill is refused", st, 409)
+        st, _ = pide(
+            puerto,
+            "/api/skill",
+            metodo="POST",
+            cuerpo={"agent": "notas", "zip": zipea([("../fuera/SKILL.md", "x")])},
+        )
+        comprueba("· non-happy: a zip that tries to escape its folder is refused", st, 400)
+        st, _ = pide(
+            puerto,
+            "/api/skill",
+            metodo="POST",
+            cuerpo={
+                "agent": "notas",
+                "zip": zipea([("liada/SKILL.md", "x")], enlace="liada/mala"),
+            },
+        )
+        comprueba("· non-happy: symlinks inside a skill are refused", st, 400)
+        st, _ = pide(
+            puerto,
+            "/api/skill",
+            metodo="POST",
+            cuerpo={"agent": "notas", "name": "sin-manifiesto", "zip": zipea([("leeme.md", "x")])},
+        )
+        comprueba("· non-happy: a skill is a folder with a SKILL.md, or nothing", st, 400)
+        st, _ = pide(
+            puerto, "/api/skill", metodo="POST", cuerpo={"agent": "notas", "remove": "mi-skill"}
+        )
+        st2, cuerpo2 = pide(puerto, "/api/estado")
+        skills_notas = json.loads(cuerpo2)["skills"].get("notas", {}).get("skills", [])
+        afirma(
+            "· happy: removing an installed skill empties exactly its folder",
+            st == 200 and not any(s["name"] == "mi-skill" for s in skills_notas),
+            str(skills_notas),
+        )
+        st, _ = pide(
+            puerto, "/api/skill", metodo="POST", cuerpo={"agent": "notas", "remove": "fantasma"}
+        )
+        comprueba("· non-happy: removing a skill that is not there is a 404", st, 404)
+
+        # The 14 MB cap bounds the upload; only the extraction budget bounds
+        # what a hostile deflate ratio inflates it to on disk. 80 MB of zeros
+        # deflates to under 100 KB — small on the wire, huge when it lands.
+        crudo_bomba = _io.BytesIO()
+        with _zip.ZipFile(crudo_bomba, "w", _zip.ZIP_DEFLATED) as z:
+            z.writestr("boom/SKILL.md", "---\nname: boom\n---\n")
+            z.writestr("boom/ceros.bin", b"\0" * (80 * 1024 * 1024))
+        st, cuerpo = pide(
+            puerto,
+            "/api/skill",
+            metodo="POST",
+            cuerpo={
+                "agent": "notas",
+                "zip": _b64.b64encode(crudo_bomba.getvalue()).decode(),
+            },
+        )
+        afirma(
+            "· non-happy: a zip bomb is refused by its decompressed size, not its upload size",
+            st == 400 and "inflates too large" in json.loads(cuerpo).get("error", ""),
+            cuerpo.decode(errors="replace"),
+        )
+        # A zip whose entries collide (a file, then a directory of the same
+        # name) once killed the handler mid-write and its debris 409'd every
+        # retry until deleted by hand.
+        st, _ = pide(
+            puerto,
+            "/api/skill",
+            metodo="POST",
+            cuerpo={
+                "agent": "notas",
+                "zip": zipea([("s/SKILL.md", "---\nname: s\n---\n"), ("s/f", "x"), ("s/f/g", "y")]),
+            },
+        )
+        st2, _ = pide(
+            puerto,
+            "/api/skill",
+            metodo="POST",
+            cuerpo={"agent": "notas", "zip": zipea([("s/SKILL.md", "---\nname: s\n---\n")])},
+        )
+        afirma(
+            "· non-happy: a colliding zip is a 400 that cleans up — the retry installs fine",
+            st == 400 and st2 == 200,
+            f"{st}/{st2}",
+        )
+        pide(puerto, "/api/skill", metodo="POST", cuerpo={"agent": "notas", "remove": "s"})
+        # Removal is keyed on the FOLDER, and the sheet is told which skills the
+        # Hall itself could remove: a SKILL.md display name is free to differ,
+        # and a repo's committed skill is the repo's property — no × for it.
+        pide(
+            puerto,
+            "/api/skill",
+            metodo="POST",
+            cuerpo={
+                "agent": "notas",
+                "zip": zipea([("deploy-tools/SKILL.md", "---\nname: deploy\n---\n")]),
+            },
+        )
+        with open(os.path.join(taller, "SKILL.md"), "w", encoding="utf-8") as f:
+            f.write("---\nname: del-repo\n---\n")
+        st, cuerpo = pide(puerto, "/api/estado")
+        skills_notas = json.loads(cuerpo)["skills"].get("notas", {}).get("skills", [])
+        subida = next((s for s in skills_notas if s["name"] == "deploy"), None)
+        del_repo = next((s for s in skills_notas if s["name"] == "del-repo"), None)
+        afirma(
+            "· happy: an installed skill is marked removable, keyed on its folder",
+            subida is not None
+            and subida.get("removable") is True
+            and subida.get("dir") == "deploy-tools",
+            str(subida),
+        )
+        afirma(
+            "· a skill committed elsewhere in the home is discovered but never removable",
+            del_repo is not None and not del_repo.get("removable"),
+            str(del_repo),
+        )
+        st, _ = pide(
+            puerto, "/api/skill", metodo="POST", cuerpo={"agent": "notas", "remove": "deploy"}
+        )
+        comprueba("· non-happy: the display name is not the folder — a 404, never a guess", st, 404)
+        st, _ = pide(
+            puerto, "/api/skill", metodo="POST", cuerpo={"agent": "notas", "remove": "deploy-tools"}
+        )
+        comprueba("· happy: removal by folder name removes exactly that folder", st, 200)
+        os.unlink(os.path.join(taller, "SKILL.md"))
+        # A repo can commit `.claude/skills` as a symlink to anywhere this user
+        # can write — the global skills folder included. Both the install and
+        # the rmtree once followed it out of the agent's home.
+        raiz_skills = os.path.join(taller, ".claude", "skills")
+        shutil.rmtree(raiz_skills, ignore_errors=True)
+        fuera_de_casa = tempfile.mkdtemp()
+        os.symlink(fuera_de_casa, raiz_skills)
+        st, _ = pide(
+            puerto,
+            "/api/skill",
+            metodo="POST",
+            cuerpo={"agent": "notas", "zip": zipea([("fuga/SKILL.md", "---\nname: fuga\n---\n")])},
+        )
+        st2, _ = pide(
+            puerto, "/api/skill", metodo="POST", cuerpo={"agent": "notas", "remove": "fuga"}
+        )
+        afirma(
+            "· non-happy: a symlinked .claude/skills is refused for install and removal alike",
+            st == 409 and st2 == 409 and not os.listdir(fuera_de_casa),
+            f"{st}/{st2}/{os.listdir(fuera_de_casa)}",
+        )
+        os.unlink(raiz_skills)
+        shutil.rmtree(fuera_de_casa, ignore_errors=True)
+
+        # ── the engine's traffic light and its test button ───────────────────
+        print("  the engine's traffic light, derived and never guessed")
+        # A fake binary makes the light deterministic on any machine, CI included.
+        cajon = tempfile.mkdtemp()
+        falso = os.path.join(cajon, "kimi")
+        with open(falso, "w") as f:
+            f.write('#!/bin/sh\necho "kimi 9.9.9"\n')
+        os.chmod(falso, 0o755)
+        ruta_previa = os.environ["PATH"]
+        os.environ["PATH"] = cajon + os.pathsep + ruta_previa
+        try:
+            pide(puerto, "/api/agente", metodo="POST", cuerpo={"agent": "notas", "runtime": "kimi"})
+            st, cuerpo = pide(puerto, "/api/estado")
+            hoja = next(x for x in json.loads(cuerpo)["agents"] if x["name"] == "notas")
+            afirma(
+                "· yellow: the binary exists and the agent's window is not running",
+                st == 200
+                and hoja["cli"]["binary"] == "kimi"
+                and hoja["cli"]["installed"] is True
+                and hoja["cli"]["connected"] is False,
+                str(hoja["cli"]),
+            )
+            st, cuerpo = pide(puerto, "/api/motor", metodo="POST", cuerpo={"agent": "notas"})
+            prueba = json.loads(cuerpo)
+            afirma(
+                "· happy: the test button runs the real binary and reports its version",
+                st == 200 and prueba["ok"] is True and "9.9.9" in prueba.get("version", ""),
+                str(prueba),
+            )
+            os.environ["PATH"] = cajon  # only the fake folder: kimi gone nowhere, others missing
+            os.remove(falso)
+            st, cuerpo = pide(puerto, "/api/motor", metodo="POST", cuerpo={"agent": "notas"})
+            prueba = json.loads(cuerpo)
+            afirma(
+                "· red: a missing binary is an honest answer, not an HTTP error",
+                st == 200 and prueba["ok"] is False and "not on this machine" in prueba["detail"],
+                str(prueba),
+            )
+            st, _ = pide(puerto, "/api/motor", metodo="POST", cuerpo={"agent": "nadie"})
+            comprueba("· non-happy: testing an unknown agent is a 404", st, 404)
+        finally:
+            os.environ["PATH"] = ruta_previa
+            shutil.rmtree(cajon, ignore_errors=True)
+
+        # ── regressions pinned by review ─────────────────────────────────────
+        print("  review regressions, pinned")
+        # tmux prefix-matches session names: bare `-t home` also matches
+        # `home-2`, lighting the green dot from a different city's windows.
+        fuente = open(os.path.join(AQUI, "serve.py"), encoding="utf-8").read()
+        afirma(
+            "· ventanas_vivas asks tmux for an exact session match",
+            '"=" + cities.sesion(owner, datos)' in fuente,
+        )
+        # An 80-char slug is a legal window name; a 64-char cap on the resolver
+        # made every sheet action 404 while the sheet itself rendered fine.
+        largo = "l" * 70
+        with open(os.path.join(hallDatos, "halltest.md"), "w", encoding="utf-8") as f:
+            f.write(
+                "---\n"
+                "user: halltest\nname: Hall Test\nrole: cpto\nagent: halltest/seat\n"
+                f"agents: [notas, {largo}]\nkind.notas: knowledge\n"
+                "goals_defined: true\n---\n"
+            )
+        st, cuerpo = pide(
+            puerto, "/api/agente", metodo="POST", cuerpo={"agent": largo, "model": "haiku"}
+        )
+        afirma(
+            "· a 65-80 char slug can use its sheet's actions, not only render it",
+            st == 200 and json.loads(cuerpo)["agent"]["slug"] == largo,
+            cuerpo.decode(errors="replace")[:200],
+        )
+        # Two names that slug to one identity: the card tools raise loudly;
+        # the Hall and read-only discovery must degrade, never traceback.
+        import capabilities as _cap
+
+        with open(os.path.join(hallDatos, "halltest.md"), "w", encoding="utf-8") as f:
+            f.write(
+                "---\nuser: halltest\nname: Hall Test\nrole: cpto\nagent: halltest/seat\n"
+                "agents: [store-service, store_service]\ngoals_defined: true\n---\n"
+            )
+        comprueba(
+            "· skills discovery over a slug-colliding card lists nothing, crashes nothing",
+            _cap.descubre_ciudad(hallDatos),
+            {},
+        )
+        st, cuerpo = pide(puerto, "/api/estado")
+        afirma(
+            "· /api/estado still answers over a slug-colliding card",
+            st == 200 and json.loads(cuerpo).get("agents") == [],
+            cuerpo.decode(errors="replace")[:200],
+        )
+        # The Hall binds loopback without the stdlib's socket.getfqdn() call:
+        # a reverse DNS lookup for a cosmetic name, which on an unanswered
+        # resolver stalls the server's start for tens of seconds.
+        import socket as _socket
+        import threading as _th
+        import time as _time
+
+        _fqdn = _socket.getfqdn
+        _socket.getfqdn = lambda *a: _time.sleep(60) or "nunca"
+        otro = {}
+        try:
+            atado = _th.Event()
+
+            def _ata():
+                otro["s"] = serve.Servidor(("127.0.0.1", 0), serve.Manejador)
+                atado.set()
+
+            _th.Thread(target=_ata, daemon=True).start()
+            afirma("· the Hall binds without waiting on reverse DNS", atado.wait(timeout=5))
+        finally:
+            _socket.getfqdn = _fqdn
+            if otro.get("s"):
+                otro["s"].server_close()
+
+        # A code agent's growth reads real local git history — merge commits
+        # as floors — instead of answering zero for lack of a counter.
+        import subprocess as _sp
+        import types as _types
+
+        repo = tempfile.mkdtemp()
+        for orden in (
+            ["git", "init", "-q"],
+            ["git", "-c", "user.email=t@t", "-c", "user.name=t",
+             "commit", "--allow-empty", "-q", "-m", "uno"],
+            ["git", "-c", "user.email=t@t", "-c", "user.name=t",
+             "commit", "--allow-empty", "-q", "-m", "dos"],
+        ):
+            _sp.run(orden, cwd=repo, capture_output=True)
+        obrero = _types.SimpleNamespace(
+            nombre="obrero", slug="obrero", legacy=False, workspace=repo, mounts=[]
+        )
+        prs, commits, act = serve.contador_git_local(obrero, hallDatos)
+        afirma(
+            "· the sheet's git counter reads real local history, no network",
+            prs == 0 and commits == 2 and act == 2,
+            f"{prs}/{commits}/{act}",
+        )
+        shutil.rmtree(repo, ignore_errors=True)
+
+        # /api/sesion is NOT exercised live on purpose: it spawns tmux windows
+        # with real agents in them. Its refusal without the token is covered by
+        # the blanket auth checks above, which is the part that must hold.
+    finally:
+        for k in (
+            "AGENTS_CITY_DATA",
+            "AGENTS_CITY_HOME",
+            "AGENTS_CITY_USER",
+            "CITY_SEARCH_IN",
+            "XDG_CACHE_HOME",
+        ):
+            os.environ.pop(k, None)
+        shutil.rmtree(hallDatos, ignore_errors=True)
+        shutil.rmtree(appDatos, ignore_errors=True)
+        shutil.rmtree(arbitraryDatos, ignore_errors=True)
+        servidor.shutdown()
+        servidor.server_close()
+        shutil.rmtree(destino, ignore_errors=True)
+
+    return resumen("serve")
+
+
+if __name__ == "__main__":
+    sys.exit(main())