Native Settings, model marks, and agent sounds delivery

This document records the native Windows delivery developed from baseline commit 25a5b09. The increment replaces EXEPERT Desktop's Settings placeholder with a native GPUI dialog, embeds the selected Zeron model marks and notification cues, adds source-qualified live completion and input-request sounds, and separates the center workspace color from the surrounding shell.

The application remains native Rust/GPUI. No WebView, Electron surface, backend endpoint, transcript schema, Codex protocol, DSH protocol, network asset fetch, renderer-fork change, or desktop banner notification was introduced. Unsloth was used only as a visual layout reference; no Unsloth source or CSS was copied.

Delivered architecture

The event adapters decide whether a live source transition is actionable. The sound runtime owns only deduplication, per-cue enablement, FIFO playback, and shutdown. This boundary prevents restored history, projection rebuilds, normal tool progress, or repeated terminal events from becoming audio notifications.

Native Settings dialog

Settings is now TopLevelOverlay::Settings, not a workbench destination. The current conversation and stage stay mounted below a 30 percent black scrim. The dialog is constrained below the custom titlebar, leaving minimize, maximize, and close available.

The dialog uses gpui_base::dialog::Dialog and supplies:

• native dialog semantics and focus containment;
• initial focus on Search settings…;
• dismissal through Escape, the close button, backdrop press, or the same Ctrl+,/Cmd+, shortcut;
• disabled default Enter-to-confirm behavior;
• focus restoration to the opening control;
• exclusivity with conflicting top-level overlays and composer popovers; and
• the preserved activity-settings control and command-palette entry.

The maximum dialog is 960 x 820 logical pixels with 16 px viewport gutters and available-height clamping. At 720 px of available width the 248 px Settings navigation stacks above the independently scrolling content. Pure geometry tests lock the intended 1280 x 720, 560 x 320, and scaled logical viewport behavior.

General is the only shipped page. It contains searchable rows for completion sound, input-request sound, navigation density, and read-only build information. Search selection scrolls to the row and briefly highlights it; an unmatched query displays No settings found. Navigation density continues to expose Full, Sidebar only, and Focus.

Stable native inspector IDs include:

• settings-dialog and settings-dialog-backdrop;
• settings-search and settings-page-general;
• settings-sound-completion and settings-sound-input-request;
• settings-navigation-density; and
• settings-close.

The modal hierarchy, focus lifecycle, keyboard operation, responsive overflow, and reduced available-space behavior follow the project's BMad UX guidance.

Settings persistence

DesktopUiSettingsV2 persists one complete object containing:

• navigation_density;
• completion_sound_enabled; and
• input_request_sound_enabled.

Version 1 is decoded explicitly, its navigation density is preserved, and both new sound preferences default on. Strict decoding continues to reject malformed content, unknown fields, unknown versions, and future versions. Writes retain the existing atomic temporary-file replacement. A failed save keeps the active session value and presents a compact, content-free warning instead of reverting the user's selection.

When EXEPERT_DISABLE_SOUND is present, both switches are visibly disabled and explain the process-wide override. Their saved values are preserved so removing the environment override restores the user's preferences.

Native notification sounds

done.wav and request.wav are embedded in the executable. Windows playback uses PlaySoundW with SND_MEMORY | SND_NODEFAULT | SND_SYNC from the existing windows-sys dependency. No temporary file, subprocess, PowerShell command, or network access is involved.

A bounded channel feeds one background FIFO worker, keeping GPUI responsive and preventing simultaneous cues from replacing each other. Per-cue generations invalidate queued instances when a preference is disabled. The worker tracks the active cue so disabling completion cannot stop a currently playing request cue, or vice versa. Shutdown interrupts current playback, drains safely, and joins the worker.

The 512-entry notification ledger is keyed by source, session or thread, turn/request identity, and cue. A full worker queue does not permanently poison deduplication: the rejected key is removed so a later authoritative event can retry.

Completion routing

Source	Rings once	Explicitly silent
Native EXEPERT	Successful live response after it is actually inserted	Cancelled, stale, failed, or non-inserted responses
Codex local and remote	Successful TurnCompleted; tracked active-turn-to-idle compatibility fallback	Failed, errored, cancelled, aborted, duplicate, restored, or projection-only state
DSH	Live top-level turn/end with explicit success/completion or canonical implicit success	turn/error, explicit failure/cancellation, nested subagent/end, replay, or ordinary tool progress

Input-request routing

request.wav rings once for each newly actionable Codex approval, user-input request, or MCP elicitation, including compatibility status fallbacks that are deduplicated against typed requests. Live DSH approval/asked receives the same cue. All live sessions are eligible even when their tab is inactive or the window is in the background.

Model marks

Seven Zeron SVGs are embedded through the existing ActivityAssets source. ModelMarkSpec resolves from provider, family, model ID, and display name:

Match	Mark behavior
Claude or Anthropic	Claude mark tinted Zeron orange #D97757
OpenAI, GPT, or Codex	OpenAI mark
xAI or Grok	Grok mark
Nous or Hermes	Hermes mark
Cursor	Cursor mark
Pi	Pi mark
OpenCode	OpenCode mark
Unknown	Existing EXEPERT generic mark

These marks are used only in the verified-model picker and selected-model composer chip. Activity-rail, titlebar, source-selector, and other EXEPERT glyphs retain their existing assets.

Pinned asset provenance

All nine files were copied byte-for-byte from Zeron commit b3fa51872f70c8f973c241b659cf0c166766f4f5:

Asset	Bytes	SHA-256
claude-mark.svg	1,950	BF611E1FDF533EA782208A2CEC8972177B782024E2C8EC337D8DDAC1799831A4
openai-mark.svg	1,656	FC418B32BF5625E1AB9CEB70CC8B2FA22E611DFE5773E82E8720ECF90477B797
cursor-mark.svg	547	2A67464511CBE5F12FD32E7CE6A667573366A138233F844CB467184527AA51C4
grok-mark.svg	979	645AAD7C24381C0DDCFF60A499228F94ED311F466CE96D6F24DF04BB68AF01D6
hermes-mark.svg	19,789	614FAD4DC0A309F7713F06174099DDBB107672350F4E4E1D3BA700F111E339D3
pi-mark.svg	274	102784EA6D06C522DFBC57875922C978790D8667A3D466AFDB1C0CBCC13D6A38
opencode-mark.svg	259	B3DD4CBF329F699D214E208C43EE1B3BBC67D8386C76A3C5B22F8774B3B1897D
done.wav	75,014	557CE54EEB2ABD42195B96291A39391F9D03625C79FB40B249089E014512E908
request.wav	66,194	0F9256A0E4E514DB156A64D00FBB69DB56FFBC39658454A266E131F21FBE8A74

THIRD_PARTY_NOTICES.md includes the pinned source paths and Zeron MIT license. Repository licensing does not grant permission to use third-party trademarks; public distribution still requires separate brand and trademark review.

Scoped desktop colors

The theme now distinguishes:

• SHELL_SURFACE = #181818 for the activity rail, navigation sidebar, titlebar, left titlebar controls, utility controls, and their shell wrappers; and
• WORKSPACE_SURFACE = #121214 for workspace-inset and its center/right stage containers.

SURFACE_1 remains #121214 for existing generic component semantics. This is an explicit scoped application, not a global token swap. Settings uses the shell surface with existing elevated, border, text, and control tokens.

Automated verification

The final native source candidate was checked with the pinned Windows Rust 1.96 MSVC toolchain:

cargo +1.96.0-x86_64-pc-windows-msvc fmt --manifest-path desktop/Cargo.toml --all -- --check
cargo +1.96.0-x86_64-pc-windows-msvc check --manifest-path desktop/Cargo.toml --package exepert-desktop --locked
cargo +1.96.0-x86_64-pc-windows-msvc test --manifest-path desktop/Cargo.toml --package exepert-desktop --tests --locked --quiet
cargo +1.96.0-x86_64-pc-windows-msvc clippy --manifest-path desktop/Cargo.toml --package exepert-desktop --tests --locked -- -D warnings
cargo +1.96.0-x86_64-pc-windows-msvc build --manifest-path desktop/Cargo.toml --package exepert-desktop --release --locked
pnpm.cmd --dir docs-site exec docusaurus build
git diff --check

Observed results on 2026-09-03:

• Rustfmt, the locked compiler check, and strict Clippy with warnings denied passed;
• the library suite reported 526 passed, zero failed, and four intentionally ignored renderer/manual harnesses;
• every enabled integration and source-contract suite passed;
• the optimized build passed and produced desktop/target/release/exepert-desktop.exe at 40,347,648 bytes;
• the Docusaurus optimized production build passed with this page registered in Desktop delivery navigation;
• embedded WAV headers, byte sizes, hashes, SVG parsing, model aliases, settings migration/round trips, event transitions, deduplication, responsive geometry, stable IDs, and scoped color contracts passed; and
• git diff --check passed with line-ending conversion notices only.

Native release evidence and manual boundary

The optimized application was launched against existing local EXEPERT data at an approximately 1280 x 720 window. The following behavior was observed:

1. Ctrl+, opened the native General dialog without replacing the workbench.
2. The preserved activity-settings control opened the same dialog.
3. Escape and the dialog close button dismissed it and restored the underlying stage.
4. The custom titlebar stayed outside the scrim and remained available.
5. Both sound switches appeared enabled, navigation density and build information rendered, and the backdrop used dim-only behavior.
6. The live model picker rendered Claude rows with the orange imported mark and retained generic marks for unmatched providers.
7. The smoke-test window closed cleanly, leaving no release EXEPERT process.

The custom window edge did not accept the automated resize gesture, so 560 x 320 and high-DPI behavior are supported by geometry and source contracts rather than claimed as manual viewport observations. A live foreground/background agent completion or input request was not generated during this smoke, so physical listening remains a manual release check. No provider request, paid API call, credential, approval decision, deployment, release upload, or binary distribution was performed.

Repository change inventory

This is the exhaustive path inventory relative to baseline 25a5b09. After adding this delivery record and sidebar entry, Git reports 27 changed paths: 12 additions, 15 modifications, and no deletions or renames. Generated Cargo and Docusaurus output remains ignored.

Documentation, provenance, and build configuration

Status	Path	Responsibility
M	THIRD_PARTY_NOTICES.md	Adds pinned Zeron paths, hashes, MIT notice, and trademark boundary
M	desktop/Cargo.toml	Enables the existing windows-sys Win32 Media Audio surface
A	docs-site/docs/architecture/native-settings-model-marks-agent-sounds-delivery.md	Provides this complete architecture, UX, provenance, verification, and delivery record
M	docs-site/sidebars.ts	Registers this page in Desktop delivery navigation

Pinned embedded assets

Status	Path	Responsibility
A	desktop/exepert-desktop/assets/third_party/zeron/icons/claude-mark.svg	Claude/Anthropic mark
A	desktop/exepert-desktop/assets/third_party/zeron/icons/openai-mark.svg	OpenAI/GPT/Codex mark
A	desktop/exepert-desktop/assets/third_party/zeron/icons/cursor-mark.svg	Cursor mark
A	desktop/exepert-desktop/assets/third_party/zeron/icons/grok-mark.svg	xAI/Grok mark
A	desktop/exepert-desktop/assets/third_party/zeron/icons/hermes-mark.svg	Nous/Hermes mark
A	desktop/exepert-desktop/assets/third_party/zeron/icons/pi-mark.svg	Pi mark
A	desktop/exepert-desktop/assets/third_party/zeron/icons/opencode-mark.svg	OpenCode mark
A	desktop/exepert-desktop/assets/third_party/zeron/sounds/done.wav	Exact successful-completion cue
A	desktop/exepert-desktop/assets/third_party/zeron/sounds/request.wav	Exact actionable-input cue

Native desktop source

Status	Path	Responsibility
M	desktop/exepert-desktop/src/app.rs	Settings overlay/lifecycle/rendering, persistence integration, shortcuts, and EXEPERT/Codex/DSH notification routing
M	desktop/exepert-desktop/src/desktop_ui_settings.rs	Strict V2 settings schema, V1 migration, and atomic complete-object persistence
M	desktop/exepert-desktop/src/lib.rs	Registers the notification-sound module
A	desktop/exepert-desktop/src/notification_sound.rs	Embedded WAVs, bounded dedupe, cue-isolated FIFO WinMM worker, override, and shutdown
M	desktop/exepert-desktop/src/ui/activity.rs	Embeds Zeron SVGs through ActivityAssets and resolves ModelMarkSpec aliases/tint
M	desktop/exepert-desktop/src/ui/chat.rs	Accepts resolved marks in the model picker and selected-model chip
M	desktop/exepert-desktop/src/ui/chrome.rs	Applies the scoped shell surface to the custom titlebar
M	desktop/exepert-desktop/src/ui/theme.rs	Defines explicit shell and workspace surface constants
M	desktop/exepert-desktop/src/ui/workbench.rs	Applies shell/workspace colors while preserving target IDs and stage structure

Native desktop tests and contracts

Status	Path	Responsibility
M	desktop/exepert-desktop/tests/chat_ux_contract.rs	Locks full model metadata flow and mark rendering at the intended two UI surfaces
M	desktop/exepert-desktop/tests/discovery_navigation_ux_contract.rs	Updates desktop settings schema contracts to V2
M	desktop/exepert-desktop/tests/seamless_workbench_polish_contract.rs	Locks V2 settings and explicit workspace surface use
A	desktop/exepert-desktop/tests/settings_sound_model_contract.rs	Locks dialog semantics/IDs, colors, assets, WinMM path, and model-mark scope
M	desktop/exepert-desktop/tests/ui_contract.rs	Locks exact shell/workspace colors and retained generic surface semantics

Maintainer reading order

1. Start with desktop_ui_settings.rs and notification_sound.rs for the persistence and playback invariants.
2. Read the Settings lifecycle/rendering and source-event adapters in app.rs.
3. Review ui/activity.rs with ui/chat.rs before changing model aliases or mark scope.
4. Review ui/theme.rs, ui/chrome.rs, and ui/workbench.rs together before changing shell/workspace ownership or stable IDs.
5. Read settings_sound_model_contract.rs and the adjacent unit tests before changing dialog behavior, event fallbacks, deduplication, assets, or colors.
6. Treat THIRD_PARTY_NOTICES.md as part of any asset replacement or public distribution review.

Git delivery boundary

The delivery branch is codex/native-settings-zeron-marks-sounds. The commit containing this record is the complete source delivery. The feature branch and its normal merge into main preserve an auditable review boundary. The local optimized executable remains an ignored build artifact and is not uploaded by the Git delivery.