kimal3 0.9.1 → 0.9.3

package/skill/en/commands/k3show.md

@@ -29,7 +29,8 @@ the cases of this command.
    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
+   window is closed again. On the Mac you open it in TextEdit: `open -e "<path>"` — that returns at
+   once. 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.
@@ -38,6 +39,10 @@ Every `kimal3 show …` runs **in the project folder** (step 3) — the program
 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/`.
 
+If Claude Code's sandbox is switched on, you run every `kimal3 show …` **outside the sandbox** (in
+the Bash tool with `dangerouslyDisableSandbox`): the program writes to `~/.kimal3` and `~/.local`,
+and that can fail inside the sandbox.
+
 ## 1. Arrive and look
 
 First run `kimal3 show status`. It only reads. **Don't** read the “Set up:” block out to the
@@ -46,7 +51,8 @@ person — just note whether anything in it is missing (a line with “missing
 
 | 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. |
+| “`kimal3 show` is available on Windows and the Mac.” (exit code 1) | Say exactly that, kindly: showing a task doesn't work on this computer, only on Windows and on the Mac. Offer that the person describes the task in words instead. The command ends here. |
+| “Recording needs macOS 13 or later — this Mac has macOS 12.” or, if the version can't be read, “Recording needs macOS 13 or later.” (exit code 1) | Say exactly that, kindly: on this Mac, showing a task only works with macOS 13 or later. 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. |
@@ -54,6 +60,29 @@ person — just note whether anything in it is missing (a line with “missing
 | “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. |
 
+**Only on the Mac** there is one more line before the last one: “Permissions go to: …”. That is how
+you know, for the whole conversation, that you are on a Mac. Remember the name after it (usually
+“Terminal”) — below it is called **<App>**.
+
+- **“Permissions go to: Claude (desktop app)”** → say this **first**, before anything else:
+
+  > “On the Mac, recording works reliably only from Terminal: in this app macOS sometimes doesn't
+  > ask for the permissions at all, and after every Claude update you'd have to grant them again.
+  > Shall I open Terminal for you in the right folder? There you type `claude` and then `/k3show` —
+  > that's a new conversation, just tell me the task there again. Or shall we try it here anyway?”
+
+  **Yes** → `open -a Terminal "<project folder>"` (if there is no project yet, the folder the session
+  is in right now). Say that Terminal is open now; the command ends here. **“Here anyway”** → carry
+  on as usual; <App> is then “Claude”.
+- **“Permissions go to: nobody — macOS can't grant permissions over SSH”** → say exactly that: over
+  a remote connection macOS can't grant the permissions for screen, keys and microphone. Suggest
+  opening a Terminal on the Mac itself and starting `claude` and `/k3show` there. The command ends
+  here.
+- **“Permissions go to: the app you started Claude from”** → ask **right here**, once, what the app
+  Claude runs in is called (suggestion: “Terminal?”), and use the answer as <App> — so the right name
+  is already in the announcement of step 4. Only after that comes the question about the task (one
+  question at a time).
+
 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).
@@ -90,28 +119,135 @@ question (step 11). A rough sentence is enough; don't dig.
 
 ## 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:
+If nothing is missing, skip this step without a word about it (on the Mac carry on with step 4b).
+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?”
 
+**On the Mac** you say this sentence instead, with <App> from step 1:
+
+> “For this I'll set up the recorder once — a free program that records screen, sound, clicks and
+> keys. About 2 GB, 10 to 20 minutes depending on your connection, only in your user folder. After
+> that you switch on four permissions for <App> in System Settings — I'll show you each one. macOS
+> asks for an admin password along the way (on your own Mac that's your login password), and <App>
+> restarts once. On a work Mac this often only works with IT. 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.
+    speech model), carry on with step 5 (on the Mac with step 4b).
   - 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,
+    message to IT (on the Mac the one below): **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.
 
+**The message to IT on the Mac:** **what** (uv from Astral, or via Homebrew if it is there · the
+recorder openadapt-capture 1.3.0, MIT licence, with Python 3.12 and the add-on
+pyobjc-framework-AVFoundation 12.2.2 · 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 Homebrew, pypi.org, github.com, huggingface.co), **which folders** (only the user
+folder) — and on top **the four permissions** under System Settings → Privacy & Security (Screen &
+System Audio Recording, Input Monitoring, Accessibility, Microphone), **for which app** (<App>), and
+that a standard account may not switch on two of them itself (Screen & System Audio Recording,
+Input Monitoring).
+
+## 4b. Permissions — only on the Mac
+
+On Windows you skip this step. On the Mac (the status has the line “Permissions go to …”) it comes
+**before every** briefing in step 5: without the four permissions the recorder records nothing
+useful. Run `kimal3 show check`.
+
+| The output says | What you do |
+|---|---|
+| “All four permissions for <App> are in place.” (exit code 0) | Carry on with step 5 without a word about it. |
+| “Permissions for <App>:” and below it, per permission, “in place”, “missing” or “can't tell” (exit code 1) | Not a failure, but the list of what is still missing → see below. Treat a line with “can't tell” like “missing”, but never call it “in place” or “missing” to the person. |
+| “I can't tell whether the permissions are in place.” (exit code 1) | Say honestly that you can't tell right now. Suggest going through the four switches anyway (below) — it can't do any harm. |
+| “The recorder isn't set up yet: `kimal3 show setup`.” | Back to step 4. |
+
+If “Permissions for” is followed only by “this app”, use as <App> the name the person gave you in
+step 1; if you don't have one yet, ask once now (suggestion: “Terminal?”).
+
+**If something is missing**, say once beforehand (if fewer than four are missing, say the number
+instead of “four”):
+
+> “I'll now show you four switches, one after another. If macOS offers ‘Quit & Reopen’ along the
+> way, click ‘Later’ until all four are on — then we restart once.”
+
+Then **for each missing permission**, in the order of the list, one after the other:
+
+1. **One sentence on what it is:**
+   Screen & System Audio Recording — so the recorder sees what happens on the screen · Input
+   Monitoring — so it can write down your clicks and keys · Accessibility — so it can read the names
+   of the buttons and fields you click · Microphone — so it hears what you say.
+2. `kimal3 show check --ask <permission>` (`screen`, `input`, `accessibility` or `microphone`) — with
+   this macOS puts <App> into the list for this permission. Say beforehand: for the microphone macOS
+   asks itself, click “Allow” there; if macOS shows a window for the others, any button in it is
+   fine — you'll open the page yourself in a moment. The output is the list again; read **only the
+   line of this permission** in it. If it says “in place” (often for the microphone after “Allow”),
+   it's done → the next one.
+3. `kimal3 show check --open <permission>` opens exactly this page of System Settings (“I opened
+   ‘…’ in System Settings.”). If it says “System Settings couldn't be opened.”, name the way by hand:
+   Apple menu → System Settings → Privacy & Security → the name of the permission.
+4. **The click path:** “In the list, switch on ‘<App>’.” For the first one, Screen & System Audio
+   Recording, more precisely: “in the **upper** section ‘Screen & System Audio Recording’, not under
+   ‘System Audio Recording Only’”. If <App> is missing from the list: “Click the plus at the bottom →
+   Applications → Utilities → Terminal” (for another app: Applications → <App>).
+   For **Screen & System Audio Recording** and **Input Monitoring** add: “macOS asks for an admin
+   password along the way — on your own Mac that's your login password.” If the person has none (work
+   Mac, standard account): offer the message to IT from step 4; the command ends here.
+5. Wait until the person says the switch is on. **Don't check now** — macOS often only reports a
+   new permission after the restart. Carry on with the next one.
+
+**Once all are on:** `kimal3 show check` again.
+
+- “All four permissions for <App> are in place.” → carry on with step 5.
+- Still “missing” (or “can't tell”) for a permission the person has switched on → **first the
+  restart** (below). Do **not** send them into the settings again.
+- “missing” for one you haven't gone through yet → back to it, point 1.
+
+### The restart
+
+**Beforehand**, put the way back into the clipboard — **always** with the folder in which **this
+Claude session was started** (“Primary working directory” in your environment), **never** the
+project folder, even if you are working there now: `claude --continue` only continues the
+conversation that began in exactly that folder.
+
+```bash
+printf '%s' "cd '<folder this Claude session was started in>' && claude --continue" | LC_CTYPE=UTF-8 pbcopy
+```
+
+(If the folder name contains a `'`, write it as `'\''`. `LC_CTYPE=UTF-8` keeps umlauts and other
+accented letters in the folder name intact.) **Also show** the same line `cd '…' && claude --continue`
+visibly in the chat, as its own code block — if pasting doesn't work, the person types it from
+there. Then say word for word:
+
+> “Now quit Terminal completely once: ⌘ + Q (or in the menu ‘Terminal → Quit Terminal’). If
+> Terminal asks whether to terminate running processes: ‘Terminate’. Then reopen Terminal (⌘ +
+> Space, type ‘Terminal’, Enter), paste with ⌘ + V and press Enter. I've already copied the command
+> for you — our conversation continues right here.”
+
+Add in the same message: “Then just type ‘continue’, and I'll check whether the permissions are in
+place now.” — in the **same** message as the sentence above: after the restart nothing new comes
+from you until the person writes something. If <App> isn't “Terminal”, put in its name. If Claude runs in the desktop app, this way
+doesn't fit: offer Terminal instead (sentence and `open -a Terminal` from step 1).
+
+When the person is back, check — **from the project folder**, like every `kimal3 show …`:
+`cd "<project folder>" && kimal3 show check`.
+
+- “All four permissions for <App> are in place.” → carry on with step 5.
+- Still “missing”: open exactly this page again (`--open`) and have them look whether the switch for
+  <App> is on. If it was off: have it switched on, then one more restart as above. If it was on: say
+  honestly that macOS doesn't accept the permission, and offer the message to IT from step 4. The
+  command ends here.
+
 ## 5. The briefing before the start
 
 Say these four points before anything records:
@@ -124,6 +260,11 @@ Say these four points before anything records:
 4. When you're done, come back here and type **“done”**; the recording stops by itself after 15
    minutes at the latest.
 
+**On the Mac** point 1 says, instead of “switch on ‘Do not disturb’”: “switch on the ‘Do Not
+Disturb’ Focus (Control Center → Focus)”. And a fifth point is added:
+
+5. If macOS asks midway whether <App> may keep recording: click ‘Allow’ and carry on.
+
 Then: “Type ‘go’ when you're ready.” — and wait.
 
 - **A clear go** — “go”, “ready”, “start” — → step 6.
@@ -146,6 +287,7 @@ explicitly wants it shorter.
 | “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: the … permission is missing — `kimal3 show check` shows what's missing. Log: …” | Name the permission. **Don't open the log.** Back to step 4b. |
 | “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. |
 
@@ -174,7 +316,7 @@ before the 10 minutes are up.
 | “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 broke off: <reason>. …” (exit code 1) | Kindly: the person did nothing wrong. Name the reason and offer a new recording (if the reason names a permission: step 4b first). |
 | “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
@@ -222,7 +364,7 @@ Then this question, word for word:
 > 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
+  `Start-Process`; on the Mac in TextEdit with `open -e "<full path>"`), 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

package/zeigen/gemeinsam.py

@@ -1,8 +1,11 @@
 # 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 contextlib
 import json
 import os
 import re
+import sys
+import threading
 import time
 
 # Der Aufnehmer bekommt einen eigenen Unterordner, in den sonst niemand schreibt: Beim Abschliessen versiegelt er JEDE
@@ -14,14 +17,30 @@ STARTER = "starter.json"
 PROTOKOLL = "aufnahme.log"
 ABBRECHEN = "abbrechen"
 ZUSTAND_AUFNEHMER = "capture-state.json"
-UMGEBUNG = {
+# Die Plattform, auf der dieses Python laeuft. Tests setzen sie (gemeinsam.PLATTFORM, starter.PLATTFORM); die Rechnungen
+# darunter nehmen sie als Parameter, damit beide Seiten ohne Mac pruefbar sind.
+PLATTFORM = sys.platform
+ANFRAGE_WARTE_SEK = 60  # so lange wartet die Mikrofon-Anfrage auf die Antwort des Menschen im Systemdialog
+_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).
+
+def umgebung(plattform: str) -> dict:
+    """Umgebung des Aufnehmers. Auf dem Mac zusaetzlich ein FESTER Steuerordner im Heim: Ohne ihn legt der Aufnehmer ihn
+    unter $TMPDIR an, und eine zweite Claude-Sitzung (anderes $TMPDIR) fande die laufende Aufnahme nicht."""
+    env = dict(_UMGEBUNG)
+    if plattform == "darwin":
+        env["OPENADAPT_CAPTURE_RUNTIME_DIR"] = os.path.join(os.path.expanduser("~"), ".kimal3", "aufnehmer-steuerung")
+    return env
+
+
+# Zwilling von GRUENDE_WINDOWS / GRUENDE_MAC in cli/src/zeigen-rechnung.ts -- gleiche Reihenfolge, gleiche Schalter (der
+# Test vergleicht beide). Die Mac-Muster sind die festen Saetze des Aufnehmers, nie "Accessibility" allein: ein
+# Fenstertitel "Accessibility Settings" ist kein Grund.
 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"),
@@ -29,10 +48,73 @@ GRUENDE = [
     (re.compile(r"DesktopCaptureError|screen layout"), "bildschirm-gesperrt"),
     (re.compile(r"did not become ready|did not start"), "startet-nicht"),
 ]
+GRUENDE_MAC = [
+    (re.compile(r"FFmpegUnavailableError|ffmpeg.*not found", re.IGNORECASE), "ffmpeg-fehlt"),
+    (re.compile(r"denied global input observation"), "freigabe-eingabe"),
+    (re.compile(r"denied the ordered input barrier"), "freigabe-bedienungshilfen"),
+    (re.compile(r"disabled the input event tap"), "abgriff-abgeschaltet"),
+    (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, plattform: str) -> str:
+    """Alles ausser win32 hat die Mac-Liste (wie in TS). Die Plattform ist Pflicht: Still die eigene anzunehmen liess
+    eine Windows-Pruefung auf einem echten Mac mit der Mac-Liste laufen (Messung 2, docs/qa/2026-10-24-zeigen-mac-messungen.md)."""
+    gruende = GRUENDE if plattform == "win32" else GRUENDE_MAC
+    return next((code for muster, code in gruende if muster.search(protokoll)), "unbekannt")
 
 
-def fehler_grund(protokoll: str) -> str:
-    return next((code for muster, code in GRUENDE if muster.search(protokoll)), "unbekannt")
+def _wahrheitswert(wert) -> bool | None:
+    """Nur ein echter Wahrheitswert zaehlt; alles andere ist "weiss ich nicht" (nie "erteilt")."""
+    return wert if isinstance(wert, bool) else None
+
+
+def _mikrofon_status(status) -> bool | None:
+    # AVAuthorizationStatus: 0 nicht gefragt, 1 eingeschraenkt, 2 abgelehnt, 3 erteilt. Alles andere: weiss ich nicht.
+    if isinstance(status, bool) or not isinstance(status, int):
+        return None
+    return status == 3 if status in (0, 1, 2, 3) else None
+
+
+def _frage_mikrofon(av) -> None:
+    antwort = threading.Event()
+    av.AVCaptureDevice.requestAccessForMediaType_completionHandler_(av.AVMediaTypeAudio, lambda erteilt: antwort.set())
+    antwort.wait(ANFRAGE_WARTE_SEK)
+
+
+def freigaben_abfragen(anfragen: str | None = None) -> dict:
+    """Fragt macOS, was dieser Prozess darf -- ohne etwas zu oeffnen (das Mikrofon wird nur nach seinem Status gefragt).
+    Jede Freigabe einzeln: fehlt das Modul oder wirft der Aufruf, ist genau diese `None` ("kann ich nicht feststellen").
+    `anfragen` loest VOR dem Abfragen genau diese eine Systemanfrage aus. Waehrend der Aufrufe ist stdout/stderr
+    umgeleitet: Eine fremde Zeile darf nie in die eine JSON-Zeile der Ausgabe geraten."""
+    def aus(name: str):
+        import importlib
+        return importlib.import_module(name)
+
+    def versuche(rechne):
+        try:
+            return rechne()
+        except Exception:
+            return None
+
+    ergebnis = {}
+    with open(os.devnull, "w") as stumm, contextlib.redirect_stdout(stumm), contextlib.redirect_stderr(stumm):
+        anfrage_fuer = {
+            "bildschirm": lambda: aus("Quartz").CGRequestScreenCaptureAccess(),
+            "eingabe": lambda: aus("Quartz").CGRequestListenEventAccess(),
+            "bedienungshilfen": lambda: (lambda aps: aps.AXIsProcessTrustedWithOptions({aps.kAXTrustedCheckOptionPrompt: True}))(aus("ApplicationServices")),
+            "mikrofon": lambda: _frage_mikrofon(aus("AVFoundation")),
+        }
+        if anfragen in anfrage_fuer:  # eine gescheiterte Anfrage aendert nur die Antwort darunter
+            versuche(anfrage_fuer[anfragen])
+        ergebnis["bildschirm"] = _wahrheitswert(versuche(lambda: aus("Quartz").CGPreflightScreenCaptureAccess()))
+        ergebnis["eingabe"] = _wahrheitswert(versuche(lambda: aus("Quartz").CGPreflightListenEventAccess()))
+        ergebnis["bedienungshilfen"] = _wahrheitswert(versuche(lambda: aus("ApplicationServices").AXIsProcessTrusted()))
+        ergebnis["mikrofon"] = _mikrofon_status(versuche(
+            lambda: (lambda av: av.AVCaptureDevice.authorizationStatusForMediaType_(av.AVMediaTypeAudio))(aus("AVFoundation"))))
+    return ergebnis
 
 
 def schreibe_json_atomar(pfad: str, daten: dict) -> None:

package/zeigen/starter.py

@@ -8,8 +8,8 @@ import sys
 import threading
 import time
 
-from gemeinsam import (ABBRECHEN, PROTOKOLL, ROH, STARTER, UMGEBUNG, _stoppe_sitzung, fehler_grund, lies_protokoll,
-                       sauber, schreibe_json_atomar)
+from gemeinsam import (ABBRECHEN, PLATTFORM, PROTOKOLL, ROH, STARTER, _stoppe_sitzung, fehler_grund, freigaben_abfragen,
+                       lies_protokoll, sauber, schreibe_json_atomar, umgebung)
 
 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
@@ -22,12 +22,16 @@ AUFNEHMEN = "import sys; from openadapt_capture.cli import record; record(sys.ar
 
 
 def _starte_kind(befehl: list, ordner: str, protokoll) -> subprocess.Popen:
+    env = dict(os.environ, **umgebung(PLATTFORM))
+    if PLATTFORM != "win32":  # Mac: STARTUPINFO und CREATE_NEW_CONSOLE gibt es dort nicht; eine eigene Sitzung loest vom Starter
+        return subprocess.Popen(befehl, cwd=ordner, env=env, stdout=protokoll, stderr=subprocess.STDOUT,
+                                start_new_session=True)
     # 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,
+    return subprocess.Popen(befehl, cwd=ordner, env=env, stdout=protokoll,
                             stderr=subprocess.STDOUT, startupinfo=si, creationflags=subprocess.CREATE_NEW_CONSOLE)
 
 
@@ -40,8 +44,15 @@ def _beende_baum(kind: subprocess.Popen) -> bool:
         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)
+    if PLATTFORM == "win32":
+        subprocess.run(["taskkill", "/PID", str(kind.pid), "/T", "/F"], capture_output=True,
+                       creationflags=subprocess.CREATE_NO_WINDOW)
+    else:  # Schnappschuss steht oben, VOR dem ersten Signal: ein beendeter Vater gaebe seine Kinder nicht mehr her
+        for p in baum:
+            try:
+                p.terminate()
+            except psutil.NoSuchProcess:
+                pass
     _, lebend = psutil.wait_procs(baum, timeout=10)
     for p in lebend:
         try:
@@ -118,7 +129,12 @@ def starte(konfig: dict, befehl: list | None = None) -> None:
     melde()
     kind = None
     try:
-        python = os.path.join(os.path.dirname(sys.executable), "python.exe")
+        if PLATTFORM == "darwin":  # ohne Freigabe nimmt der Aufnehmer nichts auf: gar nicht erst starten
+            freigaben = freigaben_abfragen()
+            for name in ("bildschirm", "eingabe", "bedienungshilfen"):  # None ("weiss nicht") haelt nicht auf
+                if freigaben.get(name) is False:
+                    return melde(zustand="fehlgeschlagen", grund=f"freigabe-{name}")
+        python = os.path.join(os.path.dirname(sys.executable), "python.exe") if PLATTFORM == "win32" else sys.executable
         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:
@@ -138,7 +154,7 @@ def starte(konfig: dict, befehl: list | None = None) -> 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)))
+                    return melde(zustand="fehlgeschlagen", grund=fehler_grund(lies_protokoll(ordner), PLATTFORM))
                 try:
                     _mit_herzschlag(lambda: _stoppe_sitzung(bericht.get("sitzung"), BREMSE_STOPP_SEK), melde)
                 except Exception:
@@ -160,4 +176,4 @@ 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))}
+    return {"zustand": "abgebrochen" if sitzung else "fehlgeschlagen", "grund": fehler_grund(lies_protokoll(ordner), PLATTFORM)}

package/zeigen/werkzeug.py

@@ -4,7 +4,8 @@
 #   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 teile                   -> eine JSON-Zeile: was eingerichtet ist (auf dem Mac auch: avfoundation)
+#   werkzeug.py freigaben [--anfragen <name>]  -> eine JSON-Zeile: was macOS diesem Prozess erlaubt (Windows: null)
 #   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)
@@ -15,6 +16,7 @@
 # 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 importlib.util
 import json
 import os
 import sqlite3
@@ -23,8 +25,8 @@ 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 gemeinsam import (ABBRECHEN, PLATTFORM, ROH, STARTER, ZUSTAND_AUFNEHMER, _stoppe_sitzung,  # noqa: E402
+                       fehler_grund, freigaben_abfragen, lies_json, lies_protokoll, sauber, umgebung)
 from starter import starte  # noqa: E402
 
 WARTEN_SEK = 15.0  # so lange wartet `stoppen` nach dem Stopp auf einen Starter ohne frischen Herzschlag
@@ -118,15 +120,15 @@ def stoppen(ordner: str) -> dict:
         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))
+            return antwort("abgebrochen", fehler_grund(lies_protokoll(ordner), PLATTFORM), aufnahme_zahlen(ordner))
     if zustand in ("abgebrochen", "fehlgeschlagen"):
-        return antwort("abgebrochen", bericht.get("grund") or fehler_grund(lies_protokoll(ordner)), aufnahme_zahlen(ordner))
+        return antwort("abgebrochen", bericht.get("grund") or fehler_grund(lies_protokoll(ordner), PLATTFORM), 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))
+        return antwort("nicht-sauber", fehler_grund(lies_protokoll(ordner), PLATTFORM), 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("nicht-sauber", fehler_grund(lies_protokoll(ordner), PLATTFORM), zahlen)
     return antwort(ergebnis, None, zahlen)
 
 
@@ -191,7 +193,10 @@ def teile() -> dict:
         aufnehmer = version("openadapt-capture")
     except PackageNotFoundError:
         aufnehmer = None
-    return {"aufnehmer": aufnehmer, "ffmpeg": _ffmpeg_da(), "modell": modell_da(_hf_cache())}
+    daten = {"aufnehmer": aufnehmer, "ffmpeg": _ffmpeg_da(), "modell": modell_da(_hf_cache())}
+    if PLATTFORM == "darwin":  # die Bruecke zu AVFoundation (Mikrofon-Status) kommt als eigenes Paket mit
+        daten["avfoundation"] = importlib.util.find_spec("AVFoundation") is not None
+    return daten
 
 
 def main(argv: list) -> int:
@@ -201,6 +206,7 @@ def main(argv: list) -> int:
     befehle.add_parser("stoppen").add_argument("ordner")
     befehle.add_parser("zustand").add_argument("ordner")
     befehle.add_parser("teile")
+    befehle.add_parser("freigaben").add_argument("--anfragen", choices=["bildschirm", "eingabe", "bedienungshilfen", "mikrofon"])
     zl = befehle.add_parser("zeitleiste")
     zl.add_argument("ordner")
     zl.add_argument("sprache", choices=["de", "en"])
@@ -210,7 +216,7 @@ def main(argv: list) -> int:
     bi.add_argument("sekunden", type=float)
     befehle.add_parser("modell-laden")
     args = parser.parse_args(argv)
-    os.environ.update(UMGEBUNG)
+    os.environ.update(umgebung(PLATTFORM))
     try:
         if args.befehl == "starten":
             konfig = lies_json(args.konfig)
@@ -224,6 +230,8 @@ def main(argv: list) -> int:
         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 == "freigaben":  # blockiert nicht laenger als freigaben_abfragen (Node: 20 s, mit --anfragen 90 s)
+            daten = {"freigaben": freigaben_abfragen(anfragen=args.anfragen) if PLATTFORM == "darwin" else None}
         elif args.befehl == "zustand":
             daten = zustand(None if ordner == "-" else ordner)
         elif args.befehl in ("zeitleiste", "bild", "modell-laden"):