Lumotia/docs/architecture-map/02-tauri-runtime/commands/power-and-security.md

name, type, slice, last_verified

name	type	slice	last_verified
Power assertions and security helpers	architecture-map-page	02-tauri-runtime	2026/05/09

commands::power and commands::security

Where you are: Architecture map → Tauri runtime → Commands → Power and security

Plain English summary. Two utility modules that the rest of the command files lean on. power.rs is the macOS App Nap power-assertion guard (no-op on Linux and Windows today). security.rs is ensure_main_window, the one-liner defence-in-depth check that several commands stamp at the top to reject calls from secondary windows even if the ACL ever drifted.

At a glance

• Paths: src-tauri/src/commands/power.rs (208 LOC), src-tauri/src/commands/security.rs (30 LOC).
• Tauri commands exposed: none. Both are pure Rust utilities.
• Events emitted: none.
• Depends on:
  • power.rs: macOS only — objc2::rc::Retained, objc2::runtime::ProtocolObject, objc2_foundation::{NSActivityOptions, NSObjectProtocol, NSProcessInfo, NSString}.
  • security.rs: nothing.
• Called from: every long-running command that wants to keep the OS awake (live transcription, LLM cleanup, content-tag extraction, task decomposition); every command that wants the extra firewall (intentions CRUD, nudges, updater stub, lots of Settings-only commands).

commands::power

PowerAssertionSnapshot (src-tauri/src/commands/power.rs:28)

Cloneable snapshot for the diagnostics report: id, reason, backend, acquired.

PowerAssertion (src-tauri/src/commands/power.rs:41)

A #[must_use] guard. Holding it keeps the macOS App Nap pin alive; dropping it ends the assertion. Fields: id, reason, backend, acquired, plus a macOS-only Option<ActivityHandle>.

PowerAssertion::begin(reason) (src-tauri/src/commands/power.rs:73)

Allocates a new id from a NEXT_ID: AtomicUsize, calls into objc_bridge::begin_activity on macOS, registers a snapshot in the global assertion_registry(). Returns the guard. Errors are logged; failure to acquire still returns a "no-op" guard (so the caller's code path is unchanged) with acquired = false.

On non-macOS, this is a no-op. The doc comment promises Linux logind inhibitors and Windows SetThreadExecutionState, but neither is wired up. See debt note in the slice README.

Drop for PowerAssertion (src-tauri/src/commands/power.rs:124)

End the macOS activity if present, remove the registry entry. Logs the end on macOS so the diagnostics bundle has a breadcrumb.

assertion_registry() (src-tauri/src/commands/power.rs:53)

Process-global Mutex<HashMap<usize, PowerAssertionSnapshot>> using OnceLock. active_assertions_snapshot() (:58) returns a sorted vector of clones for the diagnostic-report bundler.

objc_bridge module (src-tauri/src/commands/power.rs:140)

macOS-only. Wraps NSProcessInfo::processInfo().beginActivityWithOptions_reason(options, reason) and endActivity(handle). Options: NSActivityOptions::UserInitiated | NSActivityOptions::LatencyCritical. The activity object is Retained<ProtocolObject<dyn NSObjectProtocol>> and is unsafe impl Send (the activity is a process-wide pin and thread-safe).

Tests (:168)

power_assertion_is_a_no_op_drop confirms the registry entry is added on begin and removed on drop. multiple_assertions_get_unique_ids confirms the id allocator works.

Where PowerAssertion::begin is called

• commands::live::run_live_session (live.rs:660) — "magnotia live dictation session".
• commands::llm::cleanup_transcript_text_cmd (llm.rs:394) — "magnotia LLM cleanup".
• commands::llm::extract_content_tags_cmd (llm.rs:417) — "magnotia LLM content-tag extraction".

NOT called from commands::tasks::decompose_and_store or commands::tasks::extract_tasks_from_transcript_cmd, even though both run multi-second LLM inference. Flag for follow-up.

commands::security

ensure_main_window(window) (src-tauri/src/commands/security.rs:1)

One-liner: ensure_main_window_label(window.label()).

ensure_main_window_label(label) (src-tauri/src/commands/security.rs:5)

Returns Ok(()) when label is "main", Err("This command is only available from the main window (got <label>).") otherwise.

Tests (:15)

accepts_main_window and rejects_secondary_windows (the latter checks tasks-float, transcript-viewer, and transcription-preview are all rejected).

Where ensure_main_window is called

Approximately 30 commands. The Settings flows (model loads, LLM lifecycle, hotkey wiring, intentions CRUD), most of the diagnostics report flows, the transcription / live commands, the windows-builder commands, the audio-capture commands, the prefs save, the updater stubs.

NOT called from: profiles, transcripts, tasks (most), feedback, hardware, meeting, fs, clipboard, hardware, tts, hotkey-status probe, llm-status probe, llm content-tag extraction, get_os_info. Each omission is intentional today (secondary windows need to call them) but document the choice when adding new commands.

Data flow

Both modules are passive utilities. PowerAssertion is RAII: hold it for the duration of the work, drop it (explicitly or by leaving scope) to end the pin. ensure_main_window is a synchronous gate at the top of a command body.

Watch-outs

• PowerAssertion is a no-op on Linux and Windows. Long sessions on those platforms can be idled. Document this in the user-facing Settings → AI page if you ship without a Linux logind / Windows SetThreadExecutionState implementation. The macOS objc2 binding requires objc2 = "0.6.4" and objc2-foundation = "0.3.2" — bumping them is an ABI move.
• The registry is process-wide and locked behind a Mutex. Acquiring or releasing an assertion takes the mutex. Acceptable for single-digit assertions per session; if you ever spam-create assertions, this will contend.
• ensure_main_window rejects with a static message containing the offending label. Include the label so debugging via the frontend toast is obvious; do not log the full window or any secret data.
• The ACL plus ensure_main_window is two layers. Removing the second layer is "defence-in-depth removal", which the in-repo code review (docs/code-review-2026-04-22.md) flags as a non-trivial security regression. Don't.

See also

• App lifecycle — the panic hook and runtime warnings live alongside power.
• Diagnostics — the report bundler reads active_assertions_snapshot().
• Capabilities and ACL — the ACL is the first layer; this is the second.
• Live, LLM — the main consumers of PowerAssertion.
• Tests — accepts_main_window and rejects_secondary_windows plus power_assertion_is_a_no_op_drop.