agents-city 0.4.0 → 0.5.2

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "city",
       "source": "./plugin",
-      "version": "0.4.0",
+      "version": "0.5.2",
       "description": "Operate one autonomous city seat, its domain, role, repo support agents, goal, recognised skills and explicit roads to other cities."
     }
   ]

package/README.es.md

@@ -106,7 +106,7 @@ Esto es `0.x` a propósito: los comandos ya se usan hoy, pero los formatos de
 fichero y las APIs todavía pueden cambiar entre versiones menores. Aquí nada
 pretende estar congelado.
 
-Necesitas Node.js 22 o superior, Python 3 y tmux; los detalles están en la
+Necesitas Node.js 22.13 o superior, Python 3 y tmux; los detalles están en la
 [tabla de requisitos](#requisitos-base), y `agents-city seat` se ofrece a
 instalar tmux si falta. No se instala nada en el sistema más allá de la carpeta
 global de npm de tu Node activo.
@@ -162,7 +162,7 @@ agents-city --version
 
 | Requisito | Para qué se usa |
 |---|---|
-| Node.js 22 o posterior | paquete npm, bus WebSocket y frontends |
+| Node.js 22.13 o posterior | paquete npm, bus WebSocket, recepción local y frontends |
 | npm | instalación y empaquetado |
 | Python 3 | Hall, onboarding, ciudades, mapas y utilidades |
 | bash | sesiones y launchers |
@@ -491,6 +491,7 @@ agents-city setup
 agents-city seat
 agents-city cities
 agents-city road
+agents-city connect
 agents-city bus
 agents-city committee
 agents-city agents
@@ -583,6 +584,19 @@ traducciones se indexan por la frase en inglés, así que lo que aún no esté
 traducido cae en un inglés legible y no en un identificador — un texto nuevo
 nunca se queda bloqueado esperando a la traducción.
 
+La cobertura es una prueba, no una costumbre. `bin/test-i18n.py` lee las rutas de
+renderizado, saca cada frase en inglés que una persona va a ver, y falla cuando
+alguna no tiene español — así una vista nueva no puede colarse sin traducir, que
+es como la cobertura había caído al 40% sin que nadie se diera cuenta.
+
+El mecanismo evidente — barrer el DOM renderizado y traducir lo que coincida con
+una clave — es a propósito lo que **no** se hace. En el DOM no hay forma de
+distinguir una frase que escribió este producto de un nombre de ciudad o de
+agente que escribió alguien, así que a quien tenga una ciudad llamada `Overview`
+se le renombraría sola. Esa distinción sólo existe en el fuente, entre un literal
+y una interpolación, y ahí es donde se comprueba: lo que lleve un `${}` se
+salta.
+
 ### `agents-city setup`
 
 Crea o selecciona una ciudad y abre el Hall; con `--tui` entrega el flujo a
@@ -689,6 +703,59 @@ agents-city road disconnect producto <city-id-remoto>
 No se puede conectar una ciudad consigo misma. Una invitación remota debe
 aceptarse de forma independiente en cada máquina.
 
+### `agents-city connect`
+
+Empareja este ordenador con un servicio de Roads gestionadas. No crea una
+conexión unilateral: las dos personas la aprueban en el servicio y quien la
+recibe ve a la otra persona en su recepción humana privada, sin exponer un
+catálogo de ciudades. El cliente público implementa el protocolo v4; el servicio
+alojado queda fuera de este repositorio y todavía no está habilitado en
+producción ni auditado de forma independiente.
+
+```bash
+agents-city connect --service https://connect.example.com --trust-file roots.json
+agents-city connect --city producto
+agents-city connect --all
+agents-city connect status
+agents-city connect roads
+```
+
+El comando genera material Ed25519/X25519, Olm y ML-KEM-768 firmado en este
+ordenador, muestra un PASCO de un solo uso y abre el navegador para autorizarlo.
+Sólo sube material público. Las claves privadas, el estado del ratchet, las
+semillas ML-KEM y los reintentos quedan cifrados en
+`~/.agents-city/.runtime/connect/vault/`; la clave de envoltura permanece en el
+Llavero de macOS, Credential Manager de Windows o Secret Service de Linux. El
+cliente falla de forma cerrada si el keyring no está disponible. La jaula sella
+el vault para las ventanas de agentes de repositorio en macOS y Linux.
+
+La cadena de raíces firmada indicada con `--trust-file` es obligatoria en el
+primer emparejamiento con un servicio que no sea de desarrollo. El cliente
+conserva la última versión aceptada. Una raíz posterior debe continuar desde
+esa raíz local exacta y llevar suficientes firmas de las autoridades offline
+anteriores y nuevas; se rechazan saltos, rollback, caducidad y cambios
+silenciosos de operador o testigo. El protocolo v4 verifica después al peer
+mediante transparencia de claves, protege el primer mensaje Olm con X25519 +
+ML-KEM-768 híbrido y usa el Double Ratchet de Olm. Los envíos sellados normales
+omiten remitente, dispositivo, ciudad y Road de la petición exterior. Esto no
+oculta a Cloudflare la IP, el momento o el tamaño rellenado; los pasos
+posteriores del ratchet son clásicos.
+
+El paquete incluye una raíz pública únicamente para el origen exacto del
+sandbox gestionado. Los servicios autoalojados siguen necesitando su
+`--trust-file` revisado. Una raíz devuelta por el propio servicio nunca se
+acepta como primer anclaje.
+
+`--city` elige un hub local que mantiene viva la recepción del propietario; no
+elige un destinatario ni se revela a la otra persona. Un solo hub por ordenador
+mantiene el lease y una conexión cifrada saliente; no se abre ningún puerto
+público. Usa `--service URL` o `AGENTS_CITY_CONNECT_URL` para un endpoint piloto.
+El servidor alojado no forma parte de este repositorio Apache; el cliente y el
+protocolo auditables sí.
+
+[docs/managed-connect.md](docs/managed-connect.md) detalla el contrato de claves,
+sobres, cifrado, ACK, revocación y modelo de amenazas.
+
 ### `agents-city bus`
 
 Opera mensajes entre asientos sobre carreteras ya declaradas.
@@ -703,7 +770,7 @@ agents-city bus send '*' "Aviso para todas mis carreteras"
 | Subcomando | Efecto |
 |---|---|
 | `roster` | devuelve carreteras y presencia online conocida |
-| `inbox` | devuelve y consume el inbox pendiente; el historial append-only permanece |
+| `inbox` | devuelve y consume el siguiente lote aprobado de hasta 20; el texto gestionado no aparece hasta que el propietario lo envía desde el ayuntamiento |
 | `send owner/city TEXTO` | envía a un destino permitido |
 | `send '*' TEXTO` | envía a todas las carreteras; exige al menos una |
 
@@ -1572,9 +1639,28 @@ AGENTS_CITY_DATA="$HOME/.agents-city/$CITY_OWNER/producto" \
 En una sesión normal no hace falta establecer `AGENTS_CITY_DATA`: ya está
 inyectado en cada ventana. El ejemplo lo hace explícito para una terminal externa.
 
-### Caso 10: conectar ciudades de dos máquinas o personas
+### Caso 10: conectar dos personas desde ordenadores distintos
 
-En la máquina A:
+Con un operador de Roads gestionadas, cada persona empareja su ordenador.
+`--city` elige el hub local que inicia la recepción del propietario; no revela
+esa ciudad ni da acceso directo a ella:
+
+```bash
+agents-city connect --city producto --service https://connect.example.com --trust-file roots.json
+agents-city connect --city research --service https://connect.example.com --trust-file roots.json
+```
+
+Una persona solicita la conexión en el servicio y la otra la acepta. Los
+clientes reciben la Road bilateral mediante sus sesiones autenticadas; ninguna
+parte intercambia un token compartido, abre un puerto local ni recibe el catálogo
+de ciudades de la otra. El texto entrante se detiene primero en la recepción
+humana. Quien lo recibe decide qué ciudad o ciudades locales pueden leerlo, o
+activa el router opcional que falla de forma cerrada y sólo actúa cuando una
+regla coincide sin ambigüedad. El contrato del cliente público está en
+[docs/managed-connect.md](docs/managed-connect.md).
+
+Para autoalojar el transporte remoto existente basado en token, intercambia en
+cambio las invitaciones públicas de ciudad. En la máquina A:
 
 ```bash
 agents-city road invite producto > producto.invitation.json
@@ -1803,12 +1889,32 @@ El hub local no mezcla datos efímeros con la configuración legible:
 ├── road-queue/*.json
 ├── road-inbox/*.json
 └── road-history.jsonl
+
+~/.agents-city/.runtime/reception/
+└── reception.sqlite3       # cuarentena del propietario compartida por sus ciudades
 ```
 
 Las credenciales y ficheros de runtime se crean con permisos privados. Los
 outboxes permiten que un actor se reconecte sin perder tareas ya aceptadas; el
-ACK elimina el pendiente. El límite actual es 200 pendientes por cola y 72 horas
-de vida por mensaje. `bus inbox` consume `road-inbox`, no el historial append-only.
+ACK elimina el pendiente. Los outboxes de actores y la cola local de reintentos
+admiten 200 pendientes; el inbox de Roads admite 500 por defecto y devuelve como
+máximo los 20 más antiguos en cada lectura. El texto E2EE gestionado entra
+primero en la recepción separada del propietario: ninguna ciudad ni modelo puede
+consumirlo hasta que una persona lo rechaza o lo envía a una o varias ciudades
+desde el ayuntamiento. Una ráfaga ya enrutada crea una sola activación agrupada
+del asiento, no un turno del modelo por mensaje, y cada runtime nativo ejecuta
+como máximo un turno a la vez. Una cola llena aplica backpressure en vez de
+borrar silenciosamente un elemento anterior. La vida de cada mensaje es de 72
+horas. `bus inbox` consume el `road-inbox` aprobado, no la cuarentena ni el
+historial append-only.
+
+El rendimiento del relay no es el rendimiento de respuestas. Para una ciudad,
+la capacidad semántica segura es aproximadamente las peticiones agrupadas por
+turno divididas por la duración del turno. La regresión local vacía 100 mensajes
+de Road en cinco lotes exactos de 20 tras una sola activación sin contenido; una
+prueba separada con 20 peticiones y runtime lento demuestra que la concurrencia
+del modelo permanece en uno y que el backlog durable se vacía sin pérdidas. El
+resultado `queued` del remitente nunca significa leído ni respondido.
 
 ### Variables configurables
 
@@ -1830,6 +1936,12 @@ de vida por mensaje. `bus inbox` consume `road-inbox`, no el historial append-on
 | `CITY_HOOKS` | `city` | `everywhere` ejecuta los hooks de conciencia en todas las sesiones de Claude, no solo en runtimes de ciudad |
 | `CITY_DESKTOP` | `~/Desktop`, o el escritorio de Windows bajo WSL | dónde escribe `agents-city shortcut` |
 | `CITY_CAGE` | `1` | `0` arranca todas las ventanas sin jaula |
+| `CITY_ROAD_INBOX_MAX_PENDING` | `500` | capacidad local del inbox de Roads, entre 20 y 10.000; al llenarse aplica backpressure |
+| `CITY_ROAD_INBOX_WAKE_INTERVAL_MS` | `300000` | intervalo mínimo entre activaciones agrupadas del backlog, de 30 segundos a 1 hora |
+| `CITY_RECEPTION_MAX_PENDING` | `10000` | mensajes remotos pendientes del propietario antes de aplicar contrapresión al relay, de 100 a 100.000 |
+| `CITY_RECEPTION_MAX_BYTES` | `67108864` | bytes totales pendientes en la recepción local privada, de 1 MiB a 512 MiB |
+| `CITY_RECEPTION_PENDING_DAYS` | `30` | retención local de mensajes sin decidir, de 1 a 90 días |
+| `CITY_RECEPTION_DELIVERY_INTERVAL_MS` | `1000` | frecuencia con la que un bus reclama rutas aprobadas por la persona, de 250 ms a 30 segundos |
 | `CITY_CAGE_DENY` | vacío | rutas extra que sellar, separadas por `:` |
 | `CITY_CAGE_ALLOW_WRITE` | vacío | rutas extra que mantener escribibles, separadas por `:` |
 | `CITY_UPDATE_CHECK` | `1` | `0` no pregunta nunca a npm si hay versión más nueva |
@@ -1966,10 +2078,18 @@ tus repos, adjuntarse a tu tmux o leer ficheros privados de tu home. Para códig
 no confiable usa cuentas/VMs/contenedores separados y aplica también los permisos
 del CLI de cada proveedor.
 
-El bus remoto amplía la superficie de confianza. Despliega HTTPS/WSS, rota
-tokens, limita los scopes y revisa [docs/self-host.md](docs/self-host.md). Una
-carretera autoriza intercambio de mensajes entre asientos; no implica confianza
-para ejecutar comandos recibidos ni acceso al filesystem remoto.
+Un bus remoto amplía la superficie de confianza. Para el transporte autoalojado
+con token, despliega HTTPS/WSS, rota tokens, limita los scopes y revisa
+[docs/self-host.md](docs/self-host.md). Managed Connect usa firmas de
+dispositivo, transparencia de claves con testigos, establecimiento de sesión
+híbrido X25519 + ML-KEM-768, Double Ratchet de Olm y entrega sellada. Su material
+privado queda cifrado bajo una clave del keyring del sistema operativo en el
+directorio sellado por la jaula `~/.agents-city/.runtime/connect/vault/`; consulta
+[docs/managed-connect.md](docs/managed-connect.md). Una Road gestionada autoriza
+alcance cifrado hasta la recepción humana del propietario, no entrada directa a
+un modelo. Solo la ruta posterior del propietario deja el texto disponible para
+las ciudades elegidas. Ninguna Road autoriza ejecutar comandos recibidos ni
+acceder al filesystem remoto.
 
 ## Resolución de problemas
 
@@ -2131,6 +2251,115 @@ La detección exige `.git` (directorio o fichero de worktree) y un remote `origi
 Si acabas de cambiar las raíces, ejecuta `plugin/scripts/busca.py --refresh`. `AGENTS_CITY_ORG` puede estar filtrando el repo;
 déjala vacía para indexar todos los remotes.
 
+### Tus CLIs, tal y como las tienes
+
+Esto no compite con la CLI que ya usas. Las orquesta, y eso sólo funciona si
+respeta lo que configuraste en ellas — tus plugins, tus skills, tus servidores
+MCP, tu modelo, tus permisos.
+
+Eso es una afirmación sobre tu máquina, así que va como comando y no como
+promesa:
+
+```bash
+agents-city doctor --config          # qué añadimos, qué heredamos, qué no tocamos
+agents-city doctor --config --json   # lo mismo, como datos
+```
+
+Imprime tres columnas por CLI, y la diferencia entre ellas es lo importante:
+
+* **el trato** — lo que añadimos o pisamos. Es corto, cada línea dice *por qué*,
+  y es lo que hace que el bus sea la única ruta entre agentes y que la jaula
+  aguante. Sin eso no hay producto.
+* **heredamos** — lo que a propósito *no* mandamos, para que tu propia CLI lea
+  tu propia configuración. Tu modelo, tu esfuerzo, tu política de aprobación.
+* **no tocamos** — lo que carga exactamente igual que siempre.
+
+El informe y el runtime leen **el mismo fichero** —
+`plugin/channel/runtime/arnes.json` — así que la afirmación no puede separarse
+del comportamiento. Los conectores sacan sus valores de esa declaración en vez de
+escribirlos a mano, y la suite falla si un runtime impone algo que la declaración
+no menciona. Escribir esa comprobación encontró dos: un system prompt inyectado
+en Kimi que no declaraba nadie, y un valor de sandbox escrito en dos sitios.
+
+Donde tu ajuste y el nuestro se cruzan, gana el tuyo cuando puede: el
+`approval_policy` de Codex se respeta si lo has puesto, y `on-request` es sólo el
+recurso cuando no. El informe dice la consecuencia en voz alta — `never`
+desactiva las herramientas de app y MCP — en vez de decidir en silencio que no
+querías decir eso.
+
+### Tu silla conserva tu propio Claude Code
+
+La ventana del asiento abre **Claude Code de verdad** — tus plugins, tus skills,
+tus servidores MCP, tu statusline, el autocompletado de slash commands, el
+selector de modelo. Es el arnés que ya usas, en el panel, y es a propósito: la
+silla es donde una persona trabaja a mano.
+
+Sigue estando en el bus. Los hooks del plugin (`SessionStart`,
+`UserPromptSubmit`, `Stop`, `SessionEnd`) reportan los prompts y las respuestas
+de esa sesión como los mismos eventos `conversation.*` que reporta el gateway,
+así que el ayuntamiento ve la conversación igual. Y lleva los dos flags que
+hacen del bus la única ruta entre agentes — `crossSessionInbound: refuse` y
+`--disallowed-tools SendMessage,ListAgents`. Un producto más silencioso con un
+agujero dentro no sería un producto mejor.
+
+**Las casas de los agentes conservan el gateway** y su prompt `city>`, porque lo
+que compra el gateway es que el bus pueda *meter* trabajo en una ventana — que
+es el oficio entero de una casa y nada del oficio de la silla.
+
+Una clave de la ficha devuelve la silla a lo de antes:
+
+```yaml
+ui.seat: gateway     # el prompt de la ciudad en la silla, como antes
+```
+
+`CITY_UI=gateway` lo fuerza para un arranque. A las casas no se les pregunta:
+una casa existe para recibir encargos, y el gateway es lo que lo hace posible.
+
+### El motor con el que corre una casa
+
+`model.<ventana>` y `effort.<ventana>` en la ficha dicen con qué corre una casa,
+una sola vez, la mueva la CLI que la mueva. Claude los toma como flags; los
+gateways nativos leen esa misma grafía del texto del comando y la mandan con el
+turno — por eso una clave significa lo mismo para las cuatro:
+
+| proveedor | modelo | esfuerzo |
+| --- | --- | --- |
+| `claude` | sí, un alias que resuelve la CLI (`opus`, `sonnet`…) | sí |
+| `codex` | sí, el nombre que use tu Codex (`~/.codex/config.toml`) | sí |
+| `opencode` | sí, `proveedor/modelo` | no existe ese ajuste |
+| `kimi` | sí | no existe ese ajuste |
+
+Un comando que ya lleva el flag se lo queda: `runs.dbt: codex --model o3` es
+alguien diciendo lo que quería, y una clave genérica no debe pisar una frase
+concreta. El esfuerzo sólo se escribe donde se lee, porque un flag que nadie lee
+es justo como un control acaba pareciendo que funciona.
+
+### Publicar una versión
+
+Una release es una etiqueta. Empujar `v0.5.2` ejecuta la suite entera en Linux,
+macOS y Windows, comprueba que la etiqueta y los tres manifiestos dicen la misma
+versión, y publica con **procedencia**: una declaración firmada de qué commit y
+qué workflow produjeron ese tarball exacto. Cualquiera puede comprobarlo:
+
+```bash
+npm audit signatures
+```
+
+No hay ningún token guardado. Publica por *trusted publishing* de npm, que
+cambia una identidad OIDC de corta vida emitida por el workflow por el derecho a
+publicar este paquete: un secreto que no existe no se puede filtrar.
+
+```bash
+npm version patch --no-git-tag-version   # y luego un PR con la subida
+git tag v0.5.2 && git push origin v0.5.2 # la etiqueta es la release
+```
+
+Esto existe porque publicar a mano no funcionaba. Cuatro versiones se quedaron
+sin publicar en un solo día, no por descuido sino porque el paso vivía en la
+cabeza de una persona y necesitaba su passkey — y lo que llegaba al registro era
+lo que hubiera en un directorio de trabajo, sin conexión con ningún commit que
+nadie pudiera nombrar.
+
 ### Desinstalarlo del todo
 
 ```bash

package/README.md

@@ -104,7 +104,7 @@ This is `0.x` on purpose: the commands are usable today, and the file formats
 and APIs can still change between minor versions. Nothing here pretends to be
 frozen yet.
 
-You need Node.js 22+, Python 3 and tmux; the
+You need Node.js 22.13+, Python 3 and tmux; the
 [requirements table](#base-requirements) has the details, and `agents-city seat`
 offers to install tmux when it is missing. Nothing is installed system-wide
 beyond the npm global folder of your active Node installation.
@@ -160,7 +160,7 @@ agents-city --version
 
 | Requirement | Used for |
 |---|---|
-| Node.js 22 or later | npm package, WebSocket bus, and frontends |
+| Node.js 22.13 or later | npm package, WebSocket bus, local reception, and frontends |
 | npm | installation and packaging |
 | Python 3 | Hall, onboarding, cities, maps, and utilities |
 | bash | sessions and launchers |
@@ -486,6 +486,7 @@ agents-city setup
 agents-city seat
 agents-city cities
 agents-city road
+agents-city connect
 agents-city bus
 agents-city committee
 agents-city agents
@@ -576,6 +577,18 @@ explicit choice. Translations are keyed by the English sentence, so anything not
 yet translated falls back to readable English rather than to an identifier — new
 strings are never blocked on a translation pass.
 
+Coverage is a test, not a habit. `bin/test-i18n.py` reads the render paths, pulls
+out every English sentence a person will see, and fails when one has no Spanish —
+so a new view cannot quietly ship untranslated, which is how coverage had drifted
+to about 40% before anybody noticed.
+
+The obvious mechanism, sweeping the rendered DOM and translating what matches a
+key, is deliberately **not** what this does. 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 only exists in the source, between a literal and an interpolation,
+and that is where the check is made: anything holding a `${}` is skipped.
+
 ### `agents-city setup`
 
 Creates or selects a city and opens the Hall; `--tui` hands the flow to `seat`.
@@ -681,6 +694,62 @@ agents-city road disconnect product <remote-city-id>
 A city cannot connect to itself. Each machine must independently accept the
 other remote invitation.
 
+### `agents-city connect`
+
+Pairs this computer with a managed Road service. It does not create a
+connection unilaterally: both people approve it in the service, and the
+recipient sees the sender in their private human reception without exposing a
+city catalogue. The public client implements protocol v4; the hosted service is
+outside this repository and is not production-enabled or independently audited.
+
+```bash
+agents-city connect --service https://connect.example.com --trust-file roots.json
+agents-city connect --city product
+agents-city connect --all
+agents-city connect status
+agents-city connect roads
+```
+
+The command generates Ed25519/X25519, Olm and signed ML-KEM-768 material on this
+computer, prints a one-use PASCO and opens the browser for approval. Only public
+material is uploaded. Private keys, ratchet state, ML-KEM seeds and retry data
+are encrypted in `~/.agents-city/.runtime/connect/vault/`; the wrapping key
+stays in macOS Keychain, Windows Credential Manager or Linux Secret Service.
+The client fails closed if that keyring is unavailable. The vault is sealed from
+repo-agent windows on macOS and Linux.
+
+The signed root chain supplied through `--trust-file` is mandatory for first
+pairing with a non-development service. The client persists its last accepted
+version. A later root must continue from that exact local root and carry enough
+signatures from both the old and new offline authorities; skipped versions,
+rollback, expiry and silent operator/witness replacement are rejected. Protocol
+v4 then verifies the peer through key transparency, protects the first Olm
+message with hybrid X25519 + ML-KEM-768, and uses the Olm Double Ratchet. Normal
+sealed submissions omit sender, device, city and Road identity from the outer
+request. This does not hide IP address, timing or padded size from Cloudflare,
+and later ratchet steps are classical.
+
+The package includes a public root only for the exact managed sandbox origin;
+self-hosted services still require their reviewed `--trust-file`. A root
+returned by the service is never accepted as a first pin.
+
+`--city` chooses a local hub that can keep the computer's reception bridge
+alive; it is not a recipient selector and is never disclosed to the other
+person. Exactly one hub per computer holds the lease and one outbound encrypted
+session; no public port is opened. Use `--service URL` or
+`AGENTS_CITY_CONNECT_URL` for a pilot endpoint. The hosted server is not part of
+this Apache repository; the auditable client and wire protocol are.
+
+`agents-city connect roads` prints a connected person's name for a person Road,
+not the opaque `rx-*` transport endpoints. In the Hall, every incoming message
+waits for manual review by default. The owner may route it to one or more local
+cities, reject it with a reason, or explicitly enable the deterministic Auto
+router. Auto routes only one unique low-risk rule match; ambiguous, unmatched,
+prompt-like, secret-seeking, or command-like text remains in the human queue.
+
+See [docs/managed-connect.md](docs/managed-connect.md) for the exact key,
+envelope, encryption, ACK, revocation and threat-model contract.
+
 ### `agents-city bus`
 
 Operates messages between seats over declared roads.
@@ -695,7 +764,7 @@ agents-city bus send '*' "Notice for every connected city"
 | Subcommand | Effect |
 |---|---|
 | `roster` | return roads and known online presence |
-| `inbox` | return and consume pending inbox; append-only history remains |
+| `inbox` | return and consume the next approved batch of up to 20; managed text is unavailable until the owner routes it in the Hall |
 | `send owner/city TEXT` | send to one allowed destination |
 | `send '*' TEXT` | send to all roads; requires at least one |
 
@@ -1550,9 +1619,28 @@ AGENTS_CITY_DATA="$HOME/.agents-city/$CITY_OWNER/product" \
 Inside a normal session, you do not need to set `AGENTS_CITY_DATA`; it is already
 injected into each window. The example makes it explicit for an outside terminal.
 
-### Case 10: connect cities belonging to different machines or people
+### Case 10: connect two people on different machines
 
-On machine A:
+With a managed Road operator, each person pairs a computer. `--city` chooses the
+local hub that will start the owner-level reception bridge; it does not reveal
+that city or give the other person direct access to it:
+
+```bash
+agents-city connect --city product --service https://connect.example.com --trust-file roots.json
+agents-city connect --city research --service https://connect.example.com --trust-file roots.json
+```
+
+One person requests the connection in that service and the other accepts it.
+The clients learn the active bilateral person Road over their authenticated
+relay sessions; neither side exchanges a shared bus token, exposes a local
+port, or receives the other person's city catalogue. Incoming text first stops
+in the human reception. The recipient decides which local city or cities may
+read it, or lets the optional fail-closed rule router decide when one match is
+unambiguous. The public client contract is documented in
+[docs/managed-connect.md](docs/managed-connect.md).
+
+To self-host the existing token-based remote transport instead, exchange the
+public city invitations manually. On machine A:
 
 ```bash
 agents-city road invite product > product.invitation.json
@@ -1780,12 +1868,29 @@ The local hub keeps ephemeral state separate from readable configuration:
 ├── road-queue/*.json
 ├── road-inbox/*.json
 └── road-history.jsonl
+
+~/.agents-city/.runtime/reception/
+└── reception.sqlite3       # owner quarantine shared by local cities
 ```
 
 Credentials and runtime files are created with private permissions. Outboxes let
 an actor reconnect without losing an already accepted task; its ACK removes the
-pending item. Current limits are 200 pending items per queue and a 72-hour
-message lifetime. `bus inbox` consumes `road-inbox`, not append-only history.
+pending item. Actor outboxes and the local retry queue admit 200 pending items;
+the Road inbox admits 500 by default and returns at most 20 oldest items per
+read. Managed E2EE text first enters the separate owner reception: no city or
+model can consume it until a person rejects it or routes it to one or more
+cities in the Hall. A routed burst creates one coalesced seat wake-up rather
+than one model turn per message, and every native runtime runs at most one turn
+at a time. Full queues apply backpressure instead of silently deleting an older
+item. Message lifetime is 72 hours. `bus inbox` consumes approved `road-inbox`,
+not reception quarantine or append-only history.
+
+Relay throughput is not answer throughput. For one city, safe semantic capacity
+is approximately grouped requests per turn divided by turn duration. The local
+regression drains 100 Road messages in five exact batches of 20 after one
+content-free wake-up; a separate 20-request slow-runtime test proves model
+concurrency stays at one and the durable backlog drains without loss. A sender's
+`queued` result never means read or answered.
 
 ### Configurable variables
 
@@ -1807,6 +1912,12 @@ message lifetime. `bus inbox` consumes `road-inbox`, not append-only history.
 | `CITY_HOOKS` | `city` | `everywhere` runs the conscience hooks in every Claude session, not only city runtimes |
 | `CITY_DESKTOP` | `~/Desktop`, or the Windows desktop under WSL | where `agents-city shortcut` writes |
 | `CITY_CAGE` | `1` | `0` launches every window uncaged |
+| `CITY_ROAD_INBOX_MAX_PENDING` | `500` | local Road inbox capacity, from 20 to 10,000; a full inbox applies backpressure |
+| `CITY_ROAD_INBOX_WAKE_INTERVAL_MS` | `300000` | minimum interval between coalesced backlog wake-ups, from 30 seconds to 1 hour |
+| `CITY_RECEPTION_MAX_PENDING` | `10000` | owner-level pending remote messages before relay backpressure, from 100 to 100,000 |
+| `CITY_RECEPTION_MAX_BYTES` | `67108864` | total pending plaintext bytes in private local reception, from 1 MiB to 512 MiB |
+| `CITY_RECEPTION_PENDING_DAYS` | `30` | undecided local-message retention, from 1 to 90 days |
+| `CITY_RECEPTION_DELIVERY_INTERVAL_MS` | `1000` | how often a city bus claims human-approved routes, from 250 ms to 30 seconds |
 | `CITY_CAGE_DENY` | empty | extra colon-separated paths to seal |
 | `CITY_CAGE_ALLOW_WRITE` | empty | extra colon-separated paths to keep writable |
 | `CITY_UPDATE_CHECK` | `1` | `0` never asks npm whether a newer version exists |
@@ -1936,10 +2047,18 @@ read your repos, attach to tmux, or read private files in your home. Use separat
 accounts, VMs, or containers for untrusted code, and also apply each provider
 CLI's permission controls.
 
-A remote bus expands the trust surface. Deploy HTTPS/WSS, rotate tokens, limit
-scopes, and read [docs/self-host.md](docs/self-host.md). A road authorises message
-exchange between seats; it neither authorises execution of received commands nor
-grants remote filesystem access.
+A remote bus expands the trust surface. For the self-hosted token transport,
+deploy HTTPS/WSS, rotate tokens, limit scopes, and read
+[docs/self-host.md](docs/self-host.md). Managed Connect instead uses device
+signatures, witnessed key transparency, hybrid X25519 + ML-KEM-768 session
+establishment, an Olm Double Ratchet and sealed delivery. Its private material
+is encrypted under an OS-keyring wrapping key in the cage-sealed
+`~/.agents-city/.runtime/connect/vault/` directory; see
+[docs/managed-connect.md](docs/managed-connect.md). A managed Road authorises
+encrypted reachability to the owner's human reception, not direct model input.
+Only the owner's later route makes the text available to selected cities. No
+Road authorises execution of received commands or grants remote filesystem
+access.
 
 ## Troubleshooting
 
@@ -2096,6 +2215,114 @@ Discovery requires `.git` (a directory or worktree file) and an `origin` remote.
 If roots just changed, run `plugin/scripts/busca.py --refresh`. `AGENTS_CITY_ORG` may be filtering the repo;
 leave it empty to index every remote.
 
+### Your CLIs, as you have them
+
+This does not compete with the CLI you already run. It orchestrates them, which
+only works if it respects what you configured in them — your plugins, your
+skills, your MCP servers, your model, your permissions.
+
+That is a claim about your machine, so it ships as a command rather than a
+promise:
+
+```bash
+agents-city doctor --config          # what we add, inherit and leave alone
+agents-city doctor --config --json   # the same, as data
+```
+
+It prints three columns per CLI, and the difference between them is the point:
+
+* **the deal** — what we add or override. It is short, every line says *why*,
+  and it is what makes the bus the only route between agents and the cage hold.
+  Without it there is no product.
+* **we inherit** — what we deliberately do *not* send, so your own CLI reads
+  your own configuration for it. Your model, your effort, your approval policy.
+* **untouched** — what loads exactly as it always did.
+
+The report and the runtime read the **same file** — `plugin/channel/runtime/arnes.json`
+— so the claim cannot drift from the behaviour. The connectors take their policy
+values out of that declaration instead of spelling them inline, and the suite
+fails if a runtime imposes something the declaration does not mention. Writing
+that check found two: a system prompt injected into Kimi that nothing declared,
+and a sandbox value written in two places.
+
+Where your setting and ours meet, yours wins where it can: Codex's
+`approval_policy` is honoured when you set one, and `on-request` is only the
+fallback when you have not. The report says the consequence out loud — `never`
+disables app and MCP tools — instead of quietly deciding you did not mean it.
+
+### Your chair keeps your own Claude Code
+
+The seat window opens **Claude Code itself** — your plugins, your skills, your
+MCP servers, your statusline, slash-command completion, the model picker. It is
+the harness you already use, in the pane, and that is deliberate: the chair is
+where a person works by hand.
+
+It is still on the bus. The city plugin's `SessionStart`, `UserPromptSubmit`,
+`Stop` and `SessionEnd` hooks report that session's prompts and answers as the
+same `conversation.*` events the gateway reports, so the town hall sees the
+conversation either way. And it carries the same two flags that make the bus the
+only route between agents — `crossSessionInbound: refuse` and
+`--disallowed-tools SendMessage,ListAgents`. A quieter product with a hole in it
+would not be a better product.
+
+**Agent houses keep the gateway** and its `city>` prompt, because what the
+gateway buys is the bus being able to *push* work into a window — which is the
+whole job of a house and no part of the chair's.
+
+One card key moves the chair back:
+
+```yaml
+ui.seat: gateway     # the city's own prompt in the chair, as before
+```
+
+`CITY_UI=gateway` forces it for one launch. Houses are not asked: a house exists
+to receive assignments, and the gateway is what makes that possible.
+
+### The engine a house runs on
+
+`model.<window>` and `effort.<window>` on the card say what a house runs on, once,
+whatever CLI runs it. Claude takes them as flags; the native gateways parse the
+same spelling out of the command string and send it with the turn — which is why
+one key means the same thing for all four:
+
+| provider | model | effort |
+| --- | --- | --- |
+| `claude` | yes, an alias the CLI resolves (`opus`, `sonnet`…) | yes |
+| `codex` | yes, the name your Codex uses (`~/.codex/config.toml`) | yes |
+| `opencode` | yes, `provider/model` | no such setting |
+| `kimi` | yes | no such setting |
+
+A command that already carries the flag keeps it: `runs.dbt: codex --model o3`
+was somebody saying what they meant, and a generic key must not overrule a
+specific sentence. Effort is written only where it is read, because a flag
+nothing reads is how a control ends up looking like it works.
+
+### Releasing
+
+A release is a tag. Pushing `v0.5.2` runs the whole suite on Linux, macOS and
+Windows, checks that the tag and the three manifests name the same version, and
+publishes with **provenance** — a signed statement of which commit and which
+workflow produced that exact tarball. Anyone can check it:
+
+```bash
+npm audit signatures
+```
+
+No token is stored anywhere. It publishes through npm's trusted publishing,
+which trades a short-lived OIDC identity from the workflow for the right to
+publish this one package: a secret that does not exist cannot leak.
+
+```bash
+npm version patch --no-git-tag-version   # then open a PR with the bump
+git tag v0.5.2 && git push origin v0.5.2 # the tag is the release
+```
+
+This exists because publishing by hand did not work. Four versions went
+unpublished in a single day, not because anybody was careless but because the
+step lived in a person's head and needed their passkey — and what reached the
+registry was whatever happened to be in a working directory, connected to no
+commit anyone could name.
+
 ### Removing it completely
 
 ```bash