Add unattended AI power orchestration

[quasar2333]

Summary

This adds an explicit, lifecycle-aware power orchestration layer for Codex, Claude Code, Gemini CLI, and other local AI agents.

What changed

• Add bounded wake leases with acquire, heartbeat, renew, inspect, and release operations.
• Combine concurrent Agent leases so the Mac sleeps only after the final task releases ownership.
• Expose leases through the keepresso CLI, a bundled Codex Skill, and a local stdio MCP server.
• Discover enabled local Codex automations without retaining task prompts.
• Schedule an early firmware wake, check battery, power, network, and application readiness, then hand wake ownership to a correlated Agent lease.
• Lock the screen and sleep the display during unattended work, then restore normal power state and sleep the Mac after completion.
• Add durable helper recovery, lease persistence, timeout handling, audit logs, status reporting, safety limits, and localized UI.
• Accept opaque Codex project IDs, including UUIDs, instead of assuming the older local-* prefix.

Why

Traditional keep-awake apps only create a persistent assertion. AI automation needs a bounded lifecycle:

1. Wake before a scheduled run.
2. Verify the machine is ready.
3. Keep the system running while one or more Agents own active leases.
4. Recover safely from crashes, missed releases, helper restarts, and reboots.
5. Restore the prior sleep configuration and sleep after the final task ends.

Validation

• swift build passes with the available Command Line Tools.
• A real MacBook Air scheduled-wake test woke at 04:47 for a 04:50 automation.
• The Agent acquired a lease, completed a 12-step workload, and released the lease at 05:00:04.
• macOS entered a real Software Sleep at 05:00:13, nine seconds after release.
• The machine remained asleep for 55 seconds and woke at 05:01:08 due to user activity.
• Explicit lease preflight confirmed that acquiring a lease applies the sleep override and releasing it restores the previous value.

Current test limitation

swift test cannot run on the current machine because only Command Line Tools are installed and the Swift Testing module is unavailable. Core compilation succeeds, and the full suite is expected to run in GitHub Actions with the repository's Xcode toolchain.

This is intentionally opened as a draft because the change is broad and benefits from maintainer guidance on review and possible PR splitting.

[gyorgysh]

Hi @quasar2333, thank you for this proposal and for the real testing behind it. There are genuinely good ideas here, and the draft was useful to think against.

I won't be merging this PR. It bundles many concerns at once (leases, Codex automation discovery, helper rework, release pipeline changes, translations), and much of it is built around one agent's workflow. Keepresso serves a wider set of uses (render jobs, backup scripts, media servers, gaming, headless Macs, and many different AI tools), so machine control has to stay vendor-neutral: no per-vendor config scanning, no bundled integrations for a single product.

That said, the core concept was worth building, and I have implemented it independently for the next release:

• Automation leases: bounded keep-awake grants with acquire, heartbeat, release, and list, TTL plus a hard lifetime ceiling, caller-supplied UUIDs as idempotency keys, unioned as one demand source. Any tool that can run a command gets the same treatment.
• An embedded MCP server, so any MCP-capable agent (Claude Code, Codex, Gemini CLI, and whatever comes next) can use the same operations.
• Opt-in wake schedule control behind a default-off preference, since a root-applied schedule change deserves an explicit user decision.
• The helper now restores the exact prior disablesleep value instead of assuming zero. Your "never assume the original value was zero" point was correct.

The lease idea is credited to you in the changelog, and that credit will appear on the release page: "The lease concept was inspired by a proposal from @quasar2333 in PR #3."

Closing this one, but I'd be glad to see focused, vendor-neutral PRs from you in the future. Smaller scope makes them much easier to review and land. Thanks again for pushing the idea forward.