herdr-mesh-safe

Herdr でコーディングエージェントを調整するための、セーフティスコープ付き MCP ブリッジ。

このリポジトリは runchr-works/herdr-mesh のフォークです。上流の MCP/Herdr 統合を維持しつつ、無制限のターミナルライフサイクルを、セマンティックウェイトとリーススコープ付きのレビューア・ライターに置き換えます。

現在のパッケージバージョン: 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

ガバナンスアダプター

ライターツールには、作業を受け入れ、所有権を宣言し、永続的なチェックポイントを記録する外部ガバナンスプロセスが必要です。ライターを有効にする前に、governance integration contract をお読みください。

GitHub control-plane example は、Issues、GitHub Project、PRs、コンテンツフリーチェックポイントを使用する実用的なアダプターの一例を示しています。GitHub は一例であり、ブリッジの依存関係ではありません。完全なツール入力は manifest.json にあります。

オプションの agent-control-skills バンドルは、このガバナンス境界のための再利用可能なコーディネーター指示を提供します。ブリッジはこれらのスキルをインストールしたり、それらから権限を継承したりしません。

公開ツール

コントローラーライフサイクル

プロジェクトコントローラーを、プロンプト、レビューア、ライター、またはクリーンアップの変更の前に取得または再開してください。返されたリース ID とフェンストークンは一時的な機能です: 変更ツールに渡しますが、トラッカー、コミット、ログ、またはハンドオフに公開しないでください。読み取り専用のインベントリと待機ツールは、コントローラーリースなしで利用可能です。デフォルトのリースは 15 分で、長時間の調整ターン中に更新する必要があります。herdr_bridge_status はまた、各予約ロックを absent、active、stale、または indeterminate として報告しますが、その所有者 PID、ロック ID、またはコントローラー認証情報は公開しません。外部ホストのロックは意図的に indeterminate です。ブリッジはタイムアウトの推測でそれを盗みません。

コーディネーション

安定待機の after_seq は、以前の作業からの終了状態が新しい待機を満たすのを防ぎます。単一の長い MCP リクエストが、繰り返されるクライアント側のポーリングを置き換えます。SSE サイドチャネルは必要ありません。リース済みエージェントの場合、プロンプトの受け入れは、最初に正確な安定 ID を要求し、送信前に配信前カーソルを記録します。レシートは、ペイン、名前、エージェントの種類、作業ディレクトリ、ライフサイクルリース、およびカーソルをバインドします。リレーは、Herdr が次のカーソルでその正確な ID が working に入ったことを確認した後にのみ返されます。結果のレシートは不透明なルックアップキーです。フェンス、プロンプト、または出力は含まれません。そのレシートが完了、失敗、または明示的に放棄されるまで、そのターゲットへの後のすべてのプロンプトは拒否されます。すでに closing または releasing にあるリースも、新しいプロンプトを拒否します。

バッチハンドオフは、プロンプトを送信する前に、同じコントローラーフェンスとライフサイクル予約の下で、すべてのターゲットを検証します。すべてのバッチターゲットには 1 つのアクティブな保持リースが必要です。リースされていないレガシーターゲットは拒否されます。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サンドボックス内で実行されます。これらは、すでに同じホストユーザーを持つエージェントに対するセキュリティ境界ではありません。オプションのウェブブートストラップはコミットされたロックファイルを使用し、パッケージのダウンロードを許可し、パッケージのライフサイクルスクリプトを無効化します。Pythonブートストラップは、明示的に指定されたrequirements.lockファイルから実行ローカルのuvキャッシュをウォームアップできます。各ロックは、受理されたベースコミットとバイトが一致し、完全な依存関係グラフがSHA-256ハッシュを持つ、通常の非シンボリックリンクファイルでなければなりません。ブリッジはベース由来のコピーを読み取り専用でマウントし、レーンローカルのuv構成を無視し、ソースビルドを無効化し、ネットワークが利用可能な間はPythonを起動せずにuv pipを使用します。最終ゲートはオフラインのままで、同じ分離キャッシュを使用します。ホストリゾルバが/etc外のシンボリックリンクの場合、ネットワーク有効なブートストラップは解決されたファイルのみを読み取り専用でマウントします。オフラインゲートは引き続き別のネットワーク名前空間を使用します。

レガシーペインリース

ブリッジ外で作成されたレガシーエージェントは、コーディネーターがクリーンアップ専用リースを通じて採用するまで未所有のままです。採用では、正確な名前のエージェント、ペイン、種類、作業ディレクトリ、確定済み状態カーソル、永続的権限、保護されたペインを検証します。Gitの所有権や実装権限は付与されません。

ライターの受け入れには以下が必要です:

• 永続的なチケットと権限の参照に加え、受理されたSHA-256ダイジェスト;

• リポジトリのプライマリチェックアウトではなく、絶対パスのリンク済みGitワークツリー;

• 正確なブランチ、ベースコミット、HEAD、Gitステータスのダイジェスト;

• 少なくとも1つの保護ブランチ(通常は設定済みのデフォルトブランチ);

• グロブや..のない、リポジトリ相対のリテラルな所有スコープ;

• 明示的なロックスコープ;

• ワークツリー内に既存のHerdrエージェントがないこと;

• ブランチ、ワークツリー、重複する所有権、またはロックスコープに対する保持済みリースがないこと。

予約と解放はアトミックなストアロックを使用します。クラッシュにより、検査が必要な保持済み予約が意図的に残される場合があります。自動回復のために2つのライターを決して受け入れてはなりません。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を使用し、最初の終端状態と可視出力を1つの結果として受け取ります。

読み取り専用の外部レビューを実行する

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を独立して再読み取りし、所有権を予約し、専用のフォーカスなしタブを作成し、ルートペインでエージェントを起動し、アクティブなリースを返す前にそのアイデンティティを検証します。

ブリッジはファイルシステムへの書き込みを宣言されたスコープに制限しません。コーディネーターは、最終的な変更パスと差分をリース、チケット、リポジトリ契約と照合する必要があります。

ライターを解放する

解放前に、現在のブランチ、HEAD、ダーティ状態ダイジェスト、完了した証明、ブロッカー、次のアクションを含む、コンテンツなしの永続的チェックポイントを記録してください。次に、チェックポイントの参照とダイジェストに加えて、最新のエージェント状態カーソルとGit値を指定してherdr_owned_worker_releaseを呼び出します。

解放はリースされたペインのみを閉じます。コミット、スタッシュ、リセット、クリーン、削除、ワークツリーの変更は行いません。

Herdrの現在のpane closeコマンドは、期待されるエージェント状態またはカーソルを受け付けません。そのためブリッジは、クローズを要求する直前にアイデンティティ、確定状態、カーソルの安定性、コントローラー権限をチェックしますが、最終チェックとHerdrのクローズは単一のアトミック操作ではありません。クローズ開始後は、手動のHerdrプロンプトを送信したり、そのペインを再利用したりしないでください。条件付きクローズにはHerdr自体のサポートが必要です。

意図的な制限

• 独立したクローンはこのバージョンではライターレーンとして受け入れられません。リンク済みのGitワークツリーを使用してください。

• リース前に作成された既存のワーカーは自動的に採用されません。

• ブリッジはGitHub Issueが権限を付与することを証明できません。

• 所有権は受け入れ時と最終調整中にチェックされます。オペレーティングシステムのファイルシステムサンドボックスではありません。

• コントローラーフェンスとカーソルのチェックは古いブリッジ操作を防ぎますが、Herdrはこれらのチェックをプロンプト配信やペインクローズと原子的に組み合わせません。同一ユーザーによる直接のCLI操作はこの境界の外にあります。

• 人間のダイアログとblockedエージェントは、人間の判断のままです。

• コミット、プッシュ、PR、マージ、デプロイ、マイグレーション、ランタイムの権限は、このブリッジの範囲外です。

開発

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

テストでは、インストール済みのHerdr CLI引数契約、カーソル対応の待機、コントローラーフェンスと引き継ぎ、バッチリースのアイデンティティ、サンドボックスリゾルバのバインド、レビューアーリース、ライターの所有権競合、保護ブランチ、Git状態ダイジェスト、チェックポイント付き解放をカバーしています。

ビルド済みのdist/ディレクトリはコミットされているため、クライアントはTypeScriptツールチェーンなしでブリッジを実行できます。最初にソースを変更し、上記の完全なコマンドを実行して、ソース、テスト、ロックファイル、生成された出力をまとめてコミットしてください。

アップストリームとライセンス

アップストリームコミット54adef5のrunchr-works/herdr-meshに基づいています。アップストリームは汎用のHerdr MCPトランスポートとインストーラーのソースであり続けます。このフォークは、セーフ許可リスト、セマンティック待機、リースライフサイクルを所有します。

MITライセンスの下でライセンスされています。LICENSEを参照してください。アップストリームの著作権表示は保持されています。