# HyperTwist Phase 6R-AO Handy global hotkey, mute, and device-selection shell preparation packet

Created on `2026-05-31`

## Status

- bounded permissive HyperTwist packet
- source-backed `Phase 6R-AO` preparation/control slice

## Purpose

This packet scopes the next justified narrow `cjpais/Handy` reopening above the
already landed HyperTwist speech stack and the bounded `Phase 6R-AJ` external
dictation shell adjunct.

The granted slice is:

- global-hotkey lifecycle shell posture
- selected input-device shell posture
- selected output-device shell posture
- mute-while-recording shell posture
- on-demand versus always-on microphone-mode shell posture
- service-health capability exposure for those operator-facing shell surfaces

It is not:

- top-level provider/session ownership
- core native STT runtime ownership over `whisper.cpp`
- Python orchestration ownership over `faster-whisper`
- actual OS-level global-hotkey registration or capture ownership
- actual system mute, clipboard, or desktop typing execution ownership
- local model catalog/download/checksum/unload ownership
- voice-output ownership
- broad assistant-platform ownership

## Current authority basis

This control pass stands on:

- `docs/HYPERTWIST_HANDY_OFFLINE_DICTATION_SHELL_HIERARCHY_RECONCILIATION_2026-05-28.md`
- `docs/REPO_LICENSE_TRACKING.md`
- `docs/v6_5_deep_manual_pack/HyperTwist/FEATURE_REGISTRY.md`
- `docs/v6_5_deep_manual_pack/HyperTwist/ROADMAP.md`
- `docs/arch/HYPERTWIST_PHASE6R_AJ_HANDY_EXTERNAL_DICTATION_HISTORY_OUTPUT_ROUTING_IMPLEMENTATION_PACKET_2026-05-31.md`

The preserved owners do not change:

- first-party HyperTwist remains the top-level provider/session owner
- `ggml-org/whisper.cpp` remains the native speech-input runtime owner
- `SYSTRAN/faster-whisper` remains the Python orchestration/service-lane owner
- first-party HyperTwist remains the provider-profile/routing and speech-shell
  owner for the already landed lanes

## Granted family

The bounded `Phase 6R-AO` slice may land:

1. new external-dictation shell profile fields for hotkey, device-selection,
   mute, and microphone-mode posture
2. bounded shell-state fields for hotkey labels, selected devices, device
   option lists, microphone mode, and mute posture
3. bounded service-health capability exposure for the new operator-facing shell
   surfaces
4. default sample/profile builders and shell-state synchronization above the
   existing speech session
5. focused automation for:
   - session-config/profile validity
   - hotkey/device/mute shell-state validity
   - retained action and capability exposure

The packet must stay out of:

- actual OS-level shortcut registration/execution ownership
- actual system audio-device mutation ownership
- payload shipping or model-download ownership
- voice-output ownership
- assistant-platform widening

## Proposed implementation shape

Land the narrower boundary through:

- extended speech recognition/profile structs in:
  - `HyperTwistRecognitionTypes.h`
- retained shell-state synchronization in:
  - `UHyperTwistTrainingSubsystem`
- default profile/sample alignment in:
  - `HyperTwistContractLibrary.cpp`
- focused automation in:
  - `HyperTwistHandyPhase6RAOHotkeyMuteDeviceContractTest.cpp`

## Validation target

Use the documented validation split:

- safe VPS-side source checks first
- when Unreal validation is sensible and the instance is on the VPS without
  `UnrealEditor`, use the Windows reverse-SSH lane documented in the sensitive
  runbook
- if the Windows checkout lags the VPS source state, say that explicitly and
  do not claim packet coverage for missing Windows-side files

## Queue effect

If this packet lands cleanly, `cjpais/Handy` stops being only the transcript
history/output-routing adjunct and becomes the current bounded owner for the
operator-facing hotkey/device/mute shell posture too.

After that, return to the retained repo-row queue. Do not widen this row into a
broad speech-platform packet by default.
