herdr-mesh-safe

Eine sicherheitsbezogene MCP-Brücke zur Koordination von Codierungsagenten in Herdr.

Dieses Repository ist ein Fork von runchr-works/herdr-mesh. Es behält die Upstream-MCP/Herdr-Integration bei und ersetzt den uneingeschränkten Terminal-Lebenszyklus durch semantische Wartezeiten und leasingscoped Reviewer und Writer.

Aktuelle Paketversion: 0.1.0-safe.13.

Warum dieser Fork existiert

Ein Orchestrierungsagent muss Arbeiter inspizieren, Aufgaben senden, auf Ergebnisse warten und freigewordene Kapazität zurückfordern können. Wenn man diesem Agenten beliebige Terminalbefehle, rohe Tastatureingaben oder unbegrenzte Pane-Löschungen gewährt, entsteht unnötige Autorität.

Diese Brücke stellt die Operationen bereit, die der Koordinator benötigt, während sie diese Invarianten beibehält:

• keine vom Aufrufer bereitgestellten Shell-Befehle oder uneingeschränkte Terminalausführung;

• keine rohen send-keys;

• keine unbegrenzte Löschung von Panes, Tabs, Arbeitsbereichen oder Sitzungen;

• Controller-Zugangsdaten werden unmittelbar vor Brückenaufforderungen und Lebenszyklusanfragen überprüft;

• Jede Aufforderung an einen beibehaltenen Agenten wird nur zugelassen, während alle Lebenszyklus- und Handoff-Belegspeicher gesperrt sind;

• Die Ergebnissammlung ist an die exakte geleaste Pane und den akzeptierten Prompt-Cursor gebunden;

• Automatisches Schließen erfordert eine Leerlauf-/Fertig-Beobachtung und einen unveränderten Zustandscursor während der Ausgabeerfassung;

• Ein Reviewer kann nur über das mit ihm erstellte Lease geschlossen werden;

• Ein Writer startet nur in einem verknüpften Git-Worktree auf einem nicht geschützten Branch;

• Gleichzeitige Writer können keine überlappenden Pfadbereiche leasen;

• Das Freigeben eines Writers erhält seinen Branch, Worktree und seine Bytes.

Die Brücke ist eine technische Sicherheitsgrenze. Sie entscheidet nicht, ob ein GitHub-Issue, eine Spezifikation, eine Eigentumserklärung, ein Commit, ein Merge, eine Migration oder eine Bereitstellung autorisiert ist. Der Koordinator und der Vertrag des Ziel-Repositorys bleiben maßgeblich.

Related MCP server: MCP Files

Architektur

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

Lease-Datensätze werden außerhalb von Git mit Modus 0600 gespeichert unter:

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

Writer-Tools erfordern einen externen Governance-Prozess, der die Arbeit akzeptiert, Eigentum erklärt und dauerhafte Checkpoints aufzeichnet. Lesen Sie den Governance-Integrationsvertrag, bevor Sie Writer aktivieren.

Das GitHub-Control-Plane-Beispiel zeigt einen praktischen Adapter, der Issues, ein GitHub-Projekt, PRs und inhaltsfreie Checkpoints verwendet. GitHub ist ein Beispiel, keine Brückenabhängigkeit. Eine vollständige Tool-Eingabe ist in manifest.json verfügbar.

Das optionale agent-control-skills-Paket bietet wiederverwendbare Koordinatoranweisungen für diese Governance-Grenze. Die Brücke installiert diese Fähigkeiten nicht und erbt keine Autorität von ihnen.

Verfügbare Tools

Controller-Lebenszyklus

Erwerben oder setzen Sie den Projekt-Controller fort, bevor Sie eine Aufforderung, einen Reviewer, einen Writer oder eine Bereinigungsänderung durchführen. Die zurückgegebene Lease-ID und das Fence-Token sind flüchtige Fähigkeiten: Übergeben Sie sie an mutierende Tools, veröffentlichen Sie sie jedoch nicht in einem Tracker, Commit, Log oder Handoff. Schreibgeschützte Inventar- und Wartetools bleiben ohne Controller-Lease verfügbar. Das Standard-Lease dauert 15 Minuten und muss während langer Koordinationsrunden erneuert werden. herdr_bridge_status meldet auch jede Reservierungssperre als absent, active, stale oder indeterminate, ohne deren Besitzer-PID, Sperr-ID oder Controller-Anmeldeinformationen offenzulegen. Eine Sperre auf einem fremden Host ist absichtlich indeterminate; die Brücke stiehlt sie nicht auf eine Time-to-Live-Vermutung hin.

Koordination

after_seq bei den Beruhigungswartezeiten verhindert, dass ein Endzustand aus früherer Arbeit eine neue Wartezeit erfüllt. Eine einzelne lange MCP-Anfrage ersetzt wiederholtes clientseitiges Polling; ein SSE-Seitenkanal ist nicht erforderlich. Für einen geleasten Agenten erfordert die Zulassung einer Aufforderung zuerst eine exakte beruhigte Identität, dann wird der Cursor vor der Zustellung aufgezeichnet. Der Beleg bindet Pane, Name, Agentenart, Arbeitsverzeichnis, Lebenszyklus-Lease und Cursor. Relay kehrt erst zurück, nachdem Herdr bestätigt hat, dass diese exakte Identität am nächsten Cursor in working eingetreten ist. Der resultierende Beleg ist ein undurchsichtiger Nachschlageschlüssel; er enthält kein Fence, keine Aufforderung und keine Ausgabe. Bis dieser Beleg abgeschlossen, fehlgeschlagen oder explizit aufgegeben ist, wird jede spätere Aufforderung an dieses Ziel abgelehnt. Ein Lease, das sich bereits in closing oder releasing befindet, lehnt ebenfalls neue Aufforderungen ab.

Batch-Handoff validiert jedes Ziel unter demselben Controller-Fence und denselben Lebenszyklusreservierungen, bevor es eine Aufforderung übermittelt. Jedes Batch-Ziel muss ein aktives beibehaltenes Lease haben; nicht geleaste Legacy-Ziele werden abgelehnt. mode=all gibt Ergebnisse in Anfragereihenfolge zurück. mode=first bricht nur die verlierenden CLI-Wartezeiten ab; die anderen Agenten arbeiten weiter und werden als pendingReceipts zurückgegeben. Die Sammlung erfordert diese Token, wartet strikt nach dem akzeptierten working-Cursor und liest Identität und Sequenz nach der Ausgabeerfassung erneut. Die Ausgabe einer späteren Aufgabe wird daher abgelehnt und nicht falsch beschriftet. Ein abgeschlossener Beleg kann nach einem Absturz des Aufrufers nur wiedergegeben werden, solange seine exakte beruhigte Identität und sein Cursor noch aktuell sind. Eine mehrdeutige Zustellung bleibt ein blockierender reserved-Beleg. Ein Operator kann ihn nur mit herdr_handoff_receipt_abandon, gültiger Controller-Autorität und einer frischen Beobachtung, dass der exakte geleaste Agent beruhigt ist, freigeben.

Controller-CLI

herdr-agent-control ist eine lokale CLI für einen benannten Koordinator, der bereits das aktive Controller-Lease hält. Der Launcher muss AGENT_CONTROL_CONTROLLER_ID auf die stabile ID dieses Controllers in der verwalteten Koordinatorumgebung setzen. status und receipts sind schreibgeschützt und laden das Fence nicht. Mutierende Befehle laden das Lease nur, nachdem die aktuelle Herdr-Pane, der Agentenname, die Art, das Arbeitsverzeichnis und die Linux-Prozessabstammung mit dem beim Erwerb/Fortsetzen aufgezeichneten Controller-Prozess übereinstimmen. Das Fence erscheint nie in Argumenten oder Ausgabe.

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 und ask-many verwenden das beleggebundene Batch-Protokoll. collect übermittelt nie eine Aufforderung. abandon stoppt nie einen Prozess; es gibt nur die Zulassungsbarriere frei, nachdem das exakte Ziel als beruhigt beobachtet wurde. Controller-Leases, die vor der Einführung der Prozessbindung erstellt wurden, müssen einmal fortgesetzt werden, bevor die mutierende CLI sie verwenden kann. Die CLI startet, schließt, stoppt, löscht, committet oder führt keine beliebigen Terminalbefehle aus.

Das aktuelle Controller-Lease ist bewusst an einen benannten Agenten in einer verwalteten Herdr-Pane gebunden. MCP-Clients außerhalb von Herdr können schreibgeschützte Inventar- und Wartetools verwenden, aber sie können in dieser Version keine Koordinationsautorität erwerben oder ausüben. Die Unterstützung eines externen Koordinators erfordert eine separate authentifizierte Aufruferidentität; sie darf keine Pane vortäuschen oder eine selbst deklarierte Identität übergeben. Die Prozessabstammung ist eine Fail-Closed-Aufruferbindung für das kooperative Einzelbenutzer-Hostmodell, keine Isolierung von einem feindlichen Prozess mit demselben Unix-Konto und der Berechtigung, die Zustandsdateien mit Modus 0600 neu zu schreiben.

Reviewer-Lebenszyklus

Die Reviewer-Identität umfasst Controller, Agentenname und -art, Pane und Arbeitsverzeichnis. working, blocked, nicht geleaste oder identitätsabweichende Panes werden bei Beobachtung erhalten. Ein neu erstellter Tab kann existieren, bevor seine Root-Shell einen Agenten akzeptiert; die Brücke wiederholt nur die exakte agent_pane_busy-Bereitschaftsbedingung in derselben geleasten Pane für ein begrenztes Zeitfenster. Andere Startfehler schlagen fehlgeschlossen fehl. Für Claude-Reviewer kann das Startmanifest ein explizites model und effort übergeben; diese Werte werden zu nativen Claude-CLI-Argumenten nach --. Andere Agentenarten lehnen explizite Modellargumente ab, bis sie einen überprüften Provider-Adapter haben.

Writer-Lebenszyklus

Host-Verifizierung

Verifizierungsrezepte sind Code aus dem geleasten Repository. Sie laufen in einer Linux-Bubblewrap-Sandbox mit festen Argumenten und ohne Netzwerk. Sie stellen keine Sicherheitsgrenze gegen einen Agenten dar, der bereits denselben Host-Benutzer hat. Der optionale Web-Bootstrap verwendet die committete Lockfile, erlaubt Paket-Downloads und deaktiviert Paket-Lebenszyklus-Skripte. Ein Python-Bootstrap kann den run-lokalen uv-Cache aus explizit benannten requirements.lock-Dateien aufwärmen; jede Lock-Datei muss eine reguläre, nicht-symlinkische Datei sein, deren Bytes mit dem akzeptierten Basis-Commit übereinstimmen und deren vollständiger Abhängigkeitsgraph SHA-256-Hashes hat. Die Brücke mountet eine vom Basis abgeleitete Kopie schreibgeschützt, ignoriert die lane-lokale uv-Konfiguration, deaktiviert Quell-Builds und verwendet uv pip, ohne Python zu starten, solange Netzwerk verfügbar ist. Das letzte Tor bleibt offline und verwendet denselben isolierten Cache. Wenn der Host-Resolver ein Symlink außerhalb von /etc ist, mountet ein netzwerkfähiger Bootstrap nur seine aufgelöste Datei schreibgeschützt; Offline-Tore verwenden weiterhin einen separaten Netzwerk-Namespace.

Legacy-Pane-Leases

Legacy-Agenten, die außerhalb der Brücke erstellt wurden, bleiben ohne Besitzer, bis ein Koordinator sie durch eine Nur-Aufräum-Lease übernimmt. Die Übernahme verifiziert den exakt benannten Agenten, Pane, Art, Arbeitsverzeichnis, den stabilisierten Zustands-Cursor, die dauerhafte Autorität und geschützte Panes. Sie gewährt keine Git-Besitzerschaft oder Implementierungsautorität.

Für die Zulassung als Writer sind erforderlich:

• dauerhafte Ticket- und Autoritätsreferenzen sowie ein akzeptierter SHA-256-Digest;

• ein absolutes verknüpftes Git-Worktree, nicht der primäre Checkout des Repositorys;

• exakter Branch, Basis-Commit, HEAD und Git-Status-Digest;

• mindestens ein geschützter Branch, normalerweise der konfigurierte Standard-Branch;

• wörtliche repository-relative eigene Scopes ohne Globs oder ..;

• explizit gesperrte Scopes;

• kein vorhandener Herdr-Agent im Worktree;

• keine beibehaltene Lease für den Branch, das Worktree, überlappende Besitzerschaft oder gesperrten Scope.

Reservierungen und Freigaben verwenden eine atomare Store-Sperre. Ein Absturz kann absichtlich eine beibehaltene Reservierung hinterlassen, die eine Überprüfung erfordert; es darf niemals zwei Writer zulassen, nur um automatisch wiederherzustellen. Unter Linux enthalten neue Reservierungssperren die Boot-ID und die Prozessstartzeit, sodass ein Neustart oder eine wiederverwendete PID als veraltet erkannt wird. herdr_bridge_status zeigt mehrdeutige Legacy- oder Fremdhost-Sperren als indeterminate an; überprüfen Sie diese vor jeder manuellen Wiederherstellung, anstatt sie nach Alter zu löschen.

Schreibgeschützte Topologie und Erkennung

Das sichere Profil bietet auch schreibgeschützte Inspektion von Sitzung, Pane, Tab, Arbeitsbereich und Integration. Rohe Lebenszyklus-Werkzeuge bleiben durch die Zulassungsliste in src/server.ts gefiltert.

Anforderungen

• Linux oder macOS mit Node.js 18 oder neuer; Host-Verifizierung erfordert zusätzlich Linux und Bubblewrap;

• Git;

• Herdr installiert und ausgeführt;

• die Herdr-Integration für jede Agentenart, die Sie starten möchten;

• einen MCP-fähigen Client wie Codex, Claude Code oder OpenCode.

Überprüfen Sie Herdr vor der Installation:

herdr status
herdr integration status

Installieren Sie fehlende Integrationen, zum Beispiel:

herdr integration install codex
herdr integration install claude

Aus dem Quellcode installieren

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

Der kompilierte MCP-Einstiegspunkt ist dist/index.js.

Codex

Fügen Sie dies zu ~/.codex/config.toml hinzu, unter Verwendung des absoluten Klonpfads:

[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 oder ein anderer MCP-Client

Registrieren Sie einen lokalen stdio-MCP-Server namens herdr-mesh mit:

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

Starten Sie den MCP-Client nach der Installation oder bei jedem Brücken-Update neu. /clear oder eine neue Konversation innerhalb desselben Prozesses lädt einen bereits laufenden MCP-Server nicht neu.

Optionale Umgebung

Der MCP-Prozess muss denselben Herdr-Socket erreichen können wie der verwaltete Arbeitsbereich. Ein Koordinator, der bereits innerhalb von Herdr läuft, kann die Herdr-CLI verwenden, aber die Brücke bietet weiterhin engere Autorität, ereignisartige Wartezeiten und verifizierten Lebenszyklus.

So verwenden Sie es

Benutzer sprechen normalerweise mit dem Koordinator, anstatt Werkzeugnamen aufzurufen.

Auf mehrere Agenten warten

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.

Der Koordinator verwendet herdr_agent_wait_any und erhält den ersten Endzustand plus sichtbare Ausgabe in einem Ergebnis.

Eine schreibgeschützte externe Überprüfung durchführen

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.

Die erwartete Reihenfolge ist:

1. herdr_controller_acquire oder herdr_controller_resume

2. herdr_owned_reviewer_start mit der Controller-Lease/Fence und, für Claude, dem exakten Modell/Aufwand

3. herdr_relay mit derselben Controller-Lease/Fence und bewahren Sie deren Quittung auf

4. herdr_collect_handoffs mit dieser Quittung

5. herdr_owned_reviewer_close mit derselben Controller-Lease/Fence

Eine Writer-Lane starten

Der Koordinator validiert zuerst das akzeptierte Ticket/Spezifikation, Abhängigkeiten, Besitzerschaft, Sperren und Integrationsreihenfolge gegen den dauerhaften Projektzustand. Dann sammelt er die exakten lokalen Beweise, einschließlich:

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

Er ruft herdr_owned_worker_start mit diesen Beweisen auf. Das Werkzeug liest unabhängig Git, reserviert Besitzerschaft, erstellt einen dedizierten Tab ohne Fokus, startet den Agenten in seinem Root-Pane und verifiziert dessen Identität, bevor es eine aktive Lease zurückgibt.

Die Brücke beschränkt Dateisystem-Schreibvorgänge nicht auf die deklarierten Scopes. Der Koordinator muss dennoch die endgültigen geänderten Pfade und den Diff mit der Lease, dem Ticket und dem Repository-Vertrag vergleichen.

Einen Writer freigeben

Vor der Freigabe erfassen Sie einen inhaltsfreien dauerhaften Checkpoint, der den aktuellen Branch, HEAD, Dirty-State-Digest, abgeschlossenen Beweis, Blocker und nächste Aktion enthält. Rufen Sie dann herdr_owned_worker_release mit der Checkpoint-Referenz und dem Digest sowie dem frisch beobachteten Agenten-Zustands-Cursor und den Git-Werten auf.

Die Freigabe schließt nur das geleaste Pane. Sie committet, stasht, resettet, bereinigt, löscht oder modifiziert das Worktree nicht.

Herdrs aktueller pane close-Befehl akzeptiert keinen erwarteten Agentenzustand oder Cursor. Die Brücke prüft daher Identität, stabilisierten Status, Cursor-Stabilität und Controller-Autorität unmittelbar vor dem Anfordern des Schließens, aber die endgültige Prüfung und das Herdr-Schließen sind keine atomare Operation. Senden Sie keine manuelle Herdr-Eingabeaufforderung und verwenden Sie dieses Pane nach Beginn des Schließens nicht anderweitig wieder. Bedingtes Schließen erfordert Unterstützung in Herdr selbst.

Bewusste Einschränkungen

• Unabhängige Klone werden in dieser Version nicht als Writer-Lanes akzeptiert; verwenden Sie verknüpfte Git-Worktrees.

• Bestehende Worker, die vor Leases erstellt wurden, werden nicht automatisch übernommen.

• Die Brücke kann nicht beweisen, dass ein GitHub-Issue Autorität gewährt.

• Die Besitzerschaft wird bei der Zulassung und während der endgültigen Koordination geprüft; sie ist keine Betriebssystem-Dateisystem-Sandbox.

• Controller-Fencing und Cursor-Prüfungen verhindern veraltete Brückenoperationen, aber Herdr kombiniert diese Prüfungen nicht atomar mit der Zustellung von Eingabeaufforderungen oder dem Schließen von Panes. Direkte CLI-Aktivität desselben Benutzers bleibt außerhalb dieser Grenze.

• Menschliche Dialoge und blocked-Agenten bleiben menschliche Entscheidungen.

• Commit, Push, PR, Merge, Deployment, Migration und Laufzeit-Autorität bleiben außerhalb dieser Brücke.

Entwicklung

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

Die Tests decken den installierten Herdr-CLI-Argumentvertrag, cursor-bewusste Wartezeiten, Controller-Fencing und -Übernahme, Batch-Lease-Identität, Sandbox-Resolver-Bindung, Reviewer-Leases, Writer-Besitzkonflikte, geschützte Branches, Git-Status-Digests und checkpoint-basierte Freigabe ab.

Das erstellte dist/-Verzeichnis ist committet, sodass Clients die Brücke ohne TypeScript-Werkzeugkette ausführen können. Ändern Sie zuerst den Quellcode, führen Sie die obigen vollständigen Befehle aus und committen Sie Quellcode, Tests, Lockfile und generierte Ausgabe zusammen.

Upstream und Lizenz

Basiert auf runchr-works/herdr-mesh beim Upstream-Commit 54adef5. Upstream bleibt die Quelle für den generischen Herdr-MCP-Transport und Installer; dieser Fork besitzt die sichere Zulassungsliste, semantische Wartezeiten und den Lease-Lebenszyklus.

Lizenziert unter der MIT-Lizenz. Siehe LICENSE; der Upstream-Urheberrechtshinweis bleibt erhalten.