herdr-mesh-safe

안전 범위가 지정된 MCP 브리지로, Herdr에서 코딩 에이전트를 조정합니다.

이 저장소는 runchr-works/herdr-mesh의 포크입니다. 업스트림 MCP/Herdr 통합을 유지하면서, 제한 없는 터미널 수명 주기를 의미론적 대기(semantic waits)와 임대 범위(lease-scoped)의 리뷰어 및 작성자로 대체합니다.

현재 패키지 버전: 0.1.0-safe.13.

이 포크가 존재하는 이유

오케스트레이션 에이전트는 작업자를 검사하고, 작업을 보내고, 결과를 기다리고, 완료된 용량을 회수해야 합니다. 그 에이전트에게 임의의 터미널 명령, 원시 키 주입, 또는 범위가 지정되지 않은 팬 삭제 권한을 부여하면 불필요한 권한이 생깁니다.

이 브리지는 다음 불변 조건을 유지하면서 코디네이터가 필요한 작업을 노출합니다:

• 호출자가 제공한 셸 명령이나 제한 없는 터미널 실행이 없음;

• 원시 send-keys 없음;

• 범위가 지정되지 않은 팬, 탭, 워크스페이스 또는 세션 삭제 없음;

• 컨트롤러 자격 증명은 브리지 프롬프트 및 수명 주기 요청 직전에 확인됨;

• 유지된 에이전트에 대한 모든 프롬프트는 모든 수명 주기 및 핸드오프 영수증 저장소가 잠긴 경우에만 허용됨;

• 결과 수집은 정확히 임대된 팬과 수락된 프롬프트 커서에 바인딩됨;

• 자동 종료는 유휴/완료 관찰과 출력 캡처 중 변경되지 않은 상태 커서를 요구함;

• 리뷰어는 함께 생성된 임대를 통해서만 닫을 수 있음;

• 작성자는 보호되지 않은 브랜치의 연결된 Git 워크트리에서만 시작함;

• 동시 작성자는 겹치는 경로 범위를 임대할 수 없음;

• 작성자 해제는 해당 브랜치, 워크트리 및 바이트를 보존함.

브리지는 기술적 안전 경계입니다. 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

거버넌스 어댑터

작성자 도구는 작업을 수락하고, 소유권을 선언하고, 지속적인 체크포인트를 기록하는 외부 거버넌스 프로세스를 요구합니다. 작성자를 활성화하기 전에 거버넌스 통합 계약을 읽으십시오.

GitHub 컨트롤 플레인 예제는 Issues, GitHub Project, PR 및 콘텐츠 없는 체크포인트를 사용하는 실용적인 어댑터를 보여줍니다. GitHub는 예시일 뿐, 브리지 의존성이 아닙니다. 완전한 도구 입력은 manifest.json에서 확인할 수 있습니다.

선택적 agent-control-skills 번들은 이 거버넌스 경계에 대한 재사용 가능한 코디네이터 지침을 제공합니다. 브리지는 해당 스킬을 설치하거나 그로부터 권한을 상속하지 않습니다.

노출된 도구

컨트롤러 수명 주기

프롬프트, 리뷰어, 작성자 또는 정리 변경 전에 프로젝트 컨트롤러를 획득하거나 재개하십시오. 반환된 임대 ID와 펜스 토큰은 일시적인 기능입니다. 변경 도구에 전달하되, 추적기, 커밋, 로그 또는 핸드오프에 게시하지 마십시오. 읽기 전용 인벤토리 및 대기 도구는 컨트롤러 임대 없이도 사용할 수 있습니다. 기본 임대는 15분 동안 지속되며, 긴 조정 턴 동안 갱신해야 합니다. herdr_bridge_status는 각 예약 잠금을 absent, active, stale 또는 indeterminate로 보고하지만, 소유자 PID, 잠금 ID 또는 컨트롤러 자격 증명은 노출하지 않습니다. 외부 호스트 잠금은 의도적으로 indeterminate입니다. 브리지는 TTL 추측으로 이를 빼앗지 않습니다.

조정

after_seq는 안정된 대기에서 이전 작업의 터미널 상태가 새 대기를 충족하지 못하게 합니다. 단일 긴 MCP 요청이 반복적인 클라이언트 측 폴링을 대체합니다. SSE 사이드 채널은 필요하지 않습니다. 임대된 에이전트의 경우, 프롬프트 수락은 먼저 정확한 안정된 ID를 요구한 다음 제출 전에 전달 전 커서를 기록합니다. 영수증은 팬, 이름, 에이전트 종류, 작업 디렉터리, 수명 주기 임대 및 커서를 바인딩합니다. 릴레이는 Herdr이 다음 커서에서 정확한 ID가 working 상태로 진입했음을 확인한 후에만 반환됩니다. 결과 영수증은 불투명한 조회 키입니다. 펜스, 프롬프트 또는 출력을 포함하지 않습니다. 해당 영수증이 완료, 실패 또는 명시적으로 포기될 때까지 해당 대상에 대한 이후의 모든 프롬프트는 거부됩니다. 이미 closing 또는 releasing 상태인 임대도 새 프롬프트를 거부합니다.

배치 핸드오프는 프롬프트를 제출하기 전에 동일한 컨트롤러 펜스 및 수명 주기 예약 하에서 모든 대상을 검증합니다. 모든 배치 대상은 하나의 활성 유지 임대를 가져야 합니다. 임대되지 않은 레거시 대상은 거부됩니다. mode=all은 요청 순서대로 결과를 반환합니다. mode=first는 지는 CLI 대기만 취소합니다. 다른 에이전트는 계속 작업하며 pendingReceipts로 반환됩니다. 수집은 해당 토큰을 요구하고, 수락된 working 커서 이후 엄격히 대기하며, 출력 캡처 후 ID와 시퀀스를 다시 읽습니다. 따라서 이후 작업의 출력은 잘못 라벨링되지 않고 거부됩니다. 완료된 영수증은 호출자 충돌 후 정확한 안정된 ID와 커서가 여전히 현재 상태인 동안에만 재생될 수 있습니다. 모호한 전달은 차단하는 reserved 영수증으로 남습니다. 운영자는 herdr_handoff_receipt_abandon, 유효한 컨트롤러 권한, 그리고 정확한 임대 에이전트가 안정되었다는 새로운 관찰을 통해서만 이를 해제할 수 있습니다.

컨트롤러 CLI

herdr-agent-control은 활성 컨트롤러 임대를 이미 보유한 명명된 코디네이터를 위한 로컬 CLI입니다. 실행자는 관리되는 코디네이터 환경에서 AGENT_CONTROL_CONTROLLER_ID를 해당 컨트롤러의 안정적인 ID로 설정해야 합니다. status 및 receipts는 읽기 전용이며 펜스를 로드하지 않습니다. 변경 명령은 현재 Herdr 팬, 에이전트 이름, 종류, 작업 디렉터리 및 Linux 프로세스 계보가 획득/재개 시 기록된 컨트롤러 프로세스와 일치한 후에만 임대를 로드합니다. 펜스는 인수나 출력에 절대 나타나지 않습니다.

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 팬의 명명된 에이전트에 바인딩됩니다. Herdr 외부의 MCP 클라이언트는 읽기 전용 인벤토리 및 대기 도구를 사용할 수 있지만, 이 버전에서는 조정 권한을 획득하거나 행사할 수 없습니다. 외부 코디네이터를 지원하려면 별도의 인증된 호출자 ID가 필요합니다. 팬을 가장하거나 자체 선언된 ID를 전달해서는 안 됩니다. 프로세스 계보는 협력적인 단일 사용자 호스트 모델에 대한 실패 시 닫힘 호출자 바인딩이며, 동일한 Unix 계정과 모드-0600 상태 파일을 다시 쓸 수 있는 권한을 가진 적대적 프로세스로부터의 격리가 아닙니다.

리뷰어 수명 주기

리뷰어 ID에는 컨트롤러, 에이전트 이름 및 종류, 팬, 작업 디렉터리가 포함됩니다. working, blocked, 임대되지 않음 또는 ID가 변경된 팬은 관찰 시 보존됩니다. 새로 생성된 탭은 루트 셸이 에이전트를 수락하기 전에 존재할 수 있습니다. 브리지는 제한된 시간 동안 동일한 임대 팬에서 정확한 agent_pane_busy 준비 조건만 재시도합니다. 다른 시작 오류는 실패 시 닫힙니다. Claude 리뷰어의 경우 시작 매니페스트는 명시적 model 및 effort를 전달할 수 있습니다. 이 값은 -- 뒤에 네이티브 Claude CLI 인수가 됩니다. 다른 에이전트 종류는 검토된 공급자 어댑터가 있을 때까지 명시적 모델 인수를 거부합니다.

작성자 수명 주기

호스트 검증

검증 레시피는 임대된 저장소의 코드입니다. 이들은 고정된 인자와 네트워크 없이 Linux Bubblewrap 샌드박스에서 실행됩니다. 이들은 이미 동일한 호스트 사용자를 가진 에이전트에 대한 보안 경계가 아닙니다. 선택적 웹 부트스트랩은 커밋된 lockfile을 사용하고, 패키지 다운로드를 허용하며, 패키지 수명 주기 스크립트를 비활성화합니다. Python 부트스트랩은 명시적으로 이름이 지정된 requirements.lock 파일에서 실행-로컬 uv 캐시를 워밍업할 수 있습니다. 각 lock은 일반 파일(심볼릭 링크 아님)이어야 하며, 바이트가 허용된 기본 커밋과 일치하고, 전체 의존성 그래프에 SHA-256 해시가 있어야 합니다. 브리지는 기본 파생 복사본을 읽기 전용으로 마운트하고, 레인-로컬 uv 구성을 무시하며, 소스 빌드를 비활성화하고, 네트워크가 가능한 동안 Python을 시작하지 않고 uv pip를 사용합니다. 최종 게이트는 여전히 오프라인 상태로 유지되며 동일한 격리된 캐시를 사용합니다. 호스트 리졸버가 /etc 외부의 심볼릭 링크인 경우, 네트워크 지원 부트스트랩은 해결된 파일만 읽기 전용으로 마운트합니다. 오프라인 게이트는 여전히 별도의 네트워크 네임스페이스를 사용합니다.

레거시 팬 임대

브리지 외부에서 생성된 레거시 에이전트는 코디네이터가 정리 전용 임대를 통해 채택할 때까지 소유되지 않은 상태로 남습니다. 채택은 정확한 명명된 에이전트, 팬, 종류, 작업 디렉터리, 정착된 상태 커서, 지속적 권한, 보호된 팬을 검증합니다. 이는 Git 소유권이나 구현 권한을 부여하지 않습니다.

작성자 승인에는 다음이 필요합니다:

• 지속적 티켓 및 권한 참조와 허용된 SHA-256 다이제스트;

• 저장소의 기본 체크아웃이 아닌 절대 경로의 연결된 Git 작업 트리;

• 정확한 브랜치, 기본 커밋, HEAD, Git 상태 다이제스트;

• 일반적으로 구성된 기본 브랜치인 하나 이상의 보호된 브랜치;

• 글로브나 .. 없는 리터럴 저장소-상대 소유 범위;

• 명시적 잠긴 범위;

• 작업 트리에 기존 Herdr 에이전트 없음;

• 브랜치, 작업 트리, 중복 소유권 또는 잠긴 범위에 대한 유지된 임대 없음.

예약 및 해제는 원자적 저장소 잠금을 사용합니다. 충돌은 의도적으로 검사가 필요한 유지된 예약을 남길 수 있습니다. 자동 복구를 위해 두 명의 작성자를 허용해서는 안 됩니다. Linux에서 새 예약 잠금에는 부팅 ID와 프로세스 시작 시간이 포함되므로 재부팅 또는 재사용된 PID는 오래된 것으로 인식됩니다. herdr_bridge_status는 모호한 레거시 또는 외부 호스트 잠금을 indeterminate로 노출합니다. 수동 복구 전에 이러한 잠금을 검사하고 나이로 삭제하지 마십시오.

읽기 전용 토폴로지 및 검색

안전 프로필은 또한 읽기 전용 세션, 팬, 탭, 작업 공간 및 통합 검사를 노출합니다. 원시 수명 주기 도구는 src/server.ts의 허용 목록에 의해 필터링된 상태로 유지됩니다.

요구 사항

• Node.js 18 이상의 Linux 또는 macOS; 호스트 검증은 추가로 Linux 및 Bubblewrap이 필요합니다;

• Git;

• Herdr 설치 및 실행 중;

• 시작하려는 각 에이전트 종류에 대한 Herdr 통합;

• Codex, Claude Code, OpenCode와 같은 MCP 지원 클라이언트.

설치 전에 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 클라이언트

herdr-mesh라는 이름의 로컬 stdio MCP 서버를 다음으로 등록하십시오:

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

설치 후 또는 브리지 업데이트 후 MCP 클라이언트를 다시 시작하십시오. 동일한 프로세스 내에서 /clear 또는 새 대화는 이미 실행 중인 MCP 서버를 다시 로드하지 않습니다.

선택적 환경

MCP 프로세스는 관리되는 작업 공간과 동일한 Herdr 소켓에 도달할 수 있어야 합니다. Herdr 내부에서 이미 실행 중인 코디네이터는 Herdr CLI를 사용할 수 있지만, 브리지는 여전히 더 좁은 권한, 이벤트 스타일 대기, 검증된 수명 주기를 제공합니다.

사용 방법

사용자는 일반적으로 도구 이름을 호출하는 대신 코디네이터와 대화합니다.

여러 에이전트 대기

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을 다시 읽고, 소유권을 예약하고, 전용 포커스 없는 탭을 만들고, 루트 팬에서 에이전트를 시작하고, 활성 임대를 반환하기 전에 ID를 확인합니다.

브리지는 파일 시스템 쓰기를 선언된 범위로 제한하지 않습니다. 코디네이터는 여전히 최종 변경 경로와 diff를 임대, 티켓 및 저장소 계약과 비교해야 합니다.

작성자 해제

해제 전에 현재 브랜치, HEAD, 더티 상태 다이제스트, 완료된 증명, 차단자 및 다음 작업을 포함하는 내용 없는 지속적 체크포인트를 기록하십시오. 그런 다음 체크포인트 참조와 다이제스트 및 새로 관찰된 에이전트 상태 커서와 Git 값을 사용하여 herdr_owned_worker_release를 호출하십시오.

해제는 임대된 팬만 닫습니다. 작업 트리를 커밋, 스태시, 리셋, 정리, 삭제 또는 수정하지 않습니다.

Herdr의 현재 pane close 명령은 예상 에이전트 상태 또는 커서를 허용하지 않습니다. 따라서 브리지는 닫기를 요청하기 직전에 ID, 정착 상태, 커서 안정성 및 컨트롤러 권한을 확인하지만, 최종 확인과 Herdr 닫기는 하나의 원자적 작업이 아닙니다. 닫기가 시작된 후 수동 Herdr 프롬프트를 보내거나 해당 팬을 재사용하지 마십시오. 조건부 닫기는 Herdr 자체의 지원이 필요합니다.

의도적 제한

• 독립 클론은 이 버전에서 작성자 레인으로 허용되지 않습니다. 연결된 Git 작업 트리를 사용하십시오.

• 임대 전에 생성된 기존 작업자는 자동으로 채택되지 않습니다.

• 브리지는 GitHub Issue가 권한을 부여한다는 것을 증명할 수 없습니다.

• 소유권은 승인 및 최종 조정 중에 확인됩니다. 운영 체제 파일 시스템 샌드박스가 아닙니다.

• 컨트롤러 펜싱 및 커서 검사는 오래된 브리지 작업을 방지하지만, Herdr는 이러한 검사를 프롬프트 전달 또는 팬 닫기와 원자적으로 결합하지 않습니다. 동일한 사용자의 직접 CLI 활동은 이 경계 밖에 있습니다.

• 인간 대화 및 blocked 에이전트는 인간의 결정으로 남습니다.

• 커밋, 푸시, PR, 병합, 배포, 마이그레이션 및 런타임 권한은 이 브리지 외부에 있습니다.

개발

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

테스트는 설치된 Herdr CLI 인자 계약, 커서 인식 대기, 컨트롤러 펜싱 및 인수, 배치 임대 ID, 샌드박스 리졸버 바인딩, 검토자 임대, 작성자 소유권 충돌, 보호된 브랜치, Git 상태 다이제스트 및 체크포인트 해제를 다룹니다.

빌드된 dist/ 디렉터리는 클라이언트가 TypeScript 도구 체인 없이 브리지를 실행할 수 있도록 커밋됩니다. 먼저 소스를 변경하고 위의 전체 명령을 실행한 다음 소스, 테스트, lockfile 및 생성된 출력을 함께 커밋하십시오.

업스트림 및 라이선스

업스트림 커밋 54adef5의 runchr-works/herdr-mesh를 기반으로 합니다. 업스트림은 일반 Herdr MCP 전송 및 설치 프로그램의 소스로 남아 있습니다. 이 포크는 안전한 허용 목록, 의미론적 대기 및 임대 수명 주기를 소유합니다.

MIT 라이선스에 따라 라이선스가 부여됩니다. LICENSE를 참조하십시오. 업스트림 저작권 고지는 보존됩니다.