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? Dafür spricht viel: Die gemeinsame Rotation aus 1.2 verschwände, und eine Sicherung ließe sich auch von einer Instanz ziehen, die gerade nicht läuft. Dagegen spricht eine Falle — eine Sicherung zurückzuspielen heißt, in ein Instanzverzeichnis zu schreiben, während die Instanz womöglich läuft. Das muss den Prozess erst anhalten, sonst schreibt man unter einer offenen state.db das Dateisystem um. Wenn es kommt, dann mit dieser Reihenfolge: anhalten, zurückspielen, starten — und nie ohne Rückfrage.

Wie stellt eine Instanz fest, dass ein Manager da ist? Vorschlag: Der Manager startet sie und gibt ihr den Socketpfad mit; die Instanz verbindet sich einmal zurück und beendet sich, wenn das nicht gelingt. Kein Selbstzweck-Handschlag, sondern die Prüfung aus E-M3.

Startet der Manager eine abgestürzte Instanz wieder? Bisher nicht — er merkt es und meldet es, mehr nicht. Dafür spricht, dass eine Instanz, die nachts um drei abstürzt, bis zum Morgen tot bleibt. Dagegen spricht die Schleife: Eine Instanz, die an einer kaputten Konfiguration scheitert, stürzt beim zehnten Versuch genauso ab wie beim ersten, und dann hat man statt einer toten Instanz eine tote Instanz und ein volles Protokoll. Wenn es kommt, dann mit Wartezeitverdopplung und einer Obergrenze, nach der er es sein lässt und das meldet.

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.