Prevent sleep while running for increased reliability

[KayleeWilliams]

Currently when running long-tasks there is a risk of the device falling asleep, this can cause connection issues & interrupt the active task. This is a feature I've found useful on the Codex app.

We should ensure it only runs while a thread is active/running.

I think this would use https://www.electronjs.org/docs/latest/api/power-save-blocker ? And we'd want to use prevent-app-suspension so the app isn't suspended but the screen etc can still turn off e.g. so policies like auto-locking the device after 10 mins of inactivity isn't affected by long running tasks.

I can work on this feature in my free time if needed.

[leo-mathurin]

I have a working implementation of this, following what the issue proposed: a powerSaveBlocker("prevent-app-suspension") held only while an agent has an active turn, so the display can still turn off and lock policies are unaffected.

Scope decisions to keep it small:

• New setting in Settings > General, off by default, desktop only: "Caffeinate while agents are running"
• Only agents hosted by this desktop app count (primary local and WSL backends). Agents on SSH, relay, or remote environments survive local sleep, so they do not hold the machine awake.
• Releases below 10% battery while discharging, re-acquires when charging or back above the threshold (Battery Status API, event driven, no polling).
• The blocker lives in the main process behind the typed IPC bridge; a crashed or closed renderer releases it, and quitting the app drops the OS assertion.

Verified live on macOS: the assertion shows up in pmset -g assertions seconds after a turn starts and is released when the turn settles. About 300 lines of product code plus tests and a short user doc.

Windows and Linux go through the same cross-platform Electron API, but I could only verify end to end on macOS. If a Windows or Linux user wants to try the branch and confirm (powercfg /requests on Windows, systemd-inhibit --list on Linux), that would be great.

Opening a PR shortly.

[squidllee]

If you still need help, id love to test this out on Windows to help get it merged

[satyalyadav]

Filling in the Windows and Linux evidence that #5535 asked for and could not get, because it was only verified on macOS.

Why the WSL case is not covered by the provider's own flag

For a WSL environment, a provider's sleep prevention cannot help. Codex's prevent_idle_sleep calls systemd-inhibit inside the WSL namespace, and WSL2 has no power management of its own, so the assertion is scoped to the VM and never reaches the Windows host that actually powers down. Holding a Windows host awake needs a Win32 power request, and the desktop client's Electron main process is the only process in the stack that can make one. So for local and WSL environments this is either a T3 Code feature or nothing.

The same applies to a WSL-hosted Codex thread specifically, which is why enabling prevent_idle_sleep is not a workaround here.

What I measured

WSL2 on Windows 11 Home, "Legion Balance Mode" power scheme, codex-cli 0.157.1.

• powercfg /q SCHEME_CURRENT SUB_SLEEP STANDBYIDLE reports 0x00000000 for both AC and DC. That is the current workaround, the idle sleep timer disabled outright, and it is why the machine does not sleep after threads finish. Restoring a real value is the fix for that half, and it is independent of this feature.
• powercfg /requests is empty when no turn is running, so nothing is being leaked or held between turns on a machine that never took the assertion.
• WSL has systemd as PID 1 and systemd-inhibit at /usr/bin/systemd-inhibit, confirming the Linux backend is present and running, while still being unable to affect the host sleep timer.

What I can add

I can build the #5535 branch, run a turn against a WSL environment, and confirm the assertion appears in powercfg /requests while the turn runs and clears when it settles. That is the one piece of evidence the previous attempt did not have. Happy to open a PR with that verification if it is wanted.