herdr-mesh-safe

MCP-мост с ограниченной областью безопасности для координации агентов разработки в Herdr.

Этот репозиторий — ответвление (fork) runchr-works/herdr-mesh. Он сохраняет вышестоящую интеграцию MCP/Herdr и заменяет неограниченный жизненный цикл терминала семантическими ожиданиями и ограниченными арендой ревьюерами и авторами.

Текущая версия пакета: 0.1.0-safe.13.

Зачем существует этот fork

Оркестратору нужно проверять воркеров, отправлять задачи, ждать результаты и возвращать завершённые мощности. Предоставление этому агенту произвольных терминальных команд, прямой инъекции клавиш или неограниченного удаления панелей создаёт излишние полномочия.

Этот мост предоставляет операции, необходимые координатору, сохраняя следующие инварианты:

• никаких команд оболочки от вызывающей стороны и никакого неограниченного выполнения в терминале;

• никаких прямых send-keys;

• никакого неограниченного удаления панелей, вкладок, рабочих пространств или сессий;

• учётные данные контроллера проверяются непосредственно перед промптами моста и запросами жизненного цикла;

• каждый промпт удержанному агенту допускается только пока все хранилища жизненного цикла и квитанций передачи заблокированы;

• сбор результатов привязан к конкретной арендованной панели и принятому курсору промпта;

• автоматическое закрытие требует наблюдения состояния idle/done и неизменного курсора состояния во время захвата вывода;

• ревьюер может быть закрыт только через аренду, созданную вместе с ним;

• автор запускается только в связанном Git-worktree на незащищённой ветке;

• одновременные авторы не могут арендовать пересекающиеся области путей;

• освобождение автора сохраняет его ветку, worktree и байты.

Мост — это техническая граница безопасности. Он не решает, авторизованы ли GitHub Issue, спецификация, объявление владения, коммит, слияние, миграция или развёртывание. Координатор и контракт целевого репозитория остаются авторитетными.

Related MCP server: MCP Files

Архитектура

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

Записи аренды хранятся вне Git с режимом 0600 по пути:

${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

Адаптеры управления

Инструменты авторов требуют внешнего процесса управления, который принимает работу, объявляет владение и фиксирует устойчивые контрольные точки. Прочтите governance integration contract перед включением авторов.

GitHub control-plane example демонстрирует один практический адаптер, использующий Issues, GitHub Project, PR и контрольные точки без содержимого. GitHub — это пример, а не зависимость моста. Полное входное описание инструмента доступно в manifest.json.

Опциональный пакет agent-control-skills предоставляет переиспользуемые инструкции координатора для этой границы управления. Мост не устанавливает эти навыки и не наследует от них полномочия.

Предоставляемые инструменты

Жизненный цикл контроллера

Получите или возобновите контроллер проекта перед любой мутацией промпта, ревьюера, автора или очистки. Возвращённые id аренды и fence-токен — это эфемерные полномочия: передавайте их мутирующим инструментам, но не публикуйте в трекере, коммите, журнале или передаче. Инструменты инвентаризации и ожидания, доступные только для чтения, остаются доступными без аренды контроллера. Аренда по умолчанию длится 15 минут и должна продлеваться во время длительных циклов координации. herdr_bridge_status также сообщает о каждой блокировке резервирования как absent, active, stale или indeterminate, не раскрывая PID владельца, id блокировки или учётные данные контроллера. Блокировка на чужом хосте намеренно считается indeterminate; мост не забирает её по догадке о времени жизни.

Координация

after_seq в ожиданиях устоявшегося состояния предотвращает удовлетворение нового ожидания терминальным состоянием от более ранней работы. Один длинный MCP-запрос заменяет многократный опрос на стороне клиента; SSE-боковой канал не требуется. Для арендованного агента допуск промпта сначала требует точной устоявшейся идентичности, затем записывает курсор перед доставкой до отправки. Квитанция связывает панель, имя, тип агента, рабочую директорию, аренду жизненного цикла и курсор. Relay возвращается только после того, как Herdr подтвердит, что эта точная идентичность вошла в состояние working на следующем курсоре. Полученная квитанция — это непрозрачный ключ поиска; она не содержит fence, промпта или вывода. Пока квитанция не завершена, не провалена или явно не отброшена, каждый последующий промпт к этому адресату отклоняется. Аренда, уже находящаяся в состоянии closing или releasing, также отклоняет новые промпты.

Пакетная передача проверяет каждый целевой объект под тем же fence контроллера и резервированиями жизненного цикла перед отправкой любого промпта. Каждый целевой объект пакета должен иметь одну активную удержанную аренду; унаследованные цели без аренды отклоняются. mode=all возвращает результаты в порядке запросов. mode=first отменяет только проигравшие CLI-ожидания; остальные агенты продолжают работать и возвращаются как pendingReceipts. Сбор требует эти токены, ожидает строго после принятого курсора working и повторно считывает идентичность и последовательность после захвата вывода. Вывод более поздней задачи поэтому отклоняется, а не помечается неверно. Завершённая квитанция может быть воспроизведена после сбоя вызывающей стороны только пока её точная устоявшаяся идентичность и курсор всё ещё актуальны. Неоднозначная доставка остаётся блокирующей квитанцией reserved. Оператор может снять её только с помощью herdr_handoff_receipt_abandon, действующих полномочий контроллера и свежего наблюдения, что точный арендованный агент устоялся.

CLI контроллера

herdr-agent-control — это локальный CLI для именованного координатора, уже удерживающего активную аренду контроллера. Запускающая сторона должна задать AGENT_CONTROL_CONTROLLER_ID равным стабильному id этого контроллера в управляемой среде координатора. status и receipts доступны только для чтения и не загружают fence. Мутирующие команды загружают аренду только после сопоставления текущей панели Herdr, имени агента, типа, рабочей директории и происхождения процесса Linux с процессом контроллера, записанным при acquire/resume. Fence никогда не появляется в аргументах или выводе.

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 и ask-many используют протокол пакетной передачи, привязанный к квитанциям. collect никогда не отправляет промпт. abandon никогда не останавливает процесс; он только снимает барьер допуска после того, как точный целевой объект наблюдался в устоявшемся состоянии. Аренды контроллера, созданные до введения привязки процесса, должны быть один раз возобновлены, прежде чем мутирующий CLI сможет их использовать. CLI не запускает, не закрывает, не останавливает, не удаляет, не коммитит и не выполняет произвольные терминальные команды.

Текущая аренда контроллера намеренно привязана к именованному агенту в управляемой панели Herdr. MCP-клиенты вне Herdr могут использовать инструменты инвентаризации и ожидания только для чтения, но не могут получить или осуществлять полномочия координации в этой версии. Поддержка внешнего координатора требует отдельной аутентифицированной идентичности вызывающей стороны; она не должна выдавать себя за панель или передавать самообъявленную идентичность. Происхождение процесса — это отказобезопасная привязка вызывающей стороны для кооперативной однопользовательской модели хоста, а не изоляция от враждебного процесса с той же Unix-учётной записью и правом перезаписывать файлы состояния с режимом 0600.

Жизненный цикл ревьюера

Идентичность ревьюера включает контроллер, имя и тип агента, панель и рабочую директорию. Панели в состоянии working, blocked, без аренды или с отклонением идентичности сохраняются при наблюдении. Новая вкладка может существовать до того, как её корневая оболочка примет агента; мост повторяет попытки только для точного условия готовности agent_pane_busy в той же арендованной панели в течение ограниченного окна. Прочие ошибки запуска завершаются отказом закрытия. Для ревьюеров Claude стартовый манифест может передавать явные model и effort; эти значения становятся нативными аргументами Claude CLI после --. Другие типы агентов отклоняют явные аргументы модели, пока у них нет проверенного адаптера провайдера.

Жизненный цикл автора

Проверка хоста

Рецепты верификации — это код из арендованного репозитория. Они выполняются в песочнице Linux Bubblewrap с фиксированными аргументами и без сети. Они не являются границей безопасности против агента, который уже работает под тем же пользователем хоста. Необязательный веб-загрузчик использует закоммиченный lockfile, разрешает загрузку пакетов и отключает скрипты жизненного цикла пакетов. Python-загрузчик может прогревать локальный для запуска кэш uv из явно указанных файлов requirements.lock; каждый lock должен быть обычным файлом, не симлинком, чьи байты совпадают с принятым базовым коммитом и чей полный граф зависимостей имеет SHA-256 хэши. Мост монтирует производную от базовой копию в режиме только для чтения, игнорирует локальную для дорожки конфигурацию uv, отключает сборку из исходников и использует uv pip, не запуская Python, пока доступна сеть. Финальный шлюз остаётся офлайн и использует тот же изолированный кэш. Если хост-резолвер является симлинком за пределами /etc, сетевой загрузчик монтирует только его разрешённый файл в режиме только для чтения; офлайн-шлюзы по-прежнему используют отдельное сетевое пространство имён.

Аренды панелей для устаревших агентов

Устаревшие агенты, созданные вне моста, остаются без владельца, пока координатор не примет их через аренду только для очистки. Принятие проверяет точно указанного агента, панель, вид, рабочую директорию, установившийся курсор состояния, постоянные полномочия и защищённые панели. Оно не предоставляет права владения Git или полномочий на реализацию.

Для допуска писателя требуются:

• постоянные ссылки на тикет и полномочия, а также принятый SHA-256 дайджест;

• абсолютное связанное Git-рабочее дерево, а не основная рабочая копия репозитория;

• точная ветка, базовый коммит, HEAD и дайджест Git-статуса;

• как минимум одна защищённая ветка, обычно настроенная ветка по умолчанию;

• буквальные области владения относительно репозитория без glob-шаблонов и ..;

• явные заблокированные области;

• отсутствие существующего агента Herdr в рабочем дереве;

• отсутствие сохранённой аренды для ветки, рабочего дерева, пересекающегося владения или заблокированной области.

Резервирования и освобождения используют атомарную блокировку хранилища. Сбой может намеренно оставить сохранённую резервацию, требующую проверки; хранилище никогда не должно допускать двух писателей только ради автоматического восстановления. В Linux новые блокировки резерваций включают идентификатор загрузки и время запуска процесса, поэтому перезагрузка или повторно использованный PID распознаются как устаревшие. herdr_bridge_status отображает неоднозначные устаревшие блокировки или блокировки с других хостов как indeterminate; проверяйте их перед любым ручным восстановлением, а не удаляйте по возрасту.

Топология и обнаружение только для чтения

Безопасный профиль также предоставляет инспекцию сессий, панелей, вкладок, рабочих пространств и интеграций только для чтения. Сырые инструменты жизненного цикла остаются отфильтрованными списком разрешений в src/server.ts.

Требования

• Linux или macOS с Node.js 18 или новее; для проверки хоста дополнительно требуются Linux и Bubblewrap;

• Git;

• установленный и запущенный Herdr;

• интеграция Herdr для каждого вида агента, которого вы планируете запускать;

• MCP-совместимый клиент, такой как Codex, Claude Code или OpenCode.

Проверьте Herdr перед установкой:

herdr status
herdr integration status

Установите недостающие интеграции, например:

herdr integration install codex
herdr integration install claude

Установка из исходников

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

Скомпилированная точка входа MCP — dist/index.js.

Codex

Добавьте это в ~/.codex/config.toml, используя абсолютный путь к клонированному репозиторию:

[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 или другой MCP-клиент

Зарегистрируйте локальный stdio MCP-сервер с именем herdr-mesh:

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

Перезапустите MCP-клиент после установки или после каждого обновления моста. /clear или новый разговор в том же процессе не перезагружают уже запущенный MCP-сервер.

Дополнительное окружение

Процесс MCP должен иметь доступ к тому же сокету Herdr, что и управляемое рабочее пространство. Координатор, уже запущенный внутри Herdr, может использовать CLI Herdr, но мост по-прежнему предоставляет более узкие полномочия, ожидания в событийном стиле и проверенный жизненный цикл.

Как использовать

Пользователи обычно общаются с координатором, а не вызывают имена инструментов.

Ожидание нескольких агентов

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.

Координатор использует herdr_agent_wait_any и получает первое конечное состояние и видимый вывод в одном результате.

Запуск внешней проверки только для чтения

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.

Ожидаемая последовательность:

1. herdr_controller_acquire или herdr_controller_resume

2. herdr_owned_reviewer_start с арендой/ограждением контроллера и, для Claude, точной моделью/уровнем усилий

3. herdr_relay с той же арендой/ограждением контроллера и сохраните его квитанцию

4. herdr_collect_handoffs с этой квитанцией

5. herdr_owned_reviewer_close с той же арендой/ограждением контроллера

Запуск дорожки писателя

Сначала координатор проверяет принятый тикет/спецификацию, зависимости, владение, блокировки и порядок интеграции на соответствие постоянному состоянию проекта. Затем он собирает точные локальные свидетельства, включая:

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

Он вызывает herdr_owned_worker_start с этими свидетельствами. Инструмент независимо перечитывает Git, резервирует владение, создаёт выделенную вкладку без фокуса, запускает агента в его корневой панели и проверяет его идентичность перед возвратом активной аренды.

Мост не ограничивает записи в файловую систему объявленными областями. Координатор должен по-прежнему сравнивать итоговые изменённые пути и diff с арендой, тикетом и контрактом репозитория.

Освобождение писателя

Перед освобождением запишите постоянную контрольную точку без содержимого, содержащую текущую ветку, HEAD, дайджест грязного состояния, подтверждение выполнения, блокеры и следующее действие. Затем вызовите herdr_owned_worker_release со ссылкой на контрольную точку и дайджестом, а также со свежим наблюдаемым курсором состояния агента и значениями Git.

Освобождение закрывает только арендованную панель. Оно не коммитит, не делает stash, reset, clean, не удаляет и не изменяет рабочее дерево.

Текущая команда pane close в Herdr не принимает ожидаемое состояние агента или курсор. Поэтому мост непосредственно перед запросом закрытия проверяет идентичность, установившееся состояние, стабильность курсора и полномочия контроллера, но финальная проверка и закрытие Herdr не являются одной атомарной операцией. Не отправляйте ручной промпт Herdr и не используйте эту панель повторно после начала закрытия. Условное закрытие требует поддержки в самом Herdr.

Преднамеренные ограничения

• Независимые клоны не принимаются как дорожки писателя в этой версии; используйте связанные Git-рабочие деревья.

• Существующие воркеры, созданные до появления аренд, автоматически не принимаются.

• Мост не может доказать, что GitHub Issue предоставляет полномочия.

• Владение проверяется при допуске и во время финальной координации; это не песочница файловой системы операционной системы.

• Ограждение контроллера и проверки курсора предотвращают устаревшие операции моста, но Herdr не объединяет эти проверки атомарно с доставкой промпта или закрытием панели. Прямая активность CLI того же пользователя остаётся за пределами этой границы.

• Человеческие диалоги и агенты в состоянии blocked остаются человеческими решениями.

• Полномочия на commit, push, PR, merge, развёртывание, миграцию и выполнение остаются за пределами этого моста.

Разработка

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

Тесты покрывают контракт аргументов установленного CLI Herdr, ожидания с учётом курсора, ограждение и перехват контроллера, идентичность пакетных аренд, привязку резолвера песочницы, аренды ревьюеров, конфликты владения писателей, защищённые ветки, дайджесты Git-состояния и освобождение с контрольной точкой.

Собранная директория dist/ закоммичена, чтобы клиенты могли запускать мост без TypeScript-тулчейна. Сначала измените исходный код, выполните полный набор команд выше и закоммитьте исходный код, тесты, lockfile и сгенерированный вывод вместе.

Апстрим и лицензия

Основано на runchr-works/herdr-mesh в апстрим-коммите 54adef5. Апстрим остаётся источником универсального MCP-транспорта Herdr и установщика; этот форк отвечает за безопасный список разрешений, семантические ожидания и жизненный цикл аренд.

Лицензировано в соответствии с лицензией MIT. См. LICENSE; уведомление об авторских правах апстрима сохранено.