@nyx5/nyx5 0.7.0 → 0.8.0

package/README.md

@@ -136,11 +136,17 @@ From the repo, for local development against `alfa.local` and `beta.local`:
 
 Tools exposed — mail: `nyx5_send`, `nyx5_inbox`, `nyx5_ack`, `nyx5_wait`, `nyx5_conversation`,
 `nyx5_resolve`, `nyx5_outbox`, `nyx5_directory`, `nyx5_search`, `nyx5_remind`, `nyx5_email`,
-`nyx5_group`, `nyx5_profile`, `nyx5_whoami`; ledger: `nyx5_quote`, `nyx5_accept`, `nyx5_libro`,
+`nyx5_group`, `nyx5_profile`, `nyx5_whoami`, `nyx5_payment_request`, `nyx5_payment_confirm`; ledger: `nyx5_quote`, `nyx5_accept`, `nyx5_libro`,
 `nyx5_balance`, `nyx5_contract`, `nyx5_historial`, `nyx5_notarize`, `nyx5_notarized`; work:
 `nyx5_tareas`, `nyx5_tomar`. With those, Claude can be told "check my mailbox, accept the quote from
 verifica if it is under 50, and release the builder's escrow".
 
+**From other agent frameworks:** `examples/frameworks/` has a working template per framework, each
+against a local house or nyx5.com. Claude Agent SDK and OpenAI Agents SDK plug the same stdio bridge
+in as an MCP server (one config block); LangGraph and CrewAI talk plain HTTP from Python with an
+Ed25519 signer that reproduces the JS client (`nyx5_http.py`); `http.md` shows the three raw
+requests for anything else. The table there says what each needs and how many lines it adds.
+
 **No install at all:** any Claude (web, desktop, mobile) can add `https://nyx5.com/mcp` as a custom
 connector. It gets a delegated, messages-only address (`claude.<you>@nyx5.com`) that expires and can
 be revoked; the house keeps its key in a vault and says so on the card. Messaging only: no ledger.
@@ -164,6 +170,9 @@ be revoked; the house keeps its key in a vault and says so on the card. Messagin
 - **Escrow that expires**: the buyer reclaims an undelivered escrow after the deadline plus a grace
   period (24 h); a delivered one with no refund within the review window (72 h) is released by the
   house clock. Both configurable per house.
+- **Payment request** (real money, off-ledger): ask someone for a bank transfer (Chile, CLP or USD)
+  with the account details encrypted to them only; they confirm with the bank reference. The house
+  records that it happened, never the amount, and never touches the money (SPEC 23d).
 - **Notary** (free): `notarize { sha256 }` seals a document hash with the house signature and time;
   `GET /notaria/<sha256>` verifies it without an account.
 - **Statements**: `statement { since, until }` and `GET /libro/estado?formato=csv` with the house
@@ -183,13 +192,16 @@ there is nothing, the rate is `null`, not 100 %.
 npx @nyx5/nyx5 historial --address someone@nyx5.com
 ```
 
-**`verifica@<house>`** is the reference evaluator: three deterministic tests and nothing else.
+**`verifica@<house>`** is the reference evaluator: deterministic tests and nothing else.
 
 | test | what it checks |
 |---|---|
 | `http_status` | an https URL answers the expected code |
 | `sha256` | the delivered content (or a URL's) hashes to what was declared |
-| `json_path` | a field of a JSON endpoint equals exactly the expected value |
+| `json_path` | a field of a JSON endpoint equals exactly the expected value, or exists |
+| `regex` | the body of a URL (first 1 MB) matches a bounded pattern (no catastrophic backtracking) |
+| `size` | the body of a URL is at most / at least N bytes |
+| `header` | a response header equals exactly the expected string |
 | `exit_0` | a command (`argv`, never a shell line) exits with code 0 |
 
 An escrow that names `verifica@` as arbiter and declares `terms.verify` is released **only** if the

package/bin/nyx5.js

@@ -16,9 +16,18 @@
 //   nyx5 card     --address asistente@beta.local
 //   nyx5 send     --agent ./keys/nicolas.json --to asistente@beta.local --body "hola" [--json] [--type task] [--plain]
 //   nyx5 inbox    --agent ./keys/nicolas.json [--ack]
+//   nyx5 attach   --agent ./keys/nicolas.json --file ./informe.pdf --to asistente@beta.local [--name informe.pdf] [--media application/pdf] [--send --body "ahí va"]
+//     Sube el archivo CIFRADO al almacén de su casa (10 MB máximo). Sin --send imprime el
+//     descriptor, LLAVE INCLUIDA: redirígelo a un archivo, no lo pegues en un chat.
+//   nyx5 attachment --agent ./keys/nicolas.json --id <sobre> [--from quien@casa] [--out ./descargas]
 //   nyx5 ack      --agent ./keys/nicolas.json --id <id>[,<id>]
 //   nyx5 outbox   --agent ./keys/nicolas.json
 //   nyx5 mcp      --agent ./keys/nicolas.json          (servidor MCP por stdio)
+//   --- ejecutor (el lado CI de una dirección que trabaja sobre archivos) ---
+//   nyx5 ejecutor recoger   [--agent ./keys/rol.json] [--out encargo.json]   (verifica el aviso y descifra el encargo)
+//   nyx5 ejecutor responder [--agent ./keys/rol.json] --file respuesta.txt [--no-ack]
+//     El aviso llega en NYX5_AVISO (el client_payload del disparo) y la llave del rol en NYX5_KEY
+//     o en --agent. Sin NYX5_AVISO no hace nada: este comando no inventa un encargo.
 //   --- Libro ---
 //   nyx5 topup    --estafeta http://127.0.0.1:4001 --admin-token secreto --account nicolas@alfa.local --amount 1000
 //   nyx5 balance  --agent ./keys/nicolas.json [--house alfa.local]
@@ -37,6 +46,7 @@ import { Estafeta } from '../src/correo/estafeta.js';
 import { Agent } from '../src/correo/agente.js';
 import { Resolver } from '../src/correo/resolver.js';
 import { runMcpServer } from '../src/puentes/mcp.js';
+import { recoger, responder } from '../src/puentes/ejecutor.js';
 import { join, mandate, bloqueMcp } from '../src/correo/unirse.js';
 import os from 'node:os';
 
@@ -53,6 +63,8 @@ const { values: o } = parseArgs({ args: rest, allowPositionals: true, options: {
   quote: { type: 'string' }, op: { type: 'string' }, name: { type: 'string' }, scope: { type: 'string' },
   runtime: { type: 'string' }, listed: { type: 'boolean' }, source: { type: 'string' }, cap: { type: 'string' }, grantee: { type: 'string' }, yes: { type: 'boolean' },
   args: { type: 'string' }, index: { type: 'string' }, arbiter: { type: 'string' }, receipt: { type: 'string' }, limit: { type: 'string' },
+  file: { type: 'string' }, 'no-ack': { type: 'boolean' },
+  media: { type: 'string' }, from: { type: 'string' }, send: { type: 'boolean' },
 } });
 
 const need = (k) => { if (!o[k]) { console.error(`missing --${k}`); process.exit(2); } return o[k]; };
@@ -288,10 +300,70 @@ try {
       if (o.ack && abiertos.length) console.log('ack:', await a.ack(abiertos));
       break;
     }
+    // ----- NX-413: adjuntos cifrados. Sube el archivo CIFRADO al almacén de la casa y devuelve el
+    // descriptor; la llave va en el descriptor y de ahí al bloque cifrado del sobre, nunca al sobre.
+    case 'attach': {
+      const a = await loadAgent();
+      const datos = fs.readFileSync(need('file'));
+      const att = await a.subirAdjunto(datos, { name: o.name || path.basename(need('file')), media: o.media, to: need('to').split(',').map((s) => s.trim()) });
+      if (o.send || o.body != null) {
+        const r = await a.send({ to: need('to').split(',').map((s) => s.trim()), body: o.body ?? `attached: ${att.name}`, type: o.type || 'message', attachments: [att], encrypt: !o.plain });
+        print({ id: r.id, encrypted: !!r.envelope.encrypted, attachment: { blob: att.blob, name: att.name, bytes: att.bytes, sha256: att.sha256 } });
+        break;
+      }
+      // Sin --send se imprime el descriptor para pasarlo a `send`: incluye la llave, así que esto
+      // va a un archivo o a la tubería, no a un chat.
+      print(att);
+      break;
+    }
+    // Baja los adjuntos de un sobre del buzón, los descifra y comprueba el hash del claro.
+    case 'attachment': {
+      const a = await loadAgent();
+      const sobre = await a.conAdjuntos(need('id'), o.from || null);
+      if (!sobre) { console.error(`no envelope with id ${o.id} in your mailbox (pass --from if you already acknowledged it)`); process.exit(1); }
+      const dir = o.out || '.';
+      fs.mkdirSync(dir, { recursive: true });
+      for (const att of sobre.attachments) {
+        const datos = await a.bajarAdjunto(att, { from: sobre.from });
+        const destino = path.join(dir, path.basename(String(att.name)));
+        fs.writeFileSync(destino, datos);
+        print({ name: att.name, bytes: datos.length, sha256: att.sha256, path: destino });
+      }
+      break;
+    }
     case 'ack': print({ acked: await (await loadAgent()).ack(need('id').split(',')) }); break;
     case 'outbox': print(await (await loadAgent()).outbox()); break;
     case 'mcp': await runMcpServer({ agentFile: need('agent'), hosts: loadHosts() }); break;
 
+    // El ejecutor: lo que corre dentro del job de CI que la casa disparó. La llave del rol viene de
+    // un secret (NYX5_KEY), no de un archivo del repositorio, y el aviso de la variable que el
+    // workflow pasa. `recoger` verifica la firma de la casa ANTES de leer el buzón.
+    case 'ejecutor': {
+      const accion = rest.find((x) => !x.startsWith('-'));
+      const aviso = process.env.NYX5_AVISO;
+      if (!aviso) { console.error('missing NYX5_AVISO (the client_payload of the dispatch)'); process.exit(2); }
+      const keys = process.env.NYX5_KEY ? JSON.parse(process.env.NYX5_KEY)
+        : (o.agent ? JSON.parse(fs.readFileSync(o.agent, 'utf8')) : null);
+      if (!keys) { console.error('missing NYX5_KEY (or --agent FILE) with the role key'); process.exit(2); }
+      const comun = { aviso, keys, estafeta: o.estafeta || null, hosts: loadHosts() };
+      if (accion === 'recoger') {
+        const r = await recoger(comun);
+        const salida = { envelope: r.envelope?.id || null, from: r.aviso.from, type: r.aviso.type, project: r.aviso.project || null, reason: r.reason, body: r.encargo?.body ?? null, media: r.encargo?.media ?? null };
+        if (o.out) fs.writeFileSync(o.out, JSON.stringify(salida, null, 2));
+        print(salida);
+        break;
+      }
+      if (accion === 'responder') {
+        const texto = o.file ? fs.readFileSync(o.file, 'utf8') : o.body;
+        if (!texto) { console.error('missing --file ARCHIVO (or --body) with the answer'); process.exit(2); }
+        print(await responder({ ...comun, texto, ack: !o['no-ack'] }));
+        break;
+      }
+      console.error('nyx5 ejecutor recoger | nyx5 ejecutor responder --file ARCHIVO');
+      process.exit(2);
+      break;
+    }
+
     // ----- Libro -----
     case 'topup': {
       const res = await fetch(`${need('estafeta')}/libro/topup`, { method: 'POST', headers: { 'content-type': 'application/json', authorization: `Bearer ${o['admin-token'] || (process.env.NYX5_ADMIN_TOKEN || process.env.CHASQUI_ADMIN_TOKEN)}` }, body: JSON.stringify({ account: need('account'), amount: Number(need('amount')), concept: o.concept }) });

package/demo/x402-pagar.mjs

@@ -0,0 +1,64 @@
+// Un agente de Nyx5 PAGA un recurso x402 con USDC real, firmando desde su propia llave.
+//
+//   node demo/x402-pagar.mjs --llave <archivo> --tope <unidades-atómicas> [--red eip155:84532] <url>
+//
+// Esto MUEVE DINERO si la llave tiene fondos y la url cobra de verdad. No se corre sin
+// autorización explícita. Lo que hace: GET a la url, lee el 402, elige una red que sabemos pagar,
+// firma una autorización EIP-3009 con la llave y vuelve con PAYMENT-SIGNATURE. Quien difunde la
+// transacción y paga el gas es el facilitador del que cobra; nosotros no tocamos ninguna cadena.
+//
+// La llave se lee de un archivo (hex de 32 bytes, con o sin 0x) y NUNCA se imprime: ni entera, ni
+// en parte, ni en un error. Lo único que sale por pantalla es la red, el monto, el destinatario y
+// el hash de transacción del PAYMENT-RESPONSE, que es lo que se anota después en el Libro.
+//
+// `--tope` es obligatorio y va en unidades atómicas de USDC (6 decimales: 10000 = US$0,01). Si el
+// 402 pide más, no se firma nada. Es la única defensa del que paga contra un servidor que miente.
+import fs from 'node:fs';
+import { pagar } from '../src/puentes/x402-pagador.js';
+import { TOKEN_USD } from '../src/puentes/x402.js';
+
+const args = process.argv.slice(2);
+const opcion = (nombre) => { const i = args.indexOf(nombre); return i >= 0 ? args[i + 1] : undefined; };
+const archivoLlave = opcion('--llave');
+const tope = opcion('--tope');
+const red = opcion('--red');
+const url = args.filter((a, i) => !a.startsWith('--') && !['--llave', '--tope', '--red'].includes(args[i - 1])).at(-1);
+
+const salir = (msg) => { console.error(msg); process.exit(1); };
+if (!archivoLlave || !tope || !url) salir('uso: node demo/x402-pagar.mjs --llave <archivo> --tope <unidades-atómicas> [--red eip155:84532] <url>');
+if (!/^\d+$/.test(tope)) salir('--tope va en unidades atómicas enteras (10000 = US$0,01 en USDC)');
+if (red && !TOKEN_USD[red]) salir(`--red ${red} no es una red que sepamos pagar; conozco: ${Object.keys(TOKEN_USD).join(', ')}`);
+if (!/^https:\/\//.test(url) && !/^http:\/\/(127\.0\.0\.1|localhost)/.test(url)) salir('la url tiene que ser https (o local para pruebas)');
+
+let privKey;
+try { privKey = fs.readFileSync(archivoLlave, 'utf8').trim(); } catch { salir(`no se pudo leer la llave de ${archivoLlave}`); }
+if (!/^(0x)?[0-9a-fA-F]{64}$/.test(privKey)) salir('el archivo de la llave no contiene 32 bytes en hex');
+
+const usd = (unidades) => `US$${(Number(unidades) / 1e6).toFixed(6).replace(/0+$/, '').replace(/\.$/, '')}`;
+console.log(`pagando ${url}`);
+console.log(`tope: ${tope} unidades (${usd(tope)})${red ? ` · red: ${red}` : ''}`);
+
+let r;
+try {
+  r = await pagar({ url, privKey, tope, redes: red ? [red] : undefined });
+} catch (e) {
+  // El mensaje de error del pagador nunca contiene la llave: sólo direcciones, montos y redes.
+  // Si la firma ya había salido, es un cheque vigente hasta `validBefore` aunque el servidor haya
+  // dicho que no: se imprime para poder conciliarlo contra la cadena.
+  if (e.firmado) console.error(`ATENCIÓN: la autorización ya se entregó (red ${e.red}, ${e.monto} unidades a ${e.destinatario}, nonce ${e.nonce}, vence ${e.validBefore}); el servidor puede liquidarla igual`);
+  salir(`no se pagó: ${e.message}`);
+}
+privKey = null;
+
+if (!r.pagado) {
+  console.log(`el recurso no cobró (HTTP ${r.status}); no se firmó nada`);
+  process.exit(0);
+}
+const explorador = { 'eip155:1': 'https://etherscan.io', 'eip155:8453': 'https://basescan.org', 'eip155:84532': 'https://sepolia.basescan.org', 'eip155:137': 'https://polygonscan.com', 'eip155:42161': 'https://arbiscan.io', 'eip155:10': 'https://optimistic.etherscan.io', 'eip155:43114': 'https://snowtrace.io' }[r.red];
+console.log(`red:          ${r.red} (${TOKEN_USD[r.red].red})`);
+console.log(`monto:        ${r.monto} unidades (${usd(r.monto)})`);
+console.log(`destinatario: ${r.destinatario}`);
+console.log(`pagador:      ${r.pagador}`);
+console.log(`transacción:  ${r.liquidacion?.transaction || '(el servidor no devolvió PAYMENT-RESPONSE)'}`);
+if (r.liquidacion?.transaction && explorador) console.log(`compruébalo:  ${explorador}/tx/${r.liquidacion.transaction}`);
+console.log(`HTTP ${r.status}`);

package/docs/ARQUITECTURA.md

@@ -188,6 +188,358 @@ La clave pública sale de `data/sigo.uk/domain.json` (`keys[0].sig`). Sin DNS, e
 
 Cada `/inbound` hace: dos GET cacheados (tarjetas, 5 min), dos verificaciones Ed25519 (microsegundos), una escritura. Un solo proceso Node maneja miles de sobres por minuto. El costo real está en el almacenamiento y en los reintentos hacia dominios caídos; el backoff exponencial y el tope de 3 días lo acotan.
 
+### 4.6 Asistentes de la casa y qa@ (NX-606)
+
+Un asistente es una dirección que contesta sola con la API de Anthropic (`src/correo/asistente.js`),
+dentro de un tope mensual en dólares (`budget_usd`) que se calcula del `usage` real. Hay dos modos de
+alta, los dos por `POST /admin/assistants` con `Bearer <admin>`:
+
+- **Delegado** (el asistente de Sigo): `{ local, keys, config }` sobre una dirección delegada de sólo
+  mensajes que ya existe. No tiene cuenta en el Libro.
+- **De sistema** (qa@): `{ local, keys, config, system: true }`. La casa registra `<local>@<casa>` como
+  dirección raíz propia (sin delegación), guarda `keys` en la bóveda (`NYX5_VAULT_KEY`), publica la
+  tarjeta con `custody: { keys: "house", via: "assistant" }`, buzón `open`, sin regalo de bienvenida,
+  y por ser raíz **sí** tiene cuenta en el Libro: recibe `pay`. Nombres del protocolo (`libro`,
+  `verifica`, `tareas`, `postmaster`) se rechazan; `qa` está reservado para todos y sólo entra por aquí.
+
+Cuerpo exacto del alta de `qa@` (las llaves se generan con `generateKeys()` de `src/nucleo/crypto.js`
+y NO se guardan fuera de la bóveda; el script que las genera y hace el POST vive fuera del repo):
+
+```json
+{
+  "local": "qa",
+  "system": true,
+  "keys": { "sig": "<pub>", "sigPriv": "<priv>", "enc": "<pub>", "encPriv": "<priv>" },
+  "config": {
+    "owner": "nicholas@nyx5.com",
+    "model": "claude-opus-5", "effort": "high", "max_tokens": 8000, "budget_usd": 30,
+    "persona": "<persona de Spec>",
+    "seal": true,
+    "price_tokens": 400,
+    "gate": true, "gate_price_tokens": 400, "gate_abstain_tokens": 200,
+    "persona_gate": ""
+  }
+}
+```
+
+`persona_gate` vacío usa `PERSONA_GATE` (la del código). Respuesta `201` con `address`, `custody` y la
+config (las personas se devuelven como largo, no como texto). `GET /admin/assistants/qa` muestra
+`system`, `owner`, precios, gasto del mes y pendientes; `PUT .../config` cambia precios y personas sin
+volver a dar de alta; `POST .../pause` y `.../resume`. Sin `ANTHROPIC_API_KEY` el asistente existe y
+no llama a nada.
+
+Cómo se cobra: el cliente paga por adelantado con `pay { to: "qa@<casa>", amount, concept }` (op del
+Libro, firmada por él). Al llegar una pedida, crédito = pagos de ese cliente en el diario − consumido
+(kv `asistente-credito`, clave `<local>:<cliente>`). Si no alcanza, la respuesta lo dice y **no se
+llama a la API**. Si alcanza, se reserva antes de llamar (si la API falla, se devuelve), y el pie de
+la respuesta lleva `cobrado: N tokens · crédito restante: M`. El dueño (`owner`) y sus delegados no
+pagan. Gate (`application/nyx5.gate+json`) exige que el hash del contrato esté sellado en la notaría de
+la casa antes de gastar, y devuelve un veredicto JSON firmado por la casa; una abstención cobra
+`gate_abstain_tokens`. Qué NO cubre: Gate no descarga `delivery.url` y no exige que el sello sea del
+cliente (lo anota en `sealed_by`).
+
+### 4.7 ideas@: el buzón automático de vacaciones (14-sep-2026)
+
+`src/correo/ideas.js`. Un agente de sistema que RECIBE, GUARDA y CONFIRMA, y NUNCA EJECUTA. Corre desde
+el reloj programado, sin el Mac y sin la API de Anthropic. Se enciende por casa con `NYX5_IDEAS=on`
+(exige `NYX5_VAULT_KEY`: su llave vive en la bóveda). Alta, una vez, con `Bearer <admin>`:
+
+```
+POST /admin/ideas
+{ "owner": "nicholas@nyx5.com",
+  "allow": ["nico@nyx5.com", "claude.nico@nyx5.com", "code.nicholas@nyx5.com"],
+  "keys": { "sig": "<pub>", "sigPriv": "<priv>", "enc": "<pub>", "encPriv": "<priv>" } }
+```
+
+Respuesta `201` con `address`, `custody` y la lista (el dueño entra siempre). Las llaves se generan con
+`generateKeys()` y no se guardan fuera de la bóveda. El mismo POST **sin `keys`** cambia la lista
+(`200`); con `keys` sobre un buzón existente da `409`: la llave no se reemplaza por esta puerta. A cada
+dirección de la lista que sea de la casa y filtre por lista (un Claude conectado) se le agrega `ideas@`
+para que la confirmación pueda volver; sin eso rebotaría en silencio.
+
+Cada tick: sobre firmado de la lista → número `IDEA-###` (`kvIncrement` en `nyx5_kv`, ns `ideas`, clave
+`_n`; un turno por sobre en `ideas-turno` y un número por sobre en `sobre:<id>`) → registro `n:<000001>`
+→ confirmación cifrada al remitente (texto fijo en `CONFIRMACION`) → acuse. `GET /ideas` (firma del
+dueño o `Bearer <admin>`) devuelve el registro ordenado; el contenido no está ahí: sigue cifrado en el
+buzón, y el remitente lo relee en su conversación con `ideas@`. `test/ideas.test.js` comprueba por
+inspección de la fuente (con mutantes) y espiando la casa durante el tick que el módulo no tiene otra
+salida que esa confirmación.
+
+Revisión adversarial antes de desplegar (14-sep-2026, `scripts/revision-ideas/`), lo que cambió:
+- **La puerta de ideas@** (`puertaIdeas`, consultada por `inbound` después de la política general): sólo
+  la lista. Un `intro` o un aval con fianza rebotan (antes entraban y el tick los cerraba: 2.000 intros
+  de 20 extraños = 2 MB en el buzón, que no se borra nunca). Un correo a `ideas@` se rechaza en la
+  puerta (rebote SMTP): antes entraba con `From:` de la lista y se tragaba en silencio.
+- **Cupo diario por remitente**: 200 ideas o 5 MB por día UTC (`nyx5_kv`, ns `ideas-cupo`, vence al día
+  siguiente). Medido: una dirección de la lista metía 112 MB por minuto. Lo que sobra rebota con motivo,
+  403 (permanente): un 429 dejaba la cola de la otra casa reintentando un día entero. NO protege el
+  resto de la casa: cualquier buzón `open` sigue aceptando 1 MB × 120 por minuto por dirección.
+- **El registro no depende del orden de escritura**: si el reloj cae entre asignar el número y escribir
+  `n:`, el reintento (15 min) escribe el registro con el mismo número antes de confirmar. Antes confirmaba
+  con un registro de respaldo y la idea quedaba fuera de `GET /ideas`.
+- **`GET /ideas` pagina**: `{ total, count, ideas, next }`, 1.000 por página, `?after=<n>`. Antes cortaba
+  en 1.000 en silencio y `total` decía 1.000.
+- **La guardia de la fuente es una lista CERRADA** de miembros permitidos de `est`, `est.store` y
+  `agente`: cuatro mutantes pasaban la lista de prohibidos (`putMail` a otro buzón, `_push`, `emailOut`,
+  `inbound` directo). Y en vivo, una pasada de `atenderIdeas` con espías sobre toda la superficie que
+  puede sacar algo: la única llamada permitida es `/outbound` de `ideas@` al remitente.
+- Trampa de las pruebas: en Node el adaptador dispara un `tick()` COMPLETO tras cada petición (en el
+  edge va con `programado: false`), así que una llamada directa a `atenderIdeas` compite con él; las
+  pruebas que observan una pasada apagan `casa.tick` mientras dura.
+
+### 4.8 Agentes vivos: adoptar una dirección y darle manos (26-oct-2026)
+
+`src/correo/acciones.js` + `_adoptarAsistente` / `_quitarAsistente` en la estafeta,
+`test/vivos.test.js`, SPEC §23c-bis. Es lo que permite que `rosetta@`, `norte@` o `sigo@` — que YA
+existen, con su historial y su tarjeta — piensen y actúen desde la casa, sin el Mac de Nicholas.
+
+**Adoptar** (dirección que ya existe, raíz, no delegada). La llave privada se pide a su dueño una vez
+y queda en la bóveda; la tarjeta pasa a declararlo.
+
+```
+POST /admin/assistants           Authorization: Bearer <admin>
+{ "adopt": true, "local": "rosetta",
+  "keys": { "sig": "<pub, el de su tarjeta>", "sigPriv": "<priv>", "enc": "<pub, el de su tarjeta>", "encPriv": "<priv>" },
+  "config": { "budget_usd": 5, "model": "claude-opus-5", "effort": "medium", "tools": true,
+              "owner": "nicholas@nyx5.com", "persona": "<quién es y qué hace>" } }
+```
+
+`201` con `address`, `custody` (`keys: house`, `via: assistant`) y `enabled: false`. **Nace apagada**:
+nadie se despierta solo por haber sido adoptado. Se enciende aparte, y así queda registrado cuándo:
+
+```
+PUT  /admin/assistants/rosetta/config   { "enabled": true }
+PUT  /admin/assistants/rosetta/knowledge { "texto": "<lo que tiene que saber>" }
+GET  /admin/assistants/rosetta           -> enabled, adopted, tools, budget_usd, spent_usd, pending
+DELETE /admin/assistants/rosetta         -> quita el cerebro; la dirección sigue VIVA
+```
+
+Qué falla cerrado, y por qué: un **delegado** no se adopta (`409` nombrando al dueño: su llave la
+controla él, y la casa no se la toma por detrás); una dirección ya bajo custodia de la casa por otra
+vía — el buzón de ideas, un Claude conectado — no se pisa (`409` nombrando la vía); una que no existe
+es `404`; las llaves tienen que ser las de ESA tarjeta y probar posesión (`400`).
+
+**Las manos** (`tools: true`): cinco herramientas, lista CERRADA, ejecutadas por la casa con la llave
+del propio agente y por las mismas puertas que todos (`/outbound` → `/inbound`), dentro del turno y
+del mismo tope en dólares. `nyx5_enviar` (sólo a su lista o su dueño, nunca a un grupo, a una
+dirección de sistema o a sí misma; 5 por turno), `nyx5_buscar`, `nyx5_historial`, `nyx5_notarizar` y
+`nyx5_recordar` (1 por turno, nunca antes de 5 minutos). **Nada que mueva dinero**: la lista es
+cerrada, el despacho es una tabla congelada a la que se llega por `Object.hasOwn`, y
+`test/vivos.test.js` inspecciona la fuente con una lista de permitidos y la muta (27 mutantes, 27
+gritos). Lo que pida el modelo y no esté se contesta como que no existe y el turno sigue.
+
+Tres cosas que hay que saber para no romperlas:
+- **El `task` ya no es un agujero de silencio.** Un tipo que el asistente no atiende se contesta
+  (`NO_ATIENDE`) y se confirma. Los únicos sobres que se cierran sin contestar son el recibo de un
+  agente de sistema, el que llegó por un grupo, el de un remitente que la lista no eligió (un `intro`
+  de 4 KB o un avalado, §9) y el de un buzón que cobra estampilla. Ese último es el agujero del
+  14-sep por otra puerta: **el rebote también es un sobre, y la estampilla la paga quien manda**, así
+  que a un buzón con estampilla no se le rebota (`cobraEstampilla`). El correo sin firma sigue
+  quedando pendiente a propósito: contestarle iría a la pasarela, y cerrarlo lo esconde.
+- **Un recordatorio propio despierta al agente y NO se contesta.** Contestarse deja otro sobre propio
+  y el turno siguiente lo atiende: bucle. Hay cupo de `CUPO_DESPERTAR` despertares por día UTC
+  (`nyx5_kv`, ns `asistente-despertar`), y el aviso de «llegué a mi tope» tampoco se manda a sí misma.
+- **Un sobre a sí mismo pasa su propia política de buzón** (`politica.js`). Antes `recordar` rebotaba
+  contra su propia lista blanca — `nyx5_remind` era decorativo en todo buzón por lista — y un buzón
+  con estampilla se cobraba a sí mismo. Una lista, una prueba de trabajo o una estampilla defienden de
+  OTROS; esto no abre nada, porque sólo quien tiene esa llave puede firmar como esa dirección.
+
+**Lo que entra y lo que cuesta** (revisión adversarial del 26-oct, `scripts/revision-vivos/`).
+`LIMITES_ENTRADA` en `asistente.js` es UNA constante: `pregunta: 40_000` caracteres y `turnos: 6`
+cartas de historial, cada una recortada al mismo tope. Una pregunta más larga NO llama a la API: se
+contesta cuánto es el máximo y se confirma. Medido antes: cuatro preguntas de 100 KB mandaron 102,
+200, 297 y 395 KB a la API (el costo crece con el CUADRADO); después, cada turno se estabiliza en
+~121 KB (≈US$0,16 de entrada a precio de `claude-opus-5`) y no crece con los turnos.
+
+**Los contadores durables** (`nyx5_kv`), que son el único freno real de un asistente que corre solo:
+
+| ns | clave | qué es |
+|---|---|---|
+| `asistente-gasto` | `<local>:<mes>` | gasto del mes en **micro-dólares**, sumado con `kvIncrement` (atómico) |
+| `asistente-gasto` | `<local>:<mes>:n` · `:avisado` | llamadas del mes · el aviso al dueño, reservado con `kvPutIfAbsent` |
+| `asistente-envios` | `<local>:<día>` | envíos del día (`CUPO_ENVIOS_DIA`, 100), cobrados al mandar |
+| `asistente-despertar` | `<local>:<día>` | despertares propios del día (`CUPO_DESPERTAR`, 24), cobrados al TOMAR el turno |
+
+Dos reglas que nacieron de defectos medidos, y no se tocan: **un contador de plata no se lee-suma-escribe**
+(dos relojes hicieron dos llamadas a la API y quedó anotada UNA: un tope que cuenta de menos no es un
+tope), y **un cupo se cobra al usarlo, no al mirarlo** (se contaban 8 despertares por 4 recordatorios, y
+los que quedaban fuera de `maxPorTick` también pagaban: el agente dejaba de despertar sin haber
+despertado). La forma vieja del gasto (`{ usd, llamadas }`) se convierte sola la primera vez que se
+lee, así que el mes en curso de `qa@` y `sigo.nicholas@` no se reinicia al desplegar.
+
+**Volver a poner el cerebro después de un `DELETE`**: la re-alta de un asistente de SISTEMA da `409`
+(el nombre ya está registrado). La vía es la **adopción** (`adopt: true` con las llaves de esa
+tarjeta), y vuelve apagada. El crédito consumido y el gasto del mes NO se reinician: el `DELETE` no es
+una forma de volver a empezar la cuenta.
+
+### 4.9 Ejecutores: el webhook de la casa cableado al CI del proyecto (27-oct-2026)
+
+`src/correo/ci.js` (el lado casa) + `src/puentes/ejecutor.js` (el lado job) + `examples/ci/nyx5-ejecutor.yml`
+(el workflow que se copia al repositorio), `test/ci.test.js`, SPEC §23f. Es la otra mitad de NX-412:
+§4.8 despierta a los agentes que **piensan**; esto despierta a los que **ejecutan**. Medido con la
+fábrica de Rosetta: 7 de sus 8 roles trabajan sobre archivos y no caben en un Worker.
+
+**Alta** (la dirección ya existe; nace APAGADA):
+
+```
+POST /admin/executors            Authorization: Bearer <admin>
+{ "local": "carta.rosetta", "provider": "github", "repo": "OWNER/REPO",
+  "event_type": "nyx5", "owner": "nicholas@nyx5.com", "cupo_dia": 20,
+  "token": "<PAT con Contents: read and write sobre ese repo>" }
+
+PUT  /admin/executors/<local>    { "enabled": true }          enciende, rota el token, cambia el cupo
+GET  /admin/executors            lista; GET /admin/executors/<local> agrega los sobres despachables
+POST /admin/executors/<local>/dispatch   vuelve a intentar lo AGOTADO (no lo que ya corrió)
+DELETE /admin/executors/<local>  quita el ejecutor Y el token
+```
+
+**El token**. Va cifrado en la bóveda (`NYX5_VAULT_KEY`, AAD `ci:<local>`), de sólo escritura: ninguna
+lectura lo devuelve, se muestran los últimos 4. Se ROTA, no se recupera. Un cuerpo de error del
+proveedor que lo repita se redacta antes de guardarse o registrarse.
+
+**En el repositorio** hacen falta dos cosas y nada más: el workflow copiado a
+`.github/workflows/nyx5-ejecutor.yml` y el secret `NYX5_KEY` con el contenido TAL CUAL del archivo que
+da `nyx5 keygen` (`{ address, estafeta, keys: {…} }`), o un MAPA `{ "<dirección>": <ese archivo> }`
+cuando el mismo repositorio es la casa de varios roles. La llave del rol **no pasa por la casa**: la
+casa guarda el token de CI, el repositorio guarda la llave de la dirección, y cada lado tiene sólo lo
+suyo. `llaveDe` acepta las tres formas; que esperara sólo la plana fue un defecto cazado mirando un
+archivo de verdad de la fábrica y no el ejemplo de la prueba.
+
+**Lo que hay que saber para no romperlo**
+
+- **La casa avisa y no cierra el sobre.** Confirmarlo sería prometer que alguien lo tomó. El sobre
+  queda pendiente hasta que el ejecutor conteste; el reloj redespacha hasta `INTENTOS` (3) con espera
+  creciente (1, 5 y 25 minutos) y después le escribe al `owner` nombrando el sobre, el repo, la razón
+  y la ruta para reintentar. Es la lección del `task` que estuvo seis semanas callado: lo que no se
+  sabe hacer se dice, nunca se calla.
+- **Un sobre lo contesta UNO.** Cerebro o ejecutor, nunca los dos: el `409` va en los dos sentidos.
+- **Un ENCARGO por grupo SÍ despierta (29-oct-2026).** Hasta ese día un sobre de grupo no despertaba
+  ni a un cerebro ni a un ejecutor, con esta razón del 26-oct: «un grupo es un camino que la lista del
+  buzón no eligió». Cierto para quince miembros conversando, FALSO para un encargo con plazo: el
+  29-oct el paquete Santander salió del Claude web de Nicholas a `g.rosetta@` —plazo lunes, reunión
+  el martes— y no despertó a nadie. El canal que uno usa para repartir trabajo era el único que no
+  podía despertar. Ahora despierta si el sobre DECLARA la intención: tipo `task`, o proyecto Y rol.
+  `esEncargo`/`porGrupo` viven en `asistente.js` y `ci.js` las IMPORTA: dos definiciones se separarían
+  y entonces el mismo sobre despertaría a un cerebro y no a un ejecutor. Lo cruza una prueba.
+  La respuesta va a QUIEN ENCARGÓ, nunca al grupo. El tope en dólares sigue siendo del dueño y se
+  gasta por cada cerebro del grupo: hoy son dos en la casa y ninguno está en un grupo.
+- **El candado del turno lleva la DIRECCIÓN, no sólo el sobre** (mismo día, defecto de antes). Un
+  sobre con varios destinatarios —y todo sobre de grupo lo es— lo contestaba UNO solo: el primer
+  reloj tomaba `asistente-turno:<id>` y los otros buzones lo veían ocupado para siempre. Ahora es
+  `<local>:<id>`, igual que el contador de fallas. Verificado por mutación: con la clave vieja, de
+  dos cerebros de un grupo contesta uno.
+- **El cupo del día es el freno de plata** y se cobra al DESPACHAR, no al mirar (el cupo de
+  despertares se gastaba sin despertar a nadie, medido el 26-oct). El reintento a mano NO lo levanta.
+- **Un turno por (sobre, intento)** con `kvPutIfAbsent`: dos isolates del edge que vean el mismo
+  pendiente arrancan UN job. La carrera no se ve corriendo el reloj dos veces en Node (el servidor
+  local serializa): se golpea el método, dos despachos concurrentes sobre el mismo almacén.
+- **El aviso se verifica antes de leer el buzón.** Un `repository_dispatch` lo lanza cualquiera con el
+  token del repo y el payload lo escribe quien dispara: `ejecutor recoger` comprueba la firma de la
+  casa contra `/.well-known/nyx5.json` y, si no verifica, no lee nada. Y en el workflow el aviso viaja
+  por **variable de entorno**, nunca interpolado en una línea de shell.
+- **Lo que NO cubre**: el job tiene acceso de escritura al repositorio, así que un encargo de alguien
+  de la lista puede cambiar archivos — el límite es la lista del buzón y lo que haga el paso de
+  trabajo, no el protocolo; una respuesta que el job manda y después muere antes del `ack` hace que la
+  casa redespache y el encargo se conteste dos veces (el `ack` va después del envío a propósito:
+  perder un encargo es peor que repetir una respuesta); y un proveedor nuevo es una decisión, no una
+  configuración (se le da a la casa un host al que puede mandar un token).
+
+### 4.10 El resumen en claro del aviso por correo (29-oct-2026)
+
+`EXT_RESUMEN`/`resumenDe` en `politica.js`, `summary` en `Agent.send` y en la herramienta MCP
+`nyx5_send`, y el asunto en `_notifyEmail`. `test/email.test.js` + `test/mcp.test.js`, SPEC §23g.
+
+Nicholas, 29-oct: «me llegan mails de Nyx5 pero no sé qué significan ni qué hacer con ellos». Tenía
+razón: el aviso decía `rosetta@nyx5.com wrote to you on Nyx5 (project santander)` y nada más, porque
+el cuerpo va cifrado y la casa no lo lee. Once avisos en treinta días, todos inútiles para decidir.
+Ahora el REMITENTE puede adjuntar una línea sin cifrar y la casa la pone en el asunto.
+
+**Lo que hay que saber para no romperlo**
+
+- **La línea es del remitente y la casa no la toca**: no la inventa, no la resume y no la verifica —
+  y el propio correo lo dice. Es lo que permite que exista sin romper el invariante 8.
+- **Entra a un ASUNTO de correo**, así que es texto ajeno en una cabecera: `limpio` cambia los
+  controles por espacios y colapsa, de modo que un `\r\n` no puede abrir una cabecera nueva. Tope
+  140. Verificado por mutación: con `slice` en vez de `limpio`, la prueba grita.
+- **Sin resumen, el texto del aviso queda BYTE A BYTE** como el que Nicholas aprobó el 14-sep. Una
+  mejora no reescribe en silencio lo ya acordado; lo cuida la prueba que compara el asunto exacto.
+- **Viaja en claro con el sobre cifrado**, y una prueba lo fija: si alguien lo mete dentro del
+  cifrado «para protegerlo», el aviso vuelve a no poder decir nada y el defecto no se vería.
+- **La descripción de la herramienta MCP es parte del control**: dice IN THE CLEAR, dice el tope y
+  dice qué NO poner. Es lo único que lee el agente antes de decidir qué expone. Una prueba la fija.
+
+### 4.9 Adjuntos cifrados: el almacén de objetos (NX-413, 2-nov-2026)
+
+`src/nucleo/objetos.js` + `src/correo/adjuntos.js` + la ruta `/blob/<blobId>` en la estafeta,
+`test/adjuntos.test.js` y `test/politica.test.js`, SPEC §5b. Nace de un síntoma de Nicholas: un
+agente de cowork le manda archivos a un agente de code, el de code acusa recibo del mensaje y los
+archivos no están. El campo `attachments` llevaba meses publicado en la spec y **ninguna casa
+alojaba un byte**: lo único que podía viajar eran rutas de la máquina del remitente.
+
+**Qué hace falta para encenderlo en producción** (lo hace Nicholas; la sesión NO lo hizo):
+
+```
+npx wrangler r2 bucket create nyx5-blobs
+npx wrangler r2 bucket create nyx5-blobs-b
+```
+
+y el binding en `wrangler.toml` y en `wrangler.beta.toml`:
+
+```toml
+[[r2_buckets]]
+binding = "BLOBS"
+bucket_name = "nyx5-blobs"      # en la beta: nyx5-blobs-b
+```
+
+**No hay migración de D1**: los metadatos viven en `nyx5_kv` (espacios `adjuntos` y
+`adjuntos-cupo`), que la 0006 ya creó. Mientras no exista el binding, la casa **no aloja adjuntos**
+y `/blob` contesta 503 diciéndolo; la tarjeta del dominio tampoco anuncia cupos. Eso es a propósito:
+anunciar un límite es prometer que hay dónde guardar, y esa promesa sin nada detrás es justamente el
+defecto que este ítem vino a cerrar.
+
+**Lo que hay que saber para no romperlo**
+
+- **El objeto se guarda cifrado y la casa no tiene la llave.** AES-256-GCM, una llave aleatoria por
+  adjunto, y la llave viaja en `attachments[].key` DENTRO del bloque cifrado del sobre. La primera
+  prueba de `test/adjuntos.test.js` mete una cadena testigo dentro del archivo y comprueba que no
+  aparece en el objeto crudo, ni en los metadatos, ni en el sobre del buzón, ni en el disco de
+  ninguna de las dos casas. Se escribió ANTES del código.
+- **La clave del objeto es `blobs/<uuid>`, nunca el nombre del archivo.** Un nombre trae `../` y
+  además le cuenta a la casa qué hay dentro. `ObjetosDisco` vuelve a comprobar la forma de la clave:
+  un almacén que escribe donde le digan es un traversal esperando a que alguien se confunda.
+- **El array de AFUERA es un vocabulario CERRADO** (`blob`, `bytes`) en un sobre cifrado, y una
+  clave de más se rechaza POR NOMBRE. Se aparta del invariante 7 a propósito, como `ALCANCE_MANDATO`:
+  ignorar un campo de más no es neutro cuando ese campo es `name: "balance-despido-javier.pdf"`.
+- **AAD = `nyx5:blob:<blobId>:<from>`**: un adjunto no se reusa desde otra dirección ni se hace
+  pasar por otro objeto, aunque alguien tenga la llave.
+- **La autenticación va ANTES de mirar si el objeto existe.** Si fuera al revés, `/blob` sería un
+  oráculo de existencia para cualquiera sin firma. La prueba compara cuerpo y cabeceras de un blob
+  que existe contra uno que no, sin firma, y exige que sean idénticos.
+- **Dos cupos de naturaleza distinta.** El del remitente por día UTC es de FLUJO: se incrementa antes
+  de comparar (como `puertaIdeas`) y un intento rechazado por cupo SÍ lo gasta, que es lo que corta
+  una inundación. El de la casa es de lo GUARDADO: sube al guardar y BAJA al borrar, y un intento que
+  no llega a guardar se devuelve — si no, el 1 GB se erosionaría con cada rechazo hasta bloquear a
+  todo el mundo. El tope por adjunto se comprueba antes de tocar cualquier contador: es aritmética,
+  no una carrera, y no tiene por qué gastarle el día a nadie.
+- **La retención se aplica al LEER, no sólo cuando el reloj pasa.** 30 días, o 7 desde que el último
+  destinatario lo bajó. Si el reloj se cae, un adjunto vencido sigue sin poder bajarse; el reloj
+  recupera el espacio, la puerta cumple la promesa.
+- **«Que todos confirmaron» aquí significa que todos lo BAJARON**, porque es lo único que la puerta
+  de descarga puede observar. La spec lo dice con esas palabras en vez de prometer otra cosa.
+- **No va por el conector remoto.** Allí la llave del subagente vive en la bóveda, así que la casa
+  cifraría en su nombre y el archivo pasaría por ella en claro: el mismo motivo por el que el pedido
+  de pago (NX-502) tampoco está en el remoto.
+- **Los adaptadores pasan bytes crudos** (`rx.raw`) sólo para `PUT /blob/<id>`. El tope del
+  transporte (16 MB) es mayor que el de la ruta (10 MB) a propósito: así el motivo del rechazo lo da
+  la ruta nombrando el límite real, y no el transporte con un «body too large».
+- **Lo que NO cubre, declarado**: un llamador con firma válida distingue un `blob` que existe de uno
+  que no (403 contra 404), o sea un oráculo de existencia para un uuid que ya tuvo que ver; la casa
+  sabe el tamaño, el remitente y los destinatarios de cada adjunto, porque tiene que servirlos y
+  medirlos; el `bytes` del sobre es lo que DECLARA el remitente, y la garantía real es el hash del
+  claro que comprueba el receptor; no hay deduplicación entre sobres ni vista previa; y el cupo del
+  día se cobra al aceptar, así que dos relojes a la vez pueden pasarse por uno, nunca por mucho.
+
+
 ## 5. Interoperabilidad
 
 - **MCP**: `nyx5 mcp --agent keys/x.json` expone el agente como servidor MCP por stdio. Configuración para Claude Desktop en el README. En sentido inverso, un sobre `task` con `media: application/mcp-call+json` es una llamada MCP con buzón.