Nexus: autopilot, trabajo en paralelo y ejecuciones duraderas

Nexus es el orquestador de Core. Tiene cuatro roles: Scrum Master (sprints, historias, retrospectivas), Quick Flow (un cambio pequeño con el mínimo de ceremonia), Autopilot Controller (el pipeline de la idea a la entrega, con puntos de control) y Parallel Supervisor (varios agentes a la vez, sin colisiones). Debajo hay un runtime duradero, bmad-plus nexus, que guarda en disco grafos de tareas e intentos para que el trabajo sobreviva a una sesión cerrada y nada cuente como hecho hasta que lo digan comprobaciones independientes. Esta página es para quien quiere automatizar el trabajo de más de un agente y saber exactamente hasta dónde llega la automatización.

Autopilot#

Di autopilot en el chat de tu herramienta de IA y luego describe el proyecto. Son instrucciones de chat, no comandos de terminal. Nexus examina la petición y el proyecto antes de elegir etapas: un cambio pequeño va directo a la implementación y la revisión, mientras que un contrato que falta o una incertidumbre de peso justifica una planificación más profunda. Para un proyecto que necesita el pipeline completo hay tres fases.

Cada punto de control sigue el ajuste de _bmad/config.yaml: require_approval se detiene y espera, notify_only informa y continúa, auto continúa y lo registra. Con execution_mode: autopilot, el punto de control story pasa por defecto a notify_only. Una notificación externa (un mensaje a tu teléfono, por ejemplo) necesita un canal configurado y tu autorización: una instalación básica no tiene ningún emisor en segundo plano, así que ningún recordatorio se envía por sí solo.

La aceptación humana también encaja. Con uat.mode: advisory (por defecto, también cuando falta el bloque) la página se construye y se ofrece en cada entrega y nunca bloquea; gate hace que el punto de control de entrega espere a que bmad-plus uat gate pase; off no produce receta y el informe de entrega lo dice. Un pack también puede declarar un pipeline en el registro (pasos ordenados, cada uno con una puerta); autopilot ejecuta entonces ese pipeline para el trabajo del pack, tras su intake. Ningún pack declara uno en 0.23.0, así que es una capacidad del framework, no contenido entregado.

Estado, reanudación y fallos#

• El estado de referencia vive en .bmad-plus/nexus/runs/. El archivo opcional .bmad-plus/orchestrator-state.yaml es solo un resumen de navegación; no puede demostrar que algo esté aceptado ni que un proceso se haya detenido.
• No existe un ejecutable autopilot --resume. Para reanudar, inspecciona la ejecución duradera prevista y el estado real del anfitrión, y reconcilia un intento interrumpido antes de reintentar.
• Fallo de prueba: se conservan las comprobaciones fallidas, la reparación se hace dentro del maxAttempts de la tarea y luego se vuelven a verificar los artefactos cambiados. Una declaración de terminado no puede hacer pasar una comprobación que falla.
• Error de agente: se conservan el trabajo parcial y la identidad de su intento, y el informe dice qué sigue incierto. Las tareas dependientes esperan la aceptación.
• Conflicto en trabajo paralelo: se deja de asignar trabajo que se solapa, se inspeccionan los propietarios, se reconcilian sus intentos y se conservan tus cambios antes de cualquier reintento.

El trabajo en paralelo#

Di parallel en el chat, o deja que autopilot lo llame cuando parallel_execution es true y se detectan tareas independientes. El Parallel Supervisor decide qué puede ejecutarse a la vez; el anfitrión decide si puede. El paralelismo real depende de tu herramienta: si no puede ejecutar subagentes, las tareas se ejecutan una tras otra.

El runtime duradero#

bmad-plus nexus conserva un grafo de tareas y sus intentos en .bmad-plus/nexus/runs/. Cada cambio normal toma un bloqueo exclusivo del proyecto y escribe un archivo de estado con suma de comprobación, mediante un archivo temporal volcado a disco y un renombrado atómico. La inspección es de solo lectura. Se mantienen separados tres resultados, y esa separación es el sentido mismo del runtime.

Las evidencias siguen siendo honestas con el tiempo. Una tarea aceptada cuenta como vigente solo mientras sus artefactos, recursos protegidos y cada dependencia transitiva sigan coincidiendo con lo verificado: cambiar un archivo aguas arriba invalida las evidencias de los dependientes, y un registro antiguo de «aceptada» no afirma que archivos editados después sigan pasando. Un plazo es una observación, no prueba de que el trabajo nunca ocurrió o de que un proceso terminó.

El archivo de plan#

Un plan es un archivo JSON; la entrada estructurada pasa siempre por archivos para que el quoting del shell no pueda reinterpretar un array de comando. Este plan mínimo tiene una tarea cuyo resultado debe cumplir una comprobación que ya existe (checks/check-result.cjs) y cuyo código fuente queda fuera del ámbito de escritura del worker.

{
  "id": "example",
  "maxParallel": 1,
  "config": { "language": "English" },
  "tasks": [
    {
      "id": "result",
      "objective": "Produce the requested result in work/result.txt.",
      "acceptance": ["The result satisfies the independent check."],
      "dependsOn": [],
      "scope": ["work"],
      "artifacts": ["work/result.txt"],
      "resources": ["checks/check-result.cjs", ".agents/skills/agent-orchestrator/SKILL.md"],
      "checks": [
        {
          "id": "result-content",
          "command": "node",
          "args": ["checks/check-result.cjs"],
          "cwd": ".",
          "timeoutMs": 30000
        }
      ],
      "maxAttempts": 2,
      "deadlineMs": 3600000,
      "idempotent": true,
      "authorizations": ["Edit work/ and run the listed local check."]
    }
  ]
}

Las rutas de un plan son portables, relativas al proyecto y usan /. Se rechazan las rutas absolutas, el recorrido hacia arriba, los flujos alternativos, los nombres reservados de Windows, los enlaces simbólicos o uniones, y las escrituras en .git o en el árbol de estado de Nexus. Las comprobaciones se ejecutan con un entorno restringido: solo se pueden copiar PATH, SYSTEMROOT, WINDIR, TEMP, TMP y TMPDIR (más unas variables de identidad y ruta no secretas en Windows), la configuración regional es C, la zona horaria es UTC, y NODE_OPTIONS, PYTHONPATH, los hooks de carga y las credenciales están ausentes. Es una restricción del entorno, no un sandbox del sistema operativo.

El flujo gestionado por el anfitrión: create, start, record, verify, accept#

El backend por defecto es el anfitrión: tu asistente hace el trabajo con sus propios medios e informa. Abajo, una ejecución real de una dispersión (fanout) exportada desde un enjambre (tres unidades de página; solo se recorre la primera). Crea los tres archivos del enjambre y host.json en un proyecto para reproducirla. El «worker» es un sustituto que escribe a mano el archivo de respuesta: el ejemplo muestra la contabilidad, no el trabajo de ningún modelo.

{
  "schemaVersion": 1,
  "id": "site-pages",
  "kind": "fanout",
  "title": "One sub-agent per page of the site",
  "units": { "source": "input" },
  "brief": { "template": "briefs/page.md", "context": [] },
  "answer": {
    "required": ["id", "done", "words"],
    "fields": {
      "done": { "type": "boolean" },
      "words": { "type": "integer", "min": 0 },
      "note": { "type": "string", "max": 200 }
    }
  },
  "tally": { "rate": "done", "numbers": ["words"] },
  "disclosure": "Each page was written by a separate sub-agent from the same brief; read them together before publishing."
}

{
  "schemaVersion": 1,
  "units": [
    { "id": "about", "scope": "site/about", "title": "About us", "tone": "warm" },
    { "id": "pricing", "scope": ["site/pricing", "site/data/prices.json"], "title": "Pricing", "tone": "plain" },
    { "id": "contact", "scope": "site/contact", "title": "Contact", "tone": "short" }
  ]
}

# Page {{unit.id}}

Write the page "{{card.title}}" under `{{card.scope}}`, {{card.tone}} in tone. Touch nothing
outside that folder.

When the page is written, write a JSON object to `{{answer.path}}` with `id` ("{{unit.id}}"),
`done`, `words` (the word count) and an optional `note`.

{{disclosure}}

{ "backend": { "kind": "host", "id": "demo-worker", "sessionId": "demo-session-1" } }

$ npx bmad-plus swarm init --definition swarm/page-fanout.json --units swarm/units.json
site-pages-20261019-vwk0: fanout of 3 units, budget 26, approval not-needed.
Units listed, no seed.
Next: bmad-plus swarm briefs site-pages-20261019-vwk0
$ npx bmad-plus swarm plan site-pages-20261019-vwk0 --out .bmad-plus/swarm/reports/site-pages-20261019-vwk0/plan.json
/work/demo/app/.bmad-plus/swarm/reports/site-pages-20261019-vwk0/plan.json: 3 tasks, 10 in parallel.
Next: bmad-plus nexus create --plan /work/demo/app/.bmad-plus/swarm/reports/site-pages-20261019-vwk0/plan.json
$ npx bmad-plus nexus create --plan .bmad-plus/swarm/reports/site-pages-20261019-vwk0/plan.json
Nexus run site-pages-20261019-vwk0 — durable task coordination
about: not started; verification=pending; acceptance=pending
pricing: not started; verification=pending; acceptance=pending
contact: not started; verification=pending; acceptance=pending
Use inspect --json for recorded evidence and reconciliation observations.
$ npx bmad-plus nexus start site-pages-20261019-vwk0 about --input host.json
about: running; verification=pending; acceptance=pending
  Attempt: a4ec0495-660b-487c-8c83-e82ada22a857; host: demo-worker/demo-session-1
$ echo '{"id":"about","done":true,"words":120}' > .bmad-plus/swarm/runs/site-pages-20261019-vwk0/answers/about.json
# El worker de sustitución escribe su archivo de respuesta a mano. Luego escribe rec.json (se muestra bajo este terminal) con el id de intento que imprime start.
$ npx bmad-plus nexus record site-pages-20261019-vwk0 about --input rec.json
about: completed; verification=pending; acceptance=pending
  Attempt: a4ec0495-660b-487c-8c83-e82ada22a857; host: demo-worker/demo-session-1
$ npx bmad-plus nexus verify site-pages-20261019-vwk0 about
about: completed; verification=passed; acceptance=pending
$ npx bmad-plus nexus accept site-pages-20261019-vwk0 about
about: completed; verification=passed; acceptance=accepted
$ npx bmad-plus nexus inspect site-pages-20261019-vwk0
about: completed; verification=passed; acceptance=accepted
  Accept only after rechecking current artifacts and resources.
pricing: not started; verification=pending; acceptance=pending
  Start when dependencies have current accepted evidence.
# Cada comando nexus imprime además la línea de encabezado, las líneas pricing y contact y la indicación final; aquí solo se conservan las líneas que cambian.

{
  "attemptId": "a4ec0495-660b-487c-8c83-e82ada22a857",
  "backend": { "kind": "host", "id": "demo-worker", "sessionId": "demo-session-1" },
  "outcome": "completed",
  "exitCode": 0,
  "summary": "The demo host reports the about page is written."
}

record necesita el id exacto del intento y el mismo backend y sesión. Los otros resultados son failed, blocked (la petición sigue visible y conserva su capacidad) y ambiguous (entonces se rechazan los acuses ordinarios; reconcilia explícitamente). verify sale con 1 cuando la verificación no pasó, y accept rechaza una tarea sin una verificación superada elegible. El código de salida de un worker o una frase que diga «hecho» nunca sustituye un recibo de comprobación.

Interrupción, cancelación y reintento#

El backend de procesos opcional y el adaptador Codex#

Una tarea puede llevar un objeto execution en vez de pertenecer al anfitrión. Es una definición aportada por el operador, nunca un comando deducido del texto de la tarea. nexus launch RUN TASK permanece entonces en primer plano hasta que acaba la operación que posee; un terminal, un anfitrión de código o un runner de CI lo mantiene vivo. El registro de la tarea se guarda antes de lanzar el proceso: liga un id de intento nuevo a una sesión de supervisor nueva, a la definición exacta y a los hashes de sus entradas protegidas. El supervisor conserva stdout y stderr acotados, la salida o la señal reales y un recibo con suma de comprobación. launch deja pendiente la recogida incluso tras una salida limpia: nexus collect RUN TASK --input attempt.json (el attemptId exacto y el objeto backend completo) la cierra, y rechaza un recibo ajeno, repetido o tardío. El estado 0 de launch significa solo que el recibo del proceso dice completed; no significa aceptación.

{
  "execution": {
    "adapter": "command",
    "command": "node",
    "args": ["workers/task.cjs"],
    "cwd": ".",
    "input": "inputs/task.json",
    "resources": ["workers/task.cjs"],
    "blockedExitCodes": [75],
    "outputLimitBytes": 262144
  }
}

{
  "execution": {
    "adapter": "codex-exec",
    "command": "/absolute/path/to/codex",
    "input": "inputs/task.md",
    "instructions": [".agents/skills/agent-architect-dev/SKILL.md"],
    "sandbox": "workspace-write"
  }
}

• El ejecutable se resuelve a un archivo regular y su SHA-256 queda fijado en el plan. Los argumentos son arrays literales, pasados sin shell, sin sobrescribir el entorno y sin instantánea de credenciales.
• Las entradas de texto son de 256 KiB cada una como máximo y el conjunto completo de 1 MiB. Las instrucciones se anteponen a la entrada estándar con sus rutas relativas.
• Una salida a cero es finalización genérica; un código distinto de cero listado en blockedExitCodes es bloqueado. Esa lista es una convención de tu envoltorio, nunca una política de aprobación.
• El adaptador Codex construye -a never exec --json --color never --sandbox MODE --skip-git-repo-check --ignore-user-config -; model es opcional y solo añade --model MODEL. sandbox es read-only (por defecto) o workspace-write; no se acepta ningún otro flag, ninguna omisión de aprobación ni cadena de shell. Solo HOME, USERPROFILE, HOMEDRIVE, HOMEPATH y CODEX_HOME pueden heredarse más allá del entorno mínimo, y los recibos listan nombres de variables, no valores.
• La finalización de Codex exige una salida a cero, una identidad thread.started y un evento turn.completed sin error terminal. Solo los códigos de error explícitos approval_required pasan a bloqueado; los demás errores del proveedor siguen siendo fallos.
• La cancelación está ligada a la identidad devuelta. Solo el supervisor original puede señalizar al proceso hijo directo que creó; nada mata un PID guardado ni adopta un terminal antiguo. Un plazo, una salida excesiva o un supervisor perdido producen un resultado ambiguo y retienen la capacidad hasta la reconciliación.
• Evidencia honesta: el contrato de flags se comprobó con Codex CLI 0.153.4. Una llamada autorizada el 2026-09-11 produjo un hilo y un evento terminal reales, pero el anfitrión rechazó como solo lectura la edición de archivo pedida; Nexus recogió el recibo, el verificador independiente falló y se rechazó la aceptación. Eso muestra el cableado y la contención del fallo en ese anfitrión; allí no se estableció que Codex escriba archivos con éxito.

Límites y lo que no hace#

• Sin demonio, sin planificador, sin bucle desatendido. Cada lanzamiento es explícito y retiene una plaza de capacidad; la capacidad no es un presupuesto de dinero.
• Sin sandbox del sistema operativo. Los workers comparten el proyecto y el usuario del sistema con Nexus y pueden ignorar los scopes declarados; las sumas de comprobación detectan cambios accidentales, no son firmas. Protege el plan y el verificador, y usa un proyecto aislado o una política del anfitrión cuando importe.
• Sin commit de Git, fusión ni despliegue. Aceptación significa «el espacio de trabajo actual superó las comprobaciones independientes», nada más.
• Ninguna afirmación sobre la calidad de un modelo. Un recibo no es evidencia de que un modelo mejorara en nada.
• Un tiempo de verificación agotado solo señaliza al hijo directo y registra un resultado ambiguo, porque no se demuestra la ausencia de descendientes o de efectos externos. Los programas de comprobación deben ser comandos acotados en primer plano.

autopilot. El proyecto: una API pequeña que permite a autónomos enviar presupuestos y convertirlos en facturas. Empieza por el intake de cualquier pack implicado. Detente en el punto de control del PRD y en el de la arquitectura y espera mi aprobación. Mantén cada historia pequeña, verifica cada una con sus criterios de aceptación antes de la siguiente y dime al final qué sigue incierto.

parallel. Toma las historias aprobadas y divídelas en tareas que no toquen los mismos archivos. Para cada tarea da un ámbito de escritura exclusivo, los archivos que puede leer y una comprobación que yo pueda ejecutar. Registra el plan con bmad-plus nexus create, ejecuta juntas solo las tareas independientes y enséñame nexus inspect tras cada oleada. No aceptes una tarea antes de que nexus verify haya pasado.