kimal3 0.4.0 → 0.5.0

package/skill/en/commands/k3show.md

@@ -0,0 +1,302 @@
+---
+description: Show a task instead of describing it — I record it and turn it into a plan
+---
+
+<!-- kimal3:erzeugt — this file is maintained by `kimal3 skill install` and
+     overwritten on every update. Your own changes will be lost; if you want
+     to keep them, copy the file under a different name. -->
+# Show
+
+> You do a task once on screen and say out loud what you are doing and why.
+> I record it, evaluate it on your computer and write a description of it into the
+> project — so that we can automate the task afterwards without you first having to write
+> it down as a requirement.
+
+Carry out the steps in order. Stay in the coaching tone: English, friendly, **one question at a
+time and always with a suggestion**, the why before the how, no prior knowledge assumed. The
+mechanics are done by the program (`kimal3 show …`); you lead the conversation with the person. How
+to deal with `kimal3`'s exit codes in general is in `~/.claude/skills/kimal3/SKILL.md`; here are only
+the cases of this command.
+
+## 🔴 Three rules for the whole conversation
+
+1. **Before the yes in step 10 you read nothing from the recording.** No `zeitleiste.md`, no
+   picture, no log, no other file from `material/aufnahmen/` — and you don't **search** there
+   either: no grep, no glob, no file search across the project that includes this folder. What
+   lies there only leaves the computer with the person's yes. You may read the output of
+   `kimal3 show …` — it contains only numbers, times and folder names.
+2. **Install nothing, record nothing, delete nothing without an explicit yes to exactly that
+   step.** You open a file from the recording for the person only in Notepad, and in a way that
+   your call returns at once: in Bash `cmd //c start "" notepad "<path>"`, in PowerShell
+   `Start-Process notepad -ArgumentList '"<path>"'`. A bare `notepad "<path>"` blocks until the
+   window is closed again. Never in an IDE or an editor that Claude Code is attached to (selected
+   lines end up in the conversation there by themselves).
+3. **A failure never looks like a success.** If a `kimal3 show …` doesn't end with `0`, say
+   honestly what its message says, and don't carry on as if it had worked.
+
+Every `kimal3 show …` runs **in the project folder** (step 3) — the program finds the recording
+through the folder it is started in. If a recording lies in another project, change into it first:
+the project folder is the part of the path before `material/aufnahmen/`.
+
+## 1. Arrive and look
+
+First run `kimal3 show status`. It only reads. **Don't** read the “Set up:” block out to the
+person — just note whether anything in it is missing (a line with “missing”, “can't be checked”,
+“I can't tell” or “(… is needed)” → step 4).
+
+| The output says | What you do |
+|---|---|
+| `kimal3 show` is Windows-only for now; the Mac follows. | Say exactly that, kindly: showing a task doesn't work on this computer yet, the Mac is coming. Offer that the person describes the task in words instead. The command ends here. |
+| “I can't tell whether a recording is running.” (exit code 1) | Say honestly that you can't tell right now. **Start nothing.** Offer to look again in a minute. |
+| “Running since 09:12 (3 minutes), folder `…`, stops at 09:27 at the latest.” | A recording from an earlier session is still running. If the folder is a full path outside this project, first change into its project folder. Then ask: “There's still a recording running from 09:12 — are you through with showing the task? Then I'll stop it now.” Yes → step 8. |
+| “Running (started in another session).” | A recording is running that this project can't match. Say so, **don't start a second one**, and suggest checking with `kimal3 show status` once it has ended. |
+| “No recording is running.” followed by “The last one (`…`) stopped by itself after 15 minutes.” | A recording is finished but probably not evaluated yet. **Don't silently start a new one over it.** Ask with a suggestion: “The recording from 09:12 stopped by itself after 15 minutes — shall I evaluate it, or would you rather show the task again? I'd evaluate it; whatever you did after the 15 minutes is then missing.” Evaluate → step 9 (the time is in the folder name, `…-0912`). Again → carry on here. |
+| “No recording is running.” followed by “The last one (`…`) broke off.” | Kindly: the last recording broke off in the middle — the person did nothing wrong. Offer to show the task again. |
+| “No recording is running.” | Carry on. |
+
+The last line says whether the folder is right — remember it for step 3:
+“Recordings go here: …” (right) · “Switch into a project first …” (the session is in the
+workbench) · “The project folder is nested too deeply for the recorder …” (the path is too long).
+
+If the session is in the workbench, say **that first**, in one sentence: the recording belongs in
+a project, and you'll suggest one in a moment. Then explain in at most five short sentences what
+happens, and ask **one** question:
+
+> “You show me the task once and talk while you do it. I record the screen, sound, clicks and
+> keys. It stays on your computer. Before I read any of it, I'll ask you. Which task do you want
+> to show me — in one sentence?”
+
+Until the person has answered, nothing is installed and nothing is recorded.
+
+## 2. The task in one sentence
+
+Wait for the answer. You take the person's sentence **unchanged** — it will stand at the top of
+the timeline, and exactly where it and the demonstration differ lies the most important follow-up
+question (step 11). A rough sentence is enough; don't dig.
+
+## 3. The right folder
+
+- **Recordings already go to the right place here?** Carry on with step 4.
+- **The session is in the workbench** (`workbench-…`): suggest a project with a short name from the
+  task — lower case, hyphens: “I'd create the project `projects/quote-list` for this — does that
+  work?” (if the folder in the workbench is called `projekte/`, then there). Only after the yes do
+  you create **only** `plan/` and `material/` in it, nothing in advance. From now on every
+  `kimal3 show …` runs in this project folder (e.g. `cd "<project folder>" && kimal3 show status`).
+  Check with `kimal3 show status` that the last line now says “Recordings go here: …”.
+- **The path is too deep:** name the number from the message and why (the recorder fails on long
+  paths). Suggest creating the project closer to the drive, and ask before you create anything.
+
+## 4. Setting up — only if something is missing
+
+If nothing is missing, skip this step without a word about it. If something is missing, say
+**exactly this first** and wait for the answer:
+
+> “For this I'll set up the recorder once — a free program that records screen, sound, clicks
+> and keys. About 2.1 GB, 10 to 20 minutes depending on your connection, only in your user
+> folder, no admin rights. Because it records keystrokes, your company's antivirus may flag it;
+> on a work computer, check with IT first if in doubt. Shall I?”
+
+- **Yes:** start `kimal3 show setup` **in the background** — it can take longer than the ten
+  minutes a command may run in the foreground. Say that it is running and the person can do
+  something else meanwhile. **Wait for the notice that it has finished** — don't check in between,
+  and don't sleep in a loop. After that:
+  - exit code `0` → `kimal3 show status`; if all four parts are there (uv, recorder, FFmpeg,
+    speech model), carry on with step 5.
+  - exit code `1` (“Step … didn't work.”) → name that step, and offer a ready-made
+    message to IT: **what** (uv from Astral · the recorder openadapt-capture 1.3.0, MIT licence,
+    with Python 3.12 · FFmpeg · the speech model large-v3-turbo from Hugging Face), **what for**
+    (showing a work task once on screen and evaluating it on the computer), **where from**
+    (astral.sh or winget, pypi.org, huggingface.co), **which folders** (only the user folder, no
+    admin rights).
+- **No:** “No problem — you can do it any time later with `/k3show`.” The command ends here.
+
+## 5. The briefing before the start
+
+Say these four points before anything records:
+
+1. **All screens** are recorded. Close anything that shows other people's data, switch on “Do
+   not disturb”, and not during a call. If you can, use a **test customer** instead of a real
+   one.
+2. **Don't type a password** — every key is recorded.
+3. Say out loud **why** you do something.
+4. When you're done, come back here and type **“done”**; the recording stops by itself after 15
+   minutes at the latest.
+
+Then: “Type ‘go’ when you're ready.” — and wait.
+
+- **A clear go** — “go”, “ready”, “start” — → step 6.
+- **A bare “ok” or “yes”** → ask once: “Shall I start now?”
+- **Anything else** → answer and say that it starts with “go”.
+
+**Nothing starts before the go.**
+
+## 6. Starting
+
+After the go: `kimal3 show start '<the person's sentence>'`. Pass the sentence as **one** argument,
+so that the shell changes nothing in it — in Bash in single quotes (a `'` inside as `'\''`), in
+PowerShell in single quotes (a `'` inside doubled). `--at-most` (1 to 15 minutes) only if the person
+explicitly wants it shorter.
+
+| The output says | What you do |
+|---|---|
+| “The recording is running (folder …), stops at … at the latest.” (exit code 0) | Say exactly: “Running. Show me — and type ‘done’ here when you're through.” **Then end your turn** — no further command, no checking. |
+| “A recording is already running (since 09:12, folder `…`).” · “A recording is already starting …” | No second one is created. Ask: “There's still a recording running from 09:12 — shall I stop it so that we can start again?” Yes → `kimal3 show stop` (step 8), then back to step 5. |
+| “A recording is already running (started in another session).” | Ask: “There's still a recording running from another session — shall I stop it so that we can start again?” Yes → `kimal3 show stop`; if it says it can't match it here, say so honestly and suggest waiting until it stops by itself (`kimal3 show status`). |
+| “I can't tell whether a recording is running — so I won't start a second one.” | Say it honestly, force nothing, look again later. |
+| “The recorder isn't set up yet: `kimal3 show setup`.” | Back to step 4. |
+| “The recording didn't start: <reason>. Log: …” | Name the reason. **Don't open the log** — it contains window titles. If “Whether the recorder is still running: `kimal3 show status`.” follows, run `kimal3 show status` and say what it reports. Offer another attempt. |
+| “Switch into a project first …” · “The project folder is nested too deeply …” | Back to step 3. |
+
+## 7. While recording
+
+If the person writes anything other than “done” (a question, a thought), answer briefly and end
+with: “The recording is still running — type ‘done’ when you're through.” Open nothing on the
+screen meanwhile (it would end up in the video) and don't stop the recording on your own.
+“done”, “finished”, “I'm through” and the like → step 8.
+
+## 8. Stopping
+
+First say: “I'm finishing the recording — that can take a minute, with a long recording several.”
+Otherwise the person sees nothing happen while it finishes.
+
+Then `kimal3 show stop` — with the **longest wait the tool allows (10 minutes)**: the recorder finishes
+the video, and with a long recording that takes a while; with the default of 2 minutes the call
+would break off in the middle. The program answers after a little over 8 minutes at the latest, so
+before the 10 minutes are up.
+
+| The output says | What you do |
+|---|---|
+| “Recording stopped: 1:33 minutes, 30 clicks, 49 keys, audio present.” | Repeat the numbers in one sentence, carry on with step 9. |
+| “The recording is still being finished — run `kimal3 show stop` again in a moment.” (exit code 1) | Say: “The recorder is still finishing the recording — I'll check again in a moment.” Then run `kimal3 show stop` again, again with the 10-minute wait. **Never** say “not closed cleanly”, and don't offer a new recording. |
+| “The recording stopped by itself after 15 minutes: …” (exit code 0) | Say: “The recording stopped by itself after 15 minutes — whatever you did after that isn't in it.” Carry on with step 9. |
+| “No recording is running.” | Check with `kimal3 show status`. If it says “The last one (`…`) stopped by itself after … minutes.”, carry on with step 9; otherwise say honestly that there is no recording. |
+| “I can't tell whether a recording is running.” | Say it honestly — **never** “stopped”. Offer to look again in a minute with `kimal3 show status`. |
+| “The recording wasn't closed cleanly: <reason>.” (exit code 1) | Name the reason and offer a new recording. |
+| “The recording broke off: <reason>. …” (exit code 1) | Kindly: the person did nothing wrong. Name the reason and offer a new recording. |
+| “The recording couldn't be stopped …” · “A recording is running that I can't match here …” | Run `kimal3 show status` and say honestly what it reports — **never** “stopped”. If the session is in the wrong folder, change into the recording's project. |
+
+## 9. Evaluating — on the person's computer
+
+`kimal3 show evaluate` (without a folder it takes the project's latest recording; the language of
+the speech recognition follows the account — `--language de` or `--language en` only if the person
+spoke the other language). This takes about as long as the recording:
+
+- **Recording up to about 3 minutes:** in the foreground, with the longest wait (10 minutes).
+- **Longer — and always when it stopped by itself after 15 minutes:** **in the background**, as
+  with the setup. Say that it takes about as long as the recording, and **wait for the notice that
+  it has finished** — no checking in between, no loop.
+
+| The output says | What you do |
+|---|---|
+| “Timeline ready: … File: `…`.” | Say the numbers in one sentence. Remember the path — **don't open the file**. Carry on with step 10. |
+| “I didn't recognise any speech — was the microphone muted or the wrong one selected?” | Ask exactly that and offer a new recording. |
+| “The recording has no audio track — without sound there's no timeline. A new recording helps.” | Offer a new recording. |
+| “I can't find a recording in this project (`material/aufnahmen/`).” | The session isn't in the recording's project: change into it (the part of the path before `material/aufnahmen/`, from `kimal3 show status` or the stop message) and evaluate again. |
+| “The recording folder doesn't exist: …” | Say honestly that the recording isn't (or is no longer) there. Check with `kimal3 show status`; otherwise offer a new recording. |
+| “The recorder isn't set up yet: `kimal3 show setup`.” | Back to step 4, then evaluate again. |
+| “The timeline wasn't created: <reason>.” | Name the reason; if the speech model is missing, back to step 4. |
+| “The recording is still running — first `kimal3 show stop`.” | Back to step 8. |
+
+## 10. Data protection — before you read
+
+First one question, and wait for the answer:
+
+> “Did the demonstration show real data about people — customer names, email addresses?”
+
+**Yes:** then the four questions from `context/security.md` (in the workplace above the workbench;
+in a German workplace `kontext/sicherheit.md`) come **now**, before reading — one at a time, each
+with a suggestion: which fields · where to (to Anthropic, the company behind Claude, data centres
+in the USA) · on what legal basis · can it be done more sparingly, e.g. once more with test
+customers. You write the answers to `results/data-protection-demonstration.md` (in a German
+workbench `ergebnisse/`). If the answer is “once more with test customers”, read nothing, suggest
+deleting this recording (step 13, the sentence **without** the plan), and start again at step 5.
+
+Then this question, word for word:
+
+> “For me to read the timeline, it goes to Anthropic: what you said, where you clicked (with the
+> names of the buttons and fields — these can contain names) and what you typed. Screenshots show
+> your whole screen — I'll only look at those where the text isn't enough, and ask you before
+> each one. Shall I open the file for you so you can look first? Agreed — or would you rather
+> leave out the typed parts?”
+
+- **“Open it”:** in Notepad, as in rule 2 (`cmd //c start "" notepad "<full path>"` or
+  `Start-Process`), with the full path to `zeitleiste.md` (the project folder plus the path from
+  step 9). The person reads it themselves; you don't read along. Then ask the question about
+  agreeing once more.
+- **“Without the typed parts”:** `kimal3 show evaluate --without-typed` — with the same
+  `--language` as the first time, if you set one, and with the same waiting rule as in step 9. The
+  timeline is rewritten, and typed text then stands as “[typed, left out]”. The person has agreed
+  to this version → step 11.
+- **Agreed:** → step 11.
+- **No:** read nothing. Say: “You can read the file yourself and describe the task to me — or I
+  delete the recording.”
+  - **The person describes it:** take the description, ask follow-up questions as in step 11,
+    point 4 (one at a time), and carry on with step 12 — plan and way to build it **from the
+    description**, without reading anything from the recording. Then step 13.
+  - **Delete:** step 13, the sentence **without** the plan.
+
+## 11. Read, retell, ask
+
+Now — and only now — you read `zeitleiste.md`, and only this file.
+
+1. **Retell the task:** in numbered steps, in the **person's words** (quote what was said), each
+   step with the time from the timeline (`0:26`).
+2. **Look for the contradictions, explicitly.** Three sources say something about the task: the
+   task sentence at the top of the timeline, what the person **says**, and what they **click and
+   type**. Go through the task sentence part by part (what, where to, to whom, when) and ask for
+   each part: does the demonstration show exactly that? Then check every spoken sentence against
+   the click next to it. Every place where two sources differ, you name in the retelling with ⚠️ —
+   for example: “You clicked ‘tomorrow’, but said ‘for the current day’ — which one applies?” or
+   “The task sentence says ‘into a channel’, but you showed a direct message — which one applies?”
+   *These places are exactly why showing reveals more than describing.*
+3. **Screenshots only one by one and only after asking.** If the text isn't enough at a point (a
+   click without a name, a sentence pointing at something visible), ask first: “At 0:26 the text
+   only says ‘…’. May I look at the screen at that point?” Yes → `kimal3 show picture 0:26`; it
+   reports “Picture: <path>”, and you look at **only this one** picture. No → ask what was to be
+   seen there.
+4. **Then ask — one question at a time, always with a suggestion:** first the contradictions, one
+   after the other. After that, what a single demonstration can never show: **how often and when**
+   (“I'd guess every Monday morning — is that right?”) · **what happens in an exception** (a
+   public holiday, an empty list, the system can't be reached) · **who the result goes to**.
+
+## 12. Write it into the plan and suggest a way to build it
+
+Write `plan/task-shown.md` with these parts:
+
+- **Goal** in one sentence
+- **The steps**, numbered
+- **Rules and exceptions** from the answers
+- **What is still open**
+- **Where it comes from:** demonstration of <date> (or: description of <date>, if nothing was
+  read)
+
+The plan carries the content **itself** and doesn't point to files in the recording — that is
+about to go. Typed text that looks like access data doesn't go into it.
+
+Then say how you **would build it**: through the programs' interfaces (fetching the data
+directly, sending the message directly), **not** by re-clicking the clicks — that way it doesn't
+break when a screen changes. The building doesn't happen here; it is the next step in the
+project, right away or in the next session with `/k3start`.
+
+## 13. Deleting the recording — only after a yes
+
+Measure the size of the recording folder and suggest, with the real values. If the task is in
+the plan (step 12):
+
+> “The recording is 12.9 MB and lies in `material/aufnahmen/2026-10-19-0912`. I'd delete it —
+> the description is in the plan, and the recording contains everything you typed. What I read
+> from it stays in the conversation history on this computer. Is that alright?”
+
+If the suggestion comes without a plan (no in step 10, or “once more with test customers”), leave
+out the part about the plan:
+
+> “The recording is 12.9 MB and lies in `material/aufnahmen/2026-10-19-0912`. I'd delete it —
+> the recording contains everything you typed. What I read from it stays in the conversation
+> history on this computer. Is that alright?”
+
+- **Yes:** delete **exactly this one** folder — not `material/aufnahmen/` as a whole, not the
+  `.gitignore` and `.ignore` next to it — and check that it is gone.
+- **No:** it stays. Say where, and that it doesn't end up in Git.
+
+Finally, in two sentences without jargon, what is now in the project, and **one** concrete next
+step.

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))}