refactor(hud): event-driven PostMessage architecture for stability (v0.2.31)

architecture.md

@@ -15,17 +15,17 @@ graph TD
     User[User Hardware] -->|Audio| SD[AudioStreamer (Thread)]
     User -->|Keys| Hooks[keyboard (Thread)]
     User -->|Mouse| MHooks[pynput (Thread)]
-    
+
     SD -->|Queue| Pipe[AudioPipeline (Async)]
     Hooks -->|ThreadSafe Call| Coord[AppCoordinator (Asyncio)]
-    
+
     Coord -->|WebSocket| Cloud[OpenAI / AssemblyAI]
     Cloud -->|Events| Coord
-    
+
     Coord -->|State| Tray[Tray Icon (Thread)]
     Coord -->|State| Indicator[IndicatorUI (Thread)]
     Coord -->|Sound| Spkr[Speaker (Thread)]
-    
+
     Coord -->|Injection| App[Target Window]
 ```
 
@@ -114,16 +114,16 @@ sequenceDiagram
     Main->>Cloud: ensure_connected()
     Cloud-->>Main: Connected
     Main->>Pipe: start()
-    
+
     loop Audio Pipeline
         Pipe->>Cloud: Processed & Resampled Audio
     end
-    
+
     loop Transcription Events
         Cloud->>Main: Partial Transcript
         Main->>App: smart_inject()
     end
-    
+
     User->>Monitor: Release Hotkey (Hold Mode)
     Monitor->>Main: trigger stop_listening()
     Main->>Pipe: stop()

conductor/archive/accuracy_eval_20260212/spec.md

@@ -11,7 +11,7 @@ Compare the transcription accuracy and latency of the current `master` branch ag
 
 ### 1.2 Target Versions
 - **Current Version:** The code at the current `master` HEAD.
-- **Legacy Version (v0.1):** 
+- **Legacy Version (v0.1):**
     - Create a temporary branch `temp/eval-v0.1` from tag `v0.1`.
     - Port the `eval` functionality (`engine/eval_main.py`, `engine/audio/replay.py`, and CLI dispatcher) to this branch.
     - **CRITICAL:** Ensure the core transcription and audio capture logic of `v0.1` is not modified.

conductor/archive/audio_pipeline_20260211/metadata.json

@@ -5,4 +5,4 @@
   "created_at": "2026-02-11T12:52:00Z",
   "updated_at": "2026-02-11T12:52:00Z",
   "description": "Audio pipeline: remove polling + enforce invariants"
-}
+}

conductor/archive/audio_pipeline_20260211/spec.md

@@ -17,7 +17,7 @@ Refactor the audio capture pipeline to replace the current thread-polling mechan
 Enforce "cheap" universal invariants immediately at the capture boundary to prevent stereo or invalid data from leaking into the async pipeline.
 - **Downmixing:** If the input device provides stereo `(N, 2)`, automatically downmix to mono by averaging channels before reshaping.
 - **Reshaping:** Automatically flatten `(N, 1)` to `(N,)`.
-- **Validation:** 
+- **Validation:**
     - Reject non-numeric data or data with `ndim > 2` (raise `CaptureFormatError`).
     - Sanitize `NaN` or `Inf` values in float input by replacing them with `0`.
 - **Note:** Conversion to `int16` and resampling are deferred to the Provider Adapter (Track 2).

conductor/archive/code_audit_refactor_20260216/metadata.json

@@ -5,4 +5,4 @@
   "created_at": "2026-02-16T11:03:00Z",
   "updated_at": "2026-02-16T11:03:00Z",
   "description": "we need to review the code and refactor hardcode value so we need to review the code for any dead code also we need to look at every file to see if there is any hard coded value if the value is local to the file we move it at the top i mean as constant or something if it's configuration we move to the config file and expose it to the user if it's part of it if it's not it's internal configuration or something should not be exposed to the user then again if it's local or with the top of the file global probably a constant file if that's the best approach from coding perspective and best practice also the import of library should be always at the top also doing the review we need to check for best practice solid principles do not make changes till you ask me first phase is analyze second phase we need to check what to do"
-}
+}

conductor/archive/connection_lifecycle_20260211/metadata.json

@@ -5,4 +5,4 @@
   "created_at": "2026-02-11T13:22:00Z",
   "updated_at": "2026-02-11T13:22:00Z",
   "description": "Connection Lifecycle: Warm-connection optional"
-}
+}

conductor/archive/consultant_improvements_20260212/spec.md

@@ -7,7 +7,7 @@ Apply a set of critical security and stability improvements identified by a cons
 
 ### 1.1 Unified Input Monitoring (C1)
 - **Goal:** Consolidate multiple keyboard listeners into a single managed hook.
-- **Scope:** 
+- **Scope:**
     - Merge `gui_main.py` hotkey listener and `interaction.py` "stop on any key" listener.
     - Create a central `InputMonitor` (likely in `engine/interaction.py` or a new utility) that routes events thread-safely to the `AppCoordinator`.
 

conductor/archive/cosmetic_refinement_20260214/spec.md

@@ -20,7 +20,7 @@ This track focuses on modernizing the visual identity of ParrotInk and exposing
 - **Clarity:** Ensure high contrast and clear rendering (using anti-aliasing features of the rendering library).
 
 ### 2.3 Feature Exposure (Tray Menu)
-- **"Hold to Talk":** Add a new checkable menu item under "Settings". 
+- **"Hold to Talk":** Add a new checkable menu item under "Settings".
     - **Label:** "Hold to Talk".
     - **Functionality:** Toggles the `hotkeys.hold_mode` configuration boolean.
 - **Menu Header:** Add a non-clickable (disabled) menu item at the very top of the tray menu.

conductor/archive/debug_logging_20260210/plan.md

@@ -44,4 +44,4 @@ Implement detailed, sanitized logging for WebSocket traffic.
 - [x] Task: Integration Testing [b57a786]
     - [x] **Red:** Test that running with `-vv` captures mock provider traffic without leaking secrets.
     - [x] **Green:** Refine `SanitizingFormatter` if any leaks are detected.
-- [x] Task: Conductor - User Manual Verification 'Phase 3: Provider Instrumentation (Level 2)' (Protocol in workflow.md) [b57a786]
+- [x] Task: Conductor - User Manual Verification 'Phase 3: Provider Instrumentation (Level 2)' (Protocol in workflow.md) [b57a786]

conductor/archive/enhanced_status_feedback_20260215/metadata.json

@@ -5,4 +5,4 @@
   "created_at": "2026-02-15T14:00:00Z",
   "updated_at": "2026-02-15T14:00:00Z",
   "description": "Implement enhanced status feedback for connection and switching operations, including HUD messages and tray tooltips."
-}
+}

conductor/archive/fix_exit_20260209/spec.md

@@ -12,7 +12,7 @@ The current implementation of `Ctrl+C` handling in `main.py` is unresponsive and
 - **Traceback Elimination:** Resolve the `SystemExit` error by signaling `icon.stop()` and allowing threads to join, rather than forcing `sys.exit()`.
 
 ## 3. Technical Requirements
-- **Threading Model:** 
+- **Threading Model:**
   - `pystray` icon loop MUST run in a dedicated background thread.
   - The main thread MUST wait on a `shutdown_event` (with a timeout/loop) to remain responsive to `SIGINT`.
 - **Signal Handler:** Must be minimal, only updating state (timestamps/events) and printing. It MUST NOT call `sys.exit()`.

conductor/archive/fix_hotkey_connection_20260215/metadata.json

@@ -5,4 +5,4 @@
   "created_at": "2026-02-15T12:11:00Z",
   "updated_at": "2026-02-15T12:11:00Z",
   "description": "Fix regression where Ctrl+Alt triggers HUD/Sound incorrectly despite Ctrl+Alt+V hotkey, and address connection timeouts with AssemblyAI."
-}
+}

conductor/archive/fix_provider_switch_delay_20260215/metadata.json

@@ -5,4 +5,4 @@
   "created_at": "2026-02-15T08:43:00Z",
   "updated_at": "2026-02-15T08:43:00Z",
   "description": "we have a bug in switching between providers , for example from openai to assemblyai and vice versa in the tray , bug is as follow 1. teh hud does not dissapear, it should be simpel when we click dictation end just like when we press any key the connection dropped then switch provider then the user press the hotkey again and that will automatically initiate teh new provider, now this is not happeneing , the hud does not dissapear, I hear some stutter sound sometimes. then the hotkey does not work when I press it again"
-}
+}

conductor/archive/golden_tools_20260212/spec.md

@@ -8,7 +8,7 @@ Create independent, standalone Python tools to generate "Golden Standard" transc
 ### 1.1 Tool: `openai_golden.py`
 - **Model:** `gpt-4o-transcribe` (High-quality Batch API).
 - **Authentication:** Retrieve `openai_api_key` from Windows Credential Manager.
-- **Features:** 
+- **Features:**
     - Support for high-quality file-based transcription using the latest GPT-4o based model.
     - Automatic audio chunking for files exceeding the 25MB OpenAI limit.
     - **JSON Output (Metadata Mode):**

conductor/archive/resampling_contracts_20260211/metadata.json

@@ -5,4 +5,4 @@
   "created_at": "2026-02-11T13:01:00Z",
   "updated_at": "2026-02-11T13:01:00Z",
   "description": "Explicit provider audio contracts + resampling"
-}
+}

conductor/archive/secrets_management_20260210/plan.md

@@ -42,4 +42,4 @@ Connect the security module to the tray and coordinator.
     - [x] Audit `config.py` and `main.py` for any remaining hardcoded or config-based secret logic.
 - [x] Task: Final end-to-end smoke test [16e6004]
     - [x] Set keys via UI and verify successful transcription and error reporting.
-- [x] Task: Conductor - User Manual Verification 'Phase 4: Final Verification & Cleanup' (Protocol in workflow.md)
+- [x] Task: Conductor - User Manual Verification 'Phase 4: Final Verification & Cleanup' (Protocol in workflow.md)

conductor/archive/secrets_management_20260210/spec.md

@@ -15,7 +15,7 @@ This track implements a modern, secure handling system for API keys. It moves aw
 
 ### 2.2 System Tray Credential Management
 - **Menu Structure:** `Credentials` > `Set OpenAI Key...`, `Set AssemblyAI Key...`.
-- **Absolute Privacy:** 
+- **Absolute Privacy:**
     - Keys are **never** displayed in the tray menu.
     - The input dialog for setting a key must use a password-style mask (e.g., `*`) for the entry field.
 - **Immediate Update:** Saving a key updates the application's active session without requiring a restart.
@@ -44,4 +44,4 @@ This track implements a modern, secure handling system for API keys. It moves aw
 6. Missing or invalid keys trigger a user-friendly error message instead of a silent failure.
 
 ## 5. Out of Scope
-- Retrieval of existing keys via UI.
+- Retrieval of existing keys via UI.

conductor/archive/shutdown_orchestration_20260211/metadata.json

@@ -5,4 +5,4 @@
   "created_at": "2026-02-11T13:10:00Z",
   "updated_at": "2026-02-11T13:10:00Z",
   "description": "Shutdown orchestration: prevent hangs on exit"
-}
+}

conductor/archive/smart_interaction_20260210/metadata.json

@@ -5,4 +5,4 @@
   "created_at": "2026-02-10T13:30:00Z",
   "updated_at": "2026-02-10T13:30:00Z",
   "description": "Smart Toggle Logic: Modifying the hotkey listener to stop recording immediately upon any subsequent key press. Refinement: Prioritizing manual input over transcription injection."
-}
+}

conductor/archive/tray_menu_sync_20260216/metadata.json

@@ -5,4 +5,4 @@
   "created_at": "2026-02-16T10:55:00Z",
   "updated_at": "2026-02-16T10:55:00Z",
   "description": "minor bug with the change hotkey: tray menu label does not update immediately after change"
-}
+}

conductor/archive/unified_config_overhaul_20260214/spec.md

@@ -8,7 +8,7 @@ This track eliminates the "messy" state of the current configuration and provide
 ## 2. Functional Requirements
 
 ### 2.1. Refined Configuration Schema
-- **User Profiles:** 
+- **User Profiles:**
   - `latency_profile`: `fast`, `balanced`, `accurate` (Internal mapping to VAD/Turn-detection).
   - `mic_profile`: `headset`, `laptop`, `none` (Maps to OpenAI Noise Reduction).
 - **Consolidation:**
@@ -32,7 +32,7 @@ This track eliminates the "messy" state of the current configuration and provide
 ### 2.4. Interactive Hotkey UI
 - **Tray Menu:** Add a "Change Hotkey" option.
 - **Recording Dialog:** A Win32 modal prompt that captures the next key combination.
-- **Validation:** 
+- **Validation:**
   - Reject system-reserved keys (Win+L, Alt+F4, etc.).
   - If invalid, keep the dialog open and provide feedback.
 - **Auto-Sync:** On valid capture, use the "In-Flight Update" mechanism to persist and apply.

conductor/setup_state.json

@@ -1 +1 @@
-{"last_successful_step": "3.3_initial_track_generated"}
+{"last_successful_step": "3.3_initial_track_generated"}

conductor/tracks/reliability_shutdown_grace_20260219/spec.md

@@ -21,7 +21,7 @@
 - **Verification:** Ensure `suppress=True` still works (critical for user experience).
 
 ### 2.2 Clean Shutdown Orchestration
-- **Action:** 
+- **Action:**
     - Change `ui_thread` to `daemon=False`.
     - Update `main_gui` to explicitly `stop()` the `TrayApp` and `join()` the `ui_thread`.
     - Ensure `SanitizingFormatter` handles `None` records gracefully if called during finalization.