# Agent Branch (Agentenzweig)

*Jede Ausführung arbeitet auf einem Copy-on-Write-Branch. Nur ein geprüfter Merge erreicht die Hauptlinie.*

> **Ein Agent Branch** lässt jede Ausführung auf einem Copy-on-Write-Branch arbeiten. Änderungen erreichen die geschützte Hauptlinie nur durch einen geprüften Merge (einen Agent PR), und Sie können jederzeit Checkpoints setzen und wiederherstellen.

**AN-02** · Konformitätsstufe: L0 Files · Gruppe: Arbeit

## Das Problem

Agenten machen Fehler in Maschinengeschwindigkeit, und gemeinsame Daten bieten keine Möglichkeit, „es auszuprobieren, den Diff zu sehen, zu prüfen und rückgängig zu machen“. Parallele Agenten treten sich außerdem gegenseitig auf die Füße.

Bei einem Vorfall im April 2026 löschte ein Agent mit einem zu weit gefassten Token innerhalb von 9 Sekunden ein Produktionsvolume und die Backups auf demselben Volume. Hätte er nur auf einen Branch schreiben können, wäre Löschen weich gewesen und hätten Snapshots außerhalb seiner Befugnis gelegen, wäre der Schaden weit kleiner gewesen.

## So funktioniert es

- **Branches sind günstig** (je nach Engine idealerweise nahe an O(1)). Eine Lease erlaubt Schreibzugriffe **innerhalb des Branches** und `propose` in Richtung Ziel.
- **Geschützte Trees.** Die Hauptlinie lässt sich nur durch einen Merge aktualisieren: Selbst abgeflossene Zugangsdaten können nicht direkt darauf schreiben.
- **Agent PR.** Der Diff, die Absicht, die Provenienz (eine Zusammenfassung des Lesemanifests), Prüfergebnisse und eine Zusammenfassung der Labels. Bestehen die Prüfungen und erlaubt es die Richtlinie, wird automatisch gemergt; andernfalls geht es an ein [Human Gate](https://agentnas.com/de/concepts/human-gate/).
- **Soft Delete.** Löschungen in einem geschützten Tree landen standardmäßig in einem Papierkorb und werden 7 Tage aufbewahrt; Snapshots gehören dem Eigentümer und liegen **außerhalb der Befugnis jeder Lease**.
- **Checkpoints.** Benannte Snapshots; `restore` setzt Dateien auf einen Checkpoint zurück.
- **Mergen.** Text nutzt einen Drei-Wege-Merge, andere Dateien werden pro Datei gemergt. Bei einem Konflikt hält er an und **überschreibt nie stillschweigend**; strukturierte Daten brauchen einen registrierten Merger oder einen Menschen.
- **TTL und Kontingent,** um Branch-Bomben zu verhindern.
- **Parallele Versuche.** Öffnen Sie N Branches für eine Aufgabe, mergen Sie den besten und geben Sie die übrigen in den Papierkorb.

## Klein anfangen

- Git-Branches und Worktrees, dazu ein **geschützter `main`** auf Forgejo, Gitea oder GitHub.
- Für große Verzeichnisse nutzen Sie btrfs- oder ZFS-Snapshots und -Clones; für Objektspeicher Forks von Tigris oder lakeFS.
- Bringen Sie zuerst „Löschungen landen im Papierkorb“ und „Snapshots gehören dem Eigentümer“ in Ordnung. Das ist am günstigsten und verhindert den größten Schaden.

## Schnittstellenskizze

Nur zur Veranschaulichung. Feldnamen können sich vor der Spezifikation v0.3 ändern.

*nas cli*

```bash
nas branch create cleo/release-notes --from main --ttl 48h
nas checkpoint create before-refactor
nas propose --into main --checks links,schema
nas restore before-refactor
nas trash list                    # recycle area, kept 7 days by default
nas trash restore <path>
```

## Was die Spezifikation verlangt

- Ein geschützter Tree MUSS sich nur durch einen Merge aktualisieren lassen; keine Zugangsdaten DÜRFEN direkt darauf schreiben.
- Ein Merge MUSS einen Commit erzeugen, der Provenienz trägt (Run, Lease, Principal).
- Keine Lease DARF erlauben, einen Snapshot oder ein Backup zu löschen.
- Eine Löschung in einem geschützten Tree MUSS ein Soft Delete sein und innerhalb des eingestellten Zeitfensters (standardmäßig 7 Tage) wiederherstellbar bleiben.
- Ein Konflikt DARF NICHT stillschweigend aufgelöst werden; der Merge MUSS anhalten und Bericht erstatten.
- Ein Branch MUSS eine TTL und ein Kontingent haben.

## Was übernommen ist und was neu ist

Alles Folgende ist etablierte Praxis. **Neu ist:** den Branch an eine **Ausführung und eine Lease** zu binden, sodass der Branch die Einheit der Autorisierung und der Merge die Einheit der Prüfung ist. Branches und Snapshots selbst sind nicht neu.

- [Git worktree](https://git-scm.com/docs/git-worktree)
- [lakeFS for agents](https://lakefs.io/agentic-ai/)
- [Tigris Agent Kit](https://www.tigrisdata.com/docs/ai/agent-kit/)
- [Cloudflare Artifacts](https://blog.cloudflare.com/artifacts-git-for-agents-beta/)

## Ehrliche Grenzen

- Ein Branch schützt nur Daten innerhalb des NAS. Er **macht keine externen Nebenwirkungen rückgängig**: eine bereits gesendete E-Mail, eine bereits aufgerufene API.
- Große Binärdateien und Datenbankdateien lassen sich schwer mergen.
- Freigabemüdigkeit kann trotzdem auftreten, daher dürfen Pfade mit geringem Risiko automatisch gemergt werden, und die Freigabequote wird gemessen.

## Offene Fragen

- Wie werden semantische Merger registriert und als vertrauenswürdig eingestuft?
- Wie sollte die Interaktion bei Binärkonflikten aussehen?

## Fragen

### Wie unterscheidet sich das von einem Git-Branch?

Mechanisch ist es keine Magie: Sie können es auf Git bauen. Der Unterschied ist, dass es den Branch an eine Ausführung und eine Lease bindet, sodass „kann nur den eigenen Branch beschreiben“ zu einer Autorisierungsregel und der Merge zum einzigen Prüfpunkt wird.

### Verhindert ein Branch jeden Unfall?

Nein. Er schützt nur Daten innerhalb des NAS: Eine bereits gesendete E-Mail oder eine bereits aufgerufene externe API wird durch das Zurücksetzen eines Branches nicht rückgängig gemacht. Solche Aktionen sollten über `egress` in der Lease und ein Human Gate laufen.

### Muss jeder Merge von einem Menschen freigegeben werden?

Nein. Ein Merge, dessen Prüfungen bestehen, dessen Ausführung keine externen Inhalte gelesen hat und der kein Löschen oder Teilen betrifft, kann automatisch durchgehen. Ein Mensch ist nur in wenigen Fällen nötig; siehe [Human Gate](https://agentnas.com/de/concepts/human-gate/).

## Verwandte Konzepte

- [Human Gate (menschliche Freigabe)](https://agentnas.com/de/concepts/human-gate/): Erscheint nur vor unumkehrbaren, nach außen gerichteten oder rechteerweiternden Aktionen und zeigt den echten Diff.
- [Agent Home (Home-Verzeichnis)](https://agentnas.com/de/concepts/agent-home/): Ein Verzeichnis pro Rolle, mit Verlauf. Gewöhnliche Dateien, die Sie mitnehmen können.
- [Flight Recorder (Flugschreiber)](https://agentnas.com/de/concepts/flight-recorder/): Ein Protokoll pro Ausführung, per Hash verkettet, das auch festhält, was gelesen wurde.

---

Kanonische URL: https://agentnas.com/de/concepts/agent-branch/
Aktualisiert am: 2026-11-11 · Spezifikationsentwurf v0.2 · CC BY 4.0