Wake Lock

SnakeFlow can prevent the operating system from sleeping (and optionally keep the display on) while you are actively working in the editor or while Quality Hub runs checks. This uses OS-native APIs (SetThreadExecutionState on Windows, caffeinate on macOS, systemd-inhibit on Linux).

Wake Lock is separate from Team Tracker → time counting: the tracker uses its own dual-factor rules (ActivityWatch + OS idle + IDE focus) and does not treat “wake lock held” as proof of human work.

Two independent holders

Holder	When it runs	How it stacks
Activity tracker	Status-bar toggle ON (default) + `devManager.wakeLock.enabled`	Subscribes to editor events; calls `acquire('Activity')` only while recent activity is within `idleThresholdSeconds`.
Quality Hub	`devManager.wakeLock.autoActivate` + master `enabled`	Calls `acquire('Quality Hub')` for the duration of a full Quality run (separate from the toggle).

Both use the same reference-counted manager: if Quality Hub runs while the activity tracker also holds a lock, refCount is 2 until each path releases. The status-bar tooltip shows refCount and how long the current continuous hold has lasted when the lock is active.

What counts as “activity”

The activity tracker does not pin the lock for the entire lifetime of a VS Code task or debug session. onDidStartTask / onDidEndTask and debug start/end only bump the activity clock once each — they are signals, not anchors. A long-running dev server that emits no further signals releases the lock after idleThresholdSeconds (default 120 s) of silence.

Events that refresh the clock (subject to filtering):

Text edits in real documents (onDidChangeTextDocument) — schemes like output, vscode-scm, git, vscode are ignored.
Save (onDidSaveTextDocument).
Selection / cursor in the editor (debounced).
Task start / end — one bump per event, not “held until task exits”.
Debug session start / terminate — same.
Terminal shell execution start / end (when the VS Code API exposes these) — real command runs; not terminal open/close/focus/resize (those were removed because they caused false positives).

Not wired to Wake Lock: AI chat “thinking” without file edits, passive file watchers that do not surface as document changes, and merely having a server process running without the signals above.

If you need the PC awake during long chat-only agent phases with no edits, increase devManager.wakeLock.idleThresholdSeconds (e.g. 300–600) in All settings →.

Long-running tasks and sleep

Previously, any running task could keep the lock forever (isActive stayed true while _ongoingTasks was non-empty). That is fixed: a vite / watch task that never fires onDidEndTask no longer blocks sleep after the idle threshold.

Caveat: if a watcher writes files under a normal file:// workspace URI, those edits still count as activity (same as an agent editing code). Exclude noisy trees via your own workflow (e.g. do not open the repo root that receives constant generated writes) or raise the idle threshold.

Long-hold warning

devManager.wakeLock.maxHoldHours (default 4, 0 = off) starts a soft timer: if refCount stays above zero continuously for that long, SnakeFlow logs a warning and can show a notification with Release now / Show log. It does not force-release (a legitimate very long Quality run could exceed the window).

Use this to catch leaks (stuck helper, forgotten acquire path).

Persistent log file

devManager.wakeLock.persistLog (default false): when enabled and a workspace folder is open, lines from the SnakeFlow: Wake Lock output channel are also appended to:

<workspace>/.vscode/snakeflow-wakelock.log or <workspace>/.cursor/snakeflow-wakelock.log

depending on the IDE (same rule as other SnakeFlow dot-dir files). The file is rotated when it exceeds 1 MB (previous content moved to snakeflow-wakelock.log.1).

Diagnostics

Command Palette → SnakeFlow: Wake Lock — Diagnose — dumps manager state, refCount, activity flag, and OS hints (e.g. powercfg where available). On Windows, powercfg /requests may require an elevated terminal for full detail.
Status bar Wake item: when the lock is active (Awake), hover shows refCount and hold duration.

Settings quick reference

Full tables: All settings → Wake Lock.

Key	Role
`devManager.wakeLock.enabled`	Master switch; when false, activity tracker and Quality Hub acquire are no-ops.
`devManager.wakeLock.autoActivate`	Acquire during Quality Hub runs.
`devManager.wakeLock.idleThresholdSeconds`	Editor inactivity before releasing the activity lock.
`devManager.wakeLock.keepDisplayAwake`	Also keep the monitor on (Windows `ES_DISPLAY_REQUIRED`; no-op for display on some Linux setups).
`devManager.wakeLock.maxHoldHours`	Long continuous hold → warning.
`devManager.wakeLock.persistLog`	Mirror log to `snakeflow-wakelock.log`.
`devManager.wakeLock.readyTimeoutMs` / `startRetries`	Helper spawn tuning.