herdr-mesh-safe

Un puente MCP con ámbito de seguridad para coordinar agentes de codificación en Herdr.

Este repositorio es un fork de runchr-works/herdr-mesh. Mantiene la integración MCP/Herdr original y reemplaza el ciclo de vida de terminal sin restricciones con esperas semánticas y revisores y escritores con ámbito de arrendamiento.

Versión actual del paquete: 0.1.0-safe.13.

Por qué existe este fork

Un agente de orquestación necesita inspeccionar trabajadores, enviar tareas, esperar resultados y reclamar capacidad completada. Dar a ese agente comandos de terminal arbitrarios, inyección de claves sin procesar o eliminación de paneles sin ámbito crea autoridad innecesaria.

Este puente expone las operaciones que el coordinador necesita mientras conserva estos invariantes:

• ningún comando de shell proporcionado por el llamador ni ejecución de terminal sin restricciones;

• ningún send-keys sin procesar;

• ninguna eliminación de panel, pestaña, espacio de trabajo o sesión sin ámbito;

• las credenciales del controlador se verifican inmediatamente antes de las solicitudes de puente y de ciclo de vida;

• cada solicitud a un agente retenido se admite solo mientras todos los almacenes de ciclo de vida y recibos de traspaso estén bloqueados;

• la recopilación de resultados está vinculada al panel arrendado exacto y al cursor de solicitud aceptado;

• el cierre automático requiere una observación de inactivo/hecho y un cursor de estado sin cambios durante la captura de salida;

• un revisor solo puede cerrarse mediante el arrendamiento creado con él;

• un escritor solo se inicia en un árbol de trabajo Git vinculado en una rama no protegida;

• los escritores concurrentes no pueden arrendar ámbitos de ruta superpuestos;

• liberar a un escritor conserva su rama, árbol de trabajo y bytes.

El puente es un límite de seguridad técnico. No decide si una Issue de GitHub, especificación, declaración de propiedad, commit, fusión, migración o implementación está autorizada. El coordinador y el contrato del repositorio de destino siguen siendo autoritativos.

Related MCP server: MCP Files

Arquitectura

MCP client
   │ stdio
   ▼
herdr-mesh-safe
   ├── semantic Herdr waits and prompts
   ├── exclusive controller lease and fence
   ├── reviewer leases
   ├── writer lane leases
   ├── content-free handoff receipts
   └── read-only Git preflight
          │
          ▼
      Herdr CLI → Herdr socket → managed panes and agents

Los registros de arrendamiento se almacenan fuera de Git con modo 0600 en:

${HERDR_MESH_STATE_DIR:-~/.local/state/herdr-mesh}/reviewer-leases
${HERDR_MESH_STATE_DIR:-~/.local/state/herdr-mesh}/writer-leases
${HERDR_MESH_STATE_DIR:-~/.local/state/herdr-mesh}/adopted-pane-leases
${HERDR_MESH_STATE_DIR:-~/.local/state/herdr-mesh}/controller-leases
${HERDR_MESH_STATE_DIR:-~/.local/state/herdr-mesh}/handoff-receipts

Adaptadores de gobernanza

Las herramientas de escritor requieren un proceso de gobernanza externo que acepte el trabajo, declare la propiedad y registre puntos de control duraderos. Lea el contrato de integración de gobernanza antes de habilitar escritores.

El ejemplo de plano de control de GitHub muestra un adaptador práctico que usa Issues, un Proyecto de GitHub, PRs y puntos de control sin contenido. GitHub es un ejemplo, no una dependencia del puente. Una entrada de herramienta completa está disponible en manifest.json.

El paquete opcional agent-control-skills proporciona instrucciones de coordinador reutilizables para este límite de gobernanza. El puente no instala esas habilidades ni hereda autoridad de ellas.

Herramientas expuestas

Ciclo de vida del controlador

Adquiera o reanude el controlador del proyecto antes de cualquier solicitud, revisor, escritor o mutación de limpieza. El id de arrendamiento y el token de valla devueltos son capacidades efímeras: pásalos a herramientas de mutación, pero no los publiques en un rastreador, commit, registro o traspaso. Las herramientas de inventario y espera de solo lectura permanecen disponibles sin un arrendamiento de controlador. El arrendamiento predeterminado dura 15 minutos y debe renovarse durante turnos de coordinación largos. herdr_bridge_status también informa cada bloqueo de reserva como absent, active, stale o indeterminate sin exponer su PID de propietario, id de bloqueo o credenciales de controlador. Un bloqueo de host extranjero es deliberadamente indeterminate; el puente no lo roba basándose en una suposición de tiempo de vida.

Coordinación

after_seq en las esperas asentadas evita que un estado terminal de trabajo anterior satisfaga una nueva espera. Una única solicitud MCP larga reemplaza el sondeo repetido del lado del cliente; no se requiere un canal lateral SSE. Para un agente arrendado, la admisión de solicitudes primero requiere una identidad asentada exacta, luego registra el cursor previo a la entrega antes del envío. El recibo vincula panel, nombre, tipo de agente, directorio de trabajo, arrendamiento de ciclo de vida y cursor. Relay devuelve solo después de que Herdr confirme que esa identidad exacta entró en working en el siguiente cursor. El recibo resultante es una clave de búsqueda opaca; no contiene valla, solicitud ni salida. Hasta que ese recibo se complete, falle o se abandone explícitamente, cada solicitud posterior a ese objetivo es rechazada. Un arrendamiento ya en closing o releasing también rechaza nuevas solicitudes.

El traspaso por lotes valida cada objetivo bajo la misma valla de controlador y reservas de ciclo de vida antes de enviar cualquier solicitud. Cada objetivo del lote debe tener un arrendamiento retenido activo; los objetivos heredados sin arrendamiento son rechazados. mode=all devuelve resultados en orden de solicitud. mode=first cancela solo las esperas CLI perdedoras; los otros agentes continúan trabajando y se devuelven como pendingReceipts. La recopilación requiere esos tokens, espera estrictamente después del cursor working aceptado y vuelve a leer identidad y secuencia después de la captura de salida. La salida de una tarea posterior se rechaza en lugar de etiquetarse incorrectamente. Un recibo completado puede reproducirse después de un bloqueo del llamador solo mientras su identidad asentada exacta y cursor sigan siendo actuales. Una entrega ambigua permanece como un recibo reserved bloqueante. Un operador puede liberarlo solo con herdr_handoff_receipt_abandon, autoridad de controlador válida y una observación fresca de que el agente arrendado exacto está asentado.

CLI del controlador

herdr-agent-control es una CLI local para un coordinador nombrado que ya posee el arrendamiento de controlador activo. El lanzador debe establecer AGENT_CONTROL_CONTROLLER_ID al id estable de ese controlador en el entorno del coordinador gestionado. status y receipts son de solo lectura y no cargan la valla. Los comandos de mutación cargan el arrendamiento solo después de hacer coincidir el panel Herdr actual, nombre de agente, tipo, directorio de trabajo y ascendencia de proceso Linux con el proceso de controlador registrado en adquirir/reanudar. La valla nunca aparece en argumentos o salida.

herdr-agent-control status
herdr-agent-control receipts
herdr-agent-control ask TARGET -- MESSAGE
herdr-agent-control ask-many --request TARGET=MESSAGE --mode first
herdr-agent-control collect --receipt TOKEN
herdr-agent-control abandon --receipt TOKEN

ask y ask-many usan el protocolo de lote vinculado a recibos. collect nunca envía una solicitud. abandon nunca detiene un proceso; solo libera la barrera de admisión después de que el objetivo exacto se observe asentado. Los arrendamientos de controlador creados antes de la introducción del enlace de proceso deben reanudarse una vez antes de que la CLI de mutación pueda usarlos. La CLI no inicia, cierra, detiene, elimina, hace commit ni ejecuta comandos de terminal arbitrarios.

El arrendamiento de controlador actual está deliberadamente vinculado a un agente nombrado en un panel Herdr gestionado. Los clientes MCP fuera de Herdr pueden usar herramientas de inventario y espera de solo lectura, pero no pueden adquirir ni ejercer autoridad de coordinación en esta versión. Soportar un coordinador externo requiere una identidad de llamador autenticada separada; no debe hacerse pasar por un panel ni pasar una identidad autodeclarada. La ascendencia de proceso es un enlace de llamador de cierre seguro para el modelo de host cooperativo de un solo usuario, no aislamiento de un proceso hostil con la misma cuenta Unix y permiso para reescribir los archivos de estado con modo 0600.

Ciclo de vida del revisor

La identidad del revisor incluye controlador, nombre y tipo de agente, panel y directorio de trabajo. Los paneles working, blocked, sin arrendamiento o con identidad desviada se conservan cuando se observan. Una pestaña recién creada puede existir antes de que su shell raíz acepte un agente; el puente reintenta solo la condición de preparación exacta agent_pane_busy en ese mismo panel arrendado durante una ventana limitada. Otros errores de inicio fallan de forma segura. Para revisores Claude, el manifiesto de inicio puede pasar un model y effort explícitos; estos valores se convierten en argumentos nativos de la CLI de Claude después de --. Otros tipos de agente rechazan argumentos de modelo explícitos hasta que tengan un adaptador de proveedor revisado.

Ciclo de vida del escritor

Verificación del host

Las recetas de verificación son código del repositorio arrendado. Se ejecutan en un sandbox de Linux Bubblewrap con argumentos fijos y sin red. No son un límite de seguridad contra un agente que ya tiene el mismo usuario del host. El arranque web opcional usa el lockfile confirmado, permite descargas de paquetes y deshabilita los scripts de ciclo de vida de paquetes. Un arranque de Python puede calentar la caché uv local de ejecución a partir de archivos requirements.lock nombrados explícitamente; cada lock debe ser un archivo regular, sin enlace simbólico, cuyos bytes coincidan con el commit base aceptado y cuyo grafo de dependencias completo tenga hashes SHA-256. El puente monta una copia derivada de la base de solo lectura, ignora la configuración de uv específica del carril, deshabilita las compilaciones desde fuente y usa uv pip sin iniciar Python mientras haya red disponible. La compuerta final permanece sin conexión y usa la misma caché aislada. Cuando el resolvedor del host es un enlace simbólico fuera de /etc, un arranque con red monta solo su archivo resuelto de solo lectura; las compuertas sin conexión siguen usando un espacio de nombres de red separado.

Arrendamientos de paneles heredados

Los agentes heredados creados fuera del puente permanecen sin propietario hasta que un coordinador los adopta mediante un arrendamiento de solo limpieza. La adopción verifica el agente nombrado exacto, el panel, el tipo, el directorio de trabajo, el cursor de estado asentado, la autoridad duradera y los paneles protegidos. No otorga propiedad de Git ni autoridad de implementación.

La admisión de escritores requiere:

• ticket duradero y referencias de autoridad más un resumen SHA-256 aceptado;

• un árbol de trabajo de Git vinculado absoluto, no el checkout principal del repositorio;

• rama exacta, commit base, HEAD y resumen del estado de Git;

• al menos una rama protegida, normalmente la rama predeterminada configurada;

• alcances de propiedad literales relativos al repositorio sin globs ni ..;

• alcances bloqueados explícitos;

• ningún agente Herdr existente en el árbol de trabajo;

• ningún arrendamiento retenido para la rama, el árbol de trabajo, la propiedad superpuesta o el alcance bloqueado.

Las reservas y liberaciones usan un bloqueo atómico de almacenamiento. Un fallo puede dejar deliberadamente una reserva retenida que requiere inspección; nunca debe admitir dos escritores solo para recuperarse automáticamente. En Linux, los nuevos bloqueos de reserva incluyen el identificador de arranque y la hora de inicio del proceso, por lo que un reinicio o un PID reutilizado se reconoce como obsoleto. herdr_bridge_status expone bloqueos ambiguos heredados o de host extranjero como indeterminate; inspecciónalos antes de cualquier recuperación manual en lugar de eliminarlos por antigüedad.

Topología y descubrimiento de solo lectura

El perfil seguro también expone inspección de sesión, panel, pestaña, espacio de trabajo e integración de solo lectura. Las herramientas de ciclo de vida sin procesar permanecen filtradas por la lista de permitidos en src/server.ts.

Requisitos

• Linux o macOS con Node.js 18 o superior; la verificación del host requiere además Linux y Bubblewrap;

• Git;

• Herdr instalado y en ejecución;

• la integración de Herdr para cada tipo de agente que planees lanzar;

• un cliente compatible con MCP como Codex, Claude Code u OpenCode.

Comprueba Herdr antes de la instalación:

herdr status
herdr integration status

Instala las integraciones que falten, por ejemplo:

herdr integration install codex
herdr integration install claude

Instalar desde fuente

git clone https://github.com/nativestrider/herdr-mesh-safe.git
cd herdr-mesh-safe
npm ci
npm test
npm run build

El punto de entrada MCP compilado es dist/index.js.

Codex

Añade esto a ~/.codex/config.toml, usando la ruta absoluta del clon:

[mcp_servers.herdr-mesh]
command = "node"
args = ["/absolute/path/to/herdr-mesh-safe/dist/index.js"]

Claude Code

claude mcp add -s user herdr-mesh node /absolute/path/to/herdr-mesh-safe/dist/index.js

OpenCode u otro cliente MCP

Registra un servidor MCP stdio local llamado herdr-mesh con:

command: node
arguments: /absolute/path/to/herdr-mesh-safe/dist/index.js

Reinicia el cliente MCP después de la instalación o de cada actualización del puente. /clear o una conversación nueva dentro del mismo proceso no recarga un servidor MCP ya en ejecución.

Entorno opcional

El proceso MCP debe poder alcanzar el mismo socket de Herdr que el espacio de trabajo gestionado. Un coordinador que ya se ejecuta dentro de Herdr puede usar la CLI de Herdr, pero el puente aún proporciona autoridad más limitada, esperas de estilo evento y ciclo de vida verificado.

Cómo usarlo

Los usuarios normalmente hablan con el coordinador en lugar de invocar nombres de herramientas.

Esperar a varios agentes

Wait for the first active worker to become idle, done, or blocked. Use each
worker's last state-change sequence so an old idle state is not accepted.

El coordinador usa herdr_agent_wait_any y recibe el primer estado terminal más la salida visible en un solo resultado.

Ejecutar una revisión externa de solo lectura

Create a leased Claude reviewer in a dedicated tab rooted at the ticket worktree, ask it to review the
exact PR head against Standards and Spec, wait for its result, then reclaim the
reviewer pane if it is idle or done.

La secuencia esperada es:

1. herdr_controller_acquire o herdr_controller_resume

2. herdr_owned_reviewer_start con el arrendamiento/vallado del controlador y, para Claude, el modelo/esfuerzo exacto

3. herdr_relay con el mismo arrendamiento/vallado del controlador y conserva su recibo

4. herdr_collect_handoffs con ese recibo

5. herdr_owned_reviewer_close con el mismo arrendamiento/vallado del controlador

Iniciar un carril de escritor

El coordinador primero valida el ticket/especificación aceptado, las dependencias, la propiedad, los bloqueos y el orden de integración contra el estado duradero del proyecto. Luego recopila la evidencia local exacta, incluyendo:

git -C /absolute/worktree rev-parse HEAD
git -C /absolute/worktree status --porcelain=v1 --untracked-files=all | sha256sum

Llama a herdr_owned_worker_start con esa evidencia. La herramienta vuelve a leer Git de forma independiente, reserva la propiedad, crea una pestaña dedicada sin foco, inicia al agente en su panel raíz y verifica su identidad antes de devolver un arrendamiento activo.

El puente no limita las escrituras del sistema de archivos a los alcances declarados. El coordinador debe comparar aún las rutas modificadas finales y el diff con el arrendamiento, el ticket y el contrato del repositorio.

Liberar un escritor

Antes de la liberación, registra un punto de control duradero sin contenido que contenga la rama actual, HEAD, resumen del estado sucio, prueba completada, bloqueadores y siguiente acción. Luego llama a herdr_owned_worker_release con la referencia y el resumen del punto de control más el cursor de estado del agente y los valores de Git recién observados.

La liberación cierra solo el panel arrendado. No hace commit, stash, reset, clean, ni elimina o modifica el árbol de trabajo.

El comando actual pane close de Herdr no acepta un estado o cursor esperado del agente. Por lo tanto, el puente comprueba identidad, estado asentado, estabilidad del cursor y autoridad del controlador inmediatamente antes de solicitar el cierre, pero la comprobación final y el cierre de Herdr no son una operación atómica. No envíes un mensaje manual de Herdr ni reutilices ese panel después de que comience el cierre. El cierre condicional requiere soporte en el propio Herdr.

Limitaciones deliberadas

• Los clones independientes no se aceptan como carriles de escritor en esta versión; usa árboles de trabajo de Git vinculados.

• Los trabajadores existentes creados antes de los arrendamientos no se adoptan automáticamente.

• El puente no puede demostrar que un GitHub Issue otorga autoridad.

• La propiedad se comprueba en la admisión y durante la coordinación final; no es un sandbox de sistema de archivos del sistema operativo.

• El vallado del controlador y las comprobaciones de cursor evitan operaciones obsoletas del puente, pero Herdr no combina atómicamente esas comprobaciones con la entrega de mensajes o el cierre de panel. La actividad directa de CLI del mismo usuario permanece fuera de este límite.

• Los diálogos humanos y los agentes blocked siguen siendo decisiones humanas.

• La autoridad de commit, push, PR, merge, despliegue, migración y ejecución permanece fuera de este puente.

Desarrollo

npm ci
npm test
npm run build
npm audit --omit=dev

Las pruebas cubren el contrato de argumentos de la CLI de Herdr instalada, las esperas conscientes del cursor, el vallado y la toma de control del controlador, la identidad de arrendamiento por lotes, el enlace del resolvedor del sandbox, los arrendamientos de revisores, los conflictos de propiedad de escritores, las ramas protegidas, los resúmenes del estado de Git y la liberación con puntos de control.

El directorio dist/ compilado está confirmado para que los clientes puedan ejecutar el puente sin una cadena de herramientas TypeScript. Cambia primero la fuente, ejecuta los comandos completos anteriores y confirma juntos la fuente, las pruebas, el lockfile y la salida generada.

Upstream y licencia

Basado en runchr-works/herdr-mesh en el commit upstream 54adef5. Upstream sigue siendo la fuente del transporte e instalador MCP genérico de Herdr; este fork posee la lista de permitidos segura, las esperas semánticas y el ciclo de vida de arrendamiento.

Licenciado bajo la Licencia MIT. Consulta LICENSE; el aviso de copyright upstream se conserva.