agents-city 0.4.0 → 0.5.2

package/bin/test-contracts.py

@@ -328,6 +328,140 @@ def varias_ciudades():
     shutil.rmtree(casa)
 
 
+def motor_para_todos():
+    """The card says which model a window runs, once, whatever CLI runs it.
+
+    Both fields used to be Claude's alone. They are not: the native gateways
+    parse `--model` — and Codex `--effort` — out of the command string and send
+    them with the turn, which is why one key on the card can mean the same thing
+    for all four. This checks the launcher actually hands them over, because a
+    dropdown whose value never reaches a process is a lie with a nice font.
+    """
+    print('  the engine reaches every runtime')
+    fuente = open(os.path.join(RAIZ, 'plugin/scripts/city-session.sh'), encoding='utf-8').read()
+    afirma('· a native runtime command goes through con_motor, not raw',
+           'con_motor "$win" "$KIND" "$OTRO"' in fuente, '')
+    afirma('· and so does the seat when it runs one',
+           'con_motor seat "$SEAT_RUNTIME" "$SEAT_OTRO"' in fuente, '')
+
+    # The two functions, lifted out and exercised against a stub card reader.
+    casa = tempfile.mkdtemp()
+    # A stand-in for read-card.py, in the language the launcher invokes it in.
+    lector = os.path.join(casa, 'leer.py')
+    # It answers the batched form too, because that is what the launcher asks:
+    # a stub that only knows the one-field call would test a door nobody uses.
+    open(lector, 'w', encoding='utf-8').write(
+        'import sys\n'
+        "CARD = {'model.dbt': 'gpt-5.6-sol', 'effort.dbt': 'max'}\n"
+        "campos = sys.argv[3:] if sys.argv[1:2] == ['--varios'] else sys.argv[-1:]\n"
+        "print('\\n'.join(CARD.get(c, '') for c in campos))\n"
+    )
+    trozo = fuente[fuente.index('motor_de() {'):fuente.index('runtime_de() {')]
+    guion = os.path.join(casa, 'motor.sh')
+    open(guion, 'w', encoding='utf-8').write(
+        f'LEER="{lector}"\nFICHA=/dev/null\n{trozo}\n'
+        'printf "%s\\n" "$(con_motor "$1" "$2" "$3")"\n'
+    )
+
+    def con(ventana, motor, orden):
+        return subprocess.run(['bash', guion, ventana, motor, orden],
+                              capture_output=True, text=True).stdout.strip()
+
+    comprueba('· claude gets both flags',
+              con('dbt', 'claude', 'claude'), 'claude --model gpt-5.6-sol --effort max')
+    comprueba('· codex gets both too — its gateway reads them off the command',
+              con('dbt', 'codex', 'codex'), 'codex --model gpt-5.6-sol --effort max')
+    comprueba('· opencode gets the model and no effort it cannot read',
+              con('dbt', 'opencode', 'opencode'), 'opencode --model gpt-5.6-sol')
+    comprueba('· and neither does kimi',
+              con('dbt', 'kimi', 'kimi'), 'kimi --model gpt-5.6-sol')
+    comprueba('· a window with nothing on the card gets no flags at all',
+              con('otra', 'codex', 'codex'), 'codex')
+    # A command that already says it wins: somebody who wrote the flag meant it.
+    comprueba('· an explicit --model on the card is never doubled',
+              con('dbt', 'codex', 'codex --model o3'), 'codex --model o3 --effort max')
+    comprueba('· nor an explicit --effort',
+              con('dbt', 'codex', 'codex --effort low'),
+              'codex --effort low --model gpt-5.6-sol')
+    shutil.rmtree(casa, ignore_errors=True)
+
+
+def asiento_con_su_arnes():
+    """The chair keeps the harness the person came with.
+
+    Claude behind the gateway is headless with a `city>` prompt in front of it.
+    That is right for a house, which must be able to RECEIVE work from the bus,
+    and wrong for the chair, where somebody works by hand with their own
+    plugins, statusline and slash commands. The city plugin's hooks already
+    report a normal session's prompts and answers onto the bus, so the chair
+    loses nothing by opening its own interface.
+
+    What must never differ between the two shapes are the two flags that make
+    the bus the only route between agents. A quieter product with a hole in it
+    is the failure this checks for.
+    """
+    print('  the chair keeps its own interface')
+    fuente = open(os.path.join(RAIZ, 'plugin/scripts/city-session.sh'), encoding='utf-8').read()
+    cuerpo = fuente[fuente.index('lanza_asiento_claude() {'):fuente.index('# The seat runs Claude')]
+    afirma('· both shapes of the chair come out of one function',
+           fuente.count('lanza_asiento_claude "') == 2, '')
+    afirma('· the tui branch runs the command itself',
+           'lanza "$SESSION:seat" seat "$EQUIPO" "$entorno${CLAUDE_AUTH_PREFIX}$orden"' in cuerpo,
+           cuerpo)
+    afirma('· the gateway branch is still there, one card key away',
+           'gateway_line seat "$EQUIPO" "$orden"' in cuerpo, cuerpo)
+    afirma('· and the flags are built once, before the branch, so they cannot differ',
+           cuerpo.count('$SETTINGS') == 0 and cuerpo.count('NO_PEER_TOOLS') == 0, cuerpo)
+    # Every Claude command in the file is built the same way: the engine
+    # through `con_motor` (which carries the "an explicit flag wins" guard) and
+    # the deal through `$CLAUDE_TRATO` (which is asked of the declaration). A
+    # branch that skips either is a window that silently runs differently.
+    ordenes = [l for l in fuente.split('\n')
+               if 'CLAUDE_SEAT="' in l or 'CLAUDE_REPO="' in l
+               or 'lanza_asiento_claude "' in l]
+    afirma('· every Claude launch in the file was found', len(ordenes) == 5, str(ordenes))
+    for linea in ordenes:
+        if linea.strip().startswith('lanza_asiento_claude "$CLAUDE_SEAT"'):
+            continue  # this one passes a command already built above
+        afirma(f'· the engine goes through con_motor: {linea.strip()[:40]}…',
+               'con_motor' in linea, linea)
+        afirma(f'· and the deal through the declaration: {linea.strip()[:40]}…',
+               '$CLAUDE_TRATO' in linea, linea)
+    afirma('· the chair still opens with its yolo flag',
+           any('$SEAT_YOLO_FLAG' in l for l in ordenes), str(ordenes))
+    afirma('· and the deal is asked of arnes.py, not respelled here',
+           'arnes.py" flags claude' in fuente
+           and "crossSessionInbound" not in fuente
+           and "SendMessage,ListAgents" not in fuente, '')
+
+    # A house is not a chair: it must still be reachable from the bus.
+    afirma('· an agent house still goes through the gateway',
+           'gateway_line "$win" "$path" "$CLAUDE_REPO"' in fuente, '')
+
+    # `ui.<window>`, lifted out and exercised.
+    casa = tempfile.mkdtemp()
+    lector = os.path.join(casa, 'leer.py')
+    open(lector, 'w', encoding='utf-8').write(
+        'import sys\n'
+        "print({'ui.seat': 'gateway', 'ui.raro': 'nonsense'}.get(sys.argv[-1], ''))\n"
+    )
+    trozo = fuente[fuente.index('ui_de() {'):fuente.index('runtime_de() {')]
+    guion = os.path.join(casa, 'ui.sh')
+    open(guion, 'w', encoding='utf-8').write(
+        f'LEER="{lector}"\nFICHA=/dev/null\n{trozo}\nprintf "%s\\n" "$(ui_de "$1" "$2")"\n'
+    )
+
+    def ui(ventana, defecto):
+        return subprocess.run(['bash', guion, ventana, defecto],
+                              capture_output=True, text=True).stdout.strip()
+
+    comprueba('· a card that says gateway gets the gateway', ui('seat', 'tui'), 'gateway')
+    comprueba('· a card that says nothing gets the default', ui('otra', 'tui'), 'tui')
+    comprueba('· and a house defaults the other way', ui('otra', 'gateway'), 'gateway')
+    comprueba('· a card that says nonsense is not obeyed', ui('raro', 'tui'), 'tui')
+    shutil.rmtree(casa, ignore_errors=True)
+
+
 def ventanas_gemelas():
     """Window, engine key and bus actor share one canonical repo slug."""
     print('  the window slug has one owner')
@@ -529,6 +663,83 @@ def ci_bootstrap():
            'the clean checkout would launch WebSocket doubles without ws installed')
 
 
+def publicar_es_verificable():
+    """A release is a tag, and what it publishes can be checked by a stranger.
+
+    Three properties, and each one is a way this has already gone wrong or
+    could: the suite runs before the registry sees anything; the tag and the
+    manifests are made to agree, because a tag that lies publishes one version
+    under another's name forever; and the credential is an OIDC identity rather
+    than a stored token, because a secret that does not exist cannot leak.
+    """
+    print('  a release is a tag, and it is verifiable')
+    ruta = os.path.join(RAIZ, '.github', 'workflows', 'release.yml')
+    afirma('· there is a release workflow at all', os.path.isfile(ruta), ruta)
+    if not os.path.isfile(ruta):
+        return
+    release = open(ruta, encoding='utf-8').read()
+    prueba = open(os.path.join(RAIZ, '.github', 'workflows', 'test.yml'),
+                  encoding='utf-8').read()
+
+    afirma('· it runs on a tag, not on a push to a branch',
+           "tags: ['v*']" in release and 'branches' not in release, release[:400])
+    # The last occurrence: the header comment names `npm publish` while
+    # explaining what this replaced, and a check that cannot tell a command
+    # from a sentence about it fails on its own documentation.
+    afirma('· the whole suite runs before anything is published',
+           'uses: ./.github/workflows/test.yml' in release
+           and release.index('uses: ./.github/workflows/test.yml')
+           < release.rindex('run: npm publish'),
+           'publish must depend on the suite, not race it')
+    afirma('· and the suite is the same one, called rather than copied',
+           'workflow_call:' in prueba, 'test.yml must be reusable')
+    afirma('· needs: test — the dependency is declared, not implied',
+           'needs: test' in release, release)
+    afirma('· the tag has to agree with package.json before it publishes',
+           'GITHUB_REF_NAME#v' in release and 'exit 1' in release,
+           'a tag that disagrees would publish one version under another name')
+    afirma('· it publishes with provenance, so the tarball names its commit',
+           '--provenance' in release, release)
+    afirma('· through a short-lived identity, with no token stored anywhere',
+           'id-token: write' in release
+           and 'NPM_TOKEN' not in release and 'secrets.' not in release,
+           'trusted publishing: a secret that does not exist cannot leak')
+    afirma('· and it asks for nothing else',
+           release.count('write') == 1, 'id-token is the only write permission')
+    # Node 22 bundles npm 10, which cannot exchange an OIDC token and so
+    # publishes UNAUTHENTICATED — the registry answers 404, which reads like a
+    # missing package and is really a missing credential. It cost one release
+    # to find out.
+    afirma('· with an npm new enough to exchange the token at all',
+           'npm install -g npm@^11' in release and '11.5.1' in release,
+           'trusted publishing needs npm >= 11.5.1; setup-node gives 10.x')
+    afirma('· and it refuses to publish with an older one rather than trying',
+           'process.exit(1)' in release, release)
+    # prepublishOnly rebuilds and re-runs the whole suite. By hand that is the
+    # only safety net; here the suite has already run on three platforms and
+    # byte-compared the artifacts, so a fourth run verifies nothing and can
+    # only fail. It did, on a flaky test, after everything real had passed.
+    afirma('· and it does not run the suite a fourth time to publish',
+           '--ignore-scripts' in release,
+           'prepublishOnly duplicates what needs: test already proved')
+    # Skipping the scripts also skips the BUILD, and `city/web/dist*` are
+    # gitignored — they exist only because something builds them. Turning the
+    # test half off by turning the whole script off shipped a package with no
+    # map and no Hall bundle: 447 files instead of 503.
+    afirma('· but it still builds the gitignored half of the package',
+           'run: npm run build' in release
+           and release.index('run: npm run build') < release.rindex('run: npm publish'),
+           'a publish with no build ships no front end')
+    afirma('· and checks the front end is in the tarball before sending it',
+           'city/web/dist/index.html' in release and 'city/web/dist-hall/hall.js' in release,
+           'the gitignored artifacts are the ones nobody notices missing')
+    paquete = json.load(open(os.path.join(RAIZ, 'package.json'), encoding='utf-8'))
+    afirma('· and the build has one spelling, shared with a publish by hand',
+           paquete['scripts'].get('prepublishOnly', '').startswith('npm run build')
+           and 'city/web' in paquete['scripts'].get('build', ''),
+           str(paquete.get('scripts')))
+
+
 def main():
     print()
     resolvedores()
@@ -539,11 +750,14 @@ def main():
     demo_coherente()
     varias_ciudades()
     ventanas_gemelas()
+    motor_para_todos()
+    asiento_con_su_arnes()
     canal_compilado()
     plugin_canal()
     puerta_npm()
     documentacion_publica()
     ci_bootstrap()
+    publicar_es_verificable()
     return resumen('contracts')
 
 

package/bin/test-diario.py

@@ -0,0 +1,185 @@
+#!/usr/bin/env python3
+"""The journal: what it records, and everything it must survive.
+
+This exists so a failure on somebody else's machine is a file they can send
+rather than a story they have to remember. That promise has two halves, and the
+second is the one with teeth:
+
+  · it records what happened — and
+  · it is safe to attach without reading it first, it never grows without
+    bound, and it can never be the reason a request failed.
+
+A log that breaks the thing it is logging is worse than no log at all, so most
+of what follows is the unhappy path: an unwritable directory, a value that
+cannot be serialised, a line somebody corrupted, a structure with no bottom.
+"""
+
+import os
+import shutil
+import sys
+import tempfile
+
+AQUI = os.path.dirname(os.path.abspath(__file__))
+RAIZ = os.path.dirname(AQUI)
+sys.path.insert(0, AQUI)
+sys.path.insert(0, os.path.join(RAIZ, "plugin", "scripts"))
+
+import cities  # noqa: E402
+import diario  # noqa: E402
+from testlib import afirma, comprueba, resumen  # noqa: E402
+
+
+def ciudad():
+    """A city with an identity, which is what the journal's path is keyed on."""
+    base = tempfile.mkdtemp()
+    datos = os.path.join(base, "home")
+    os.makedirs(datos)
+    with open(os.path.join(datos, "city.yml"), "w", encoding="utf-8") as f:
+        f.write("owner: quien\nname: home\nslug: home\nid: city-diario-prueba\n")
+    return base, datos
+
+
+def lo_que_registra(datos):
+    print("  what it records")
+    diario.apunta(datos, "post", ruta="/api/agentes", estado=400, error="an agent needs a name")
+    diario.apunta(datos, "browser", que="api refused", donde="/api/agentes")
+    lineas = diario.lee(datos)
+    comprueba("· one line per thing that happened", len(lineas), 2)
+    comprueba("· in the order they happened", lineas[0]["tipo"], "post")
+    afirma("· with the moment", bool(lineas[0].get("t")), str(lineas[0]))
+    comprueba("· and the reason a request was refused",
+              lineas[0]["error"], "an agent needs a name")
+    afirma("· the browser's half lands in the same file as the server's",
+           lineas[1]["tipo"] == "browser" and lineas[1]["que"] == "api refused", str(lineas[1]))
+    afirma("· the file is where the runtime keeps this city's things",
+           diario.ruta(datos).endswith("hall.jsonl")
+           and cities.identidad(datos).lower().replace("_", "-")[:20] in diario.ruta(datos).lower(),
+           diario.ruta(datos))
+
+
+def nunca_un_secreto(datos):
+    print("  what it must never record")
+    diario.apunta(
+        datos, "post",
+        PASE="s3cr3t-pase-value", token="tok_abc", Authorization="Bearer xyz",
+        api_key="k", password="p",
+        anidado={"cookie": "c", "inocente": "visible"},
+        suelto="sk-ant-" + "A" * 44,
+    )
+    linea = diario.lee(datos)[-1]
+    for clave in ("PASE", "token", "Authorization", "api_key", "password"):
+        comprueba(f"· {clave} by name", linea.get(clave), "[redacted]")
+    comprueba("· and inside a nested object", linea["anidado"]["cookie"], "[redacted]")
+    comprueba("· while its neighbour survives", linea["anidado"]["inocente"], "visible")
+    afirma("· a value merely SHAPED like a credential goes too",
+           "[redacted]" in linea["suelto"] and "AAAA" not in linea["suelto"], linea["suelto"])
+
+    # The regression that made this worse than useless: a temp directory is a
+    # long run of characters, and redacting it turned a real error message into
+    # `[redacted]` while protecting nothing.
+    for ruta in ("/var/folders/xy/T/tmpab12cd34ef56gh78ij90klmnopqrs/city",
+                 "~/.agents-city/quien/home",
+                 "/Users/alguien/codigo/un-repo-con-nombre-larguisimo-de-verdad"):
+        comprueba(f"· but a path is not a credential: {ruta[:24]}…", diario.limpia(ruta), ruta)
+
+
+def nunca_rompe_la_peticion(datos):
+    print("  what it must survive")
+    # It is called from inside request handlers. Anything it raises becomes a
+    # 500 on a request that had already succeeded.
+    imposible = os.path.join(datos, "no-existe", "ni-va-a-existir")
+    open(os.path.join(datos, "fichero"), "w").close()
+    for roto, como in (
+        (os.path.join(datos, "fichero", "sub"), "a file where a directory should be"),
+        (imposible, "a directory nobody created"),
+    ):
+        try:
+            diario.apunta(roto, "post", ruta="/x")
+            afirma(f"· {como} is survived, not raised", True, "")
+        except Exception as e:  # noqa: BLE001  that is the assertion
+            afirma(f"· {como} is survived, not raised", False, f"{type(e).__name__}: {e}")
+
+    class NoSerializa:
+        pass
+
+    try:
+        diario.apunta(datos, "post", objeto=NoSerializa())
+        afirma("· a value that cannot be written is survived too", True, "")
+    except Exception as e:  # noqa: BLE001
+        afirma("· a value that cannot be written is survived too", False, str(e))
+
+    print("  and what it must not do to itself")
+    hondo = {"a": {}}
+    nodo = hondo["a"]
+    for _ in range(40):
+        nodo["a"] = {}
+        nodo = nodo["a"]
+    diario.apunta(datos, "post", hondo=hondo)
+    afirma("· a structure with no bottom does not recurse forever",
+           len(diario.lee(datos)) > 0, "")
+    diario.apunta(datos, "post", larga="x" * 5000, lista=list(range(500)))
+    linea = diario.lee(datos)[-1]
+    afirma("· a very long string is cut, and says so",
+           len(linea["larga"]) <= 501 and linea["larga"].endswith("…"), str(len(linea["larga"])))
+    afirma("· and a very long list is cut", len(linea["lista"]) <= 40, str(len(linea["lista"])))
+
+
+def se_puede_leer_siempre(datos):
+    print("  and reading it")
+    with open(diario.ruta(datos), "a", encoding="utf-8") as f:
+        f.write("esto no es json\n\n")
+    lineas = diario.lee(datos)
+    afirma("· a corrupted line does not stop the rest being read",
+           any(l.get("tipo") == "unreadable" for l in lineas) and len(lineas) > 1, str(lineas[-2:]))
+    comprueba("· a city with no journal reads as nothing, not as an error",
+              diario.lee(tempfile.mkdtemp()), [])
+
+
+def no_crece_sin_fin(datos):
+    print("  and it does not grow without bound")
+    limite = diario.LIMITE
+    diario.LIMITE = 2000
+    try:
+        for i in range(60):
+            diario.apunta(datos, "post", ruta="/api/x", relleno="y" * 200, i=i)
+        actual = os.path.getsize(diario.ruta(datos))
+        afirma("· it rotates instead of growing", actual < 2000 * 3, str(actual))
+        afirma("· and keeps the previous one, so the rotation is not a hole",
+               os.path.isfile(diario.ruta(datos) + ".1"), "")
+        lineas = diario.lee(datos, 500)
+        afirma("· reading spans the rotation, oldest first",
+               len(lineas) > 20
+               and [l.get("i") for l in lineas if "i" in l]
+               == sorted(l.get("i") for l in lineas if "i" in l),
+               str([l.get("i") for l in lineas][:8]))
+    finally:
+        diario.LIMITE = limite
+
+
+def main():
+    # An app home of its own. Without this the journal's path is derived from
+    # `cities.raiz()`, which is the caller's real `~/.agents-city` — so this
+    # suite wrote into the machine it was running on, and read back somebody
+    # else's lines. A test that touches the real home is worse than a flaky
+    # one: it is a test that changes the thing it is measuring.
+    previo = os.environ.get("AGENTS_CITY_HOME")
+    os.environ["AGENTS_CITY_HOME"] = tempfile.mkdtemp()
+    base, datos = ciudad()
+    try:
+        lo_que_registra(datos)
+        nunca_un_secreto(datos)
+        nunca_rompe_la_peticion(datos)
+        se_puede_leer_siempre(datos)
+        no_crece_sin_fin(datos)
+    finally:
+        shutil.rmtree(os.environ["AGENTS_CITY_HOME"], ignore_errors=True)
+        if previo is None:
+            os.environ.pop("AGENTS_CITY_HOME", None)
+        else:
+            os.environ["AGENTS_CITY_HOME"] = previo
+        shutil.rmtree(base, ignore_errors=True)
+    return resumen("diario")
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/bin/test-doctor.py

@@ -135,5 +135,36 @@ def revision_del_entorno():
 
 
 
+def puerta_de_config():
+    """`doctor --config` is a door on the environment report, not a new binary.
+
+    It is the command that turns "we respect your CLI configuration" from a
+    sentence in a README into something a person can check on their own machine
+    before trusting this with it.
+    """
+    print('  the config report has a door')
+    import io
+    from contextlib import redirect_stdout
+
+    guion = os.path.join(RAIZ, 'plugin', 'scripts', 'doctor.py')
+    afirma('· doctor --help mentions it',
+           '--config' in open(guion, encoding='utf-8').read(), '')
+    for bandera in ('--config', 'config'):
+        salida = io.StringIO()
+        with redirect_stdout(salida):
+            codigo = doctor.main(['doctor', bandera])
+        texto = salida.getvalue()
+        comprueba(f'· `doctor {bandera}` exits cleanly', codigo, 0)
+        afirma(f'· `doctor {bandera}` prints the deal, not the environment',
+               'the deal' in texto and 'we inherit' in texto, texto[:300])
+    salida = io.StringIO()
+    with redirect_stdout(salida):
+        doctor.main(['doctor', '--config', '--json'])
+    datos = json.loads(salida.getvalue())
+    afirma('· and --json answers with data, one entry per runtime',
+           isinstance(datos, list) and len(datos) == 4, str(datos)[:200])
+
+
 revision_del_entorno()
+puerta_de_config()
 sys.exit(resumen("doctor"))

package/bin/test-i18n.py

@@ -0,0 +1,189 @@
+#!/usr/bin/env python3
+"""Translation coverage, as a number instead of a habit.
+
+The Hall speaks Spanish and English. It got there by wrapping strings in `t()`
+one call site at a time, which means coverage was decided per line by whoever
+happened to be looking — and it showed: whole views shipped in English inside an
+otherwise Spanish page, and nothing failed.
+
+The obvious mechanism, sweeping the rendered DOM and translating what matches a
+dictionary key, is the wrong one. At DOM time there is no way to tell a sentence
+this product wrote from a city or agent name somebody typed, so a person whose
+city is called `Overview` would watch it rename itself. The distinction has to
+be made where it still exists: in the source, between a literal and an
+interpolation.
+
+So this is the enforcement half, and it is the half that actually fixes the
+habit. It reads the render paths, pulls out every English sentence a person will
+see, and fails when one has no Spanish. Nothing changes at runtime, so no user's
+data can be mistranslated — and a new view cannot quietly ship untranslated.
+"""
+
+import os
+import re
+import sys
+
+AQUI = os.path.dirname(os.path.abspath(__file__))
+RAIZ = os.path.dirname(AQUI)
+FUENTE = os.path.join(RAIZ, "city", "web", "src")
+sys.path.insert(0, AQUI)
+from testlib import afirma, resumen  # noqa: E402
+
+#: The files that render something a person reads.
+VISTAS = ("hall.ts", "bienvenida.ts", "casa.ts", "demo.ts", "explorador.ts",
+          "dialogo.ts", "motores.ts")
+
+#: A filename, an identifier, a single word of markup. Matched whole, so it
+#: cannot hide a real sentence.
+NO_ES_PROSA = re.compile(r"^(?:[\w.\-/]+|.{0,3})$")
+
+
+def normaliza(s):
+    return re.sub(r"\s+", " ", s.replace("’", "'")).strip()
+
+
+def sin_lo_traducido(texto):
+    """The source with every `_( … )` and `plural( … )` call cut out.
+
+    What is left is, by construction, the text nobody wrapped. Cutting first
+    also removes the `<b>` and `<code>` fragments *inside* a translated
+    paragraph, which are not sentences of their own and must not be counted as
+    missing ones.
+    """
+    fuera = []
+    i = 0
+    while i < len(texto):
+        for aguja in ("_(", "plural("):
+            j = i if texto.startswith(aguja, i) else -1
+            # `_(` must not be the tail of a longer identifier.
+            if j == 0 or (j > 0 and not (texto[j - 1].isalnum() or texto[j - 1] == "_")):
+                if j >= 0:
+                    break
+        else:
+            fuera.append(texto[i])
+            i += 1
+            continue
+        hondo, k = 0, i + len(aguja) - 1
+        while k < len(texto):
+            if texto[k] == "(":
+                hondo += 1
+            elif texto[k] == ")":
+                hondo -= 1
+                if hondo == 0:
+                    break
+            k += 1
+        i = k + 1
+    return "".join(fuera)
+
+
+def visibles(texto):
+    """Every English sentence this file puts on screen unwrapped.
+
+    Only inside template literals: that is where this codebase builds markup,
+    and it keeps TypeScript's own `Promise<void>` from reading as a tag. Two
+    shapes, because those are the two a template can produce — text between
+    tags, and the attributes a person actually reads.
+
+    Anything holding a `${` is skipped. That is an interpolation, and an
+    interpolation is precisely the thing that must never be translated blind:
+    it is where a city's name and an agent's name come from.
+    """
+    crudo = sin_lo_traducido(texto)
+    fuera = set()
+    for plantilla in re.findall(r"`(?:[^`\\]|\\.)*`", crudo, re.S):
+        for bruto in re.findall(r">([^<>{}\n]+)<", plantilla):
+            limpio = normaliza(bruto)
+            if limpio and "$" not in limpio and not NO_ES_PROSA.match(limpio):
+                fuera.add(limpio)
+        for bruto in re.findall(
+            r'(?:title|placeholder|aria-label)="([^"${}\n]+)"', plantilla
+        ):
+            limpio = normaliza(bruto)
+            if limpio and not NO_ES_PROSA.match(limpio):
+                fuera.add(limpio)
+    return fuera
+
+
+def traducidas():
+    """Every key the Spanish dictionary answers to, normalised the way
+    `idioma.ts` normalises it before looking one up."""
+    texto = open(os.path.join(FUENTE, "es.ts"), encoding="utf-8").read()
+    claves = set()
+    for a, b, c in re.findall(
+        r"^\s*(?:'((?:[^'\\]|\\.)*)'|\"((?:[^\"\\]|\\.)*)\"|([A-Za-z][A-Za-z0-9_]*)):",
+        texto,
+        re.M,
+    ):
+        clave = (a or b or c).replace("\\'", "'").replace('\\"', '"')
+        if clave:
+            claves.add(normaliza(clave))
+    return claves
+
+
+def pedidas(texto):
+    """Every key the code asks `t()` for. A sentence can be wrapped and still
+    untranslated — that is a miss the extractor above cannot see, because the
+    wrapping is exactly what hides it from a `>text<` scan."""
+    fuera = set()
+    for patron in (r"_\(\s*'((?:[^'\\]|\\.)*)'", r'_\(\s*"((?:[^"\\]|\\.)*)"',
+                   r"_\(\s*`((?:[^`\\]|\\.)*)`"):
+        for bruto in re.findall(patron, texto, re.S):
+            clave = normaliza(bruto.replace("\\'", "'").replace('\\"', '"'))
+            # A key built from a variable is resolved at runtime; there is
+            # nothing here to check it against.
+            if clave and "${" not in clave:
+                fuera.add(clave)
+    return fuera
+
+
+def cobertura():
+    print("  every sentence on screen has a Spanish one")
+    claves = traducidas()
+    sin_traducir = {}
+    for nombre in VISTAS:
+        texto = open(os.path.join(FUENTE, nombre), encoding="utf-8").read()
+        for frase in visibles(texto) | pedidas(texto):
+            if frase not in claves:
+                sin_traducir.setdefault(nombre, []).append(frase)
+    for nombre in VISTAS:
+        faltan = sin_traducir.get(nombre, [])
+        afirma(
+            f"· {nombre}",
+            not faltan,
+            "untranslated: " + " | ".join(sorted(faltan)[:6]) + (" …" if len(faltan) > 6 else ""),
+        )
+
+
+def el_mecanismo():
+    print("  and the mechanism that keeps it honest")
+    idioma = open(os.path.join(FUENTE, "idioma.ts"), encoding="utf-8").read()
+    afirma(
+        "· the dictionary is keyed by the English sentence, so a miss degrades to English",
+        "ES[clave(fuente)] ?? fuente" in idioma,
+        idioma,
+    )
+    afirma(
+        "· whitespace and typographic apostrophes are normalised on both sides",
+        "\\u2018" in idioma and "\\s+" in idioma,
+        idioma,
+    )
+    # The one thing a DOM sweep could not do, said as a check: nothing
+    # translates a value that came from outside this codebase.
+    for nombre in VISTAS:
+        texto = open(os.path.join(FUENTE, nombre), encoding="utf-8").read()
+        malos = re.findall(r"_\(\s*(?:esc\(|E\.|this\.p\.esc\()", texto)
+        afirma(
+            f"· {nombre} never translates an escaped or server-sent value",
+            not malos,
+            str(malos[:3]),
+        )
+
+
+def main():
+    cobertura()
+    el_mecanismo()
+    return resumen("i18n")
+
+
+if __name__ == "__main__":
+    sys.exit(main())