# How KeepAwakeManager Handles Power Assertions and Lid-Closed State in vorssaint-utils

> Learn how KeepAwakeManager in vorssaint-utils prevents macOS sleep using IOKit power assertions and manages lid-closed state with pmset for uninterrupted operation.

- Repository: [vorssaint/vorssaint-utils](https://github.com/vorssaint/vorssaint-utils)
- Tags: internals
- Published: 2026-09-11

---

**KeepAwakeManager prevents macOS sleep by creating IOKit power assertions for system and display idle prevention, while optionally managing clamshell mode through password-less sudo rules that execute `pmset disablesleep`.**

The `KeepAwakeManager` class in the **vorssaint-utils** repository serves as the central coordination service for maintaining macOS wakefulness during user-requested sessions. It implements a dual-layered approach combining IOKit power assertions for standard sleep prevention with specialized handling for lid-closed scenarios through system-level power management commands.

## Creating IOKit Power Assertions

The manager creates **IOKit power assertions** through the `applyAssertions()` method in [`Sources/Vorssaint/Services/KeepAwakeManager.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Services/KeepAwakeManager.swift). These assertions interface directly with macOS power management to block idle sleep triggers.

### Preventing System Idle Sleep

To inhibit system-wide sleep, the manager creates an assertion of type `PreventUserIdleSystemSleep` using `IOPMAssertionCreateWithName`. The resulting `IOPMAssertionID` is stored in the `systemAssertion` property for later release. This mechanism is implemented in lines 15-27 of [`KeepAwakeManager.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/KeepAwakeManager.swift).

When the session ends, `releaseAssertions()` invokes `IOPMAssertionRelease` on the stored ID to restore normal sleep behavior (lines 45-56).

### Preventing Display Sleep

Display sleep inhibition operates conditionally based on the `DefaultsKey.keepAwakeAllowDisplaySleep` preference. When the user disables display sleep, `applyAssertions()` creates a second assertion of type `PreventUserIdleDisplaySleep`, storing the ID in `displayAssertion`. If the user enables display sleep, any existing display assertion is immediately released.

This logic is handled within lines 27-44 of the same file, ensuring the display assertion state always reflects current user preferences.

## Managing Lid-Closed (Clamshell) State

Beyond standard idle assertions, **KeepAwakeManager** implements **clamshell mode** handling to prevent sleep when the laptop lid is closed. This requires elevating privileges to modify system power settings.

### Password-Less Sudo Configuration

The manager avoids repeated password prompts by utilizing a **password-less sudoers rule** defined in [`Sources/Vorssaint/Support/Sudoers.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Support/Sudoers.swift). When `applyClamshellPreference()` detects that `clamshellPreferred` is enabled (defined in [`Sources/Vorssaint/Core/Defaults.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Core/Defaults.swift)), it first checks for the existence of the `passwordlessClamshell` rule.

If the rule is missing, `prepareClamshellPreference()` installs it via `Sudoers.install` and sets a retry flag (`clamshellSetupRetried`) to attempt activation once after installation completes. This setup flow spans lines 58-107 in [`KeepAwakeManager.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/KeepAwakeManager.swift).

### Enabling and Disabling Clamshell Mode

Once the sudoers infrastructure exists, `enableClamshell()` executes `Sudoers.pmsetDisableSleep(true)` to invoke `pmset disablesleep 1`, preventing the system from sleeping when the lid closes. The method updates the published properties `clamshellActive`, `clamshellSetupInProgress`, and `clamshellSetupFailed` to reflect the operation state.

Termination requires `disableClamshell(_:)`, which accepts a synchronous parameter. When the app quits, it runs synchronously to guarantee cleanup; during normal operation, it runs asynchronously. This teardown logic is located in lines 124-148.

## Session Lifecycle Coordination

Session state changes are orchestrated through `activate(minutes:)` and `deactivate(reason:)`, defined in lines 50-63 and 92-107 respectively.

When activation occurs, the manager first checks `sessionPausedForScreenLock` to determine if the screen is currently locked. If not paused, it immediately invokes `applyAssertions()` and conditionally calls `applyClamshellPreference()` when `clamshellPreferred` is true.

Deactivation triggers a comprehensive teardown: `releaseAssertions()` clears both system and display IOKit assertions, while `disableClamshell(synchronous:)` restores normal lid-close behavior. This ensures no power assertions or system modifications persist beyond the intended session duration.

## Practical Implementation Examples

The following patterns demonstrate typical usage of the **KeepAwakeManager** API:

```swift
import Vorssaint

// Initiate a 10-minute keep-awake session
KeepAwakeManager.shared.activate(minutes: 10)

// Enable clamshell mode to prevent sleep when closing the lid
UserDefaults.standard.set(true, forKey: DefaultsKey.clamshellPreferred)

// Manually terminate the current session and restore power settings
KeepAwakeManager.shared.deactivate(reason: .manual)

```

## Summary

- **KeepAwakeManager** creates `PreventUserIdleSystemSleep` and optional `PreventUserIdleDisplaySleep` assertions via `applyAssertions()` to block macOS idle sleep.
- **Clamshell mode** is managed through password-less sudo rules that execute `pmset disablesleep`, with on-demand installation and retry logic in `prepareClamshellPreference()`.
- **State cleanup** is guaranteed through `releaseAssertions()` and `disableClamshell()`, called during `deactivate(reason:)` to restore normal power management.
- **Session coordination** respects screen-lock states and user preferences defined in [`Defaults.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Defaults.swift), ensuring assertions only apply during active, unlocked sessions.

## Frequently Asked Questions

### What IOKit power assertion types does KeepAwakeManager use?

The manager utilizes two distinct assertion types: `PreventUserIdleSystemSleep` to block system-wide idle sleep, and `PreventUserIdleDisplaySleep` to inhibit display dimming and sleep. These are created via `IOPMAssertionCreateWithName` and stored as `IOPMAssertionID` values in `systemAssertion` and `displayAssertion` respectively.

### How does KeepAwakeManager handle lid-closed sleep without requiring a password every time?

It installs a **password-less sudoers rule** via `Sudoers.install` that permits the specific `pmset disablesleep` command without authentication. The `passwordlessClamshell` property checks for this rule's existence; if missing, the manager installs it once and retries the operation using `clamshellSetupRetried`, avoiding interactive password prompts during normal usage.

### What happens to power assertions when the session ends or the app quits?

The `deactivate(reason:)` method calls `releaseAssertions()`, which invokes `IOPMAssertionRelease` on both the system and display assertion IDs. For clamshell mode, `disableClamshell(synchronous:)` runs `pmset disablesleep 0` to re-enable normal lid-close behavior, ensuring all power management restrictions are cleared synchronously during app termination.

### Can KeepAwakeManager prevent display sleep independently of system sleep?

Yes. The manager checks `DefaultsKey.keepAwakeAllowDisplaySleep` to determine whether to create the `PreventUserIdleDisplaySleep` assertion. When this preference is false, it creates only the system sleep assertion, allowing the display to sleep while keeping the machine awake for background processing.