feat(sleep): prevent system sleep during runs

[kunchenguid]

Summary

Adds built-in sleep prevention for long-running gnhf runs and hardens the surrounding lifecycle so it works across macOS, Linux, and Windows. The change is not just a new flag: it also fixes shutdown, subprocess cleanup, stdin handoff, and cross-platform verification so overnight runs do not leave helper processes behind.

Risk Assessment: 🟡 Medium — Well-covered cross-platform lifecycle changes look mergeable, but default-on sleep prevention and two unresolved re-exec edge cases keep the risk at medium.

Architecture

flowchart TD
subgraph runtime["Run Lifecycle"]
  direction TB
  config["Config defaults + --prevent-sleep (updated)"]
  cli["CLI entrypoint (updated)"]
  renderer["Renderer stop handling (updated)"]
  orchestrator["Orchestrator shutdown flow (updated)"]
  sleep["SleepPrevention service (added)"]
  proc["Managed process helpers (added)"]
  agents["OpenCode / RovoDev servers (updated)"]
  debug["Debug log sink (added)"]

  config -->|"enables or disables sleep prevention"| cli
  cli -->|"starts run UI"| renderer
  renderer -->|"requests stop"| orchestrator
  cli -->|"starts and cleans up"| sleep
  orchestrator -->|"closes agent backends"| agents
  sleep -->|"uses for helper shutdown"| proc
  agents -->|"uses for server shutdown"| proc
  cli -->|"writes run and signal events"| debug
  sleep -->|"writes helper lifecycle events"| debug
  agents -->|"writes spawn and shutdown events"| debug
end

subgraph helpers["Platform Sleep Helpers"]
  direction TB
  linux["systemd-inhibit re-exec wrapper (added)"]
  stdin["stdin prompt handoff (added)"]
  mac["caffeinate helper (added)"]
  win["PowerShell sleep blocker (added)"]

  stdin -->|"restores piped prompt inside"| linux
end

cli -->|"serializes piped prompt for"| stdin
sleep -->|"re-execs under"| linux
sleep -->|"spawns on macOS"| mac
sleep -->|"spawns on Windows"| win

Loading

Key changes made

• Added preventSleep to config with a default of true, plus a --prevent-sleep on|off runtime override and README/docs updates.
• Introduced a new sleep-prevention layer that uses caffeinate on macOS, systemd-inhibit re-exec plus readiness/stdin handoff on Linux, and a PowerShell SetThreadExecutionState helper on Windows.
• Added shared child-process shutdown utilities and updated the CLI, renderer, orchestrator, opencode, and rovodev shutdown paths so signals, timeouts, and late agent results are handled cleanly.
• Added JSONL debug logging, cross-platform CI, and new unit/e2e coverage including mock opencode fixtures and Windows-friendly wrappers.

How was this tested

• Full build+test suite passed, and manual macOS end-to-end validation confirmed sleep prevention activates and cleans up correctly on both normal completion and SIGINT shutdown.
• Lint passed using cached script (no agent needed)

Critique Comments

• 🟡 src/cli.ts:145 - Validate GNHF_REEXEC_STDIN_PROMPT_FILE with isTrustedReexecPromptPath() before readFileSync(). As written, any inherited env value can make gnhf read an arbitrary local file and use its contents as the agent prompt.
• 🟡 src/core/sleep.ts:384 - If SIGINT/SIGTERM arrives while waiting for systemd-inhibit readiness and the helper never exits, this timeout branch falls back to an unprotected normal run instead of honoring the interrupt. Record the received signal and return its exit code here so startup cannot continue after the user tried to stop it.