pmset -g assertions      # look for a PreventUserIdleDisplaySleep holder

---
name: hd-screen-lock-mac
description: >
  macOS platform companion to hd-screen-lock — the Apple-specific half of the display
  wake-lock that a getDisplayMedia capture asserts. The cross-platform story (HD is
  native → CDP screenshots hold no lock; the recording cap + "● Recording" indicator;
  the contention guard) lives in hd-screen-lock (adom/hd-bootstrap); THIS skill carries
  only the macOS power-assertion mechanics: the IOKit IOPMAssertion
  (PreventUserIdleDisplaySleep), diagnosing the holder with `pmset -g assertions`, and
  `caffeinate`. Mirror of hd-screen-lock-windows (SetThreadExecutionState /
  ES_DISPLAY_REQUIRED, `powercfg /requests`). Trigger words — macos display wake-lock,
  iopmassertion, preventuseridledisplaysleep, pmset assertions, caffeinate, display
  won't sleep mac, screensaver blocked mac, screen capture assertion safari.
---

# hd-screen-lock (macOS) — IOKit power assertions & the display wake-lock

This is the **macOS half** of `hd-screen-lock`. The core point — HD is native, so its
**CDP screenshots hold no wake-lock** (no `MediaStream`, one-shot grab) and the web
`getDisplayMedia` burn-in leak **cannot happen from HD's own capture** — plus the
recording cap, the "● Recording" indicator, and the multi-thread contention guard, are
cross-platform and live in the generic **hd-screen-lock** skill. Read that first; this
skill only covers the Apple power-state mechanics.

## What asserts the lock on macOS

A `getDisplayMedia` screen capture asserts an **IOKit power assertion** of type
`kIOPMAssertionTypePreventUserIdleDisplaySleep` (via `IOPMAssertionCreateWithName`).
While it's held the OS **won't run the screensaver or sleep the display** → burn-in.
This is the macOS analog of Windows' `SetThreadExecutionState(ES_DISPLAY_REQUIRED)`.

On macOS HD itself does **not** assert this for screenshots (CDP is one-shot,
assertion-free). It legitimately appears only when a **`getDisplayMedia` recording**
runs — the in-app recorder, an AD desktop recording, or a pup tab capture (see
[hd-recording-mac]). Release it by **stopping that recording**; a programmatic focus or
the screensaver itself cannot clear another process's assertion.

## Diagnose the holder — `pmset -g assertions`

If you find the display pinned awake:

```bash
pmset -g assertions      # look for a PreventUserIdleDisplaySleep holder
```

- A **browser** holder (a Safari/Chrome "screen capture" assertion) = a `getDisplayMedia`
  hold from web Hydrogen, the in-app recorder, or a pup tab — stop that capture (close
  the tab / `browser_record_stop` / stop the in-app recording), not an HD-shell problem.
- The **HD app process** holding `PreventUserIdleDisplaySleep` from a CDP **screenshot**
  is unexpected (CDP capture holds no assertion) — capture it and file a bug.

`caffeinate` is the macOS CLI that holds the same assertion deliberately (e.g.
`caffeinate -d`); if you see it in `pmset -g assertions`, something invoked it on
purpose — it is not HD.

## NOT here (lives in the Windows companion)

The Windows wake-lock mechanics — `SetThreadExecutionState(ES_DISPLAY_REQUIRED)` as the
lock primitive, and diagnosing the holder with `powercfg /requests` (the elevated
`DISPLAY:` section) — are in `hd-screen-lock-windows`. On macOS it's the IOKit
`IOPMAssertion` + `pmset -g assertions`, full stop.