kimal3 0.4.0 → 0.6.0

package/skill/en/commands/k3start.md

@@ -24,7 +24,7 @@ say so briefly and skip it — no filler.
 - Is there a status file (`NEXT-STEPS.md` or `ROADMAP.md`) — a small file in which the
   latest status and the next step are written down? Then read it.
 - **Where the status file lives and what it is called.** The project rule applies **only inside a workplace**: if a folder `projects/` or `projekte/` sits directly in a folder `workbench-…` or `werkbank-…` (both spellings occur, also mixed) and the session is in or under a folder in it, that **project folder** is the place. Name there: under `projects/` it is `NEXT-STEPS.md`, under `projekte/` `WEITER-HIER.md`. **Everywhere else** (starter package, your own repos, even a folder `~/projects/my-repo`) it stays as before: the file lives in the folder you started in; if one exists, use it; if one has to be created, it is called `NEXT-STEPS.md` — or `WEITER-HIER.md` if the folder was created in German. If both exist, ask which one applies and write to neither until you have the answer. **Which one applies (in a workplace):** if the project has one, the project's applies. Otherwise an existing workbench note (`workbench-…/NEXT-STEPS.md` or `werkbank-…/WEITER-HIER.md` from the old template) applies — you keep reading and maintaining it. If neither exists, it is created **in the project**. **Never create a new status file in the workbench.**
-- **Are you in the workbench itself (`workbench-…` or `werkbank-…`), not inside a project?** If its `CLAUDE.md` has the section “First session” (German: “Erste Sitzung”), follow **it** — it takes priority over everything below. If it isn't there (any more), show the projects in `projects/` or `projekte/` (without `example-capture-invoices` and `beispiel-rechnungen-erfassen`) with the **first status line** of each one's status file, or “no status file yet” if there is none; an existing workbench note (`NEXT-STEPS.md` or `WEITER-HIER.md`) goes above them. Recommend **one** of them and ask **one** question about it.
+- **Are you in the workbench itself (`workbench-…` or `werkbank-…`), not inside a project?** If its `CLAUDE.md` has the section “First session” (German: “Erste Sitzung”), follow **it** — it takes priority over everything below. If it isn't there (any more), show the projects in `projects/` or `projekte/` (without `example-capture-invoices` and `beispiel-rechnungen-erfassen`) with the **first status line** of each one's status file, or “no status file yet” if there is none; an existing workbench note (`NEXT-STEPS.md` or `WEITER-HIER.md`) goes above them. Recommend **one** of them and ask **one** question about it. If the person picks a project from the list or names a new task (then you first create the folder and status file in the project, never in the workbench), bring the session into the project folder: with `change_directory` (if it only appears as a name in your tool list, load it via the tool search) — and say first: “The Claude app will ask whether I may change the folder, and then whether you trust it — both are fine, click Allow each time. If you land in an empty conversation, type `/k3start` there; you will find this conversation again in the list on the left.” Without the tool, or if the person declines: give the exact project folder (not the workbench above it) — in the app “Choose folder” and pick that folder, in the terminal `/exit`, `cd '‹path›'`, `claude` — and then `/k3start`. For a new project, read `projects/CLAUDE.md` (German: `projekte/CLAUDE.md`) first: from now on it applies.
 - No status file? **First check whether there is a `.git` folder where the status file would live** (in a workplace the project folder, otherwise the folder you started in). If there is, this
   project keeps a version history, and `git log --oneline -10` plus `git status` show you the
   latest state.

package/zeigen/gemeinsam.py

@@ -0,0 +1,82 @@
+# Gemeinsame Teile von werkzeug.py und starter.py: Dateinamen, Umgebung des Aufnehmers, Musterliste der Fehlergruende,
+# JSON lesen/schreiben, Stopp einer Sitzung. Kein eigener Einstieg; laeuft mit dem Python des Aufnehmers.
+import json
+import os
+import re
+import time
+
+# Der Aufnehmer bekommt einen eigenen Unterordner, in den sonst niemand schreibt: Beim Abschliessen versiegelt er JEDE
+# Datei seines Ordners und prueft das Siegel danach nach. Lag unser Herzschlag (starter.json) mit darin, brach es
+# (`capture_seal_failed`, Lauf 1 am 21.10.); dasselbe droht jeder Datei, die wir dort schreiben. Bericht, Protokoll,
+# Abbruch-Datei, Zeitleiste und Bilder liegen deshalb eine Ebene hoeher.
+ROH = "roh"
+STARTER = "starter.json"
+PROTOKOLL = "aufnahme.log"
+ABBRECHEN = "abbrechen"
+ZUSTAND_AUFNEHMER = "capture-state.json"
+UMGEBUNG = {
+    "STOP_SEQUENCES": '[["o","a",".","s","t","o","p"]]',  # die Strg-Folge des Aufnehmers beendet sonst bei Strg+C (B1)
+    "RECORD_AUDIO_RETAIN_WAVEFORM": "true",
+    "PYTHONUNBUFFERED": "1",
+    "PYTHONUTF8": "1",
+}
+
+# Zwilling von GRUENDE in cli/src/zeigen-rechnung.ts -- gleiche Reihenfolge, gleiche Schalter (der Test vergleicht beide).
+GRUENDE = [
+    (re.compile(r"FFmpegUnavailableError|ffmpeg.*not found", re.IGNORECASE), "ffmpeg-fehlt"),
+    (re.compile(r"returned success without a non-empty output"), "pfad-zu-lang"),
+    (re.compile(r"PortAudio|No Default Input Device|sounddevice"), "kein-mikrofon"),
+    (re.compile(r"DesktopCaptureError|screen layout"), "bildschirm-gesperrt"),
+    (re.compile(r"did not become ready|did not start"), "startet-nicht"),
+]
+
+
+def fehler_grund(protokoll: str) -> str:
+    return next((code for muster, code in GRUENDE if muster.search(protokoll)), "unbekannt")
+
+
+def schreibe_json_atomar(pfad: str, daten: dict) -> None:
+    tmp = pfad + ".tmp"
+    with open(tmp, "w", encoding="utf-8") as f:
+        json.dump(daten, f)
+    for versuch in range(20):
+        try:
+            os.replace(tmp, pfad)
+            return
+        except PermissionError:  # Windows: ein Leser haelt die Datei gerade offen
+            if versuch == 19:
+                raise
+            time.sleep(0.05)
+
+
+def lies_json(pfad: str) -> dict | None:
+    try:
+        with open(pfad, encoding="utf-8") as f:
+            daten = json.load(f)
+    except (OSError, ValueError):
+        return None
+    return daten if isinstance(daten, dict) else None
+
+
+def lies_protokoll(ordner: str) -> str:
+    try:
+        with open(os.path.join(ordner, PROTOKOLL), encoding="utf-8", errors="replace") as f:
+            return f.read()
+    except OSError:
+        return ""
+
+
+def sauber(ordner: str) -> bool:
+    zustand = lies_json(os.path.join(ordner, ROH, ZUSTAND_AUFNEHMER)) or {}
+    return zustand.get("integrity_verified") is True and zustand.get("phase") == "complete"
+
+
+def _stoppe_sitzung(sitzung: str, timeout: float) -> None:
+    """Stoppt genau diese Sitzung und kehrt erst nach dem geprueften Abschluss zurueck; sonst eine Ausnahme. Laut
+    Aufnehmer (control.stop_recording) ist ein Stopp idempotent: ein zweiter, gleichzeitiger wartet auf denselben
+    Abschluss. Nach Ablauf von `timeout` schliesst der Aufnehmer trotzdem weiter ab -- nur die Antwort fehlt."""
+    if not sitzung:  # ohne Sitzung stoppt stop_recording die EINE laufende Aufnahme -- womoeglich eine fremde
+        raise ValueError("keine Sitzung")
+    from openadapt_capture.control import stop_recording  # erst nach chdir: der Aufnehmer liest beim Import eine .env
+
+    stop_recording(sitzung, timeout=timeout)

package/zeigen/starter.py

@@ -0,0 +1,163 @@
+# Starter hinter `werkzeug.py starten <konfig.json>`: haelt den Aufnehmer als eigenes Kind (versteckte Konsole), zieht die
+# Bremse nach der Frist, beendet ihn bei `abbrechen` und schreibt laufend starter.json mit Herzschlag `zuletzt`.
+# Von Node mit pythonw abgehaengt gestartet: keine Ausgabe. Einstieg bleibt werkzeug.py (Ruling R-12: eigene Datei).
+import os
+import re
+import subprocess
+import sys
+import threading
+import time
+
+from gemeinsam import (ABBRECHEN, PROTOKOLL, ROH, STARTER, UMGEBUNG, _stoppe_sitzung, fehler_grund, lies_protokoll,
+                       sauber, schreibe_json_atomar)
+
+TAKT_SEK = 2.0  # so oft schaut der Starter nach Sitzung, Abbruch und Frist (Wanduhr, nicht ein Zeitgeber ueber 15 Minuten)
+NACHTOETEN_SEK = 0.5  # Pause zwischen den ersten Versuchen, einen Prozessbaum zu beenden
+NACHTOETEN_VERSUCHE = 3  # danach meldet der Starter "nicht-beendet" und versucht es jeden Takt weiter
+# Video-Abschluss und eingebaute Spracherkennung nach 15 Minuten brauchen mehr als die Vorgabe 60 s. Der Starter
+# laeuft ohne Claudes 10-Minuten-Grenze; `kimal3 zeigen stopp` wartet kuerzer (werkzeug.STOPP_SEK) und meldet dann
+# "wird noch abgeschlossen".
+BREMSE_STOPP_SEK = 600
+AUFNEHMEN = "import sys; from openadapt_capture.cli import record; record(sys.argv[1], audio=True)"
+
+
+def _starte_kind(befehl: list, ordner: str, protokoll) -> subprocess.Popen:
+    # Eigene, VERSTECKTE Konsole: Sonst oeffnen python.exe, sein multiprocessing-Kind und FFmpeg je ein Fenster
+    # (gemessen 18.10.: detached + windowsHide allein reicht nicht; starter-probe.py).
+    si = subprocess.STARTUPINFO()
+    si.dwFlags |= subprocess.STARTF_USESHOWWINDOW
+    si.wShowWindow = 0  # SW_HIDE
+    return subprocess.Popen(befehl, cwd=ordner, env=dict(os.environ, **UMGEBUNG), stdout=protokoll,
+                            stderr=subprocess.STDOUT, startupinfo=si, creationflags=subprocess.CREATE_NEW_CONSOLE)
+
+
+def _beende_baum(kind: subprocess.Popen) -> bool:
+    """Beendet Kind samt Enkeln (multiprocessing, FFmpeg) und prueft, dass keiner mehr lebt."""
+    import psutil
+
+    try:
+        baum = [psutil.Process(kind.pid)]
+        baum += baum[0].children(recursive=True)
+    except psutil.NoSuchProcess:
+        baum = []
+    subprocess.run(["taskkill", "/PID", str(kind.pid), "/T", "/F"], capture_output=True,
+                   creationflags=subprocess.CREATE_NO_WINDOW)
+    _, lebend = psutil.wait_procs(baum, timeout=10)
+    for p in lebend:
+        try:
+            p.kill()
+        except psutil.NoSuchProcess:
+            pass
+    _, lebend = psutil.wait_procs(lebend, timeout=5)
+    try:
+        kind.wait(timeout=5)
+    except subprocess.TimeoutExpired:
+        return False
+    return not lebend
+
+
+def _mit_herzschlag(arbeit, melde):
+    """Fuehrt eine blockierende Arbeit (Stopp, Prozessbaum beenden) in einem Faden aus und schreibt waehrenddessen jeden
+    Takt `zuletzt` -- sonst haelt Node einen gesunden Starter, der gerade abschliesst, nach 10 s fuer tot."""
+    ergebnis = {}
+
+    def lauf():
+        try:
+            ergebnis["wert"] = arbeit()
+        except BaseException as fehler:
+            ergebnis["fehler"] = fehler
+
+    faden = threading.Thread(target=lauf, daemon=True)
+    faden.start()
+    while True:
+        faden.join(TAKT_SEK)
+        if not faden.is_alive():
+            break
+        melde()
+    if "fehler" in ergebnis:
+        raise ergebnis["fehler"]
+    return ergebnis.get("wert")
+
+
+def _warte_auf_kind(kind: subprocess.Popen, sekunden: float, melde) -> bool:
+    """Wartet in Takt-Scheiben mit Herzschlag; True, wenn das Kind in der Zeit geendet hat."""
+    ende = time.time() + sekunden
+    while kind.poll() is None and time.time() < ende:
+        try:
+            kind.wait(timeout=TAKT_SEK)
+        except subprocess.TimeoutExpired:
+            melde()
+    return kind.poll() is not None
+
+
+def _raeume_weg(kind: subprocess.Popen, melde) -> None:
+    """Kehrt erst zurueck, wenn der Baum nachweislich weg ist. Solange er lebt, bleibt der Starter da (Bremse bleibt
+    gezogen) und meldet `grund: nicht-beendet` -- nie einen Endzustand, waehrend noch etwas aufnimmt."""
+    versuch = 0
+    while not _mit_herzschlag(lambda: _beende_baum(kind), melde):
+        versuch += 1
+        if versuch < NACHTOETEN_VERSUCHE:
+            time.sleep(NACHTOETEN_SEK)
+            continue
+        melde(grund="nicht-beendet")
+        time.sleep(TAKT_SEK)
+
+
+def starte(konfig: dict, befehl: list | None = None) -> None:
+    ordner = konfig["ordner"]
+    gestartet = time.time()
+    bericht = {"zustand": "startet", "sitzung": None, "gestartet": gestartet,
+               "frist": gestartet + float(konfig["hoechstens_sek"]), "grund": None, "zuletzt": gestartet}
+    pfad = os.path.join(ordner, STARTER)
+
+    def melde(**felder):
+        # `zuletzt` ist der Herzschlag: Node haelt einen Starter, der vor <= 10 s schrieb, fuer lebendig (Ruling R-3).
+        bericht.update(felder, zuletzt=time.time())
+        schreibe_json_atomar(pfad, bericht)
+
+    melde()
+    kind = None
+    try:
+        python = os.path.join(os.path.dirname(sys.executable), "python.exe")
+        roh = os.path.join(ordner, ROH)  # nur der Aufnehmer schreibt dort (gemeinsam.ROH)
+        os.makedirs(roh, exist_ok=True)
+        with open(os.path.join(ordner, PROTOKOLL), "w", encoding="utf-8") as protokoll:
+            kind = _starte_kind(befehl or [python, "-c", AUFNEHMEN, roh], roh, protokoll)
+        while True:
+            try:
+                kind.wait(timeout=TAKT_SEK)
+            except subprocess.TimeoutExpired:
+                pass
+            treffer = None if bericht["sitzung"] else re.search(r"Capture session: ([0-9a-f-]{36})", lies_protokoll(ordner))
+            melde(**({"zustand": "laeuft", "sitzung": treffer.group(1)} if treffer else {}))
+            if kind.poll() is not None:
+                return melde(**_ende(ordner, bericht["sitzung"], "gestoppt"))
+            if os.path.exists(os.path.join(ordner, ABBRECHEN)):
+                _raeume_weg(kind, melde)
+                return melde(zustand="abgebrochen", grund=None)
+            if time.time() >= bericht["frist"]:
+                if bericht["sitzung"] is None:
+                    _raeume_weg(kind, melde)
+                    return melde(zustand="fehlgeschlagen", grund=fehler_grund(lies_protokoll(ordner)))
+                try:
+                    _mit_herzschlag(lambda: _stoppe_sitzung(bericht.get("sitzung"), BREMSE_STOPP_SEK), melde)
+                except Exception:
+                    pass  # ob die Aufnahme sauber zu ist, sagt danach capture-state.json (_ende)
+                if not _warte_auf_kind(kind, 120, melde):
+                    _raeume_weg(kind, melde)
+                return melde(**_ende(ordner, bericht["sitzung"], "selbst-gestoppt"))
+    except Exception:
+        grund = "unbekannt"
+        if kind is not None and kind.poll() is None:
+            try:
+                _raeume_weg(kind, melde)
+            except Exception:
+                grund = "nicht-beendet"  # nicht nachgewiesen weg: Node sagt "kann ich nicht feststellen", nie "beendet"
+        melde(zustand="fehlgeschlagen", grund=grund)
+
+
+def _ende(ordner: str, sitzung: str | None, art: str) -> dict:
+    """Das Kind ist weg: sauber abgeschlossen -> `art`; mit Sitzung, aber nicht sauber -> abgebrochen; ohne -> fehlgeschlagen."""
+    if sitzung is not None and sauber(ordner):
+        return {"zustand": art, "grund": None}
+    return {"zustand": "abgebrochen" if sitzung else "fehlgeschlagen", "grund": fehler_grund(lies_protokoll(ordner))}

package/zeigen/werkzeug.py

@@ -0,0 +1,250 @@
+# Werkzeug hinter `kimal3 zeigen`: spricht mit dem Aufnehmer (openadapt-capture 1.3.0) ueber dessen Python-Funktionen,
+# nie ueber dessen Befehlszeile (Python Fire zerlegt dort Werte, Spec US-4). Laeuft mit dem Python des Aufnehmers.
+#
+#   werkzeug.py starten <konfig.json>   Starter mit Bremse (von Node mit pythonw abgehaengt gestartet, keine Ausgabe)
+#   werkzeug.py stoppen <ordner>        -> eine JSON-Zeile: Ergebnis und Zahlen
+#   werkzeug.py zustand <ordner|->      -> eine JSON-Zeile: aktive Sitzungen des Aufnehmers, Bericht des Starters
+#   werkzeug.py teile                   -> eine JSON-Zeile: was eingerichtet ist
+#   werkzeug.py zeitleiste <ordner> <de|en> [--ohne-getipptes]   -> schreibt zeitleiste.md, eine JSON-Zeile mit Zahlen
+#   werkzeug.py bild <ordner> <sekunden>                          -> bilder/<m-ss>.png, eine JSON-Zeile
+#   werkzeug.py modell-laden                                      -> eine JSON-Zeile (laedt large-v3-turbo, Netz)
+# Die drei letzten wohnen in zeitleiste.py (Ruling R-6); hier steht nur der Aufruf.
+# Der Starter wohnt in starter.py (Ruling R-12), was beide brauchen in gemeinsam.py; Einstieg bleibt diese Datei.
+#
+# 🔴 Keine Ausgabe enthaelt Inhalte aus der Aufnahme: Das Protokoll des Aufnehmers traegt Fenstertitel. Es wird nur nach
+# festen Mustern durchsucht (fehler_grund), nie zurueckgegeben -- auch nicht auf stderr, auch nicht im Fehlerfall.
+# Gedeckt von `npm run check:zeigen-python` (scripts/zeigen/test_werkzeug.py). Spec 2026-10-18-k3zeigen-design.md.
+import argparse
+import json
+import os
+import sqlite3
+import sys
+import time
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))  # Nachbardateien auch unter -I/-P, die den Ordner weglassen
+sys.dont_write_bytecode = True  # kein __pycache__ neben den Dateien: der Ordner geht so, wie er ist, ins npm-Paket
+from gemeinsam import (ABBRECHEN, ROH, STARTER, UMGEBUNG, ZUSTAND_AUFNEHMER, _stoppe_sitzung,  # noqa: E402
+                       fehler_grund, lies_json, lies_protokoll, sauber)
+from starter import starte  # noqa: E402
+
+WARTEN_SEK = 15.0  # so lange wartet `stoppen` nach dem Stopp auf einen Starter ohne frischen Herzschlag
+# Claude Code bricht einen Werkzeugaufruf nach 10 Minuten ab -- dann kaeme gar kein Satz. Deshalb endet `stoppen`
+# spaetestens nach STOPP_SEK + WARTEN_SEK (495 s) mit einer Antwort; schliesst der Aufnehmer dann noch ab, heisst sie
+# "wird-abgeschlossen". Node gibt dem Aufruf STOPPEN_MS (zeigen-umgebung.ts) als letztes Netz.
+STOPP_SEK = 480.0
+LEBENSZEICHEN_SEK = 10  # Zwilling von LEBENSZEICHEN_SEK in zeigen-rechnung.ts: so alt darf `zuletzt` hoechstens sein
+MODELL_REPO = "mobiuslabsgmbh/faster-whisper-large-v3-turbo"  # faster_whisper.utils._MODELS["large-v3-turbo"]
+
+
+def aufnahme_zahlen(ordner: str, ende: float | None = None) -> dict | None:
+    """Zahlen aus recording.db; None, wenn sie nicht lesbar ist. `ende` = Moment der Bremse (sonst letztes Ereignis)."""
+    pfad = os.path.join(ordner, ROH, "recording.db")
+    if not os.path.isfile(pfad):
+        return None
+    try:
+        db = sqlite3.connect(f"file:{pfad}?mode=ro", uri=True)
+        try:
+            start = float(db.execute("select min(timestamp) from recording").fetchone()[0])
+            klicks = db.execute("select count(*) from action_event where name = 'click'").fetchone()[0]
+            tasten = db.execute("select count(*) from action_event where name = 'press'").fetchone()[0]
+            ton = db.execute("select count(*) from audio_info where length(flac_data) > 0").fetchone()[0] > 0
+            letzte = db.execute("select max(timestamp) from action_event").fetchone()[0]
+        finally:
+            db.close()
+    except (sqlite3.Error, TypeError, ValueError):
+        return None
+    if ende is None and letzte is not None:
+        ende = float(letzte)
+    if ende is None:
+        ende = (lies_json(os.path.join(ordner, ROH, ZUSTAND_AUFNEHMER)) or {}).get("finalized_at")
+    dauer = max(0.0, float(ende) - start) if isinstance(ende, (int, float)) else 0.0
+    return {"dauer_sek": round(dauer, 2), "klicks": klicks, "tasten": tasten, "ton": ton}
+
+
+# --- Stoppen, Zustand, Teile -----------------------------------------------------------------------------------
+
+def _frisch(bericht: dict) -> bool:
+    zuletzt = bericht.get("zuletzt")
+    return isinstance(zuletzt, (int, float)) and time.time() - zuletzt <= LEBENSZEICHEN_SEK
+
+
+def _warte_auf_starter(ordner: str, solange: str, bis: float) -> dict:
+    """Wartet, solange der Starter `solange` meldet und lebt -- hoechstens bis `bis`. Ein Starter ohne frischen
+    Herzschlag schreibt nie mehr etwas und bekommt nur WARTEN_SEK; einer, der `nicht-beendet` meldet, gar keine."""
+    gnade = time.time() + WARTEN_SEK
+    bericht = lies_json(os.path.join(ordner, STARTER)) or {}
+    while (bericht.get("zustand") == solange and bericht.get("grund") != "nicht-beendet"
+           and time.time() < (bis if _frisch(bericht) else min(bis, gnade))):
+        time.sleep(0.25)
+        bericht = lies_json(os.path.join(ordner, STARTER)) or bericht
+    return bericht
+
+
+def stoppen(ordner: str) -> dict:
+    def antwort(ergebnis, grund=None, zahlen=None):
+        z = zahlen or {"dauer_sek": 0.0, "klicks": 0, "tasten": 0, "ton": False}
+        return {"ergebnis": ergebnis, **z, "grund": grund}
+
+    bis = time.time() + STOPP_SEK + WARTEN_SEK
+    bericht = lies_json(os.path.join(ordner, STARTER))
+    if bericht is None:
+        return antwort("keine")
+    if bericht.get("zustand") == "startet":  # noch keine Sitzung, die man stoppen koennte: Bremse ziehen
+        open(os.path.join(ordner, ABBRECHEN), "w").close()
+        bericht = _warte_auf_starter(ordner, "startet", bis)
+    if bericht.get("zustand") == "laeuft":
+        # Nach der Frist stoppt ein lebender Starter schon selbst (die Bremse): dann nur auf ihn warten. Ein zweiter
+        # Stopp fuehrte zum selben Abschluss, liefe aber gegen die eigene Uhr -- und meldete "nicht sauber" (Review).
+        # Der Stopp bekommt nur, was von `bis` uebrig ist: Hat das Warten auf "startet" schon Zeit verbraucht, kaeme
+        # `stoppen` sonst erst nach bis zu 495 + 480 s zurueck -- Node braeche bei 540 s ab, und es gaebe keinen Satz.
+        # Ist nichts mehr uebrig, wird nicht gestoppt: Die Bremse (`abbrechen`) liegt dann schon.
+        rest = min(STOPP_SEK, bis - time.time())
+        if rest > 0 and not (time.time() >= (bericht.get("frist") or float("inf")) and _frisch(bericht)):
+            try:
+                _stoppe_sitzung(bericht.get("sitzung"), rest)
+            except Exception:
+                pass  # ob die Aufnahme zu ist, sagen danach der Starter und capture-state.json
+        bericht = _warte_auf_starter(ordner, "laeuft", bis)
+    zustand = bericht.get("zustand")
+    if zustand in ("startet", "laeuft"):
+        # Der Starter hat kein Ende gemeldet. Lebt er und laeuft die Aufnahme, schliesst er noch ab. Steht er trotz
+        # Bremse noch in "startet" (oder meldet `nicht-beendet`), schliesst er nichts ab, sondern wird sie nicht los:
+        # dann "unklar". Ist er still, entscheidet die Liste des Aufnehmers -- im Zweifel nie ein Ergebnis, das wie ein
+        # Ende aussieht.
+        if _frisch(bericht):
+            abschluss = zustand == "laeuft" and bericht.get("grund") != "nicht-beendet"
+            return antwort("wird-abgeschlossen" if abschluss else "unklar")
+        aktive = _aktive_sitzungen()
+        if aktive is None or (bericht.get("sitzung") in aktive if zustand == "laeuft" else aktive):
+            return antwort("unklar")
+        if zustand == "startet":  # ohne Sitzung gibt es keine Aufnahme, die man abschliessen koennte
+            return antwort("abgebrochen", fehler_grund(lies_protokoll(ordner)), aufnahme_zahlen(ordner))
+    if zustand in ("abgebrochen", "fehlgeschlagen"):
+        return antwort("abgebrochen", bericht.get("grund") or fehler_grund(lies_protokoll(ordner)), aufnahme_zahlen(ordner))
+    if zustand not in ("gestoppt", "selbst-gestoppt", "laeuft"):  # "laeuft" = Starter still, Sitzung nicht mehr aktiv
+        return antwort("nicht-sauber", fehler_grund(lies_protokoll(ordner)), aufnahme_zahlen(ordner))
+    ergebnis = "selbst-gestoppt" if zustand == "selbst-gestoppt" else "gestoppt"
+    zahlen = aufnahme_zahlen(ordner, bericht.get("frist") if ergebnis == "selbst-gestoppt" else None)
+    if zahlen is None or not sauber(ordner):
+        return antwort("nicht-sauber", fehler_grund(lies_protokoll(ordner)), zahlen)
+    return antwort(ergebnis, None, zahlen)
+
+
+def _aktive_sitzungen() -> list | None:
+    try:
+        from openadapt_capture.control import discover_recorders  # nur lebende Prozesse, Steuerdateien des Aufnehmers
+
+        return [str(s) for s in discover_recorders()]
+    except Exception:
+        return None
+
+
+def zustand(ordner: str | None) -> dict:
+    return {"aktive_sitzungen": _aktive_sitzungen(),
+            "starter": lies_json(os.path.join(ordner, STARTER)) if ordner else None}
+
+
+def modell_da(cache: str) -> bool:
+    """large-v3-turbo vollstaendig im Hugging-Face-Zwischenspeicher? Ohne Netz: Groessen gegen den Dateibaum."""
+    repo = os.path.join(cache, "models--" + MODELL_REPO.replace("/", "--"))
+    try:
+        with open(os.path.join(repo, "refs", "main"), encoding="utf-8") as f:
+            stand = f.read().strip()
+    except OSError:
+        return False
+    snapshot = os.path.join(repo, "snapshots", stand)
+    baum = (lies_json(os.path.join(repo, "trees", stand + ".json")) or {}).get("files", {})
+    for name in ("config.json", "preprocessor_config.json", "model.bin", "tokenizer.json", "vocabulary.json"):
+        datei = os.path.join(snapshot, name)
+        if not os.path.isfile(datei):
+            return False
+        soll = (baum.get(name) or {}).get("size")
+        ist = os.path.getsize(datei)
+        if (isinstance(soll, int) and ist != soll) or (name == "model.bin" and ist == 0):
+            return False
+    return True
+
+
+def _hf_cache() -> str:
+    try:
+        from huggingface_hub import constants
+
+        return constants.HF_HUB_CACHE
+    except Exception:
+        return os.path.join(os.path.expanduser("~"), ".cache", "huggingface", "hub")
+
+
+def _ffmpeg_da() -> bool:
+    try:
+        from openadapt_capture.video import resolve_ffmpeg  # genau die Suche des Aufnehmers
+
+        resolve_ffmpeg()
+        return True
+    except Exception:
+        return False
+
+
+def teile() -> dict:
+    from importlib.metadata import PackageNotFoundError, version
+
+    try:
+        aufnehmer = version("openadapt-capture")
+    except PackageNotFoundError:
+        aufnehmer = None
+    return {"aufnehmer": aufnehmer, "ffmpeg": _ffmpeg_da(), "modell": modell_da(_hf_cache())}
+
+
+def main(argv: list) -> int:
+    parser = argparse.ArgumentParser(prog="werkzeug.py")
+    befehle = parser.add_subparsers(dest="befehl", required=True)
+    befehle.add_parser("starten").add_argument("konfig")
+    befehle.add_parser("stoppen").add_argument("ordner")
+    befehle.add_parser("zustand").add_argument("ordner")
+    befehle.add_parser("teile")
+    zl = befehle.add_parser("zeitleiste")
+    zl.add_argument("ordner")
+    zl.add_argument("sprache", choices=["de", "en"])
+    zl.add_argument("--ohne-getipptes", action="store_true")
+    bi = befehle.add_parser("bild")
+    bi.add_argument("ordner")
+    bi.add_argument("sekunden", type=float)
+    befehle.add_parser("modell-laden")
+    args = parser.parse_args(argv)
+    os.environ.update(UMGEBUNG)
+    try:
+        if args.befehl == "starten":
+            konfig = lies_json(args.konfig)
+            konfig["ordner"] = os.path.abspath(konfig["ordner"])  # vor chdir: ein relativer Pfad zeigte sonst ins Leere
+            os.chdir(konfig["ordner"])  # Arbeitsordner = Aufnahmeordner: nie eine fremde .env (Spec US-4)
+            starte(konfig)
+            return 0
+        ordner = getattr(args, "ordner", "-")
+        ordner = ordner if ordner == "-" else os.path.abspath(ordner)
+        fehlt = args.befehl in ("zeitleiste", "bild") and not os.path.isdir(ordner)  # zeitleiste.py meldet ordner-fehlt
+        os.chdir(os.path.dirname(os.path.abspath(__file__)) if ordner == "-" or fehlt else ordner)
+        if args.befehl == "stoppen":
+            daten = stoppen(ordner)
+        elif args.befehl == "zustand":
+            daten = zustand(None if ordner == "-" else ordner)
+        elif args.befehl in ("zeitleiste", "bild", "modell-laden"):
+            import zeitleiste
+
+            if args.befehl == "zeitleiste":
+                daten = zeitleiste.auswerten(ordner, args.sprache, args.ohne_getipptes, lambda: modell_da(_hf_cache()))
+            elif args.befehl == "bild":
+                daten = zeitleiste.bild(ordner, args.sekunden)
+            else:
+                daten = zeitleiste.modell_laden(lambda: modell_da(_hf_cache()))
+        else:
+            daten = teile()
+    except Exception as fehler:
+        # Fester Code statt Meldung: eine Meldung koennte einen Pfad oder eine Zeile des Aufnehmers tragen.
+        if sys.stderr is not None:  # unter pythonw (Starter) gibt es keinen stderr
+            sys.stderr.write(f"werkzeug-fehler:{type(fehler).__name__}\n")
+        return 1
+    sys.stdout.write(json.dumps(daten) + "\n")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))