feat: Sitzungsklammer in fault.log schliessen, Fehlerdiagnose dokumentieren

Die Startzeile allein sagt nur, dass der Prozess lief. Erst mit einer Endzeile
laesst sich der entscheidende Fall auseinanderhalten:

  Start + Ende            -> sauber beendet
  Start + Traceback       -> Python-Fehler, das Programm hat ihn gesehen
  Start und sonst nichts  -> Prozess hart abgeraeumt, KEIN Python-Fehler

Im Terminal sehen die letzten beiden Faelle gleich aus - Steuerzeichen-Muell
und sonst nichts. Ein Signalhandler hilft unter Windows nicht weiter: ein
Abbruch von aussen laeuft dort ueber TerminateProcess und liefert dem Ziel kein
abfangbares Signal. Die FEHLENDE Endzeile ist der einzige Beleg.

Die Endzeile haengt an atexit und ist damit an denselben Pfad gebunden wie ein
regulaeres Programmende. Belegt in beide Richtungen: bei sauberem Ende stehen
beide Zeilen da, bei hart abgeraeumtem Prozess nur die Startzeile.

Nebenbei den Typ von _fault_log praezisiert - object kennt weder write noch
flush, mypy hat das zu Recht bemaengelt.

Doku
----
Alle READMEs (deutsch und englisch) haben jetzt einen Abschnitt "Wenn etwas
schiefgeht": welche der beiden Dateien wofuer zustaendig ist, wie sich die drei
Faelle unterscheiden lassen und warum man unter Windows besser ueber run.ps1
startet.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: michaelblaess

README.de.md

@@ -300,6 +300,37 @@ ein Fehler beim Auslesen) führt zu Englisch.
 
 ---
 
+## Wenn etwas schiefgeht
+
+Stuerzt das Programm ab, landet der Bericht auf Platte statt nur im Terminal -
+zwei Dateien neben den Einstellungen, beide im Speicherort-Tab der
+Einstellungen verlinkt, sobald es sie gibt:
+
+| Datei | Wofuer |
+| --- | --- |
+| `last-crash.txt` | Python-Fehler samt Traceback. Wird geschrieben, **bevor** der Fehlerdialog laeuft - faellt dieser beim Neuaufbau selbst mit, waere der Bericht sonst verloren. |
+| `fault.log` | Alles darunter: native Speicherzugriffsfehler, Stack-Overflow, fataler Interpreter-Fehler. Solche Abstuerze laufen an Pythons Fehlerbehandlung vorbei. |
+
+Beide Dateien werden **angehaengt**, nicht ersetzt - ein zweiter Absturz
+verdeckt den ersten nicht.
+
+`fault.log` bekommt ausserdem je Programmlauf eine Start- und eine Endzeile.
+Damit ist ablesbar, was passiert ist:
+
+| Was in der Datei steht | Was es bedeutet |
+| --- | --- |
+| Start, Traceback, Ende | Python-Fehler, das Programm hat ihn gesehen |
+| Start, Ende | sauber beendet |
+| Start, dann nichts | Prozess hart abgeraeumt - **kein** Python-Fehler |
+
+Ein hart abgeraeumter Prozess und ein Absturz sehen im Terminal gleich aus.
+Erst die fehlende Endzeile trennt beide Faelle.
+
+Unter Windows startest Du das Programm am besten ueber `run.ps1`: das Skript
+setzt das Terminal auch dann wieder zurueck, wenn das Programm hart abstuerzt
+und selbst nichts mehr tun kann. Sonst bleibt die Maus-Erfassung aktiv, und
+jede Mausbewegung kippt Steuerzeichen in die Eingabezeile.
+
 ## Entwickler
 
 ### Setup

README.md

@@ -300,6 +300,37 @@ environment - German only for a demonstrably German-speaking environment, everyt
 
 ---
 
+## When something goes wrong
+
+If the program crashes, the report is written to disk instead of only to the
+terminal - two files next to the settings, both linked from the storage tab in
+the settings once they exist:
+
+| File | What for |
+| --- | --- |
+| `last-crash.txt` | Python errors including the traceback. Written **before** the error dialog runs - if that dialog dies during its own re-layout, the report would otherwise be lost. |
+| `fault.log` | Everything below that: native access violations, stack overflow, fatal interpreter errors. Such crashes bypass Python's error handling entirely. |
+
+Both files are **appended to**, not replaced - a second crash does not hide the
+first one.
+
+`fault.log` also gets a start and an end line per run, which makes the file
+readable at a glance:
+
+| What the file contains | What it means |
+| --- | --- |
+| start, traceback, end | Python error, the program saw it |
+| start, end | exited cleanly |
+| start, then nothing | process was killed - **not** a Python error |
+
+A killed process and a crash look identical in the terminal. Only the missing
+end line tells them apart.
+
+On Windows, prefer starting the program via `run.ps1`: the script restores the
+terminal even when the program crashes hard and can no longer do so itself.
+Otherwise mouse tracking stays on and every mouse move spills control
+characters into your prompt.
+
 ## Developers
 
 ### Setup

src/console_error_scanner/__main__.py

@@ -5,6 +5,7 @@
 import argparse
 import os
 import sys
+from typing import TextIO
 
 # Frozen-EXE Erkennung (PyInstaller UND Nuitka):
 # PLAYWRIGHT_BROWSERS_PATH muss gesetzt werden BEVOR playwright importiert wird,
@@ -20,7 +21,7 @@
 
 # Log-Handle offen halten, solange der Prozess laeuft - faulthandler schreibt
 # beim fatalen Signal direkt hinein. Ohne Referenz wuerde der GC es schliessen.
-_fault_log: object | None = None
+_fault_log: TextIO | None = None
 
 from console_error_scanner import __version__
 from console_error_scanner.i18n import SUPPORTED_LANGUAGES, load_locale
@@ -307,6 +308,7 @@ def _enable_faulthandler() -> None:
     allem darunter. Die Startzeile ist die zweite Haelfte der Diagnose: steht
     danach nichts weiter in der Datei, wurde der Prozess von aussen abgeraeumt.
     """
+    import atexit
     import contextlib
     import faulthandler
     from datetime import datetime
@@ -324,6 +326,8 @@ def _enable_faulthandler() -> None:
         _fault_log.write(f"\n===== Start {stamp} - v{__version__} =====\n")
         _fault_log.flush()
         faulthandler.enable(file=_fault_log, all_threads=True)
+        # Gegenstueck zur Startzeile - siehe _write_fault_end.
+        atexit.register(_write_fault_end)
 
 
 def _reset_mouse_tracking() -> None:
@@ -340,3 +344,27 @@ def _reset_mouse_tracking() -> None:
         return
     stream.write("[?1000l[?1002l[?1003l[?1006l[?1015l")
     stream.flush()
+
+
+def _write_fault_end() -> None:
+    """Schreibt die Endzeile der Sitzungsklammer (ueber atexit registriert).
+
+    Erst dieses Gegenstueck zur Startzeile macht die Datei aussagekraeftig:
+
+      Start + Ende            -> sauber beendet
+      Start + Traceback       -> Python-Fehler (der Handler hat ihn gesehen)
+      Start und sonst nichts  -> Prozess hart abgeraeumt
+
+    Unter Windows hilft ein Signalhandler dabei nicht: ein Abbruch von aussen
+    laeuft dort ueber TerminateProcess und liefert dem Ziel kein abfangbares
+    Signal. Die FEHLENDE Endzeile ist der einzige Beleg.
+    """
+    import contextlib
+    from datetime import datetime
+
+    if _fault_log is None:
+        return
+    with contextlib.suppress(Exception):
+        stamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+        _fault_log.write(f"===== Ende {stamp} =====\n")
+        _fault_log.flush()

tests/test_crash_log.py

@@ -61,3 +61,23 @@ def test_fault_log_start_line() -> None:
     assert erste_zeile.startswith("===== Start ")
     assert __version__ in erste_zeile
     assert faulthandler.is_enabled()
+
+
+def test_end_line_closes_the_session() -> None:
+    """Das Gegenstueck zur Startzeile - ohne sie ist die Datei nicht deutbar.
+
+    Steht nur eine Startzeile da, wurde der Prozess hart abgeraeumt; mit
+    Endzeile ist er sauber gelaufen. Genau diese Unterscheidung ist der Zweck.
+    """
+    from console_error_scanner.__main__ import _enable_faulthandler, _write_fault_end
+
+    _enable_faulthandler()
+    _write_fault_end()  # ruft sonst atexit auf
+    zeilen = (
+        (Path(settings_module.SETTINGS_FILE).parent / "fault.log")
+        .read_text(encoding="utf-8")
+        .strip()
+        .split("\n")
+    )
+    assert any(z.startswith("===== Start ") for z in zeilen)
+    assert any(z.startswith("===== Ende ") for z in zeilen)