ClawdDotNet/docs/Instanzmanager-Konzept.md

Instanzmanager — Befund und Konzept

Warum mehrere Instanzen heute nicht unabhängig voneinander laufen, und wie es stattdessen aussehen soll.

Stand: 2026-09-08. Anlass: Beim Instanzwechsel hat sich die Anwendung aufgehängt und wurde von Windows beendet. Vorhaben: #528, zugehöriger Fehler: #529.

Die Entscheidungen in Abschnitt 2 sind getroffen. Was danach kommt, folgt aus ihnen.

---

1 — Der Befund

1.1 Was passiert ist

Am 2026-09-08 wurde aus der laufenden Anwendung heraus eine zweite Instanz angelegt und auf sie gewechselt:

Zeit	Quelle	Eintrag
17:26:48	Dateisystem	Instance-Test2 angelegt
17:26:50	Lifetime.log	Application is shutting down...
17:26:55	Diagnostics.log	Zwei Ereignisströme beendet, 33 s und 776 s Laufzeit
17:27:45	Windows-Ereignisprotokoll	AppHangB1 — „hat aufgehört mit Windows zu interagieren und wurde geschlossen"

Die Anwendung wurde nicht beendet, sie wurde erschlagen. Bemerkenswert ist, was dabei nicht geschah: Zu diesem Prozess steht keine einzige Protokollzeile in den Instanzprotokollen — der Schreibpuffer wurde nie geleert. Keine Fehlermeldung, kein Bugtracker-Eintrag, kein Watchdog-Alarm. Der Vorfall ist ausschließlich rekonstruierbar, weil das Betriebssystem ihn festgehalten hat.

Das ist der Kern: Meldeweg, Watchdog und Fehler-Stream leben in dem Prozess, über dessen Zustand sie berichten sollen. Fällt er hart, fällt der Meldeweg mit — genau in dem Fall, der gemeldet werden müsste.

1.2 Was heute geteilt ist, obwohl es getrennt sein müsste

Geteilt	Wirkung	Beleg
Ein Protokollverzeichnis	Alle Instanzen schreiben in dieselben Dateien, ohne Kennzeichnung, welche spricht	Startup.log enthält abwechselnd Zeilen von Test und Test2
Eine Settings.json	Vier Stellen schreiben sie im laufenden Betrieb. Zwei Instanzen: die letzte gewinnt, stillschweigend	LicenseGate, MainWindowViewModel, AgentsPageViewModel, SettingsPageViewModel
Ein Sicherungsverzeichnis	Ein Ordner für alle Archive. Die Aufbewahrung räumt dort nach dem Präfix backup_<Instanzname>_ auf — und ein Präfix ist keine Grenze: backup_Test_2_….zip fängt mit backup_Test_ an, Test wirft es also weg	AppSettings.BackupDirectory
Ein Sicherungs-Schalter	Wer die tägliche Sicherung für eine Instanz einschaltet, schaltet sie für alle ein	AppSettings.AutoBackupEnabled
Ein Web-Port als Vorgabe	Jede Instanz bringt webServerPort: 7001 mit; die zweite kann nicht binden	InstanceConfig.WebServerPort

1.3 Der Wechsel kann gar nicht anders enden

Der Instanzmanager ist heute ein Fenster innerhalb einer laufenden Instanz. Wechseln heißt deshalb: Der Prozess fährt sich selbst herunter, startet sich mit --instance neu und beendet sich. Wer die Instanz wechselt, beendet zwangsläufig die, aus der heraus er es tut.

---

2 — Die Entscheidungen

Getroffen am 2026-09-08.

E-M1 — Der Weg zwischen Manager und Instanz

Entschieden: HTTP über einen Unix-Domain-Socket je Instanz, unter Windows über eine Named Pipe. Der Socket liegt im Instanzverzeichnis (<Instanz>/manager.sock), Rechte 0600.

Warum nicht TCP: Ports müssten verwaltet, vergeben und gegen Kollisionen gesichert werden — genau das Problem, an dem die heutige Vorbelegung 7001 scheitert. Ein Socket im Instanzverzeichnis braucht keine Vergabe, und die Zugriffsrechte stehen schon am Dateisystem.

Warum trotzdem HTTP darüber: Weil der Manager Anfragen an die Instanzen weiterleitet (E-M5). Bleibt das Protokoll HTTP, ist das Weiterleiten eine Weiterleitung und keine Übersetzung — und die bestehenden Endpunkte, DTOs und der Ereignisstrom aus #494 gelten unverändert weiter. Kestrel kann auf beidem hören, SocketsHttpHandler kann auf beidem verbinden.

E-M2 — Die Oberflächen

Entschieden: Jede Instanz behält ihr eigenes Desktop-Fenster, der Manager bekommt ein eigenes. Die Instanzfenster laufen im Hintergrund und werden beim Wechsel nach vorn geholt. Ein Wechsel ist damit kein Neustart mehr, sondern ein Fensterwechsel.

E-M3 — Lizenz

Entschieden: Die Lizenz liegt im Manager und wird dort geprüft. Instanzprozesse starten nicht ohne aktiven Manager. Eine Lizenz erlaubt beliebig viele Instanzen.

Folge: LicenseGate und LicenseWatch wandern aus dem Instanzprozess in den Manager. AppHost.Callbacks.License entfällt für Instanzen.

E-M4 — Einstellungen

Entschieden: Der Manager kennt nur das Nötigste, alles andere gehört der Instanz. Die Aufteilung steht in Abschnitt 6.

E-M5 — Die Weboberfläche

Entschieden: Eine Adresse, ein Zugang, alle Instanzen. Der Manager besitzt Port, Zugang und Rahmen. Anfragen zu Chat, Agenten, Aufgaben und Freigaben reicht er über E-M1 an die betroffene Instanz weiter.

Er leitet weiter, er implementiert nicht. Keine Fachlogik im Manager — die Weiterleitung kennt Kennungen und Pfade, sonst nichts.

E-M6 — Wenn der Manager ausfällt

Entschieden: Laufende Instanzen laufen weiter. Der neu gestartete Manager findet sie über eine Datei im Instanzverzeichnis wieder und übernimmt die Aufsicht.

Damit wird der Manager nicht zu dem Einzelpunkt, gegen den dieses ganze Vorhaben gebaut wird. Die Prüfung „gibt es einen Manager?" findet beim Start einer Instanz statt, nicht fortlaufend.

Ausnahme: Ein Lizenzwiderruf ist kein Ausfall, sondern ein Urteil. Erfährt der Manager davon, hält er die Instanzen an.

---

3 — Der Schnitt

┌──────────────────────────────────────────────────────────────┐
│  Instanzmanager  (ein Prozess je Maschine)                   │
│  · eigenes Fenster + die eine Weboberfläche                  │
│  · Instanzen anlegen, starten, anhalten, entfernen           │
│  · Aufsicht: lebt sie? stürzt sie wiederholt ab?             │
│  · Lizenz · Update · DC-Master-Token → Sub-Token je Instanz  │
│  · KEINE Datenbank. KEINE Fachlogik. KEINE Werkzeuge.        │
└──────┬───────────────────────────────────────────────────────┘
       │ manager.sock (HTTP über UDS / Named Pipe)
   ┌───┴────────┬────────────────┬───────────────┐
   ▼            ▼                ▼               ▼
┌────────┐  ┌────────┐      ┌────────┐    Fenster je Instanz
│Instanz │  │Instanz │      │Instanz │    (laufen im Hinter-
│  A     │  │  B     │      │  C     │     grund, kommen beim
│        │  │        │      │        │     Wechsel nach vorn)
│ Engine · Werkzeuge · Taskboard · Staging · state.db          │
│ eigenes Protokoll · eigenes Sub-Token · eigener Meldeweg     │
│ Telegram · Rocket.Chat · Mail · FTP — ausschliesslich hier   │
└────────┘  └────────┘      └────────┘

3.1 Der Manager hat keine Datenbank

Alles, was er braucht, liegt als JSON im Projektverzeichnis: die Instanzliste, seine drei Einstellungen, je Instanz eine kleine Zustandsdatei (läuft sie? seit wann? mit welcher Prozesskennung? wie oft zuletzt abgestürzt?).

state.db einer Instanz fasst er nicht an — die Datei gehört genau einem Prozess, und prozessübergreifend gilt die Schreibsperre von SqliteStorage nicht.

3.2 Werkzeuge laufen ausschließlich in der Instanz

Telegram, Rocket.Chat, Mail, FTP, Datenbank — alle Werkzeuge gehören der Instanz und nur ihr. Der Manager kennt sie nicht und spricht nie mit ihnen.

Das gilt auch für die Telegram-Anmeldung. Sie ist ein Rückruf in AppHost.Callbacks; mit E-M2 beantwortet ihn das eigene Fenster der Instanz. Über den Manager läuft davon nichts. (Eine frühere Fassung dieses Papiers hat den Rückruf als Beleg für Kopflosigkeit angeführt — das war missverständlich: Der Rückruf zeigt nur, dass die Anwendungsschicht ihre Umgebung nicht festschreibt.)

---

4 — Was der Manager protokolliert und meldet

Nur, was aus seiner Sicht relevant ist:

Ereignis	Protokoll	Ans Deploymentcenter
Instanz gestartet	ja	Zustandswechsel
Instanz geordnet beendet	ja	Zustandswechsel
Instanz abgestürzt	ja	Fehlermeldung stellvertretend
Instanz startet wiederholt neu	ja	Fehlermeldung
Instanz antwortet nicht mehr auf dem Socket	ja	Fehlermeldung
Lizenz ungültig, Update fehlgeschlagen	ja	Fehlermeldung

Was die Instanz betrifft, bleibt in der Instanz. Ein fehlgeschlagener Werkzeugaufruf, ein abgebrochener Agentenlauf, eine überschrittene Budgetgrenze — das protokolliert und meldet die Instanz selbst, mit ihrem eigenen Sub-Token. Der Manager sieht davon nichts und soll davon nichts sehen.

Der Fall aus 1.1 ist genau der, für den es den Manager gibt: Die Instanz kann nichts mehr sagen, also sagt er es an ihrer Stelle — mit Prozesskennung, Beendigungsgrund und dem Ausschnitt aus ihrem Protokoll, der noch auf der Platte liegt.

4.1 Jede Instanz meldet weiterhin selbst

Zwei Wege, mit Absicht:

• Die Instanz meldet, solange sie lebt — eigener Fehler-Stream, eigener Heartbeat, eigener Watchdog-Monitor. Das Deploymentcenter führt Instanzen bereits über source + instance als eigene Monitore.
• Der Manager meldet, was die Instanz nicht mehr melden kann.

Jeder Weg deckt den Ausfall des anderen ab. Ein Manager, der jede Meldung durchreicht, wäre der neue Einzelpunkt.

---

5 — Lizenz und Token

Der Manager hält das Master-Token, die Instanzen halten Sub-Token.

Das Verfahren ist gebaut: TokenProvisioner tauscht über POST /api/tokens/v1/provision das Master-Token gegen ein Sub-Token je Instanz, mit den Rechten watchdog:ping und bugtracker:report. Rechte lassen sich dabei nur einschränken, nie erweitern; jedes Sub-Token ist einzeln widerrufbar.

Zu tun bleibt der Umzug: Heute wird bei der Einrichtung provisioniert (setup.json, "source": "provision"), künftig beim Anlegen einer Instanz durch den Manager.

Achtung bei der Projektbindung. Seit SDK 2.8.1 erben Watchdog-Monitore das Projekt ihres Ping-Tokens; ein Monitor mit project_slug = NULL erzeugt Befunde im Scheinprojekt „default", und dc_findings(project_slug=…) liefert für eine laufende, meldende Instanz dann null Befunde. Die Sub-Token müssen also projektgebunden ausgestellt werden — sonst sieht die Aufsicht aus wie „nichts auffällig".

Wir stehen auf SDK 2.6.0, aktuell ist 2.8.2. #218 ist damit Voraussetzung, nicht Nacharbeit.

---

6 — Einstellungen: die Aufteilung

Der Manager (manager.json)

Feld	Warum es nicht in die Instanz kann
webUiPort, webUiBinding, webUiToken	Eine Weboberfläche für alle
licenseKey	E-M3: die Lizenz gilt der Installation
deploymentcenterUrl, deploymentcenterMasterToken	Aus ihm entstehen die Sub-Token
instancesDirectory	Wo die Instanzen liegen — das muss er wissen, bevor es eine gibt
updateChannel	Aktualisiert wird das Programm, nicht die Instanz

Mehr nicht. Farbschema, Teilerstellungen und Protokollstufe sind Werte einer Oberfläche und gehören zu der, die sie anzeigt.

Die Instanz (InstanceSettings.json)

Alles Übrige, und drei Felder ziehen aus den Anwendungseinstellungen dorthin um — sie waren nie anwendungsweit, sie sahen nur so aus:

Feld	Heute	Künftig
logDirectory	geteilt, alle Instanzen in denselben Dateien	<Instanz>/Logs, Vorbelegung
backupDirectory + backupKeepCount	geteilt, Präfixkollision bei ineinanderliegenden Namen	je Instanz
autoBackupEnabled + autoBackupTime	geteilt, ein Schalter für alle	je Instanz
webServerPort	je Instanz, Vorbelegung 7001, Kollision	entfällt — es gibt nur noch den Socket

autoBackupEnabled und autoBackupTime standen in der ersten Fassung dieser Tabelle nicht. Sie sind mitgegangen, weil die Hälfte eines Blocks zu verschieben eine Einstellungsseite hinterlässt, auf der zwei von vier Sicherungsfeldern für alle Instanzen gelten und zwei nur für eine — und weil ein Schalter, der die Sicherung für alle einschaltet, derselbe Fehler ist wie ein Ordner für alle.

deploymentcenterEnvironment bleibt bei der Instanz: Eine Maschine kann eine Produktions- und eine Testinstanz nebeneinander betreiben.

---

7 — Noch zu klären

Sicherungen im Manager — gebaut (2026-09-11, #530): verschlüsselt mit dem Lizenzschlüssel, auf Wunsch per FTP hinaus. Siehe Abschnitt 9.10.

Eine Sache ist daran aber schon entschieden: Zurückspielen heißt, in ein Instanzverzeichnis zu schreiben, und das darf ausschließlich bei inaktiver Instanz geschehen — sonst schreibt man unter einer offenen state.db das Dateisystem um. Reihenfolge, wenn es kommt: anhalten, zurückspielen, starten. Und nie ohne Rückfrage. Der Manager kann das inzwischen: Er kennt den Zustand jeder Instanz über ihren Socket und hält sie geordnet an.

Wie stellt eine Instanz fest, dass ein Manager da ist? — Entschieden (2026-09-10, #535): über eine Unterschrift, die der Manager beim Start mitgibt. Siehe Abschnitt 9.9.

Startet der Manager eine abgestürzte Instanz wieder? — Entschieden (2026-09-08): ja, aber nur, wenn die Instanz es verlangt. Der Schalter heißt „Autostart durch Manager" und steht in der Instanzdatei; siehe Abschnitt 9.7.

Was ist mit einer Instanz, die verstummt? — Entschieden (2026-09-10): Ja, der Manager darf sie abschießen — aber erst am Ende einer Leiter, und nie ohne Nachweis. Siehe Abschnitt 9.8.

Der Aufhänger aus 1.1 ist nicht geklärt (#529). Er verschwindet mit dem Umbau vermutlich von selbst, weil es den Selbst-Neustart nicht mehr gibt — aber „vermutlich" ist kein Befund. Zwei unbelegte Verdachtsmomente: BackupScheduler hat sechs await und kein einziges ConfigureAwait(false) und fängt sich damit den Oberflächenfaden ein; ShutdownRequested ist ein async void-Behandler.

---

8 — Was aus #494 wird

Die Weboberfläche ist nicht umsonst gebaut. Sie zerfällt in zwei Teile, die beide bleiben:

Teil	Wohin
Endpunkte, DTOs, Maskierung, Ereignisstrom	In die Instanz. Statt auf einem TCP-Port hört Kestrel auf dem Socket. Der Code bleibt, die Bindung ändert sich
wwwroot (Gemini), Anmeldung, Token, Rahmen	In den Manager. Dazu die Instanzauswahl und die Verwaltungsansichten
Weiterleitung /api/instanzen/{id}/… → Instanz	Neu im Manager

Der Ereignisstrom ist die eine Stelle, die wirklich neu gedacht werden muss: N Instanzen, ein Strom zum Browser. Der Manager hält je laufender Instanz eine Verbindung und führt sie zusammen, mit der Instanzkennung an jedem Ereignis.

---

9 — Reihenfolge

Stufe	Inhalt	Woran man es misst
1 ✔	Einstellungen und Protokolle je Instanz trennen (Abschnitt 6)	Zwei Instanzen gleichzeitig, keine schreibt der anderen ins Protokoll
2 ✔	Instanzprozess kopflos lauffähig, Kestrel auf dem Socket	Eine Instanz läuft ohne Fenster, der Socket antwortet
3 ◑	Manager: anlegen, starten, anhalten, Prozessaufsicht, Lizenz, Sub-Token	Eine Instanz abschießen — der Manager merkt es und meldet es
4 ◑	Weboberfläche zieht um, Weiterleitung, ein Ereignisstrom	Eine Adresse, ein Zugang, Wechsel ohne Neustart
5 ✔	Instanzfenster als eigener Prozess, Wechsel holt das Fenster nach vorn	Kein Neustart mehr beim Wechseln
6	Sicherungen im Manager (falls Abschnitt 7 dafür entscheidet)	Zurückspielen hält die Instanz an und startet sie wieder

Stufe 1 ist die, die man überspringen möchte und nicht überspringen darf. Solange alle Instanzen in dieselben Protokolldateien schreiben, ist jede Fehlersuche im Mehrinstanzbetrieb Ratearbeit — und genau in dieser Lage ist der Vorfall aus 1.1 entstanden.

9.1 Was Stufe 1 gebracht hat

Fünf Schlüssel sind aus AppSettings in InstanceSettings.json gewandert: logDirectory, backupDirectory, backupKeepCount, autoBackupEnabled, autoBackupTime. Leer heißt jetzt <Instanz>/Logs und <Instanz>/Backups; ein relativer Wert zählt weiterhin gegen das Instanzverzeichnis (#375).

Keine Übernahme der Altwerte, aber eine Ansage. Ein anwendungsweiter Pfad, in alle Instanzen kopiert, wäre wieder derselbe Ordner für alle. Stehen die Schlüssel noch in einer alten Settings.json, meldet SettingsManager.AbandonedKeys sie, und der Start protokolliert einmal, was nicht mehr gilt und wohin diese Instanz stattdessen schreibt. Beim nächsten Speichern verschwinden sie aus der Datei.

webServerPort bleibt vorerst stehen. Es entfällt erst mit Stufe 4, wenn der Manager den Port übernimmt — nicht schon, sobald Kestrel den Socket hat. Eine frühere Fassung dieses Absatzes sagte „mit Stufe 2"; das war falsch gerechnet: Solange es keinen Manager gibt, der die Weboberfläche trägt, hieße Wegnehmen, sie ersatzlos abzuschalten.

---

10 — Was das für Vorhandenes bedeutet

„Kern als Dienst, Oberfläche als Client" aus dem Roadmap-Rückstau wird überholt: Dort ging es um einen Kern und eine Oberfläche. Der dort notierte Auslöser — „lohnt sich, sobald der erste UI-Absturz eine Nacht Agentenarbeit kostet" — ist mit 1.1 eingetreten.

#214 (24/7-Betriebsform) sagt heute „Kein kopfloser Betrieb: Die Oberfläche läuft laut Zielbetrieb immer mit". Das gilt nach E-M2 in anderer Form: Der Manager läuft immer mit, die Instanzfenster laufen mit, aber eine Instanz kann ohne Fenster laufen.

#218 (SDK 2.6.0 → aktuell) wird Voraussetzung — siehe Abschnitt 5.

9.2 Was Stufe 2 gebracht hat

Kestrel hört auf dem Socket — <Instanz>/manager.sock unter Linux, unter Windows eine Named Pipe, deren Name aus einem Fingerabdruck des Instanzpfades entsteht (InstanceEndpoint). Zwei Instanzen bekommen zwangsläufig zwei Adressen, ohne dass jemand etwas vergeben müsste.

Der Socket ist immer da, auch ohne Weboberfläche. Er ist nicht Teil von #494, sondern die Steuerfläche der Instanz: webUiEnabled schaltet den TCP-Zugang, nicht den Socket. Was aus WebUiHost wurde, heißt deshalb jetzt InstanceHttpHost — ein Kestrel, zwei Zugänge.

Der Torwächter unterscheidet die Zugänge. Über TCP gilt Token-Pflicht, über den Socket nicht: Dort steht die Grenze am Dateisystem (0600 beziehungsweise CurrentUserOnly), und wer die Socketdatei öffnen darf, sieht ohnehin in das Verzeichnis, in dem alles liegt, was ein Token schützen würde. Woran die beiden auseinandergehalten werden, ist der Punkt, an dem ein Irrtum teuer wäre: Bei Socket-Verbindungen stehen in HttpContext.Connection keine IP-Adressen — daraus zu schließen „keine IP, also Socket" wäre eine Vermutung an der Stelle, an der ein Torwächter steht, und ließe im Zweifel eine TCP-Anfrage ohne Token durch. Der Socket-Zuhörer hängt deshalb jeder Verbindung selbst eine Marke an (LocalTransport); wo sie fehlt, gilt Token-Pflicht.

Ein belegter Port kostet nur noch die Weboberfläche. Vorher gab TryStart in dem Fall null zurück und die ganze HTTP-Fläche war weg. Das ist seit dem Socket die falsche Rangfolge: Ihn zu verlieren, weil eine zweite Instanz schon läuft, hieße die Instanz unerreichbar zu machen — in genau dem Fall, für den es den Manager gibt.

Kopfloser Betrieb über --headless --instance <Pfad>. Die Verzweigung sitzt in Program.Main vor BuildAvaloniaApp, damit auf einem Server ohne Bildschirmsitzung kein Fenstersystem angefasst wird. Gefragt wird nichts: Instanz aus dem Argument, Lizenz über NonInteractiveLicensePrompt, Telegram-Anmeldung aus.

Nachgemessen, nicht angenommen: Eine kopflose Instanz auf Instance-Test lief ohne Fenster, und eine rohe HTTP-Anfrage aus einem fremden Prozess (PowerShell, direkt auf die Pipe) bekam 200 OK auf /api/info — ohne Token.

Zwei Lücken, die offen bleiben. Die Socketdatei-Fälle (liegengebliebene Leiche, Aufräumen beim Beenden) sind unter Windows gegenstandslos und werden dort mit Begründung übersprungen — der Unix-Domain-Socket selbst ist auf der Entwicklungsmaschine also ungeprüft, obwohl er die Zielplattform ist. Und das geordnete Ende auf SIGTERM ließ sich hier nicht auslösen: Windows kennt das Signal für einen fensterlosen Prozess nicht. Beides gehört auf die Linux-Testmaschine.

9.3 Was Stufe 3 bisher gebracht hat

Die Aufsicht steht, Lizenz und Sub-Token fehlen noch. Neu ist das Projekt ClawdDotNet.Manager mit genau einem Projektverweis: ClawdDotNet.Core. Das ist keine Sparsamkeit, sondern die halbe Architektur — ClawdDotNet.App schleppt sechzehn Werkzeugprojekte hinter sich her, und „keine Werkzeuge im Manager" soll eine Eigenschaft des Bauplans sein und keine Absichtserklärung. Damit InstanceDirectoryManager von beiden Seiten erreichbar ist, ist er nach Core/Instances gezogen; dorthin gehört er ohnehin, denn er beschreibt, wie eine Instanz auf der Platte liegt.

Der Socket ist die Auskunftsquelle, nicht die Prozessliste. Das ist die eine Entscheidung, an der alles hängt. Die Prozessliste sagt, dass etwas da ist — sie sagt nicht, ob es noch arbeitet, und genau das war der Zustand aus 1.1: Die Anwendung stand einwandfrei in der Prozessliste, bis Windows sie als „reagiert nicht mehr" beendet hat. Ein Aufsichtsdurchgang fragt deshalb den Socket und kennt drei Antworten:

Socket	Prozess	Befund
antwortet	—	läuft
schweigt	ist weg	Absturz, mit Abschiedscode
schweigt	lebt	verstummt — nach genügend Fehlversuchen in Folge

Nicht beim ersten Aussetzer: Eine einzelne verpasste Antwort ist Alltag, und ein Alarm bei jedem Aussetzer ist nach einer Woche der Alarm, den niemand mehr liest.

Ein Start gilt erst, wenn die Instanz antwortet. Zwischen „der Prozess läuft" und „die Instanz läuft" liegen Datenbank, Agenten und Kestrel. Wer nur auf Process.Start wartet, hält eine Instanz für gestartet, die gleich an einer kaputten Konfiguration scheitert.

Angehalten wird durch Bitten, nicht durch Schießen. Neu auf der Instanzseite: POST /api/instanz/beenden, ausschließlich über den Socket — über TCP gibt es den Endpunkt nicht, auch mit gültigem Token nicht, und er antwortet dort mit 404 statt 403. Die Lebensdauer einer Instanz gehört dem Manager; eine Browsersitzung soll den Prozess, der sie bedient, nicht beenden können. Erst nach Ablauf der Frist wird hart beendet.

Wiederfinden nach einem Managerausfall (E-M6). Die Zustandsdatei <Instanz>/instance-state.json ist der Hinweis, der Socket ist der Beweis: Erst wird gefragt, wer da antwortet, und nur wenn dieselbe Instanzkennung zurückkommt, wird die Prozesskennung aus der Datei überhaupt angefasst. Andersherum — Prozess suchen, finden, für die eigene Instanz halten — führt nach einem Neustart der Maschine geradewegs dazu, ein fremdes Programm zu beaufsichtigen und beim Anhalten zu beenden. Startzeit und Prozesskennung zusammen entlarven eine wiederverwendete Nummer.

Selbsttätiger Neustart ist bewusst nicht gebaut. Die Abnahmebedingung lautet „merkt es und meldet es", und zum Neustarten trifft dieses Papier keine Entscheidung. Eine Instanz in einer Schleife wieder hochzufahren, die jedes Mal abstürzt, wäre die falsche Vorgabe für etwas, das niemand entschieden hat. Das ist eine offene Frage — siehe Abschnitt 7.

Das Register und die stellvertretende Meldung. InstanceRegistry hält je Instanz eine Aufsicht und hat zwei Zusagen, die beide aus E-M6 folgen: Beim Start wird übernommen, nicht gestartet — ein Manager, der beim Hochkommen alles hochfährt, was er findet, startet nach einem Neustart der Maschine auch das, was jemand mit Absicht angehalten hat. Und beim Beenden wird nichts beendet: Wer den Manager schließt, will den Manager schließen. Die einzige Ausnahme ist StopAllAsync — für einen Grund, der alle betrifft, und der heißt Lizenzwiderruf.

SupervisionReporter macht aus einem Befund eine Meldung im Bugtracker, stellvertretend: mit Prozesskennung, Abschiedscode und dem Ausschnitt aus dem Protokoll der Instanz, der noch auf der Platte liegt. Der Idempotenzschlüssel ist stabil je Instanz und Art — stürzt dieselbe Instanz wiederholt ab, zählt der Server hoch, statt den Bugtracker mit Zwillingen zu füllen; wiederholte Abstürze sind ein Befund und nicht ein Dutzend gleicher.

Ein leerer Protokollauszug ist die aussagekräftigste Zeile der Meldung. Genau das war der Zustand aus 1.1: Der Prozess wurde erschlagen, bevor sein Schreibpuffer geleert war, und hinterließ nichts. Die Meldung sagt das ausdrücklich, statt eine leere Stelle zu lassen.

manager.json trägt die acht Felder aus Abschnitt 6 und sonst nichts. Lizenzschlüssel, Master-Token und Web-Token liegen darin verschlüsselt und zur Laufzeit im Klartext — wie in den Anwendungseinstellungen, mit Absicht dieselbe Bauart. Unsinnige Aufsichtswerte (Abfragetakt 0, Alarm nach null Fehlversuchen) werden eingefangen: Die Datei lässt sich von Hand bearbeiten.

Ein Defekt, den erst die Tests gezeigt haben. Eine angehaltene Instanz erschien als Instance-Alpha statt Alpha — die Aufsicht kennt den Namen erst, wenn die Instanz einmal geantwortet hat, und eine angehaltene tut das nie. Genau diese Ansicht zeigt der Manager aber an. Das Register führt den Namen jetzt aus InstanceSettings.json mit.

Abnahme, mit echten Prozessen gemessen. Der Manager hat die Instanz Test in 0,7 s gestartet und über die Named Pipe identifiziert, die Zustandsdatei geschrieben (pid=54476, id=d68af6fd), dann wurde der Prozess von außen abgeschossen. Der nächste Durchgang meldete Crashed, Abschiedscode −1, meldenswert, und räumte die Zustandsdatei weg. Dazu 20 Tests gegen gesteuerte Prozesse — ein Absturz zum gewünschten Zeitpunkt und eine wiederverwendete Prozesskennung sind mit einem echten Programm nicht herzustellen.

Ein Hinweis zur Messumgebung. Die Abnahme lief über einen eigens gebauten Treiber außerhalb der Werkzeugumgebung. Ein Prozess, den ein Agentenwerkzeug hier startet, landet in einem Job-Objekt, das seine Kinder sofort mitnimmt; der Instanzprozess starb dadurch, bevor er die erste Protokollzeile schreiben konnte. Das ist ein Artefakt der Umgebung und keine Eigenschaft des Managers — aber es heißt, dass ein Abnahmetest dieser Art nicht in die gewöhnliche Testreihe gehört.

9.4 Lizenz und Sub-Token im Manager

Ein neues Projekt: ClawdDotNet.Licensing. LicenseGate, LicenseWatch, LicenseInfo und ILicensePrompt sind aus ClawdDotNet.App dorthin gezogen. Der Grund ist der Schnitt: Zwei Prozesse brauchen dieselbe Lizenzprüfung, und keiner von beiden darf den anderen kennen. In Core konnte es nicht landen — dann zöge jedes der sechzehn Werkzeugprojekte das Deploymentcenter-SDK mit.

Dabei ist die Kopplung an SettingsManager verschwunden: LicenseGate kennt jetzt nur ILicenseStore — Serveradresse lesen, Schlüssel lesen und schreiben, speichern. Die Anwendung führt ihn in Settings.json, der Manager in manager.json. Der Torwächter prüft Schlüssel; Dateien verwaltet er nicht. Die Anwendungsversion kommt als Parameter statt aus einem globalen Zugriff — diese Schicht weiß nicht, welche Anwendung sie benutzt.

ManagerCore ist die Klammer: eigene Einstellungen, Lizenz, Register, Meldeweg. Was darüber liegt — ein Fenster, die eine Weboberfläche für alle — setzt darauf auf.

• Ohne gültige Lizenz startet er keine Instanz. Laufende werden trotzdem in die Liste genommen: Man soll sie sehen — und anhalten können.
• Ein Widerruf hält alle an. Der einzige Fall, in dem der Manager das von sich aus tut. Ein Serverausfall gehört ausdrücklich nicht dazu; das SDK trennt Urteil und gescheiterten Versuch, und nur das Urteil kommt hier an. Sonst nähme ein Netzproblem sämtliche Installationen gleichzeitig mit.
• Ohne hinterlegte Lizenzprüfung sperrt er nichts. Sonst gäbe es eine Henne-Ei-Sperre, bevor überhaupt jemand einen Schlüssel eintragen kann.

Sub-Token je Instanz. Der Manager hält das Master-Token und tauscht es beim Anlegen einer Instanz gegen ein eigenes — watchdog:ping und bugtracker:report, einzeln widerrufbar. Beim Anlegen und nicht beim ersten Start, weil die Instanzdatei dann zweifelsfrei niemandem gehört; sie später zu schreiben, während der Instanzprozess läuft, hieße zwei Schreiber auf einer Datei. Für Instanzen, die es vor dem Manager schon gab, wird es vor dem Start nachgeholt.

Danach wird nachgefragt (whoami), ob das neue Token an ein Projekt gebunden ist — seit SDK 2.8.1 erbt ein Watchdog-Monitor das Projekt seines Ping-Tokens, und ohne Bindung landen die Befunde im Scheinprojekt „default". Ein fehlgeschlagener Tokenbezug hält die Instanz nicht auf: Monitoring, das nur bei perfekter Rechtelage läuft, ist genau dann still, wenn man es braucht.

Was noch fehlt, damit E-M3 vollständig ist: Die Instanzen prüfen die Lizenz weiterhin selbst. Das lässt sich erst abschalten, wenn eine Instanz feststellen kann, ob ein Manager da ist (Abschnitt 7) — vorher entstünde eine Fassung ganz ohne Durchsetzung. Bis dahin führen beide ihren eigenen Schlüssel.

Ein Testfehler, der zweimal derselbe war. In den Manager-Tests hatte ich die Antwort des Sockets hinterlegt, bevor der Manager hochfuhr — damit sagt man „diese Instanz läuft bereits", der Manager übernimmt sie (E-M6), der Starter wird nie angefasst, und der Test prüft etwas anderes, als er behauptet. Es gibt jetzt eine Hilfsmethode, die genau das ausschließt.

9.5 Was Stufe 4 gebracht hat

Den Managerprozess. ClawdDotNet.Instanzmanager ist eine Konsolenanwendung: Sie prüft die Lizenz, übernimmt, was läuft, hängt die Weboberfläche auf und wartet. Sie beendet beim Herunterfahren keine Instanz.

Zwei neue Projekte. ClawdDotNet.Manager.Web trägt die Weboberfläche — ohne jeden Verweis auf ClawdDotNet.Web, denn dort hängt App und daran sechzehn Werkzeugprojekte. ClawdDotNet.ManagerApp ist der Einstiegspunkt. wwwroot ist aus der Instanz in den Manager gezogen (Abschnitt 8).

Der Schnitt der HTTP-Fläche. Unter /api/verwaltung steht, was den Manager angeht: Instanzen auflisten, anlegen, starten, anhalten. Alles andere unter /api geht unverändert an eine Instanz — er leitet weiter, er implementiert nicht. Welche Instanz gemeint ist, sagt die Kopfzeile X-Instanz; läuft genau eine, ist sie gemeint, und laufen mehrere, wird nachgefragt statt geraten. Eine Anfrage an die falsche Instanz ist schlimmer als eine abgelehnte.

Der zusammengeführte Ereignisstrom. Der Manager hält je laufender Instanz eine Zuleitung und schreibt an jedes Ereignis, von wem es kommt (instanz, instanzName). Ergänzt statt verpackt: Ein Umschlag wäre einfacher gewesen, hätte aber jede Ansicht der Weboberfläche zum Umschreiben gezwungen.

Abnahme, gegen laufende Prozesse gemessen:

Geprüft	Ergebnis
/api/verwaltung/instanzen ohne Token	401
Oberfläche ohne Token	200 — die leere Hülle, wie vorgesehen
Instanz über den Manager starten	Running, PID 18104
/api/info durchgereicht	Antwort der Instanz (instanceId d68af6fd)
/api/status durchgereicht	503 der Instanz, unverfälscht
/events/logs	Zeilen der Instanz, mit "instanz":"Instance-Test" daran
Anhalten über den Manager	Stopped
Manager abgeschossen	Instanz läuft weiter (E-M6)
Manager neu gestartet	„1 Instanzen bekannt, 1 laufen bereits" — übernommen

Drei Defekte, die erst der Lauf gezeigt hat:

1. Der Manager hing an einer Konsolenabfrage. ConsoleLicensePrompt wartete auf eine Eingabe, die niemand geben konnte; die Weboberfläche kam nie hoch, und im Protokoll stand nichts davon, weil die Frage auf der Standardausgabe steht. Ein Test auf Console.IsInputRedirected reicht dafür nicht: Er beantwortet „ist die Eingabe umgeleitet", nicht „kann jemand antworten" — ein Prozess ganz ohne Konsole, der gefährlichste Fall, ist nicht umgeleitet. Der Manager fragt jetzt gar nicht; ein Schlüssel gehört in manager.json.
2. Eine unlesbare manager.json wurde stillschweigend durch Vorgaben ersetzt. Der Manager suchte dann im falschen Verzeichnis, hörte auf einem anderen Port und fragte nach einer Lizenz, die woanders stand — und nichts sagte, woran es lag. Es kostete eine halbe Stunde und einen fehlenden Backslash. LoadProblem meldet den Grund jetzt.
3. Der Instanzprozess erbte CLAWD_CONFIG_DIR vom Manager und legte sich im Konfigurationsverzeichnis des Managers eine eigene Settings.json an. Eine Umgebungsvariable vererbt sich, ein Argument nicht — deshalb nimmt der Manager sein Konfigurationsverzeichnis jetzt über --config. Für eine systemd-Unit ist das ohnehin der geradere Weg.

Was in Stufe 4 noch fehlt: Die Weboberfläche selbst kennt noch keine Instanzen — sie spricht /api/… an und bekommt die eine laufende. Instanzauswahl, X-Instanz und die Verwaltungsansicht sind Arbeit an wwwroot und gehören damit in Geminis Spur. Und webServerPort steht noch in der Instanz: Ihr TCP-Zugang ist erst überflüssig, wenn die Oberfläche im Manager vollständig ist.

9.6 Was Stufe 5 gebracht hat

Der Wechsel ist kein Neustart mehr. Vorher hieß „Instanz wechseln": Der laufende Prozess fährt sich herunter und startet sich mit einer anderen Instanz neu — wer wechselte, beendete zwangsläufig die Instanz, aus der heraus er es tat, und genau dabei hat sich die Anwendung am 2026-09-08 aufgehängt. Jetzt laufen alle, und es kommt eine nach vorn.

Die Instanz holt ihr Fenster selbst. Neu ist POST /api/instanz/fenster, wieder ausschließlich über den Socket. Der Manager kennt kein Fenstersystem und soll keines kennen; er bittet, und wer ein Fenster hat, holt es nach vorn. Kopflos läuft die Bitte ins Leere, und das ist die richtige Antwort. Das letzte Wort hat der Fenstermanager — Windows lässt einen Hintergrundprozess den Vordergrund nicht einfach an sich reißen; der kurze Ausflug über Topmost half im Versuch, unter Linux entscheidet der Fenstermanager. Mehr als bitten kann eine Anwendung nicht.

--managed schaltet den Wechsel im Instanzfenster ab. Der Manager gibt es jedem Instanzprozess mit; das Fenster gräut seinen Instanz-Schalter aus und erklärt auf Nachfrage, wo gewechselt wird. Zwei Schlösser an derselben Tür: Der Knopf ist aus, und der Weg dahinter prüft es noch einmal — hinter ihm wartet ein Selbst-Neustart.

instanceWindows in manager.json, vorbelegt auf true: Jede Instanz behält ihr Fenster (E-M2). Auf einer Maschine ohne Bildschirmsitzung gehört false hin.

Abnahme, an echten Fenstern gemessen:

Geprüft	Ergebnis
Instanz über den Manager gestartet	PID 18128, Fenstertitel „ClawdDotNet"
Befehlszeile	--managed --instance …
Fenster von außen minimiert	IsIconic = True
POST /instanzen/Instance-Test/fenster	„Fenster von 'Test' nach vorn geholt"
Danach	IsIconic = False, im Vordergrund
Prozess danach	PID 18128, unverändert — nichts neu gestartet

Die letzte Zeile ist die Abnahmebedingung: kein Neustart mehr beim Wechseln.

9.7 Autostart durch Manager

Entschieden am 2026-09-08. Der Schalter heißt autostartByManager und steht in InstanceSettings.json — bei der Instanz, nicht beim Manager.

Zwei Dinge in einem Schalter, weil es dieselbe Zusage ist: Der Manager startet diese Instanz, wenn er selbst hochkommt, und er startet sie wieder, wenn sie abstürzt. Ohne den Schalter rührt er nichts an — ein Manager, der nach einem Neustart der Maschine alles hochfährt, was er findet, startet auch das, was jemand mit Absicht angehalten hat. Ausgeschaltet vorbelegt.

Der Sicherungsautomat ist der eigentliche Inhalt. Wieder hochzufahren ist die einfache Hälfte; die schwierige ist zu erkennen, wann man es lassen muss. Nach drei Neustarts in zehn Minuten (maxRestartsInWindow, restartWindowMinutes in manager.json) setzt der Manager aus und meldet es. Die Instanz bleibt dann aus, bis jemand sie von Hand startet — und dieser Start räumt den Zähler ab, denn wer von Hand startet, hat entweder etwas geändert oder weiß, was er tut.

Das Zeitfenster wandert: Eine Instanz, die einmal im Monat abstürzt und wieder hochkommt, läuft nie in die Grenze — eine, die im Minutentakt fällt, sofort.

Warum der Schalter bei der Instanz steht und nicht beim Manager: Er ist eine Eigenschaft dieser Instanz. Und die Instanzdatei gehört dem Instanzprozess — sie vom Manager schreiben zu lassen, während die Instanz läuft, wären zwei Schreiber auf einer Datei. Der Manager liest den Schalter; geändert wird er auf der Einstellungsseite der Instanz.

Ein Defekt, den erst diese Tests gezeigt haben. StartAsync gab „läuft schon" zurück, wenn die Aufsicht die Instanz für laufend hielt — ohne nachzusehen. Zwischen zwei Aufsichtsdurchgängen liegen aber Sekunden, und in denen kann sie wegbrechen: Wer in dieser Lücke „starten" verlangte, bekam einen Erfolg, hinter dem nichts stand, und der nächste Durchgang meldete einen Absturz, den niemand mehr erwartete. Jetzt wird gefragt, bevor zugestimmt wird.

Und ein Testdouble, das die Wirklichkeit nicht abbildete. Der falsche Socket antwortete unabhängig davon, ob ein Prozess lief. Damit war jeder Testaufbau, der die Antwort vor dem Hochfahren hinterlegte, stillschweigend ein anderer Test als beabsichtigt — dem Manager sagt eine Antwort „diese Instanz läuft bereits", er übernimmt sie, und der Starter wird nie angefasst. Das ist mir dreimal passiert. Der falsche Socket hängt jetzt am falschen Starter: Er antwortet nur, wenn wirklich ein Prozess läuft.

---

11 — Übergabe an den Frontend-Agenten

Stand 2026-09-09. Der C#-Teil des Instanzmanagers ist fertig; was fehlt, ist die Oberfläche. Dieser Abschnitt ist die Übergabe dafür.

11.1 Der Auftrag, in einem Satz

Bringe der Weboberfläche bei, dass es mehrere Instanzen gibt — Vorhaben #531, alles in src/ClawdDotNet.Manager.Web/wwwroot/.

Heute spricht sie /api/… an und bekommt die eine laufende Instanz. Laufen zwei, antwortet der Manager mit HTTP 409 und der Bitte, die Kopfzeile X-Instanz zu setzen. Dann ist die Oberfläche unbedienbar — und das ist der einzige Punkt, der den Mehrinstanzbetrieb im Browser noch aufhält.

11.2 Die Grenze, und sie ist hart

Nicht anfassen	Warum
Jede .cs-Datei, überall	Dahinter stehen Prozessaufsicht, Lizenz, Token und die Weiterleitung. Ein Fehler dort beendet Instanzen oder lässt einen Absturz unbemerkt
*.csproj, ClawdDotNet.slnx, deploy/, NuGet.Config	Bauplan und Release-Strecke
docs/Roadmap.md zwischen den <!-- dc:roadmap -->-Markern	Erzeugte Kopie

Ein Griff nach C# ist kein Regelverstoß, sondern ein Befund: Er heißt, dass die API etwas nicht hergibt, was sie hergeben müsste. Dann melden (dc_report, Projekt clawddotnet) und an der Oberfläche weiterbauen — nicht selbst in den Kern greifen.

Zur Kontrolle vor jeder Abgabe: git status darf ausschließlich Dateien unter src/ClawdDotNet.Manager.Web/wwwroot/ zeigen.

11.3 Was sich seit dem WebUI-Leitfaden geändert hat

Der WebUI-Leitfaden gilt weiter für Stil, Sicherheit und Aufbau der Oberfläche. Vier Dinge darin sind überholt:

Damals	Heute
wwwroot liegt in src/ClawdDotNet.Web/	src/ClawdDotNet.Manager.Web/
Die Oberfläche läuft im Prozess der Instanz	Sie läuft im Instanzmanager, einem eigenen Prozess
http://127.0.0.1:7001, Token in InstanceSettings.json	webUiPort und webUiToken in manager.json (Vorgabe 7000)
Eine Instanz, ein /api	N Instanzen, der Manager leitet weiter

Der Rest des Leitfadens — kein innerHTML, kein Paketmanager, Token nur im sessionStorage, Farben aus app.css — gilt unverändert.

11.4 Die API, gegen die du baust

Was den Manager selbst angeht (wird nicht weitergeleitet):

Aufruf	Was er tut
GET /api/verwaltung/instanzen	Liste: { id, name, zustand, prozess, autostart }
POST /api/verwaltung/instanzen { "name": "…" }	Legt eine an
POST /api/verwaltung/instanzen/{id}/start	Startet sie
POST /api/verwaltung/instanzen/{id}/stop	Hält sie an
POST /api/verwaltung/instanzen/{id}/fenster	Holt ihr Desktop-Fenster nach vorn

id ist der Ordnername (Instance-Test). zustand ist einer von Unknown, Stopped, Running, Silent, Crashed.

Alles andere unter /api geht unverändert an eine Instanz — /api/info, /api/agents, /api/chat, /api/jobs, /api/tasks, /api/staging, /api/usage, /api/logs/modules. Die Übertragungstypen sind dieselben wie bisher; hier ändert sich nichts außer der Adressierung.

Welche Instanz gemeint ist, sagt die Kopfzeile X-Instanz mit der id. Fehlt sie: Läuft genau eine, ist sie gemeint. Laufen mehrere, kommt 409 mit einem erklärenden Text — dann muss die Oberfläche eine wählen lassen. Läuft keine, ebenfalls 409.

Der Ereignisstrom (/events, /events/logs) führt alle laufenden Instanzen zusammen. Jedes Ereignis hat zusätzlich instanz (die id) und instanzName. Die bisherigen Felder bleiben unverändert — vorhandene Ansichten funktionieren weiter, sie wissen nur noch nicht, von wem etwas kommt.

Antwortcodes, die eine eigene Behandlung verdienen:

Code	Bedeutung
401	Token fehlt oder taugt nicht → zurück zur Anmeldung (gibt es schon)
402	Ohne gültige Lizenz startet keine Instanz
409	Unklar, welche Instanz gemeint ist — oder eine Aktion passt nicht zum Zustand
502	Die Instanz antwortet nicht. Kein Fehler des Managers — sag das auch so

11.5 Reihenfolge

1. X-Instanz mitschicken. In modules/api.js gibt es genau eine Stelle, an der fetch aufgerufen wird — dort die Kopfzeile aus einer gewählten Instanz setzen. Beim Ereignisstrom geht das nicht (EventSource kann keine Kopfzeilen); dort ist es auch nicht nötig, der Manager führt ohnehin alle zusammen.
2. Instanzauswahl im Rahmen. Eine Liste aus /api/verwaltung/instanzen, die gewählte Instanz im sessionStorage neben dem Token. Zustand sichtbar machen — Silent und Crashed sind keine Nebensache, sondern der Grund, warum es den Manager gibt.
3. Verwaltungsansicht. Anlegen, starten, anhalten, Fenster nach vorn. Die Liste nach jeder Aktion neu holen; die Zustände ändern sich im Hintergrund.
4. Herkunft der Ereignisse zeigen. instanzName an Chat-, Schritt- und Protokollzeilen, damit in einem Fenster mit drei Instanzen erkennbar ist, wer spricht.

11.6 Zwei Fallen

Der Zustand ändert sich, ohne dass jemand klickt. Der Manager sieht alle paar Sekunden nach; eine Instanz kann abstürzen oder verstummen, während die Liste offen steht. Eine Ansicht, die nur beim Öffnen lädt, zeigt dann etwas Falsches — und zwar genau in dem Moment, für den es diese Ansicht gibt.

Der Manager beendet beim Schließen keine Instanz. Wer die Weboberfläche zumacht oder den Manager beendet, beendet nichts. Was läuft, läuft weiter, und der nächste Manager findet es wieder. Eine Oberfläche, die „Manager beenden" mit „alles beenden" beschriftet, sagt die Unwahrheit.

11.7 Wie du es ausprobierst

dotnet build

manager.json liegt unter %APPDATA%\ClawdDotNet\ (Windows) beziehungsweise ~/.config/clawddotnet/ (Linux, klein geschrieben wie in AppPaths); ein anderer Ort geht über --config <Verzeichnis>. Nötig sind mindestens webUiToken (≥ 20 Zeichen) und instanceExecutable, wenn Manager und Instanz nicht im selben Ausgabeordner liegen.

dotnet run --project src/ClawdDotNet.ManagerApp

Der Manager schreibt seine Adresse auf die Standardausgabe und protokolliert nach <Datenverzeichnis>/Logs/Manager/. Zum Prüfen mit zwei Instanzen: eine zweite über POST /api/verwaltung/instanzen anlegen, beide starten — dann muss die Oberfläche eine wählen lassen.

11.8 Was ausdrücklich liegen bleibt

Diese drei Punkte sind C# und warten auf den Kern-Agenten. Nicht anfangen:

1. webServerPort aus der Instanz entfernen. Erst sinnvoll, wenn 11.5 steht.
2. Lizenzprüfung aus der Instanz nehmen (E-M3 vollständig). Braucht vorher einen Handschlag, an dem eine Instanz erkennt, ob ein Manager da ist.
3. Verstummte Instanzen neu starten? Nicht entschieden — siehe Abschnitt 7.

9.8 Geordnetes Ende und Puls

Entschieden am 2026-09-10, aus zwei Befunden derselben Sitzung.

Der erste: Jedes Beenden war ein Abschneiden. TaskScanner.DisposeAsync bricht den laufenden Takt über sein Token ab — mitten in ProcessAsync, also nachdem eine Aufgabe beansprucht wurde und bevor CompleteClaimAsync sie wieder freigibt. Sie steht danach auf running und bleibt dort, bis das Lease abläuft. Ein Agentenlauf mitten im Werkzeugaufruf verlor seine Antwort ganz.

Der zweite, schlimmere: Der Manager konnte eine Instanz mit Fenster überhaupt nicht geordnet beenden. Control.ShutdownRequested war nur kopflos verdrahtet (HeadlessRun), nicht in der Avalonia-Anwendung — und ein Fenster ist die Vorgabe (InstanceWindows). Die Bitte über den Socket wurde angenommen, mit 202 beantwortet, und niemand hörte zu. Der Manager wartete seine Frist ab und schoss den Prozess dann jedes Mal ab. Das geordnete Ende gab es auf dem Papier.

Erst die Tür, dann warten

ShutdownCoordinator (in Core/Instances) schließt zuerst alle Arbeitsquellen und wartet danach, bis nichts mehr offen ist. Die Reihenfolge ist der ganze Trick: Andersherum beansprucht der Scanner im nächsten Takt die nächste Aufgabe, und die Zahl der offenen Arbeiten geht nie auf null.

Zwei Quellen sind angemeldet — Agentenläufe und Aufgaben. Beide können genau zweierlei: keine neue Arbeit mehr annehmen und sagen, wie viel noch läuft. Was daraus folgt, entscheidet der Koordinator. Die Frist (zwei Minuten) ist eine Zusage, keine Hoffnung: Danach endet die Instanz, ob fertig oder nicht — sonst hinge sie an einem Agentenlauf, der auf ein Modell wartet, das nicht antwortet. Was dann noch offen war, steht im Protokoll.

Beide Wege dorthin gibt es wirklich: Der Manager bittet über den Socket, und gleichzeitig kann jemand am Fenster auf das Kreuz klicken. Ein zweiter Aufruf wartet deshalb auf denselben Vorgang, statt einen neuen anzustoßen.

Der Puls

Der Manager fragte bisher /api/info und wusste danach nur, dass überhaupt jemand geantwortet hat. Das reicht, um „läuft" von „tot" zu unterscheiden — aber nicht für die beiden Fälle, die gleich aussehen und gegensätzlich zu behandeln sind: eine Instanz, die hängt, und eine, die gerade aufräumt. Die erste gehört nach einer Frist abgeschossen, die zweite in Ruhe gelassen.

GET /api/instanz/puls liegt hinter dem Socket-Gate, gehört also dem Manager allein, und nennt zusätzlich Phase und offene Arbeiten. Bewusst weiter gefragt und nicht gemeldet: Ein Puls, den die Instanz von sich aus schickt, fehlt genau dann, wenn sie hängt — und dann kann der Manager „hängt" nicht von „hat es vergessen" unterscheiden. Wer fragt, weiß, wann er keine Antwort bekommen hat.

Die Leiter

Stufe	Was passiert
3 Durchgänge ohne Antwort	Unresponsive, gemeldet. Vorher nicht — ein Agentenlauf, der die Maschine auslastet, ist kein Vorfall
sofort danach	Einmal über den Socket um ein Ende bitten. Ein Versuch, mehr nicht — wer eben auf demselben Socket geschwiegen hat, hört wahrscheinlich auch das nicht. Es kann ein einzelner hängender Endpunkt sein und nicht der ganze Prozess; gewartet wird auf die Uhr, nicht auf die Antwort
nach 30 s (silentKillGraceSeconds)	Der Prozess wird beendet — und der Vollzug abgewartet. Kill() ist eine Bitte an das Betriebssystem, keine vollzogene Tatsache
danach	Gemeldet als Absturz, nicht als geordnetes Ende. Gewollt hat es niemand — und nur so greift der Autostart
vor jedem Start	EnsureDeadAsync: Antwortet noch jemand auf dem Socket? Lebt das Prozesshandle noch? Solange ja, wird nicht gestartet

Antwortet die Instanz zwischendurch wieder, war es ein Aussetzer, und niemand wird abgeschossen (Recovered).

Der Fehlschluss, der hier begraben liegt

StopAsync brach seine Warteschleife ab, sobald der Socket nicht mehr antwortete, meldete „beendet" und gab true zurück — ohne den Prozess anzufassen. Bei einer verstummten Instanz ist der Socket aber von vornherein still: Der Aufruf meldete sofort Erfolg, der Prozess lief weiter, und der Neustart setzte einen zweiten auf dieselbe state.db.

Schweigen ist nur dann ein Todesnachweis, wenn es keinen anderen Zeugen gibt. Hält der Manager ein Prozesshandle und sagt das „lebt noch", dann lebt der Prozess — er antwortet bloß nicht mehr. Nur bei einer wiederaufgenommenen Instanz ohne Handle muss das Schweigen reichen, weil mehr nicht zu haben ist.

Und die Fristen greifen ineinander

Die Instanz gibt sich zwei Minuten zum Auslaufen, der Manager wartet bis zu fünf (maxDrainWaitSeconds), solange sie meldet, dass sie aufräumt. Wäre seine Frist kürzer, schösse er mitten in das Aufräumen hinein, um das er gerade gebeten hat. Und trotzdem endlich: Eine Instanz, die dauerhaft „ich räume noch auf" sagt, hängt genauso wie eine, die schweigt.

9.9 Der Handschlag: woran eine Instanz einen Manager erkennt

Behoben am 2026-09-10 (#535).

Das Loch. Mit E-M3 wanderte die Lizenzprüfung in den Manager: Eine geführte Instanz prüft nicht mehr selbst, weil der Manager es zentral getan hat. Woran sie „geführt" erkannte, war der Schalter --managed — und ein Schalter ist keine Erkennung. ClawdDotNet --managed startete eine Instanz ganz ohne Lizenzprüfung. Vor E-M3 gab es die Lücke nicht, weil jede Instanz selbst geprüft hat; sie ist mit der Zentralisierung entstanden.

Die Lösung. ManagerHandshake in Core/Instances. Der Manager unterschreibt Instanzverzeichnis und Ablaufzeitpunkt mit HMAC-SHA256; die Instanz rechnet dieselbe Unterschrift nach. An diese Stelle kommt der Manager nur, wenn seine Lizenzprüfung bestanden hat — ManagerCore.StartInstanceAsync weist vorher mit StartRefusal.NoLicense ab. Dass die Unterschrift existiert, ist der Beweis.

Vier Eigenschaften, und jede hat einen Grund:

	Warum
Gebunden an das Verzeichnis — und geprüft wird gegen das, in dem die Instanz tatsächlich läuft	Sonst unterschriebe man das Argument statt der Sache: Eine Unterschrift für Alpha ließe Beta starten, indem man beim Prüfen Alpha vorzeigt
Fünf Minuten gültig, Ablauf geht in die Unterschrift ein	Sonst höbe jemand eine Unterschrift auf und startete damit nächste Woche eine Instanz ohne Lizenz. Am Ablauf zu drehen bricht die Unterschrift
Über die Umgebung, nicht die Befehlszeile	Eine Befehlszeile steht in jeder Prozessliste — die Unterschrift wäre abzulesen und abzuschreiben
Ungültig heißt nicht geführt, nicht Abbruch	Dann prüft die Instanz ihre Lizenz eben selbst — der Weg von vor E-M3. Kein neuer Fehlerfall, sondern der alte. Wer eine Lizenz hat, merkt nichts

Was das aushält und was nicht — ausdrücklich. Der Schlüssel steht in der Quelldatei und liegt damit in jeder ausgelieferten Programmdatei; wer ihn sucht, findet ihn. Das ist die bewusste Abwägung und keine Nachlässigkeit: Es geht nicht darum, jemanden abzuwehren, der Werkzeuge und Willen mitbringt, sondern darum, dass der gewöhnliche Weg um die Lizenz herum verschlossen ist. Ein Schalter, den man in der Hilfe liest, ist etwas anderes als ein HMAC, den man nachbauen muss.

Abgenommen an echten Prozessen, nicht nur im Test — und die Unterschrift für den Positivfall wurde unabhängig in Python gerechnet, damit nicht der C#-Code sich selbst bestätigt:

Lauf	Ergebnis
--managed, keine Unterschrift	„Lizenz erforderlich" — kein Start
--managed + gültige Unterschrift	Instanz kommt hoch, meldet ihren Named Pipe
Unterschrift für ein anderes Verzeichnis	„Lizenz erforderlich"
Gültige Unterschrift, Ablauf hochgedreht	„Lizenz erforderlich"

9.10 Sicherungen: verschlüsselt mit dem Lizenzschlüssel

Entschieden am 2026-09-11, als bewusste Vereinfachung gegenüber dem Schlüsselbund aus #190.

Die Vorgabe. Eine Sicherung wird mit dem Lizenzschlüssel des Managers und einem festen Salt aus dem Code verschlüsselt. Beim Zurückspielen versucht der Manager den eigenen Schlüssel; passt er nicht, fragt ein Fenster nach dem Lizenzschlüssel der Quellinstallation. Die ganze Sicherung liegt als ein verschlüsseltes Archiv vor, auf Wunsch zusätzlich per FTP hinaus.

Warum das trägt. Der Lizenzschlüssel ist der eine Wert, den jede Installation ohnehin hat und den ihr Betreiber ohnehin kennt — und er liegt im Manager, nicht neben den Archiven. Damit fällt der Grund weg, aus dem die tägliche Sicherung bisher keine Zugangsdaten enthielt: Eine Passphrase hätte gespeichert werden müssen, und neben den Sicherungen abgelegt wäre sie wirkungslos gewesen. Jetzt reisen die Zugangsdaten mit, und eine Sicherung übersteht den Maschinenwechsel ohne Passphrase.

Zwei Abweichungen von der Vorgabe, beide erzwungen:

Vorgabe	Umgesetzt	Warum
RAR	nicht möglich	RAR zu schreiben braucht das lizenzpflichtige Programm des Herstellers
verschlüsseltes ZIP	eigener Behälter .clawdbak	.NET kann kein ZIP mit Kennwort schreiben, und das verbreitete ZipCrypto ist gebrochen. Weil der Schlüssel ohnehin abgeleitet wird, ließe sich ein solches ZIP auch mit 7-Zip nicht öffnen — die Verträglichkeit brächte nichts

Der Behälter: Kopf mit Kennung, Fassung und einer Schlüsselprobe; das Manifest als eigener Abschnitt; das ZIP in Stücken zu 1 MiB, jedes mit AES-256-GCM und eigener Nonce, das letzte mit Endmarke. Die Stückelung, weil AES-GCM in einem Zug alles im Speicher bräuchte. Das Manifest vorn, damit die Übersicht nicht jedes Archiv ganz entschlüsseln muss. Die Endmarke, damit ein abgeschnittenes Archiv auffällt. Und die Schlüsselprobe, damit „fremder Schlüssel" von „beschädigt" zu unterscheiden ist, bevor etwas angehalten wird.

Was das aushält und was nicht — ausdrücklich. Wer Lizenzschlüssel und Archiv hat, hat alle Zugangsdaten darin. Der Schlüssel ist dem Hersteller bekannt, und er gilt für alle Instanzen einer Installation. Das ist die Abwägung, nicht ein Versehen: Ein Archiv auf einem FTP-Server oder einem USB-Stick soll niemandem nützen, der es nur findet — aufhalten soll es nicht jemanden, der Schlüssel und Absicht mitbringt.

Die Reihenfolge beim Zurückspielen. Erst die Schlüsselprobe, dann das Anhalten. Wer anhält und danach merkt, dass der Schlüssel nicht passt, hat eine laufende Instanz für nichts gestoppt. Passt er nicht, antwortet der Endpunkt mit 422 und dem Code fremde_lizenz, und die Oberfläche öffnet das Fenster für den Schlüssel der Quelle. Groß- und Kleinschreibung und Leerzeichen spielen dabei keine Rolle — dort tippt ein Mensch einen fremden Schlüssel ab.

Geführte Instanzen sichern sich nicht mehr selbst. Nur der Manager hat den Lizenzschlüssel. Liefen beide, lägen jeden Tag zwei Archive im Ordner, eines davon unverschlüsselt und ohne Zugangsdaten. Die Einstellungen — Schalter, Uhrzeit, Aufbewahrung, Zielordner — bleiben in der InstanceSettings.json; der Manager liest sie. Einmal am Tag heißt dabei auch über einen Neustart des Managers hinweg: Eine Datei von heute, die nach der eingestellten Uhrzeit entstanden ist, gilt als erledigt.

Ohne Lizenzschlüssel im Manager wird nichts gesichert — nicht ersatzweise unverschlüsselt. Das steht beim Start als Warnung im Protokoll.

FTP. Hochgeladen wird unter einem vorläufigen Namen und erst danach umbenannt: Eine halbe Datei unter richtigem Namen würde beim Aufräumen als gültige Sicherung mitgezählt, während eine vollständige dafür gelöscht wird. Auf dem Server wird je Instanz aufgeräumt, sonst füllt ein automatischer Upload ihn, bis ausgerechnet die jüngste Sicherung scheitert. TLS wird genommen, wo der Server es anbietet, und lässt sich mit requireTls erzwingen; Zertifikate werden nicht geprüft, weil eigene FTP-Server meist selbstsignierte haben. Ein gescheiterter Upload lässt die lokale Sicherung stehen und steht in der Meldung. Das FTP-Kennwort liegt verschlüsselt in manager.json und geht nie an die Oberfläche zurück.

Ein Präfix ist keine Grenze. Welche Datei zu welcher Instanz gehört, entscheidet ein Zeitstempel unmittelbar nach dem Namen, nicht der Anfang des Namens. Sonst zählte Test die Archive von Test_2 mit und würfe beim Aufräumen fremde weg (siehe 1.2).

Und der Schlüsselbund aus #190? Er bleibt, verliert aber seine Rolle für Sicherungen: Dafür ist jetzt der Lizenzschlüssel da. Das Wiederherstellungsfach ist nur noch für den Fall nötig, dass eine laufende Installation ihr Maschinenfach verliert, ohne dass eine Sicherung im Spiel ist. Die Naht für #180 bleibt davon unberührt.

Nicht über die Oberfläche abgenommen. Behälter, Sicherungsdienst und der Rundlauf über einen Maschinenwechsel sind mit Tests belegt; der Weg durch die Weboberfläche — das Fenster für den fremden Schlüssel, der FTP-Upload gegen einen echten Server — noch nicht. Beides steht in #537.