agents-city 0.3.0-beta.21 → 0.3.0

package/bin/test-busca.py

@@ -0,0 +1,216 @@
+#!/usr/bin/env python3
+"""The disk scanner: repositories, worktrees and folders of documents.
+
+The thing this suite really guards is that the scan finds what a person came to
+find. The picker in the Hall is only as good as this index, and every mistake it
+can make is silent — a repo missing from a list looks exactly like a repo that
+was never cloned.
+"""
+
+import os
+import shutil
+import subprocess
+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 busca  # noqa: E402
+from testlib import afirma, comprueba, resumen  # noqa: E402
+
+
+def git(*args, cwd):
+    subprocess.run(["git", *args], cwd=cwd, capture_output=True, text=True, check=False)
+
+
+def monta(raiz):
+    """A believable disk: two clones, a linked worktree, a vault of notes, a
+    folder of documents inside a repo, and a lot of noise to walk past."""
+    clon = os.path.join(raiz, "codigo", "el-repo")
+    os.makedirs(clon)
+    git("init", "-q", cwd=clon)
+    git("remote", "add", "origin", "git@github.com:alguien/nombre-remoto.git", cwd=clon)
+    open(os.path.join(clon, "a.txt"), "w").close()
+    git("add", "-A", cwd=clon)
+    git("-c", "user.email=t@t", "-c", "user.name=t", "commit", "-qm", "one", cwd=clon)
+
+    otro = os.path.join(raiz, "codigo", "otro")
+    os.makedirs(otro)
+    git("init", "-q", cwd=otro)
+    git("remote", "add", "origin", "https://gitlab.com/otra-org/segundo.git", cwd=otro)
+
+    # A linked worktree: `.git` is a FILE here, which is exactly the case the
+    # first version of the scanner missed.
+    arbol = os.path.join(raiz, "arboles", "rama-viva")
+    git("worktree", "add", "-q", "-b", "rama-viva", arbol, cwd=clon)
+
+    # Documents with no git anywhere near them.
+    boveda = os.path.join(raiz, "Documents", "handbook")
+    os.makedirs(boveda)
+    for n in ("uno.md", "dos.md", "tres.pdf"):
+        open(os.path.join(boveda, n), "w").close()
+
+    # Documents INSIDE a repo: reachable through the repo already.
+    dentro = os.path.join(clon, "docs")
+    os.makedirs(dentro)
+    for n in ("a.md", "b.md", "c.md"):
+        open(os.path.join(dentro, n), "w").close()
+
+    # Two loose files are not a knowledge base.
+    flojo = os.path.join(raiz, "Documents", "sueltos")
+    os.makedirs(flojo)
+    for n in ("solo.md", "otro.md"):
+        open(os.path.join(flojo, n), "w").close()
+
+    # Noise the scan must never walk into.
+    for basura in ("node_modules", ".cache", "Library"):
+        ruta = os.path.join(raiz, "codigo", basura, "paquete")
+        os.makedirs(ruta)
+        git("init", "-q", cwd=ruta)
+        git("remote", "add", "origin", "https://x/y/basura.git", cwd=ruta)
+    return clon, arbol, boveda
+
+
+def escaneo(raiz):
+    print("  what the scan finds")
+    clon, arbol, boveda = monta(raiz)
+    sitios = busca.escanea()
+    por_ruta = {s["ruta"]: s for s in sitios}
+    nombres = {s["nombre"] for s in sitios}
+
+    afirma("· a clone is named by its remote, not by its folder",
+           "nombre-remoto" in nombres, str(sorted(nombres)))
+    afirma("· an https remote is named too", "segundo" in nombres, str(sorted(nombres)))
+    comprueba("· and it is a repo", por_ruta[clon]["clase"], "repo")
+
+    afirma("· a linked worktree is found at all", arbol in por_ruta, str(sorted(por_ruta)))
+    comprueba("· and named repo@branch", por_ruta[arbol]["nombre"], "nombre-remoto@rama-viva")
+    comprueba("· and marked as a worktree", por_ruta[arbol]["clase"], "worktree")
+
+    afirma("· a folder of documents with no git is offered",
+           boveda in por_ruta, str(sorted(por_ruta)))
+    comprueba("· and marked as documents", por_ruta[boveda]["clase"], "docs")
+    afirma("· a repo's own docs/ is not offered separately",
+           os.path.join(clon, "docs") not in por_ruta, str(sorted(por_ruta)))
+    afirma("· two loose files are not a knowledge base",
+           os.path.join(raiz, "Documents", "sueltos") not in por_ruta, str(sorted(por_ruta)))
+
+    afirma("· nothing under node_modules, .cache or Library is indexed",
+           not any("node_modules" in r or ".cache" in r or "/Library/" in r for r in por_ruta),
+           str(sorted(por_ruta)))
+    afirma("· every place has a last-touched time",
+           all(s.get("cuando", 0) > 0 for s in sitios), str(sitios))
+    afirma("· most recently touched first",
+           [s["cuando"] for s in sitios] == sorted((s["cuando"] for s in sitios), reverse=True),
+           str([(s["nombre"], s["cuando"]) for s in sitios]))
+    return clon
+
+
+def cache(raiz, clon):
+    print("  the cache")
+    fichero = busca.fichero_cache()
+    afirma("· nothing cached yet", not os.path.exists(fichero), fichero)
+    primera = busca.lugares()
+    afirma("· the first call writes the index", os.path.isfile(fichero), fichero)
+    afirma("· and a second call is served from it", busca.lugares() == primera, "")
+
+    # A repo cloned after the index was built is invisible until asked again —
+    # that is the honest behaviour, and the reason the Hall has a button.
+    nuevo = os.path.join(raiz, "codigo", "recien")
+    os.makedirs(nuevo)
+    git("init", "-q", cwd=nuevo)
+    git("remote", "add", "origin", "https://x/y/recien-clonado.git", cwd=nuevo)
+    afirma("· a just-cloned repo is not in the stale index",
+           "recien-clonado" not in {s["nombre"] for s in busca.lugares()}, "")
+    afirma("· asking again finds it",
+           "recien-clonado" in {s["nombre"] for s in busca.lugares(refrescar=True)}, "")
+    comprueba("· and by name", busca.ruta_de("recien-clonado"), nuevo)
+    comprueba("· a name nobody has is nothing, not a guess", busca.ruta_de("no-existe"), "")
+
+    guardado = busca.lugares()
+    afirma("· the cached rows survive the round trip intact",
+           all(s["clase"] and s["nombre"] and s["ruta"] for s in guardado), str(guardado))
+    afirma("· repos() is the git half only",
+           all(not r[0].startswith("handbook") for r in busca.repos())
+           and any(n == "nombre-remoto" for n, _ in busca.repos()), str(busca.repos()))
+    comprueba("· the clone is still where it was", dict(busca.repos())["nombre-remoto"], clon)
+
+
+def filtros(raiz):
+    print("  the search aperture")
+    os.environ["AGENTS_CITY_ORG"] = "otra-org"
+    solo = {s["nombre"] for s in busca.escanea()}
+    afirma("· an org filter keeps that org", "segundo" in solo, str(sorted(solo)))
+    afirma("· and drops the others", "nombre-remoto" not in solo, str(sorted(solo)))
+    del os.environ["AGENTS_CITY_ORG"]
+    afirma("· unset means index what is there",
+           "nombre-remoto" in {s["nombre"] for s in busca.escanea()}, "")
+
+    hondo = os.path.join(raiz, "a", "b", "c", "d", "e", "hondo")
+    os.makedirs(hondo)
+    git("init", "-q", cwd=hondo)
+    git("remote", "add", "origin", "https://x/y/muy-hondo.git", cwd=hondo)
+    os.environ["CITY_SEARCH_DEPTH"] = "2"
+    afirma("· depth is respected",
+           "muy-hondo" not in {s["nombre"] for s in busca.escanea()}, "")
+    os.environ["CITY_SEARCH_DEPTH"] = "9"
+    afirma("· and a deeper aperture reaches it",
+           "muy-hondo" in {s["nombre"] for s in busca.escanea()}, "")
+    os.environ["CITY_SEARCH_DEPTH"] = "4"
+
+    print("  the roots")
+    anidada = os.pathsep.join([raiz, os.path.join(raiz, "codigo")])
+    os.environ["CITY_SEARCH_IN"] = anidada
+    afirma("· a root already covered by another is not walked twice",
+           len(busca.raices()) == 1, str(busca.raices()))
+    os.environ["CITY_SEARCH_IN"] = os.pathsep.join([raiz, os.path.join(raiz, "no-existe")])
+    afirma("· a root that does not exist is skipped, not an error",
+           len(busca.raices()) == 1, str(busca.raices()))
+    os.environ["CITY_SEARCH_IN"] = raiz
+
+
+def compatibilidad(raiz):
+    if os.name != "posix":
+        # The shim is bash, for bash callers. Its absence is the entire reason
+        # the scanner beneath it stopped being a shell script.
+        return
+    print("  the shell shim")
+    guion = os.path.join(RAIZ, "plugin", "scripts", "find-repos.sh")
+    r = subprocess.run([guion], capture_output=True, text=True, timeout=120, env=os.environ)
+    lineas = [l for l in r.stdout.splitlines() if "\t" in l]
+    afirma("· find-repos.sh still prints name<TAB>path", bool(lineas), r.stdout + r.stderr)
+    afirma("· and only git places", all(len(l.split("\t")) == 2 for l in lineas), r.stdout)
+    afirma("· no document folder leaks into the git-only contract",
+           not any("handbook" in l for l in lineas), r.stdout)
+    uno = subprocess.run([guion, "nombre-remoto"], capture_output=True, text=True,
+                         timeout=120, env=os.environ)
+    comprueba("· and one name still resolves to one path",
+              uno.stdout.strip(), os.path.join(raiz, "codigo", "el-repo"))
+
+
+def main():
+    raiz = tempfile.mkdtemp()
+    cache_dir = tempfile.mkdtemp()
+    viejo = dict(os.environ)
+    try:
+        os.environ["CITY_SEARCH_IN"] = raiz
+        os.environ["CITY_SEARCH_DEPTH"] = "4"
+        os.environ["XDG_CACHE_HOME"] = cache_dir
+        os.environ.pop("AGENTS_CITY_ORG", None)
+        clon = escaneo(raiz)
+        cache(raiz, clon)
+        filtros(raiz)
+        compatibilidad(raiz)
+    finally:
+        os.environ.clear()
+        os.environ.update(viejo)
+        shutil.rmtree(raiz, ignore_errors=True)
+        shutil.rmtree(cache_dir, ignore_errors=True)
+    return resumen("busca")
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/bin/test-cage.py

@@ -23,8 +23,19 @@ import cage  # noqa: E402
 from testlib import afirma, comprueba, resumen  # noqa: E402
 
 
-def entorno_falso():
-    base = tempfile.mkdtemp(prefix="agents-city-cage-")
+def entorno_falso(como_un_home_real=False):
+    """A throwaway HOME with credentials planted in it.
+
+    `como_un_home_real` puts it under the caller's own home instead of /tmp,
+    and that is not cosmetic: the Linux cage keeps /tmp writable, so a fixture
+    living there is writable through-and-through and CANNOT reproduce what a
+    real `/home/you` does. A launch-blocking bug shipped behind exactly that
+    blind spot — the suite was green while no real user could start a window.
+    """
+    if como_un_home_real:
+        base = tempfile.mkdtemp(prefix=".agents-city-cage-", dir=os.path.expanduser("~"))
+    else:
+        base = tempfile.mkdtemp(prefix="agents-city-cage-")
     casa = os.path.join(base, "home")
     repo = os.path.join(base, "repo")
     os.makedirs(os.path.join(casa, ".ssh"))
@@ -199,8 +210,165 @@ def jaula_viva():
         shutil.rmtree(base, ignore_errors=True)
 
 
+def argv_de_linux():
+    """The Linux argv, checked on whatever machine runs this.
+
+    The live namespace checks below only run on Linux, which means a macOS-only
+    contributor could break the Linux cage and see every suite pass — the shape
+    of bug this repo has already met once. The ORDER is the security invariant
+    (last mount wins), so the order is asserted everywhere.
+    """
+    print("  the Linux cage's argv, from whichever kernel we are on")
+    base, casa, repo = entorno_falso()
+    try:
+        # Every path in the argv is canonical (on macOS /var resolves under
+        # /private), so the expectations resolve the same way the cage does.
+        real = cage.rutas.canonicaliza
+        argv = cage.argv_bwrap(repo, casa=casa)
+        texto = " ".join(argv)
+        afirma("it starts by binding the whole filesystem read-only",
+               argv[:5] == ["bwrap", "--ro-bind", "/", "/", "--dev"], " ".join(argv[:6]))
+        i_repo = argv.index(real(repo))
+        i_ssh = argv.index(real(os.path.join(casa, ".ssh")))
+        afirma("the writable working set is bound before the seals are applied",
+               i_repo < i_ssh, f"repo at {i_repo}, sealed .ssh at {i_ssh}")
+        afirma("a sealed directory becomes an empty tmpfs, not a refusal",
+               f"--tmpfs {real(os.path.join(casa, '.ssh'))}" in texto, texto[-400:])
+        afirma("a sealed FILE reads as nothing instead",
+               f"--ro-bind-try /dev/null {real(os.path.join(casa, '.git-credentials'))}" in texto,
+               texto[-400:])
+        afirma("the window keeps its own repo writable",
+               f"--bind-try {real(repo)} {real(repo)}" in texto, texto[:400])
+        # NOT --die-with-parent, and not by omission: the bus hub is started
+        # detached on purpose, so tying the namespace to one pane would take
+        # the city's bus down with whichever window happened to start it.
+        afirma("the namespace does not tie itself to one pane's lifetime",
+               "--die-with-parent" not in argv)
+        # /proc arrives with the read-only bind of /. Mounting a fresh one
+        # without a PID namespace buys nothing, and WITH one it would make the
+        # gateway record a namespace-local pid that `agents-city exit` then
+        # signals on the host.
+        afirma("no separate /proc mount, so recorded pids stay host pids",
+               "--proc" not in argv)
+        afirma("the device tree is the sandbox's own, not the host's re-bound",
+               argv.count("/dev") == 1, " ".join(a for a in argv if "dev" in a))
+        afirma("the probe runs exactly the flags a real launch starts from",
+               argv[:len(cage.BASE_BWRAP)] == cage.BASE_BWRAP, " ".join(argv[:8]))
+        afirma("Claude's own config file at the HOME root stays writable",
+               f"--bind-try {real(os.path.join(casa, '.claude.json'))}" in texto,
+               texto[-300:])
+        # The broker token is the one file re-admitted, and it must come after
+        # the seal that hides the directory it lives in — last mount wins.
+        token = os.path.join(casa, ".agents-city", ".runtime", "broker", "web.token")
+        os.makedirs(os.path.dirname(token), exist_ok=True)
+        open(token, "w").write("t")
+        conficha = cage.argv_bwrap(repo, casa=casa, fichero_token=token)
+        i_sello = max(i for i, a in enumerate(conficha)
+                      if a.endswith(os.path.join(".runtime", "broker")))
+        i_token = max(i for i, a in enumerate(conficha) if a == real(token))
+        afirma("this window's own token is re-admitted after the broker seal",
+               i_token > i_sello, f"seal at {i_sello}, token at {i_token}")
+        # A mount that resolves inside a sealed root must never become writable.
+        dentro = os.path.join(casa, ".ssh", "robado")
+        os.makedirs(dentro, exist_ok=True)
+        con_fuga = " ".join(cage.argv_bwrap(repo, casa=casa, extra_escritura=(dentro,)))
+        afirma("a mount inside a sealed root is dropped, not bound writable",
+               f"--bind-try {real(dentro)}" not in con_fuga, con_fuga[-300:])
+    finally:
+        shutil.rmtree(base, ignore_errors=True)
+
+
+def sonda_compartida():
+    """The bubblewrap probe is paid once per city, not once per window.
+
+    `cage.py` runs as a fresh process per window, so an in-process memo dies
+    every time: without a channel between them, a city of eight agents forks
+    eight namespaces before the first prompt — and on a kernel that refuses
+    them, forks eight failures.
+    """
+    print("  the probe that must not be paid per window")
+    previo = os.environ.get("CITY_CAGE_BWRAP")
+    try:
+        os.environ["CITY_CAGE_BWRAP"] = "0"
+        afirma("an owner-supplied answer is believed without probing",
+               cage.bwrap_sirve() is False)
+        os.environ["CITY_CAGE_BWRAP"] = "1"
+        # Believed, but never blindly: tmux windows inherit the server's whole
+        # environment, so a value carried over from another machine would build
+        # a prefix that exits 127 on every window. The binary still has to be
+        # there — which is why this asserts agreement with `which`, not True.
+        afirma("an affirmative answer still requires bwrap to exist here",
+               cage.bwrap_sirve() == (shutil.which("bwrap") is not None))
+    finally:
+        if previo is None:
+            os.environ.pop("CITY_CAGE_BWRAP", None)
+        else:
+            os.environ["CITY_CAGE_BWRAP"] = previo
+    lanzador = open(os.path.join(RAIZ, "plugin", "scripts", "city-session.sh"),
+                    encoding="utf-8").read()
+    afirma("the launcher asks once and exports the answer to every window",
+           "export CITY_CAGE_BWRAP" in lanzador and lanzador.count("$CAGE\" check") <= 1,
+           "")
+
+
+def jaula_linux():
+    """The Linux cage, exercised against a real namespace.
+
+    Same guarantees as the macOS block above, proven the same way: a planted
+    key must be unreadable, the repo must stay writable, and a grandchild must
+    not escape. Different kernel, identical promise — which is the only reason
+    it is allowed to be a different mechanism.
+    """
+    if not sys.platform.startswith("linux"):
+        print("  (live bubblewrap checks skipped: not Linux)")
+        return
+    if not cage.bwrap_sirve():
+        if os.environ.get("CITY_CAGE_REQUIRED") == "1":
+            afirma("the Linux cage is available where it was required", False,
+                   "bwrap missing or namespaces refused, and CITY_CAGE_REQUIRED=1")
+            return
+        print("  (live bubblewrap checks skipped: bwrap missing or namespaces refused)")
+        return
+    base, casa, repo = entorno_falso(como_un_home_real=True)
+    try:
+        def dentro(*orden):
+            argv = cage.argv_bwrap(repo, casa=casa)
+            return subprocess.run([*argv, *orden], capture_output=True, text=True)
+
+        # First: the cage must START. Four of the checks below are vacuous if
+        # bwrap dies — "the key was unreadable" is also true when nothing ran.
+        arranque = dentro("/bin/echo", "in")
+        afirma("live: a window actually launches inside the cage",
+               arranque.returncode == 0 and arranque.stdout.strip() == "in",
+               arranque.stderr or arranque.stdout)
+        r = dentro("/bin/cat", os.path.join(casa, ".ssh", "id_ed25519"))
+        afirma("live: the planted SSH key is unreadable inside the cage",
+               r.returncode != 0 and "FAKE-PRIVATE-KEY" not in r.stdout, r.stdout or r.stderr)
+        r = dentro("/bin/cat", os.path.join(casa, ".git-credentials"))
+        afirma("live: the planted git credentials are unreachable inside the cage",
+               r.returncode != 0 and "FAKE-TOKEN" not in r.stdout, r.stdout or r.stderr)
+        r = dentro("/bin/sh", "-c", f"echo ok > {repo}/build.txt && cat {repo}/build.txt")
+        afirma("live: the window still writes freely in its own repo",
+               r.returncode == 0 and r.stdout.strip() == "ok", r.stderr)
+        fuga = f"echo leak > {casa}/.ssh/stolen.txt; cat {casa}/.ssh/stolen.txt"
+        r = dentro("/bin/sh", "-c", fuga)
+        afirma("live: a write into a sealed directory never reaches the real disk",
+               not os.path.exists(os.path.join(casa, ".ssh", "stolen.txt")), r.stdout or r.stderr)
+        r = dentro("/bin/sh", "-c", f"/bin/sh -c 'cat {casa}/.ssh/id_ed25519'")
+        afirma("live: a grandchild process inherits the cage",
+               r.returncode != 0 and "FAKE-PRIVATE-KEY" not in r.stdout)
+        linea = cage.linea(repo, "win one", casa=casa)
+        afirma("live: linea() hands back a bwrap prefix on Linux",
+               linea.startswith("bwrap ") and linea.endswith(" "), linea[:80])
+    finally:
+        shutil.rmtree(base, ignore_errors=True)
+
+
 texto_del_perfil()
 excepciones_y_errores()
 mounts_agente_primero()
 jaula_viva()
+argv_de_linux()
+sonda_compartida()
+jaula_linux()
 sys.exit(resumen("cage"))

package/bin/test-card.py

@@ -24,7 +24,7 @@ sys.path.insert(0, os.path.join(RAIZ, 'plugin', 'scripts'))
 sys.path.insert(0, AQUI)
 import card  # noqa: E402
 
-from testlib import comprueba, afirma, resumen  # noqa: E402
+from testlib import comprueba, afirma, resumen, roster  # noqa: E402
 
 
 def ficha(cuerpo):
@@ -370,7 +370,7 @@ def de_verdad():
             'command': 'echo 1', 'baseline': '0', 'target': '1', 'by': 'Q3'}
     casa = tempfile.mkdtemp()
     porSeat = os.path.join(casa, 'ana.md')
-    seat.escribe_ficha(porSeat, 'ana', 'cpto', ['api'], meta)
+    seat.escribe_ficha(porSeat, 'ana', 'cpto', roster(('api',)), meta)
 
     otro = os.path.join(casa, 'wiz')
     os.makedirs(otro + '/roles', exist_ok=True)

package/bin/test-cities.py

@@ -438,6 +438,50 @@ def skills_transparentes():
         comprueba("· there is no stale capability cache", nombres, ["safe-deploy", "audit"])
 
 
+def reset_de_varias():
+    """`reset` takes several cities, or `all` — and stops before touching any
+    of them when one name is wrong.
+
+    Resetting three of four cities and then failing on a typo is the worst
+    possible outcome of a destructive command, so resolution happens first and
+    completely.
+    """
+    print("  resetting more than one city")
+    base = tempfile.mkdtemp()
+    previo = {k: os.environ.get(k) for k in ("AGENTS_CITY_HOME", "AGENTS_CITY_USER")}
+    os.environ.update(AGENTS_CITY_HOME=base, AGENTS_CITY_USER="ana")
+    registro = cities.REGISTRO
+    cities.REGISTRO = os.path.join(base, "reg")
+    try:
+        for n in ("home", "producto", "cliente"):
+            cities.crea("ana", n)
+        entorno = dict(os.environ, AGENTS_CITY_HOME=base, AGENTS_CITY_USER="ana")
+        guion = os.path.join(RAIZ, "plugin", "scripts", "reset.py")
+
+        r = subprocess.run(["python3", guion, "all", "--dry-run"],
+                           capture_output=True, text=True, env=entorno)
+        comprueba("· `all` covers every city this owner has",
+                  sum(1 for ln in r.stdout.splitlines() if "Would reset" in ln), 3)
+        r = subprocess.run(["python3", guion, "home", "cliente", "--dry-run"],
+                           capture_output=True, text=True, env=entorno)
+        afirma("· several names, space separated, cover exactly those",
+               "`home`" in r.stdout and "`cliente`" in r.stdout and "`producto`" not in r.stdout,
+               r.stdout)
+        r = subprocess.run(["python3", guion, "home", "inventada", "--dry-run"],
+                           capture_output=True, text=True, env=entorno)
+        afirma("· one unknown name aborts the whole run, before any city is touched",
+               r.returncode == 1 and "Nothing was reset" in r.stderr, r.stderr)
+        comprueba("· so nothing was reset", len(cities.lista("ana")), 3)
+    finally:
+        cities.REGISTRO = registro
+        for k, v in previo.items():
+            if v is None:
+                os.environ.pop(k, None)
+            else:
+                os.environ[k] = v
+        shutil.rmtree(base, ignore_errors=True)
+
+
 def main():
     print()
     identidad_y_catalogo()
@@ -446,6 +490,7 @@ def main():
     carreteras()
     reinicio_aislado()
     skills_transparentes()
+    reset_de_varias()
     return resumen("cities")
 
 

package/bin/test-contracts.py

@@ -435,11 +435,10 @@ def documentacion_publica():
     runtime, or release without documenting it in both supported languages.
     """
     print('  bilingual public documentation')
-    package = json.load(open(os.path.join(RAIZ, 'package.json'), encoding='utf-8'))
     public_commands = [
         'hall', 'seat', 'cities', 'road', 'bus', 'committee', 'benchmark',
         'reset', 'skills', 'city', 'demo', 'setup', 'report', 'tokens', 'exit',
-        'test',
+        'test', 'shortcut', 'doctor', 'update',
     ]
     public_contract = [
         '--help', '--version', '--no-browser', '--out', '--tui', '--repos',
@@ -499,9 +498,17 @@ def documentacion_publica():
         afirma(f'· {filename} carries eighteen reproducible use cases',
                content.count(cookbook_prefix) == 18,
                f'found {content.count(cookbook_prefix)}')
-        afirma(f'· {filename} tracks the package release used by its tarball examples',
-               package['version'] in content,
-               f"README has no {package['version']}")
+        # The install instructions must not name a versioned tarball. They used
+        # to, and every release left a README telling newcomers to install a
+        # file that no longer existed — so the contract was "repeat the current
+        # version everywhere". A glob cannot go stale, which is the better
+        # answer: what is pinned here is that nobody re-introduces the trap.
+        tarballs_fijos = re.findall(r'agents-city-\d[\w.\-]*\.tgz', content)
+        afirma(f'· {filename} installs by glob, never a tarball name that goes stale',
+               not tarballs_fijos, 'pinned: ' + ', '.join(sorted(set(tarballs_fijos))))
+        afirma(f'· {filename} opens with the one command that installs from npm',
+               'npm install -g agents-city' in content.split('## ')[0],
+               'the first screen does not show the npm install line')
         afirma(f'· {filename} links to the other language',
                '[Español](README.es.md)' in content and '[English](README.md)' in content)
         afirma(f'· {filename} shows the real city identity key',

package/bin/test-doctor.py

@@ -103,4 +103,37 @@ configs_malformadas()
 idempotencia()
 fichero()
 preserva_permisos()
+
+def revision_del_entorno():
+    """The report a person means when they type `doctor`.
+
+    Not "is my config an old shape" — that is one line of it. Whether this
+    machine can run a city at all, and if not, which part is missing.
+    """
+    print("  the machine, not just the config")
+    filas = doctor.revisa_entorno()
+    areas = {a for a, _, _ in filas}
+    for esperada in ("python", "tmux", "node", "runtimes", "cage", "city", "hall bundle"):
+        afirma(f"· it checks {esperada}", esperada in areas, str(sorted(areas)))
+    afirma("· every row carries a verdict and a reason, never a bare tick",
+           all(isinstance(d, str) and d for _, _, d in filas), str(filas))
+    # The cage row must explain ITSELF: "no cage" without a reason is the
+    # answer that leaves somebody running uncaged and none the wiser.
+    fila = next(f for f in filas if f[0] == "cage")
+    afirma("· and the cage row says which mechanism, or why there is none",
+           any(p in fila[2] for p in ("seatbelt", "bubblewrap", "not installed",
+                                      "refuses", "no cage")), str(fila))
+    import io
+    from contextlib import redirect_stdout
+
+    salida = io.StringIO()
+    with redirect_stdout(salida):
+        codigo = doctor.informe_entorno()
+    texto = salida.getvalue()
+    afirma("· the printed report names the version it is running",
+           "version" in texto and codigo in (0, 1), texto[-300:])
+
+
+
+revision_del_entorno()
 sys.exit(resumen("doctor"))