Muse-Code-Unterbrechungen bei langen Aufgaben beheben

Geeignet: für Unterbrechungen von Muse Code bei langen Aufgaben, wenn Änderungen bereits im Arbeitsbereich liegen, aber der letzte sichere Verarbeitungsschritt unklar ist. Nicht geeignet: für ein blindes Neustarten desselben Ziels. Prüfen Sie zuerst Ereignisprotokoll, Git-Zustand und externe Nebenwirkungen. Erst danach entscheiden Sie zwischen Fortsetzen, Rücklauf oder Neuaufbau aus einem Checkpoint.

Dieser Leitfaden richtet sich an Entwickler, die große Repositories mit Muse Code bearbeiten, an Plattformingenieure für entfernte Sitzungen und an technische Verantwortliche, die Agentenänderungen freigeben müssen.

Zuletzt aktualisiert am 12.08.2026; die Wiederherstellungsmechanik wurde anhand der offiziellen Muse-Code-Versionsbeschreibung geprüft. Die konkreten Wiederherstellungsergebnisse müssen für jede Muse-Code- und Muse-Spark-1.2-Version separat getestet werden.

Nach einer doppelten Aktion zählt nicht der Chat, sondern der Zustand

Der typische Fehler sieht unspektakulär aus: Eine lange Aufgabe verliert die Verbindung. Nach dem Neustart meldet Muse Code, der letzte Schritt sei unklar. Der Agent führt daraufhin erneut ein Skript aus, erstellt einen zweiten Commit oder sendet dieselbe Nachricht nochmals an einen externen Dienst.

Das Problem ist nicht zwingend ein verlorener Codezustand. Drei Dinge können unabhängig voneinander passiert sein:

• Die Terminal- oder SSH-Verbindung ist abgebrochen, während der Prozess weiterlief.
• Der Muse-Code-Prozess ist beendet worden, obwohl bereits Dateien geschrieben wurden.
• Die Modellanfrage ist fehlgeschlagen, nachdem ein Tool die Änderung schon ausgeführt hatte.

Die offizielle Beschreibung von Muse Code bestätigt, dass lokale Ereignisprotokolle die Wiederaufnahme nach einem Neustart unterstützen. Daraus folgt jedoch nicht, dass das Protokoll ein vollständiges Transaktionssystem ist. Ein Eintrag kann eine Modellentscheidung, einen Tool-Aufruf, eine Antwort oder einen bestätigten Dateischritt dokumentieren. Ob eine externe Nebenwirkung tatsächlich abgeschlossen wurde, muss separat geprüft werden.

Für eine belastbare Wiederaufnahme benötigen wir deshalb mindestens vier Belege:

1. den letzten bestätigten Eintrag im Ereignisprotokoll,
2. den aktuellen Git- und Dateisystemzustand,
3. die Rückmeldung des verwendeten Tools,
4. den Status jeder externen Aktion.

Das entspricht auch dem Grundprinzip von Git: git status beschreibt den aktuellen Arbeitsbaum, während git reflog lokale Referenzbewegungen dokumentiert. Beide Perspektiven ersetzen keine Agentenprotokollierung, ergänzen sie aber um überprüfbare Zustände. Siehe dazu die offizielle Dokumentation zu git status und zum Git-Reflog.

Muse Code nach einem Absturz sicher wiederherstellen

Bei der Wiederherstellung nach einem Muse-Code-Absturz geht es nicht um einen einzigen Reparaturbefehl. Entscheidend ist, welche Komponente tatsächlich ausgefallen ist.

1. Terminal getrennt, Prozess wahrscheinlich aktiv

Bei einer SSH-Unterbrechung kann der Prozess im Hintergrund weiterlaufen. Das prüfen wir zunächst über die Sitzungsverwaltung oder den Prozessstatus:

ps aux | grep -i muse
pgrep -af "muse|code"
git status --short

Beispielausgabe:

1842 muse-code --workspace /srv/app
 M src/auth/session.ts
?? .muse/checkpoints/

In diesem Fall sollte kein zweiter Muse-Code-Prozess gestartet werden. Eine doppelte Instanz kann denselben Arbeitsbaum gleichzeitig untersuchen oder verändern. Für lange entfernte Sitzungen sind tmux oder ein vergleichbarer Sitzungsmanager sinnvoll; die tmux-Dokumentation beschreibt das Wiederverbinden mit einer laufenden Shell-Sitzung.

2. Prozess beendet, Dateien aber vorhanden

Hier lesen wir das lokale Ereignisprotokoll bis zum letzten bestätigten Tool-Aufruf. Der relevante Punkt ist nicht die letzte Textnachricht des Modells, sondern der letzte Schritt, dessen Ergebnis als erfolgreich zurückgemeldet wurde.

Danach vergleichen wir:

git status --short
git diff --stat
git diff --name-only
find . -maxdepth 3 -type f \( -name '*checkpoint*' -o -name '*.tmp' \)

Ein vorhandener Diff ist kein Beweis für eine abgeschlossene Aufgabe. Er zeigt lediglich, dass Dateien verändert wurden. Wir müssen zusätzlich prüfen, ob die Änderung syntaktisch gültig ist und ob die Aufgabe den vorgesehenen Checkpoint erreicht hat.

3. Modellanfrage fehlgeschlagen, Tool möglicherweise erfolgreich

Das ist der gefährlichste Fall. Eine Netzwerk- oder API-Fehlermeldung kann nach dem Tool-Aufruf erscheinen. Der Agent interpretiert die fehlende Modellantwort dann als Fehlschlag und wiederholt die Aktion.

Die sichere Reihenfolge lautet:

1. Ereignisprotokoll öffnen.
2. Tool-Aufruf und Tool-Antwort suchen.
3. Ergebnis im Zielsystem prüfen.
4. Erst danach eine neue Agentenanweisung formulieren.

Die Meldung „keine Antwort erhalten“ darf nicht automatisch mit „keine Aktion ausgeführt“ gleichgesetzt werden.

Warum wiederholt Muse Code Werkzeuge?

Die Wiederholung von Werkzeugen lässt sich meistens auf eine fehlende Zustandsbestätigung zurückführen. Ein Agent arbeitet nicht wie eine Datenbanktransaktion. Zwischen Planung, Tool-Aufruf, Rückgabe und nächster Modellentscheidung können unterschiedliche Fehler entstehen.

Typische Ursachen sind:

• Das Tool schreibt die Änderung, aber die Antwort erreicht Muse Code nicht.
• Die Antwort wird protokolliert, aber ohne eindeutige externe Objekt-ID.
• Der Agent erhält nach dem Neustart nur den Auftrag, nicht den Nachweis des letzten Ergebnisses.
• Ein Commit oder eine Nachricht besitzt keine Idempotenzprüfung.
• Ein Hintergrund-Agent meldet einen alten Auftrag als aktuell.
• Eine manuelle Änderung verschiebt den Arbeitsbereich gegenüber dem Ereignisprotokoll.

Für externe Aktionen brauchen wir daher einen eindeutigen Schlüssel. Bei einem Commit kann das die erwartete Basis-Commit-ID sein. Bei einer Nachricht oder API-Anfrage sollte ein stabiler Idempotency-Key verwendet werden. Bei einem Deployment muss das Zielsystem den bereits angewendeten Vorgang erkennen können.

Beispiel für eine einfache lokale Sperre:

set -euo pipefail

key="muse-task-2026-08-12-auth-01"
lock=".muse/side-effects/${key}.done"

if [ -e "$lock" ]; then
  echo "Aktion bereits bestätigt: $key"
  exit 0
fi

./scripts/send-review-notification.sh
mkdir -p "$(dirname "$lock")"
printf '%s\n' "$(date -u +%FT%TZ)" > "$lock"

Dieses Muster ist kein Ersatz für eine transaktionale API. Es verhindert lediglich eine Wiederholung innerhalb desselben kontrollierten Arbeitsbereichs. Für produktive Systeme sollten wir zusätzlich die externe Antwort-ID, den Zielnamen und den Zeitpunkt speichern.

Nicht automatisch wiederholen sollten wir:

• das Veröffentlichen eines Releases,
• das Versenden von Kunden- oder Teamnachrichten,
• das Löschen von Ressourcen,
• Datenbankmigrationen ohne Rückwärtsstrategie,
• Zahlungen oder andere nicht widerrufbare Aktionen.

In diesen Fällen ist eine menschliche Freigabe erforderlich. Der Agent darf den Zustand prüfen und einen Vorschlag vorbereiten. Die endgültige Fortsetzung muss an eine eindeutig bestätigte Aktion gebunden sein.

Entscheidungshilfe für die sichere Fortsetzung

Verwenden Sie diese Prüfliste, bevor Sie einen unterbrochenen Lauf fortsetzen:

• [ ] Der alte Muse-Code-Prozess läuft nicht mehr oder wurde eindeutig als alleinige Instanz bestätigt.
• [ ] Der letzte Ereignisprotokolleintrag ist mit einer konkreten Tool-Antwort verknüpft.
• [ ] git status, Dateidiff und die im Protokoll genannten Dateien widersprechen sich nicht.
• [ ] Temporäre Dateien, generierte Artefakte und externe Systeme wurden geprüft.
• [ ] Keine Person und kein paralleler Agent hat denselben Arbeitsbaum zwischenzeitlich verändert.
• [ ] Jede externe Aktion besitzt eine bestätigte Ergebnis-ID oder eine nachweisbare Idempotenzprüfung.
• [ ] Der nächste Schritt ist reversibel oder durch eine verantwortliche Person freigegeben.
• [ ] Ein aktueller Checkpoint beschreibt Basis-Commit, Tests, offene Risiken und den nächsten Schritt.

Treffen Sie die Entscheidung anschließend nach diesen Bedingungen:

Fortsetzen, wenn alle Punkte erfüllt sind und die nächste Aktion keine unkontrollierbare Nebenwirkung auslöst.

Zurückrollen, wenn die Änderung eindeutig zum unterbrochenen Lauf gehört, aber Tests oder Tool-Ergebnisse fehlgeschlagen sind und ein verlässlicher Ausgangspunkt vorhanden ist.

Beenden, wenn eine externe Aktion möglicherweise doppelt ausgeführt wurde oder ihre Wirkung nicht eindeutig festgestellt werden kann.

Neu aufbauen, wenn Ereignisprotokoll, Arbeitsbereich und Basis-Commit nicht zusammenpassen oder mehrere Agenten denselben Zustand verändert haben.

Wenn auch nur ein sicherheitsrelevanter Punkt ungeklärt bleibt, ist „Fortsetzen“ nicht die Standardoption. In diesem Fall sichern wir zuerst die Beweise und wechseln zu „Beenden“ oder „Neu aufbauen“.

Ereignisprotokoll und Arbeitsbereich: so erkennen Sie eine Zustandsabweichung

Eine Muse-Code-Wiederherstellung ist nur dann vertrauenswürdig, wenn Protokoll und Arbeitsbereich dieselbe Geschichte erzählen. Wir behandeln das Ereignisprotokoll deshalb als Beweiskette, nicht als absolute Wahrheit.

Prüfen Sie zunächst die Basis:

git rev-parse --show-toplevel
git branch --show-current
git rev-parse HEAD
git status --short
git diff --check

git diff --check findet unter anderem problematische Leerzeichen und Konfliktmarker. Die Funktion ist in der Git-Dokumentation zu diff --check beschrieben.

Danach teilen wir die Abweichung in vier Fälle ein:

Fall A: Protokoll und Git-Diff stimmen überein.
Die im Protokoll genannten Dateien wurden verändert, und die erwarteten Inhalte sind vorhanden. Fortsetzen ist möglich, wenn Tests und Nebenwirkungen ebenfalls geprüft wurden.

Fall B: Git-Diff enthält weniger Änderungen als das Protokoll.
Ein Schreibvorgang könnte fehlgeschlagen oder rückgängig gemacht worden sein. Nicht fortsetzen, bevor die fehlenden Dateien und der letzte Tool-Status geklärt sind.

Fall C: Git-Diff enthält zusätzliche Änderungen.
Möglicherweise hat eine Person, ein CI-Prozess oder ein paralleler Agent in denselben Arbeitsbaum geschrieben. Die zusätzliche Änderung muss einem Urheber und Zeitpunkt zugeordnet werden.

Fall D: Temporäre Dateien oder generierte Artefakte widersprechen dem Protokoll.
Das ist bei Build-Schritten relevant. Ein sauberer Git-Status beweist nicht, dass außerhalb des Repositorys keine Nebenwirkung aufgetreten ist. Prüfen Sie Cache-Verzeichnisse, Datenbanken, Container und erzeugte Pakete separat.

Wenn die Konsistenz nicht beweisbar ist, erstellen wir einen neuen Arbeitsbaum. Git unterstützt getrennte Arbeitsverzeichnisse mit git worktree:

git fetch --all --prune
git worktree add ../app-recovery origin/main
cd ../app-recovery
git status --short

Die Aufgabe wird anschließend aus einer dokumentierten Basis neu aufgebaut. Das kostet mehr Zeit als ein direkter Neustart, verhindert aber, dass unbekannte Altänderungen in den nächsten Lauf gelangen.

Veraltete Hintergrund-Agenten nicht direkt zusammenführen

Bei großen Repositories läuft häufig ein Teil der Aufgabe als Hintergrund-Agent: Tests, Dokumentationssuche, Abhängigkeitsanalyse oder eine Teilimplementierung. Wenn dieser Agent nicht antwortet, darf ein später eintreffendes Ergebnis nicht automatisch übernommen werden.

Wir prüfen mindestens:

• Aufgaben-ID,
• Startzeit und letzte Aktualisierung,
• zugrunde liegende Commit-ID,
• verwendete Konfigurations- oder Testversion,
• Referenzen auf Dateien und Zeilen,
• Ergebnisstatus und Fehlerausgabe.

Ein Ergebnis ist veraltet, wenn es auf einer anderen Basis als dem aktuellen Arbeitsbaum erstellt wurde. Das gilt auch dann, wenn der Text plausibel klingt. Vor einer Übernahme führen wir mindestens einen erneuten Diff- und Testlauf aus:

git diff --stat origin/main...HEAD
git status --short
./scripts/test-targeted.sh

Die konkrete Testdatei ist projektspezifisch. Wichtig ist die Reihenfolge: Basis prüfen, Änderung prüfen, Tests mit der aktuellen Basis wiederholen. Ein alter Agentenbericht dient als Hinweis, nicht als Freigabe.

Das gleiche Prinzip gilt für Muse Spark 1.2. Wenn sich Modell-, Tool- oder Kontextverhalten zwischen Versionen ändert, darf ein früheres Ergebnis nicht ohne erneute Prüfung als kompatibel gelten. Die Versionsnummer allein beweist keine Wiederherstellungsgenauigkeit. Wir dokumentieren deshalb Version, Repository-Basis und Testbedingungen im Checkpoint.

Lange Aufgaben mit Checkpoints absichern

Die Frage nach Checkpoints ist wichtiger als der perfekte Wiederaufnahmebefehl. Ein Checkpoint sollte nicht nur „Phase 2 fertig“ heißen. Er muss einen überprüfbaren Zustand beschreiben.

Ein belastbarer Checkpoint enthält:

• Ziel und Abgrenzung der Teilaufgabe,
• Basis-Commit,
• geänderte Dateien,
• ausgeführte Tests,
• offene Risiken,
• externe Aktionen mit Ergebnis-ID,
• erwarteten nächsten Schritt,
• Zeitpunkt und verwendete Muse-Code-Version.

Beispielstruktur:

.muse/checkpoints/2026-08-12-auth-01.md

# Checkpoint auth-01

Basis: 7f3c1ab
Geändert:
- src/auth/session.ts
- tests/auth/session.test.ts

Tests:
- targeted: bestanden
- integration: ausstehend

Externe Aktionen:
- keine

Nächster Schritt:
- Integrationstest ausführen, danach Review-Diff erzeugen

Sicherheitsbedingung:
- keine Nachricht versenden, bevor der Integrationstest bestätigt ist

Für sehr lange Aufgaben teilen wir die Arbeit nicht nur nach Dateien, sondern nach reversiblen Zuständen. Ein guter Schnitt ist beispielsweise „Analyse abgeschlossen“, „Patch geschrieben“, „gezielter Test bestanden“ und „externe Aktion freigegeben“. Dadurch lässt sich nach einer Unterbrechung ein kleiner Abschnitt erneut prüfen, ohne den gesamten Auftrag zu wiederholen.

Zusätzlich sollte jede Phase einen Abbruchpunkt besitzen. Wenn der Agent den erwarteten Checkpoint nicht schreiben kann, wird die Aufgabe angehalten. Ein fehlender Checkpoint ist ein Fehlerzustand, kein Grund, stillschweigend weiterzuarbeiten.

Wiederherstellung mit Beweisen statt mit Aufräumen

Nach einem Fehlschlag ist die Versuchung groß, temporäre Dateien, Protokolle und fehlgeschlagene Ausgaben zu löschen. Für die Ursachenanalyse ist das genau die falsche Reihenfolge.

Wir sichern mindestens:

mkdir -p recovery-evidence
git status --short > recovery-evidence/git-status.txt
git diff > recovery-evidence/worktree.diff
git log -10 --oneline > recovery-evidence/recent-commits.txt
date -u > recovery-evidence/captured-at.txt

Zusätzlich kopieren wir das relevante Ereignisprotokoll, Tool-Ausgaben und Fehlermeldungen. Zugangsdaten, Tokens und personenbezogene Daten müssen vor einer Weitergabe entfernt werden. Bei entfernten Mac-Umgebungen gehören außerdem Sitzungs-ID, Betriebssystemversion, Netzwerkunterbrechung und Nutzerfreigaben in den Untersuchungsbericht. Das unterstützt Datenschutzanforderungen nach DSGVO, ohne sensible Inhalte unkontrolliert zu verteilen.

Die Untersuchung sollte außerdem zwischen drei Zeitpunkten unterscheiden:

• Zeitpunkt des Modellauftrags,
• Zeitpunkt des Tool-Aufrufs,
• Zeitpunkt der beobachteten Nebenwirkung.

Wenn nur der erste Zeitpunkt bekannt ist, ist die Aktion nicht ausreichend bestätigt. Diese Unterscheidung verhindert, dass eine plausible Agentenantwort fälschlich als technische Quittung behandelt wird.

Für die langfristige Ausführung empfiehlt sich eine getrennte Protokollaufbewahrung. Git-Diffs zeigen Codeänderungen, aber keine vollständige Historie von Shell-Befehlen, API-Antworten oder Hintergrund-Agenten. Ein dedizierter Remote-Aufgabenleitfaden sollte deshalb Sitzungslebensdauer, Log-Aufbewahrung, SSH-Wiederverbindung und Zugriffskontrollen gemeinsam behandeln.

Der nüchterne Vergleich: vorhandene Umgebung oder gemieteter Mac?

Eine bestehende Windows-, Linux- oder unsauber geteilte Remote-Umgebung kann für kurze Tests ausreichen. Für lange Muse-Code-Läufe entstehen dort jedoch häufig vier konkrete Nachteile: Sitzungen werden durch lokale Netzabbrüche beendet, mehrere Agents teilen sich versehentlich denselben Arbeitsbaum, Logs liegen an verschiedenen Orten und Berechtigungen sind nach manuellen Änderungen schwer nachzuvollziehen.

Ein gemieteter Mac von leapmac ist nicht automatisch die beste Wahl. Für dauerhaft hohe Last, spezielle physische Schnittstellen oder eine langfristig amortisierte Eigeninstallation kann ein eigener Mac wirtschaftlicher und kontrollierbarer sein. Für zeitlich begrenzte Muse-Code-Tests bietet eine isolierte Umgebung jedoch einen praktischen Vorteil: Repository, Sitzungsprozess, Ereignisprotokoll und Checkpoints lassen sich von Anfang an getrennt aufsetzen.

Wir empfehlen deshalb keinen sofortigen Plattformwechsel. Führen Sie zuerst einen kurzen, absichtlich unterbrochenen Test in einer isolierten Umgebung durch. Wenn Wiederaufnahme, Log-Aufbewahrung und Arbeitsbaumprüfung zuverlässig funktionieren, kann ein gemieteter Mac für längere AI-Coding-Läufe die sauberere Betriebsoption sein. Die Entscheidung sollte auf nachgewiesener Wiederherstellbarkeit beruhen, nicht auf der Annahme, ein anderer Rechner löse automatisch ein Zustandsproblem.

Für den Test reicht eine kontrollierte Aufgabe mit einem bekannten Repository, einem reversiblen Patch und einer ausdrücklich simulierten Unterbrechung. Erst wenn der Lauf vier Ergebnisse sauber dokumentiert — Ereignisprotokoll, Git-Diff, Tool-Ausgabe und Wiederaufnahmeentscheidung — sollte daraus ein regulärer Remote-Betrieb werden.