Maintain Insomnia

Reference pages in https://github.com/krishhgg/Insomnia: docs/recovery.md, docs/install.md, docs/lid-close.md and docs/extras.md.

Rules

• Never run sudo, pmset changes, kill or kill -CONT yourself. Show the user the command, say why, and let them run it.
• Never edit or delete files in ~/Library/Application Support/Insomnia/. state.json there is the recovery journal: the list of changes Insomnia still has to undo.
• Never signal a pid taken from an old log line. Pids get reused. Check it with ps -o pid,stat,lstart,command -p <pid> first.
• Kong's Insomnia API client uses the same support folder name. brew uninstall --zap insomnia for that app moves this app's journal to the Trash. Check which app the user means before anything like that.

Check the state

1. tail -n 100 ~/Library/Logs/Insomnia/insomnia.log shows what the app and the recovery agent did last.
2. pmset -g | grep -i sleepdisabled shows 1 while sleep is turned off.

3. cat ~/Library/Application\ Support/Insomnia/state.json shows what is still waiting to be undone. These entries are pending:

   • sleepDisabledByUs, lowPowerSetByUs or dockerFrozen set to true
   • a non-empty frozenProcesses, appNapOverrides or savedAudioOutputs
   • savedOutputVolume or savedMuted
   • savedDisplayBrightness or savedKeyboardBrightness, unless displayRestoreRefused or keyboardRestoreRefused is true

   Other keys, such as keptDisplayReadLit, keptDisplayUnderLowPower and displayRestoredUnderLowPower, are records the app keeps, not changes to undo. A brightness value kept after a refused restore blocks nothing. Saved audio for an output that isn't connected waits for it to reconnect and doesn't block ending a session.

4. launchctl print gui/$(id -u)/com.insomnia.backstop shows whether the recovery agent is loaded.

Warnings in the menu

Match the warning to docs/recovery.md, "Recovery limits and manual attention".

• A stuck power command with a pid. The user checks the pid, then runs the sudo kill <pid> the menu shows.
• Stopped processes Insomnia cannot prove it froze. The user checks each pid with ps and decides whether to run kill -CONT <pid>.
• An output device still muted. Reconnect it and open Insomnia, or choose "Stop waiting for <device>" in the menu.
• Sleep disabled by something else. Insomnia did not set it and leaves it alone. Whoever set it turns sleep back on with sudo pmset -a disablesleep 0.
• Hotspot password unreadable by this build. A reinstall changes the app's signature. Enter the password again in Settings.

Uninstall

Follow "Uninstall" in docs/install.md and hand the user the command, since it asks for the password. It stops when something is still waiting to be undone. Fix that first, then run it again. A failed uninstall does not mean the power settings are back to normal, so check pmset -g afterward.