pmset disablesleep fix keeps Claude Code alive with lid shut

The problem the author describes is not a bug in the code or the API — it's macOS itself. When the lid closes without an external display attached, the machine enters what the logs call "Clamshell Sleep", and a request that was in flight at that moment is cut. The failure doesn't surface immediately; it was recorded hours later, during a DarkWake, as "Request timed out". That gap is why the symptom looks mysterious and the cause is easy to misattribute.

The tools that seem like they should help don't. `--bg` background sessions and Remote Control both keep execution on the local Mac, so they are preserved across sleep but produce no progress during it. `caffeinate` and the Desktop app's "Keep computer awake" setting only target idle sleep — as the macOS SDK comment quoted in the piece puts it, the system may still sleep for lid close, low battery, or other reasons. The author also points out that idle sleep is already handled: Claude Code itself spawns a `caffeinate -i -t 300` child process, so the only remaining gap is the lid.

The proposed fix, `sudo pmset -a disablesleep 1`, has to be run in an ordinary Terminal, because Claude Code's `!` bash mode has no terminal to read a password. Interestingly, the `AppleClamshellCausesSleep` flag still reads `Yes` even after the change; based on a reading of the public XNU source, `SleepDisabled` sets a separate `userDisabledAllSleep` path that rejects the clamshell sleep request, so `pmset -g log` is the more reliable check. The author tested this once, only on battery, with the lid closed for an unrecorded period, and warns the option isn't documented — hence the caution about power draw, heat, and remembering to reset it.