Configuración de Repo Mesh dirigida por un agente

Esta página está escrita para un agente de codificación con IA (Claude Code, Codex, Hermes o similar) al que se le ha pedido configurar Repo Mesh en una o varias máquinas que ya ejecutan ADHDev. Sigue los pasos numerados en orden y ejecuta cada paso exactamente como está escrito — algunos son comandos de shell, otros son llamadas a herramientas MCP (mira el recuadro justo debajo).

Para lectores humanos: entrégale esta página a tu agente y dile "configura Repo Mesh siguiendo la guía de configuración del mesh" — el agente hará el descubrimiento, propondrá la configuración y se detendrá para pedir tu aprobación en cada paso que escriba algo. Tú apruebas; él hace el resto.

Este es el atajo automatizado. Para los conceptos que hay detrás lee Repo Mesh; para un recorrido manual y práctico lee Tutorial: tu primera tarea real.

La forma del flujo: máquinas ya configuradas → crear el mesh → mesh_init propone la configuración → tú apruebas → lanzar un coordinador.

Herramientas MCP vs. comandos de CLI — no son intercambiables

Cada nombre mesh_* de esta página (mesh_plan_onboarding, mesh_create, mesh_add_node, mesh_init, mesh_status, …) es una herramienta MCP — llámala a través de la interfaz de herramientas de tu agente, no desde la shell. No existe ningún comando adhdev mesh init ni adhdev mesh_status; ejecutar un nombre mesh_* en la shell falla con "unknown command."

Algunos de estos pasos también tienen un equivalente en la CLI (adhdev mesh plan, adhdev mesh create, adhdev mesh add-node) que hace lo mismo sin un cliente MCP — se muestran en bloques ```bash a lo largo de la página. Todo lo que aparece en un bloque de código plano y sin etiqueta (sin bash) es una llamada a una herramienta MCP, no un comando de shell. Los equivalentes de CLI se detienen en el Paso 2 — mesh_init (Paso 3) y todo lo que viene después (slots, MAGI, el conjunto de herramientas del coordinador) no tiene forma de CLI; es solo MCP.

Qué asume esta guía

Necesitas una instalación funcional de ADHDev en cada máquina que vaya a alojar un nodo del mesh. Si una máquina aún no está configurada, ejecuta primero en ella Configuración de una máquina nueva dirigida por un agente y vuelve aquí.

Una sola máquina vs. multimáquina

	Mesh de una sola máquina	Mesh multimáquina
Funciona en	Standalone y Cloud	Solo Cloud
Nodos	Worktrees de git de un repo en una máquina	Workspaces repartidos entre varias máquinas
¿Requiere cuenta?	No (standalone)	Sí — la misma cuenta en cada daemon

Un mesh de una sola máquina es real y totalmente funcional en la build autoalojada standalone: los nodos worktree, la cola de tareas, Refinery, MAGI y el modo mesh de MCP se ejecutan todos localmente. Lo que standalone no puede hacer es transmitir entre máquinas — coordinar varios daemons de la misma cuenta es la función de Cloud.

Regla práctica para el agente: si el usuario quiere paralelismo de worktrees en una sola máquina, standalone es suficiente. Si menciona dos o más máquinas, necesita iniciar sesión en Cloud en cada una (consulta Multimáquina).

Paso 0 — Verifica los requisitos previos

0a. ¿Está el daemon levantado en esta máquina?

bash

adhdev status

Esperado: el daemon se reporta sano — standalone en localhost:3847, o la máquina mostrada como online contra api.adhf.dev en modo Cloud.

Si no: detente y ejecuta primero Configuración de una máquina nueva dirigida por un agente. No continúes contra un daemon muerto — todos los pasos posteriores lo necesitan.

0b. ¿Es el workspace un repositorio Git con un remoto?

Repo Mesh identifica un mesh por la identidad de su repo, que proviene del remoto de Git. Ejecuta esto en el workspace que pretendes añadir:

bash

git rev-parse --show-toplevel
git remote -v

Esperado: una ruta a la raíz del repo y al menos un remoto. Si no hay remoto, el descubrimiento del Paso 2 fallará con remote_not_found — todavía puedes pasar una identidad a mano al crear el mesh (--identity), pero un remoto real es la vía normal.

0c. ¿Tienes las herramientas del mesh?

Este es el paso que más a menudo se salta, y nada de lo que viene después funciona sin él. Tus herramientas mesh_* provienen del servidor MCP de ADHDev ejecutándose en modo mesh. Hay dos formas de llegar ahí, y están ordenadas:

Primero el modo estándar — un registro MCP normal te da tres herramientas de bootstrap: mesh_plan_onboarding, mesh_create, mesh_add_node. Eso es exactamente lo suficiente para crear un mesh.
Después el modo mesh — una vez que existe un mesh, vuelve a registrarlo con --repo-mesh <mesh_id> para obtener el conjunto completo de herramientas del coordinador.

El modo mesh se niega a arrancar si aún no existe ningún mesh, así que no puedes saltar directamente a él.

Comprueba si hay un mesh fantasma antes de fiarte de un .mcp.json existente

Si este workspace ya tiene un .mcp.json con --repo-mesh <mesh_id> dentro, no asumas que ese mesh es real — puede ser un resto de una sesión anterior cuyo mesh se eliminó después. Confírmalo primero:

bash

adhdev mesh list

Si el mesh_id de .mcp.json no está en esa lista, trata el registro existente como una configuración fantasma: fallará al arrancar en modo mesh (o apuntará silenciosamente a la nada). Elimínalo o reemplázalo con el mesh_id que obtengas del Paso 2 más abajo, en lugar de intentar reutilizarlo.

Registra el modo estándar en la configuración de tu cliente MCP. El nombre del servidor lo eliges tú; adhdev es lo convencional:

json

{
  "mcpServers": {
    "adhdev": {
      "command": "adhdev",
      "args": ["mcp"]
    }
  }
}

Para Codex, el registro equivalente es una llamada de CLI en lugar de una edición de JSON:

bash

codex mcp add adhdev -- adhdev mcp

El servidor MCP necesita un daemon vivo

adhdev mcp hace ping al daemon antes de registrar ninguna herramienta y sale con código 1 si no puede alcanzar uno. El modo local apunta al daemon standalone en el puerto 3847 (adhdev standalone); el modo IPC apunta al daemon de la nube (adhdev daemon). Si el servidor MCP muere al arrancar, vuelve a revisar el Paso 0a — casi siempre es un daemon que no está en ejecución.

Flags útiles, por si los necesitas:

Flag	Significado
`--mode <local\|ipc>`	Transporte. `local` = daemon standalone, `ipc` = daemon de la nube
`--port <n>`	Puerto del daemon. Por defecto: local `3847`, ipc `19222`
`--password <pass>`	Contraseña del daemon standalone, si has definido una
`--repo-mesh <mesh_id>`	Cambia al modo mesh (Paso 2c)

Variables de entorno equivalentes: ADHDEV_PASSWORD, ADHDEV_MESH_ID, ADHDEV_MCP_TRANSPORT.

Reinicia el cliente tras editar la configuración MCP

Los servidores MCP se leen al arrancar el cliente. Después de cualquier cambio de registro, inicia una sesión de agente nueva — una sesión ya en ejecución no recogerá las herramientas nuevas.

Paso 1 — Inventaría las máquinas

Si el usuario quiere un mesh multimáquina, confirma que cada máquina está online antes de construir el mesh, para no añadir un nodo que no puedas alcanzar.

bash

adhdev status

Ejecuta esto en cada máquina, o revisa la lista de máquinas del panel de la nube. Cada host previsto debe aparecer online bajo la misma cuenta.

Si falta una máquina: pásala por Configuración de una máquina nueva dirigida por un agente. El inicio de sesión en Cloud en esa máquina es un paso humano — el agente no puede hacerlo.

Si el usuario solo tiene una máquina: no pasa nada, continúa. Construirás nodos worktree en lugar de nodos remotos en el Paso 2b.

Paso 2 — Construye el mesh

2a. Planifica primero (solo lectura, no escribe nada)

Empieza siempre con el dry-run. mesh_plan_onboarding realiza únicamente lecturas del sistema de archivos y consultas locales de Git — sin fetch, sin escritura de configuración, sin creación de ramas ni worktrees.

Llamada a herramienta MCP (a través de la interfaz de herramientas de tu agente, no desde la shell):

mesh_plan_onboarding(workspace: "<absolute path to repo>")

Equivalente en la CLI, que imprime el mismo plan:

bash

adhdev mesh plan
adhdev mesh plan --json    # complete machine-readable plan

Esperado: un plan cuyo kind sea uno de create_mesh_and_onboard, add_existing_workspace o clone_new_worktree, más un bloque discovery (identidad del repo, rama, limpio/sucio) y una lista de pasos, cada uno marcado como de solo lectura o que requiere aprobación. La CLI termina con: "Nothing was written."

Lee el plan antes de actuar. Te dice cuál de las tres herramientas siguientes debes llamar, y hará aflorar los bloqueos por adelantado en vez de a mitad de camino.

Códigos de fallo habituales y qué significan:

Código	Significado
`not_git_repository`	Directorio equivocado — apunta `workspace` a la raíz del repo
`remote_not_found`	Sin remoto de Git; consulta el Paso 0b
`dirty_workspace`	Cambios sin commitear — haz commit o stash y vuelve a planificar
`nested_worktree`	Estás dentro de un worktree de un worktree; usa el checkout principal
`compatible_mesh_exists`	Ya existe un mesh para este repo — añade un nodo en vez de crear uno
`detached_head`	Haz checkout de una rama primero

2b. Crea el mesh y añade nodos

Sigue lo que te haya dicho el plan.

Crear un mesh nuevo (plan de tipo create_mesh_and_onboard) — llamada a herramienta MCP:

mesh_create(name: "<mesh name>", add_current: true)

add_current: true registra el workspace actual como el primer nodo del mesh en la misma llamada. La respuesta contiene el mesh_id que necesitarás en todo lo que viene abajo.

mesh_create(add_current: true) no define providerPriority

A diferencia de mesh_add_node, mesh_create no tiene parámetro provider_priority. El primer nodo que registra no tiene policy.providerPriority hasta que definas uno — consulta el aviso al final de este paso.

Equivalente en la CLI:

bash

adhdev mesh create my-project --add-current

Añadir un workspace existente como nodo (plan de tipo add_existing_workspace) — usa esto para una segunda máquina, o un segundo checkout. Llamada a herramienta MCP:

mesh_add_node(workspace: "<absolute path>", mesh_id: "<mesh_id>")

Opcional: read_only: true para un nodo al que nunca deban asignarse tareas de escritura, y provider_priority: ["claude-cli", "codex-cli"] para fijar qué agente se ejecuta ahí — consulta el aviso sobre providerPriority más abajo para ver por qué esto importa.

Equivalente en la CLI:

bash

adhdev mesh add-node mesh_abc123 --worktree --provider-priority claude-cli,codex-cli

Crear un nodo worktree (plan de tipo clone_new_worktree) — así es como consigues paralelismo en una sola máquina. En realidad ejecuta git worktree add. Llamada a herramienta MCP (sin equivalente en la CLI):

mesh_clone_node(source_node_id: "<node_id>", branch: "<new branch name>")

base_branch es opcional — por defecto es el HEAD actual.

Confirma providerPriority antes de seguir

mesh_launch_session falla de forma cerrada (missing_provider_priority) cuando se llama sin un type explícito sobre un nodo cuyo policy.providerPriority está vacío — y ni mesh_create(add_current: true) ni mesh_clone_node lo definen. Comprueba cada nodo que acabas de crear:

mesh_status()

Si a un nodo le falta providerPriority, o bien pasa provider_priority al registrarlo vía mesh_add_node, o llama siempre a mesh_launch_session con un type explícito para ese nodo, o define la política a través del editor de políticas de Repo Mesh del panel / un .adhdev/mesh.json commiteado. mesh_init (Paso 3) recomienda una lista de providerPriority a partir de los proveedores de CLI detectados, pero es solo orientativa — no la escribe en la política del nodo por ti.

Verifica lo que has construido:

bash

adhdev mesh show mesh_abc123
adhdev mesh status mesh_abc123

show lista los nodos; status sondea la salud de cada uno.

2c. Vuelve a registrar el servidor MCP en modo mesh

Ahora que existe un mesh, cambia tu cliente a modo mesh para desbloquear el conjunto completo de herramientas del coordinador. Actualiza la configuración MCP, reemplazando el marcador de posición por tu mesh_id real:

⏸ El runtime de tu agente puede bloquear esta edición — no la sortees

Editar .mcp.json cambia qué herramientas recibe una sesión futura, así que algunos runtimes de agente lo protegen tras una aprobación aparte (distinta de las ediciones de archivos ordinarias). Si eres un agente y esta edición está bloqueada: no intentes saltarte el control. Detente y entrégale a la persona el diff exacto de una línea para .mcp.json (o el bloque YAML para Hermes) más el comando a ejecutar, para que pueda aplicarlo ella misma. Reintentar, escalar o buscar otra forma de escribir los mismos bytes anula el propósito de la comprobación de seguridad.

json

{
  "mcpServers": {
    "adhdev-mesh": {
      "command": "adhdev",
      "args": ["mcp", "--mode", "ipc", "--repo-mesh", "mesh_abc123"]
    }
  }
}

Para Hermes, lo mismo en YAML bajo mcp_servers — localiza el archivo con hermes config path:

yaml

mcp_servers:
  adhdev-mesh:
    command: adhdev
    args:
      - mcp
      - --mode
      - ipc
      - --repo-mesh
      - mesh_abc123
    enabled: true

Para Codex:

bash

codex mcp add adhdev-mesh -- adhdev mcp --mode ipc --repo-mesh mesh_abc123

Luego reinicia la sesión del agente. En modo mesh la superficie de herramientas se reemplaza por completo — las herramientas de sesión estándar desaparecen y aparecen las herramientas del coordinador del mesh.

Usuarios de standalone

Usa --mode local en lugar de --mode ipc. El modo IPC habla con el daemon de la nube; el modo local habla con el daemon standalone en el puerto 3847.

Paso 3 — Deja que `mesh_init` proponga la configuración del repo

Este es el paso init — el que lee tu repo y escribe valores por defecto sensatos para que no tengas que redactar archivos de configuración a mano.

mesh_init es una herramienta MCP, no un comando de CLI — no existe adhdev mesh init. Llámala a través de la interfaz de herramientas de tu agente. Es una herramienta de dos etapas: previsualiza por defecto y solo escribe cuando lo indicas explícitamente.

3a. Previsualización (por defecto — no escribe nada)

Llamada a herramienta MCP (sin equivalente en la CLI):

mesh_init()

Eso es todo. write es false por defecto, así que esta ejecución es un dry-run: la respuesta vuelve con dryRun: true y cada configuración propuesta lleva written: false.

Propone tres archivos de configuración a nivel de repo:

Archivo	Qué configura
`.adhdev/refine.json`	Validación de Refinery — los comandos que deben pasar antes de que una rama converja
`.adhdev/worktree_bootstrap.json`	Qué ejecutar en un worktree recién creado (instalación de dependencias)
`.adhdev/change-impact.json`	Ajustes del análisis de impacto de cambios

También devuelve una recomendación de providerPriority, que es solo orientativa — mesh_init nunca la aplica por ti.

Cómo se eligen los comandos de verificación. mesh_init lee los scripts de tu package.json y los coteja con cuatro categorías: typecheck, test, lint, build. Un script cuyo nombre sea igual a una categoría, o que empiece por <category>:, se convierte en un comando sugerido como npm run <script>. Las sugerencias se combinan con cualquier comando de proyecto a nivel de mesh, se deduplican y se limitan a 4.

Los repos que no usan npm no reciben sugerencias

La detección solo coteja scripts de npm llamados exactamente typecheck / test / lint / build o con el prefijo typecheck: / test: / etc. Un repo que usa cargo test, go test, poetry run pytest, un tsc --noEmit a secas, o un script llamado de otra forma (check, vitest) recibe cero sugerencias y un skippedReason: "no_suggestion". Eso es lo esperado, no un fallo — escribe .adhdev/refine.json a mano para esos repos.

3b. Revisa con la persona ⏸ PASO HUMANO

⏸ PASO HUMANO — muestra la propuesta antes de escribir

Presenta al usuario los bloques refine, worktreeBootstrap y changeImpact propuestos y obtén una aprobación explícita. Estos archivos aterrizan en el repo y se convierten en la puerta que decide si el trabajo futuro converge — un comando de test equivocado aquí bloquea silenciosamente cada merge posterior.

Pregunta específicamente por los comandos de validación de refine: ¿son estos los comandos que realmente tienen que pasar en este repo? Ese es el único campo que una persona debería revisar siempre con sus propios ojos.

3c. Escritura (solo tras la aprobación)

Llamada a herramienta MCP:

mesh_init(write: true)

mesh_init nunca pisa una configuración existente. Si un archivo ya está ahí, vuelve con skippedReason: "already_exists" y se deja intacto. Para reemplazarlo deliberadamente:

mesh_init(write: true, overwrite: true)

También existe mesh_reinit, que es la misma operación con overwrite a true por defecto — úsala cuando pretendas un refresco, para que la intención quede explícita en la llamada.

Verifica: la respuesta informa dryRun: false y written: true por archivo. Confirma en disco:

bash

ls .adhdev/

Commitea estos archivos. Son configuración del repo — todo el sentido es que cada nodo y cada coordinador futuro lean las mismas reglas.

Paso 4 — Modelos, límites y MAGI

Todo en este paso tiene un valor por defecto que funciona. Cambia solo lo que al usuario realmente le importe, y pregunta solo cuando la respuesta cambiaría el resultado.

4a. Slots de nodo — qué agente y qué modelo se ejecuta dónde

Un slot vincula un proveedor (y opcionalmente un modelo y un nivel de razonamiento) a una clase de dificultad. Inspecciona lo que tiene ahora un nodo:

mesh_node_slots_list(node_id: "<node_id>")

Si un nodo no tiene slots explícitos, se derivan unos sensatos a partir de su prioridad de proveedores y de los presets de dificultad por mesh, que por defecto son:

Dificultad	Modelo	Nivel de razonamiento
`easy`	`haiku`	`low`
`medium`	`sonnet`	`medium`
`difficult`	`opus`	`high`

freeform es la cuarta dificultad válida y deliberadamente no tiene preset.

Deja esto en paz salvo que el usuario lo pida. Los valores derivados por defecto son correctos para la mayoría de los meshes. Define slots explícitamente cuando el usuario quiera control de costes (fijar el trabajo barato a un modelo pequeño) o tenga un proveedor que solo existe en una máquina.

Igual que mesh_init, esta herramienta es dry-run por defecto:

mesh_node_slots_set(node_id: "<node_id>", slots: [...])            # preview
mesh_node_slots_set(node_id: "<node_id>", slots: [...], write: true)  # apply

Los slots se reemplazan en bloque

slots no se fusiona con lo que ya hay — reemplaza la lista de slots completa del nodo. Ejecuta siempre mesh_node_slots_list primero y construye tu nuevo array a partir del actual, o perderás configuración de forma silenciosa. Ejecuta el dry-run y compara currentSlots con proposedSlots antes de escribir.

Por slot: provider es obligatorio; model, thinkingLevel, difficulty (array), capability (array) y maxParallel son opcionales. Un difficulty vacío significa que el slot atiende todas las dificultades.

4b. Límites de política — quédate con los valores por defecto

La política del mesh gobierna los checkpoints, la aprobación de push, los reintentos y la concurrencia. Los valores por defecto son deliberadamente permisivos en concurrencia y conservadores en seguridad, y no deberías tocarlos durante la configuración. En particular:

maxParallelTasks es efectivamente ilimitado por defecto; el panel oculta este control a propósito.
requireApprovalForPush es true por defecto — los push preguntan primero.
requirePostTaskCheckpoint es true por defecto — se hace checkpoint del trabajo después de cada tarea.
delegatedWorkerAutoApprove es true por defecto — las sesiones worker no se atascan en sus propios avisos de herramientas.

Pregunta al usuario solo sobre esto: si quiere que la aprobación de push siga activada. Para todo lo demás, quédate con el valor por defecto y sigue adelante. La política se define a través del editor de políticas de Repo Mesh del panel o de un .adhdev/mesh.json commiteado, no mediante una herramienta de configuración del mesh.

4c. MAGI — opcional, vale la pena activarlo si usas más de un agente

MAGI hace la misma pregunta a varios agentes a la vez y compara las respuestas. Es una función de verificación cruzada, y el eje que la hace funcionar es la diversidad de agentes/proveedores — modelos distintos fallan de formas distintas, así que dos proveedores en desacuerdo es la señal que estás comprando.

Esto va de qué CLIs tienes instaladas, no de cuántas máquinas posees. Si hay dos o más agentes distintos disponibles — por ejemplo claude-cli y codex-cli — un panel MAGI es perfectamente válido en una sola máquina. La mayoría de los desarrolladores ya tienen varias CLIs instaladas, así que vale la pena ofrecerlo en vez de saltárselo. Repartir el panel entre máquinas añade independencia por encima, pero es un extra, nunca un requisito previo.

Pregunta al usuario si lo quiere. Si ejecuta más de un proveedor de agentes, recomiéndalo; si solo tiene una CLI instalada, sáltatelo y explica por qué.

Mecánicamente, MAGI requiere al menos 2 objetivos (nodo, proveedor) independientes y nunca degrada silenciosamente a un solo agente. Un objetivo se identifica por nodo y proveedor juntos, así que dos proveedores distintos en un mismo nodo son dos objetivos distintos y satisfacen el requisito. MAGI además emite una nota orientativa cuando un panel tiene menos de 2 proveedores distintos o menos de 2 nodos distintos — eso es una pista sobre lo correlacionado que está tu panel, no un fallo. La configuración que de verdad importa son dos proveedores distintos; un panel con un solo proveedor replicado dos veces es el caso débil, abarque o no varias máquinas.

Si el usuario lo quiere, vincula un panel a un tipo de tarea. Los tipos válidos son claim_audit, rca, design y freeform:

mesh_magi_kind_panel_list()                                        # what's configured now
mesh_magi_kind_panel_set(task_kind: "rca", slots: [...])           # preview
mesh_magi_kind_panel_set(task_kind: "rca", slots: [...], write: true)

Las mismas dos reglas que con los slots de nodo: dry-run por defecto, y la lista de slots reemplaza el panel en bloque. Cada slot necesita un provider; nodeId, model, capabilityTags y n (número de réplicas, 1 por defecto) son opcionales. Un nodeId debe nombrar un nodo de este mesh o la llamada se rechaza.

Los paneles se almacenan por mesh y son locales a la máquina — viven en ~/.adhdev/meshes.json, no en el repo.

Paso 5 — Lanza el coordinador

El coordinador es la sesión que sostiene las herramientas del mesh y entrega trabajo a los nodos.

Un coordinador no puede lanzarse a sí mismo

No existe una herramienta mesh_launch_coordinator ni un subcomando adhdev mesh que arranque uno. Si eres un agente leyendo esto, no puedes completar este paso llamando a una herramienta — pásaselo a la persona, o usa la Vía B de abajo.

Vía A — Panel (la forma normal) ⏸ PASO HUMANO

⏸ PASO HUMANO — esto lo pulsa la persona

Abre la página Repo Mesh (/mesh) en el panel.
Si el mesh aún no tiene un host fijado, define el daemon host — esta es una acción aparte y deliberada, distinta de lanzarlo.
Elige un proveedor de CLI en el desplegable.
Haz clic en Launch Host.

El daemon registra automáticamente el servidor MCP del mesh para ese proveedor y abre la sesión coordinadora como una pestaña del panel. Si el proveedor elegido necesita configuración MCP manual, la interfaz muestra un bloque de configuración para pegar — aplícalo e inicia una sesión de CLI nueva.

Los fallos afloran como códigos explícitos que vale la pena conocer: mesh_coordinator_node_not_found (no se resolvió ningún workspace), mesh_coordinator_provider_priority_unusable (no hay ningún agente utilizable en ese nodo), mesh_coordinator_mcp_registration_failed (el registro falló, así que la sesión no se lanzó — un fallo cerrado deliberado).

Vía B — Modo mesh de MCP (sin panel)

Si ya hiciste el Paso 2c, eres efectivamente un coordinador: tu sesión sostiene la superficie de herramientas de modo mesh. Confírmalo:

mesh_status()

Esperado: un snapshot agregado que lista tus nodos. Si la herramienta no existe, el registro en modo mesh no cuajó — revisa el Paso 2c y reinicia la sesión.

Paso 6 — Prueba de humo

Demuestra que el bucle funciona antes de entregarle el mesh a trabajo real. Encola una tarea pequeña y segura:

mesh_enqueue_task(...)

Un nodo inactivo reclama el trabajo encolado — esa es la vía prevista. mesh_send_task apunta directamente a una sesión concreta en su lugar; úsalo solo cuando pretendas saltarte la cola.

Míralo avanzar:

mesh_view_queue()
mesh_status()

Esperado: la tarea pasa de encolada a reclamada y a completada, y mesh_git_status muestra el cambio en el nodo que la ejecutó.

La finalización se basa en evidencia — estado de git, checkpoints y eventos del ledger, no el autoinforme del agente. Si una tarea informa de éxito, confirma el efecto secundario antes de creértelo.

Para una primera tarea más completa y con sustancia real, sigue Tutorial: tu primera tarea real.

Lo que la persona hizo realmente

Pegó esta página en un agente.
Inició sesión en cada máquina — una vez por máquina, aprobación en el navegador (solo Cloud).
Aprobó la propuesta de configuración de mesh_init.
Hizo clic en Launch Host en el panel. 4′. Condicional: si el runtime del agente bloqueó la edición de .mcp.json en el Paso 2c, aplicó el diff de una línea que le entregó el agente.
Todo lo demás — descubrimiento de Git, creación del mesh, nodos worktree, detección de configuración, slots por defecto — lo hizo el agente.

Resolución de problemas

Las herramientas mesh_* no existen en la sesión — el servidor MCP no está en modo mesh, o la sesión es anterior al cambio de configuración. Revisa el Paso 2c e inicia una sesión nueva; la configuración MCP se lee al arrancar el cliente.
El servidor MCP sale inmediatamente — hace ping al daemon antes de registrar herramientas y sale con 1 cuando no puede alcanzar uno. Ejecuta adhdev status. El modo local necesita adhdev standalone; el modo ipc necesita adhdev daemon.
El modo mesh se niega a arrancar — el modo mesh requiere un mesh existente. Ejecuta adhdev mesh list para confirmar el ID, y crea uno mediante el modo estándar primero si no hay ninguno.
.mcp.json ya tiene un --repo-mesh <id> pero el modo mesh no arranca / adhdev mesh list no lo muestra — es una configuración fantasma de un mesh eliminado (mira el aviso del Paso 0c). Confírmalo con adhdev mesh list y reemplaza el id por uno real del Paso 2.
adhdev mesh init dice unknown command — mesh_init es una herramienta MCP, no un subcomando de la CLI. Llámala a través de la interfaz de herramientas de tu agente una vez que estés registrado en modo mesh (Paso 2c), no desde la shell.
El runtime del agente bloquea la edición de .mcp.json — es lo esperado en algunos runtimes (Paso 2c); el agente debería entregarte el diff exacto en vez de intentar sortear el bloqueo.
mesh_launch_session falla con missing_provider_priority / "no providerPriority policy" — el nodo no tiene policy.providerPriority y no pasaste un type explícito. O bien llama a mesh_launch_session con type definido, o define provider_priority en el nodo (vuelve a añadirlo vía mesh_add_node, o edita la política del mesh). La sugerencia de providerPriority de mesh_init es solo orientativa — no se aplica automáticamente.
dirty_workspace desde el plan — haz commit o stash y vuelve a planificar. El onboarding se niega deliberadamente a construir nodos sobre trabajo sin commitear.
compatible_mesh_exists — ya existe un mesh para este repo. Usa mesh_add_node contra él en lugar de mesh_create.
mesh_init no escribió nada — o bien los archivos ya existen (skippedReason: "already_exists" — pasa overwrite: true si pretendes reemplazarlos) o no se detectó nada (skippedReason: "no_suggestion" — un repo que no usa npm; escribe la configuración a mano).
Un nodo aparece como probe-failed en adhdev mesh status — el daemon de esa máquina está offline, o es un mesh multimáquina sobre standalone. La coordinación entre máquinas requiere Cloud.
MAGI da error magi_kind_not_configured — vincula primero un panel a ese tipo de tarea con mesh_magi_kind_panel_set. No hay panel de reserva automático.
MAGI da error magi_insufficient_targets — hay menos de 2 objetivos (nodo, proveedor) independientes disponibles. La solución habitual es instalar o habilitar una segunda CLI de agente; no hace falta una segunda máquina. MAGI no se ejecutará con un solo objetivo.

Adónde ir después

Repo Mesh — los conceptos: nodos, misiones, cola, ledger, Refinery
Tutorial: tu primera tarea real — un recorrido manual completo
Servidor MCP — la referencia completa de herramientas y todas las formas de registro
Multimáquina — enlazar portátil + escritorio + máquina de trabajo (solo Cloud)
Configuración de una máquina nueva dirigida por un agente — preparar una máquina nueva para unirse

Configuración de Repo Mesh dirigida por un agente ​

Qué asume esta guía ​

Una sola máquina vs. multimáquina ​

Paso 0 — Verifica los requisitos previos ​

0a. ¿Está el daemon levantado en esta máquina? ​

0b. ¿Es el workspace un repositorio Git con un remoto? ​

0c. ¿Tienes las herramientas del mesh? ​

Paso 1 — Inventaría las máquinas ​

Paso 2 — Construye el mesh ​

2a. Planifica primero (solo lectura, no escribe nada) ​

2b. Crea el mesh y añade nodos ​

2c. Vuelve a registrar el servidor MCP en modo mesh ​

Paso 3 — Deja que mesh_init proponga la configuración del repo ​

3a. Previsualización (por defecto — no escribe nada) ​

3b. Revisa con la persona ⏸ PASO HUMANO ​

3c. Escritura (solo tras la aprobación) ​

Paso 4 — Modelos, límites y MAGI ​

4a. Slots de nodo — qué agente y qué modelo se ejecuta dónde ​

4b. Límites de política — quédate con los valores por defecto ​

4c. MAGI — opcional, vale la pena activarlo si usas más de un agente ​

Paso 5 — Lanza el coordinador ​

Vía A — Panel (la forma normal) ⏸ PASO HUMANO ​

Vía B — Modo mesh de MCP (sin panel) ​

Paso 6 — Prueba de humo ​

Lo que la persona hizo realmente ​

Resolución de problemas ​

Adónde ir después ​

Configuración de Repo Mesh dirigida por un agente

Qué asume esta guía

Una sola máquina vs. multimáquina

Paso 0 — Verifica los requisitos previos

0a. ¿Está el daemon levantado en esta máquina?

0b. ¿Es el workspace un repositorio Git con un remoto?

0c. ¿Tienes las herramientas del mesh?

Paso 1 — Inventaría las máquinas

Paso 2 — Construye el mesh

2a. Planifica primero (solo lectura, no escribe nada)

2b. Crea el mesh y añade nodos

2c. Vuelve a registrar el servidor MCP en modo mesh

Paso 3 — Deja que `mesh_init` proponga la configuración del repo

3a. Previsualización (por defecto — no escribe nada)

3b. Revisa con la persona ⏸ PASO HUMANO

3c. Escritura (solo tras la aprobación)

Paso 4 — Modelos, límites y MAGI

4a. Slots de nodo — qué agente y qué modelo se ejecuta dónde

4b. Límites de política — quédate con los valores por defecto

4c. MAGI — opcional, vale la pena activarlo si usas más de un agente

Paso 5 — Lanza el coordinador

Vía A — Panel (la forma normal) ⏸ PASO HUMANO

Vía B — Modo mesh de MCP (sin panel)

Paso 6 — Prueba de humo

Lo que la persona hizo realmente

Resolución de problemas

Adónde ir después