Add safe transcription errors and opt-in private debug logging

docs/overlay.md

@@ -98,6 +98,7 @@ installer creates one with defaults on first install. Copy the shipped
 {
   "font": "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf",
   "input_priority": "normal",
+  "advanced_debug": false,
   "wrist": {"x": 0, "y": 0.18, "z": 0.089, "width": 0.30, "roll_degrees": 0},
   "theme": {
     "background": "#0c101b", "card": "#141c2b", "ink": "#e6f0f9",
@@ -117,6 +118,17 @@ installer creates one with defaults on first install. Copy the shipped
 
 Each theme color is `#RRGGBB`; omitted colors keep the default. `font` is a
 TTF/OTF file path (not a family name); a missing file uses the bundled font.
+`advanced_debug` is a boolean (default `false`, not a string): an opt-in
+request for full diagnostic logs. Full logs may contain speech/transcribed text
+and local paths; **raw audio clips are not archived**. The Settings tab shows
+an Advanced debugging ON/OFF toggle and warns that changing it restarts the
+worker and cancels current work (including pending review). Changes take effect
+immediately; failed saves show a warning and keep the selection for this session.
+Detailed logs are bounded and owner-private; see [worker diagnostics](worker.md#advanced-debugging). The native
+`save_advanced_debug(path, bool)` helper updates only this value in a valid
+config, retaining other fields and formatting; invalid/unwritable configs are
+left untouched and return failure. The installer backs up original bytes before
+repairing invalid values, while valid `true` and `false` are retained.
 `buttons` maps named OpenVR actions (`left_grip`, `right_grip`, `ptt`, `cancel`,
 `insert`, `enter`) to Frame physical `/user/hand/{left|right}/input/NAME`
 button paths. Omitted actions retain their bundled defaults; an empty string
@@ -202,7 +214,8 @@ keeps the selection for the session and displays a warning. `--mount
 world|left-wrist|right-wrist|head` overrides the saved choice for one launch without
 writing it; `--head` remains an alias for `--mount head`.
 
-Settings also has **Lasers anytime** (default off). When enabled, FrameYap sets
+Settings also has **Lasers anytime** (default off). Open the dashboard to change
+it when system-wide lasers are disabled. When enabled, FrameYap sets
 OpenVR's `VROverlayFlags_MakeOverlaysInteractiveIfVisible` on its panel. OpenVR
 requests system-wide laser mouse mode while the panel is visible, including
 with Steam's dashboard closed; it may change interaction with games. Turning

docs/worker.md

@@ -1,8 +1,8 @@
 # Offline Redux worker adapter (component, not an installed product)
 
 `src/worker.hpp` provides `frameyap::Worker`: call `start(python, script, model,
-threads=2)` explicitly, poll until `ready()`, then `submit(id, pcm)` and poll for
-one `WorkerReply` (text or generic per-request error). One request at a time;
+threads=2, advanced_debug=false)` explicitly, poll until `ready()`, then `submit(id, pcm)` and poll for
+one `WorkerReply` (text or privacy-safe per-request error). One request at a time;
 no queue, no capture and no input injection. `stop()` discards pending audio,
 terminates/reaps **only its direct child** (TERM, bounded 500 ms, then KILL),
 and is safe to repeat. Destruction stops it. `start()` returns without waiting
@@ -19,16 +19,19 @@ and writes only `clip.raw` with `O_EXCL|O_NOFOLLOW`, mode 0600. Clips are
 float32 (0.2..20 s). Files are unlinked after replies or shutdown, and the
 private directory is removed. Private clips are not encrypted against the
 account owner/root; do not use an untrusted runtime directory. The caller
-should pass a trusted interpreter and script. Neither audio nor transcripts
-are logged; child stderr is redirected to `/dev/null`, so worker diagnostics
-are deliberately generic.
+should pass a trusted interpreter and script. By default audio/transcripts are
+not logged and child stderr is redirected to `/dev/null`. Request errors report
+only a fixed stage (`audio`, `inference`, `response`) and built-in exception
+category, never the exception message, arbitrary class name, traceback or text.
+The native receiver allowlists those labels before displaying/logging them;
+unknown/legacy errors remain generic.
 
 The private pipes use unsigned LE32 payload lengths (1..65536), a one-byte
 message type and, for requests/replies, unsigned LE64 request ID. `T` + ID
 requests reading the fixed clip; `Y` means ready; `F` means load failure
 (`M` for missing/mismatched pinned model or private clip directory, `I` for a
 missing Python dependency, `D` for runtime/model load failure); `R` + ID + UTF-8
-text and `E` + ID + generic UTF-8 error are replies. Text is at most 4096
+text and `E` + ID + privacy-safe UTF-8 error are replies. Text is at most 4096
 bytes. An unexpected or duplicate reply, wrong ID, extra frame, closed pipe
 or oversized frame stops the worker. Warmup deadline is 120 s, transcription
 deadline 60 s; `poll()` must be called regularly to enforce deadlines. It
@@ -58,6 +61,32 @@ or bundling. See [third-party notes](third-party.md). No public runtime bundle h
 been released. Limited ARM64 measurements are in the [POC record](evidence/poc-cpu-overlay-2026-09-24.md),
 not a claim of complete headset acceptance.
 
+## Advanced debugging
+
+Explicitly set `"advanced_debug": true` in config or enable Settings → Advanced
+debugging. It is off by default. A Settings change restarts the owned worker,
+closes the microphone and discards current work/review; the replacement worker
+warms normally. Turning it off stops detailed capture but **does not delete
+previous logs**. Manual config edits take effect on application restart.
+
+With this opt-in the worker receives `--advanced-debug`: native/model stdout and
+stderr, sample counts, full exception tracebacks and recognized transcripts are
+captured. **These logs may contain private speech, transcript text and local
+paths. Inspect/redact before sharing; keep out of Git.** No raw audio archive is
+created; normal temporary clips still expire after replies/cancellation.
+
+Files: `$XDG_STATE_HOME/frameyap/worker-debug.log` (fallback
+`~/.local/state/frameyap/worker-debug.log`) and `worker-debug.previous.log`.
+Each debug worker start rotates the current log once; only these two files are
+retained, each bounded to 4 MiB. At the limit a marker is written and further
+output is drained/discarded for that worker session, not allowed to block it.
+The directory is owner-private 0700 and logs are 0600. Unsafe paths, symlinks,
+hardlinks or preexisting permissive files are refused with a visible error;
+there is no fallback to public temporary files. The app's single-instance lock
+is required to avoid competing rotation by multiple workers. Debug output never
+shares the framed protocol stdout. Direct worker CLI use with `--advanced-debug`
+writes to its caller's stderr; the native adapter supplies the private bounded sink.
+
 Hardware-free tests run through CTest, including fake-child cancellation, short
 injected warmup/request deadlines, duplicate/stale replies, malformed frames,
 missing/hash-mismatched model files and symlink refusal. Default production