docs(wake-lock): record wake-lock change workflow

Add the wake-lock SCR, discussion summary, and task artifacts that captured investigation, specification, and implementation handoff for the system-sleep-only behavior change.

docs/features/wake-lock/SPECIFICATION.md

@@ -0,0 +1,17 @@
+# Wake Lock Behavior
+
+## Product Rule
+
+CodeNomad only requests a wake lock for qualifying active work that is already running and can continue without continuous foreground interaction. The goal is to prevent idle system sleep where the platform supports that behavior without intentionally keeping the display awake.
+
+Wake lock must not be held when work is idle, paused, completed, cancelled, failed, or waiting for new user input or permission before it can continue.
+
+## Platform Behavior
+
+- **Electron:** request system-sleep-only behavior with `prevent-app-suspension`.
+- **Tauri:** request the native keep-awake mode with `display: false`, `idle: true`, and `sleep: false`.
+- **Web:** do not fall back to `navigator.wakeLock.request("screen")`; if a true system-sleep-only primitive is unavailable, CodeNomad degrades to no wake lock.
+
+## Release Expectations
+
+Wake lock should be released promptly when qualifying active work ends or when the app cleans up the active session lifecycle.

docs/scrs/SCR-2026-04-21-001-wake-lock-system-sleep-only.md

@@ -0,0 +1,79 @@
+---
+id: SCR-2026-04-21-001
+title: Wake lock should allow screen lock while preventing system sleep
+status: draft
+---
+
+# Summary
+
+Refine wake-lock behavior so the product protects long-running active work from device/system sleep without intentionally keeping the display awake. The desired product experience is: users may lock the screen or let the display sleep, and in-platform work should continue whenever the platform can support that behavior.
+
+# Problem
+
+Current wake-lock behavior on desktop is oriented around display wake, which prevents normal screen lock or display sleep behavior on macOS and does not match the requested product outcome. The Product Owner wants wake lock to protect only against system/device sleep during active work, not against display sleep or screen lock. Scope includes Electron, Tauri, and web, with documented best-effort degradation where platform APIs cannot provide a system-sleep-only capability.
+
+# Requested Outcome
+
+- Allow the screen/display to sleep or lock normally while qualifying work is in progress.
+- Prevent only system/device sleep during qualifying active work on platforms that support a system-sleep-only hold.
+- Keep platform behavior aligned to a single product rule: never intentionally keep the display awake as a fallback for this feature.
+- Apply the behavior across Electron, Tauri, and web using best-effort platform support with explicit limitation handling.
+
+# Product Scope
+
+## Active Work Definition
+
+For this change, **active work** means a user-initiated or product-initiated in-app operation that:
+
+- has started execution,
+- is represented by the product as still in progress,
+- is expected to continue without continuous foreground interaction, and
+- would lose reliability or stop early if the device enters normal system sleep.
+
+Active work does **not** include:
+
+- the app merely being open or focused,
+- idle viewing or reading states,
+- paused, completed, failed, or cancelled work,
+- states waiting indefinitely for new user input before further execution, or
+- generic background presence without a currently running task.
+
+## Product Behavior Rule
+
+- When active work starts, the product may request a wake lock only if the platform can do so **without intentionally blocking screen lock or display sleep**.
+- When active work ends, pauses, fails, is cancelled, or no longer needs protection, the product must release the wake lock promptly.
+- The product intent is consistent across platforms, but implementation is **best-effort by platform capability**, not strict-identical by mechanism.
+
+## Fallback Policy
+
+- If a platform can provide **system-sleep-only** protection, the product should use it.
+- If a platform can only provide a **display/screen wake** lock that keeps the screen awake, the product must **not** use that mode as a fallback for this feature.
+- In unsupported or partially supported environments, the product should fall back to **no wake lock** rather than preserving the old display-wake behavior.
+- Unsupported behavior must be treated as a documented platform limitation, not as a product failure.
+
+## Platform Expectations
+
+- **Electron:** In scope to use a system-sleep-only mode if available.
+- **Tauri:** In scope to use a system-sleep-only mode if available through the chosen Tauri/native path.
+- **Web:** Default expectation is unsupported or partially supported for this exact behavior unless a browser/runtime exposes a true system-sleep-only primitive. A screen wake lock that keeps the display awake is not an acceptable substitute.
+
+## Non-Goals
+
+- Keeping the display continuously awake during long-running work.
+- Preserving current display-wake behavior on platforms where that is the only available wake-lock mode.
+- Inventing platform-specific user settings to choose between display wake and system-sleep-only behavior as part of this SCR.
+
+# Acceptance Criteria
+
+- AC-1: The specification defines **active work** in user-observable product terms, including the states that do and do not qualify for wake-lock protection.
+- AC-2: The specification defines a single cross-platform product rule: qualifying active work should protect against system sleep where possible, while screen lock and display sleep remain allowed.
+- AC-3: The specification defines the fallback policy for unsupported platforms: if system-sleep-only protection is unavailable, the product must not substitute display/screen wake behavior and must instead degrade to no wake lock.
+- AC-4: Platform expectations are documented for Electron, Tauri, and web, including the explicit expectation that web is best-effort and may remain unsupported for this exact behavior.
+- AC-5: The specification defines wake-lock release expectations so protection ends promptly when qualifying active work is no longer running.
+- AC-6: Any implementation derived from this SCR must document user-visible limitations for unsupported platforms in the appropriate product-facing documentation if final technical validation confirms those limitations.
+
+# Implementation Notes For Follow-On Technical Assessment
+
+- Electron and Tauri feasibility still requires technical validation of the exact API mode, lifecycle reliability, and background-execution behavior.
+- Web feasibility still requires confirmation of browser/runtime support, permission constraints, visibility restrictions, and whether any supported runtime offers a true system-sleep-only primitive.
+- If technical validation shows a desktop platform cannot provide system-sleep-only behavior safely, implementation should follow the fallback policy above rather than retaining display-wake behavior.

packages/electron-app/electron/main/ipc.ts

@@ -92,7 +92,7 @@ export function setupCliIPC(mainWindow: BrowserWindow, cliManager: CliProcessMan
         return { enabled: true }
       }
       try {
-        wakeLockId = powerSaveBlocker.start("prevent-display-sleep")
+        wakeLockId = powerSaveBlocker.start("prevent-app-suspension")
       } catch {
         wakeLockId = null
         return { enabled: false }

packages/tauri-app/src-tauri/src/main.rs

@@ -145,8 +145,8 @@ fn wake_lock_start(
     config: Option<WakeLockConfig>,
 ) -> Result<(), String> {
     let config = config.unwrap_or(WakeLockConfig {
-        display: true,
-        idle: false,
+        display: false,
+        idle: true,
         sleep: false,
     });
 

packages/ui/src/App.tsx

@@ -50,7 +50,7 @@ import {
   updateSessionModel,
 } from "./stores/sessions"
 
-import { getInstanceSessionIndicatorStatus } from "./stores/session-status"
+import { hasWakeLockEligibleWork } from "./stores/session-status"
 import { openSettings } from "./stores/settings-screen"
 import {
   closeSidecarTab,
@@ -204,8 +204,7 @@ const App: Component = () => {
   const shouldHoldWakeLock = createMemo(() => {
     const map = instances()
     for (const id of map.keys()) {
-      const status = getInstanceSessionIndicatorStatus(id)
-      if (status !== "idle") {
+      if (hasWakeLockEligibleWork(id)) {
         return true
       }
     }

packages/ui/src/components/tool-call/diagnostics.ts

@@ -58,7 +58,9 @@ export function extractDiagnostics(state: ToolState | undefined): DiagnosticEntr
   const diagnosticsMap = metadata?.diagnostics as DiagnosticsMap | undefined
   if (!diagnosticsMap) return []
 
-  return buildDiagnosticEntries(diagnosticsMap, [input.filePath, metadata.filePath, metadata.filepath, input.path])
+  return buildDiagnosticEntries(diagnosticsMap, [input.filePath, metadata.filePath, metadata.filepath, input.path].map((value) =>
+    typeof value === "string" ? value : undefined,
+  ))
 }
 
 export function resolveDiagnosticsKey(diagnostics: DiagnosticsMap, preferredPaths: Array<string | undefined>): string | undefined {

packages/ui/src/lib/native/wake-lock.ts

@@ -9,51 +9,6 @@ let inFlight: Promise<boolean> | null = null
 
 let applied = false
 
-let webWakeLock: any = null
-
-async function setWebWakeLock(enabled: boolean): Promise<boolean> {
-  if (typeof navigator === "undefined") return false
-
-  const api = (navigator as any).wakeLock
-  if (!api?.request) {
-    return false
-  }
-
-  try {
-    if (enabled) {
-      if (webWakeLock) {
-        return true
-      }
-      webWakeLock = await api.request("screen")
-      try {
-        webWakeLock.addEventListener?.("release", () => {
-          // If the lock is released by the UA (e.g., tab hidden), clear local state.
-          webWakeLock = null
-          if (desired) {
-            // Re-acquire best-effort.
-            queueMicrotask(() => {
-              void setWakeLockDesired(true)
-            })
-          }
-        })
-      } catch {
-        // optional
-      }
-      return true
-    }
-
-    if (webWakeLock) {
-      await webWakeLock.release?.()
-    }
-    webWakeLock = null
-    return false
-  } catch (error) {
-    log.log("[wake-lock] web wake lock failed", error)
-    webWakeLock = null
-    return false
-  }
-}
-
 function hasAnyWakeLockSupport(): boolean {
   if (typeof window === "undefined") return false
   if (isElectronHost()) {
@@ -63,7 +18,7 @@ function hasAnyWakeLockSupport(): boolean {
   if (isTauriHost()) {
     return typeof window.__TAURI__?.core?.invoke === "function"
   }
-  return Boolean((navigator as any)?.wakeLock?.request)
+  return false
 }
 
 async function setElectronWakeLock(enabled: boolean): Promise<boolean> {
@@ -89,9 +44,7 @@ async function setTauriWakeLock(enabled: boolean): Promise<boolean> {
     }
 
     if (enabled) {
-      // Match Electron's prevent-display-sleep behavior by keeping the display
-      // awake without blocking explicit system sleep requests.
-      await invoke("wake_lock_start", { config: { display: true, idle: false, sleep: false } })
+      await invoke("wake_lock_start", { config: { display: false, idle: true, sleep: false } })
       return true
     }
 
@@ -108,17 +61,15 @@ async function applyWakeLock(enabled: boolean): Promise<boolean> {
 
   if (isElectronHost()) {
     const ok = await setElectronWakeLock(enabled)
-    if (ok || !enabled) return ok
-    // fallback to web API if electron preload didn't expose it
+    return ok
   }
 
   if (isTauriHost()) {
     const ok = await setTauriWakeLock(enabled)
-    if (ok || !enabled) return ok
-    // fallback to web API if tauri command isn't available
+    return ok
   }
 
-  return await setWebWakeLock(enabled)
+  return false
 }
 
 export function setWakeLockDesired(nextDesired: boolean): Promise<boolean> {

packages/ui/src/stores/session-status.test.ts

@@ -0,0 +1,20 @@
+import assert from "node:assert/strict"
+import { describe, it } from "node:test"
+
+import { shouldSessionHoldWakeLock } from "./wake-lock-eligibility.ts"
+
+describe("shouldSessionHoldWakeLock", () => {
+  it("holds wake lock only for qualifying active work", () => {
+    assert.equal(shouldSessionHoldWakeLock({ status: "working", pendingPermission: false, pendingQuestion: false }), true)
+    assert.equal(
+      shouldSessionHoldWakeLock({ status: "compacting", pendingPermission: false, pendingQuestion: false }),
+      true,
+    )
+    assert.equal(shouldSessionHoldWakeLock({ status: "idle", pendingPermission: false, pendingQuestion: false }), false)
+  })
+
+  it("does not hold wake lock while waiting for permission or input", () => {
+    assert.equal(shouldSessionHoldWakeLock({ status: "working", pendingPermission: true, pendingQuestion: false }), false)
+    assert.equal(shouldSessionHoldWakeLock({ status: "working", pendingPermission: false, pendingQuestion: true }), false)
+  })
+})

packages/ui/src/stores/session-status.ts

@@ -1,11 +1,27 @@
 import type { Session, SessionRetryState, SessionStatus } from "../types/session"
 import { getInstanceSessionIndicatorStatusCached, sessions } from "./session-state"
+import { shouldSessionHoldWakeLock } from "./wake-lock-eligibility"
 
 function getSession(instanceId: string, sessionId: string): Session | null {
   const instanceSessions = sessions().get(instanceId)
   return instanceSessions?.get(sessionId) ?? null
 }
 
+export function hasWakeLockEligibleWork(instanceId: string): boolean {
+  const instanceSessions = sessions().get(instanceId)
+  if (!instanceSessions) {
+    return false
+  }
+
+  for (const session of instanceSessions.values()) {
+    if (shouldSessionHoldWakeLock(session)) {
+      return true
+    }
+  }
+
+  return false
+}
+
 export function getSessionStatus(instanceId: string, sessionId: string): SessionStatus {
   const session = getSession(instanceId, sessionId)
   if (!session) {

packages/ui/src/stores/wake-lock-eligibility.ts

@@ -0,0 +1,11 @@
+import type { Session } from "../types/session"
+
+export function shouldSessionHoldWakeLock(
+  session: Pick<Session, "status" | "pendingPermission" | "pendingQuestion">,
+): boolean {
+  if (session.pendingPermission || session.pendingQuestion) {
+    return false
+  }
+
+  return session.status === "working" || session.status === "compacting"
+}

tasks/current.md

@@ -0,0 +1,19 @@
+# Current Tasks
+
+## Active Discussions
+
+- DISCUSSION-001 — Wake lock behavior change for macOS sleep vs screen lock — summarized, routed to task 056
+
+## Active
+
+- 055-wake-lock-investigation.md — standard / investigation / logic — Assigned to tech_lead
+- 056-wake-lock-behavior-change.md — complex / spec / logic — Assigned to business_analyst
+- 057-implement-system-sleep-only-wake-lock.md — complex / implementation / logic — Assigned to workflow_runner
+
+## Todo
+
+- 023-symbol-attachments.md
+
+## Blocked
+
+- None.

tasks/discussions/DISCUSSION-001-wake-lock-behavior-change-for-macos-sleep-vs-screen-lock.md

@@ -0,0 +1,76 @@
+---
+id: DISCUSSION-001
+title: "Wake lock behavior change for macOS sleep vs screen lock"
+status: closed
+summarized_by: business_analyst
+source: runtime-transcript
+---
+
+# Discussion Summary
+
+## Topic
+Change wake lock behavior so screen lock/display sleep is allowed while system sleep is still prevented during active work.
+
+## Purpose
+Capture a workflow-ready summary of a requested product behavior change affecting desktop apps and web, including current behavior, desired behavior, scope, and unresolved platform feasibility.
+
+## Repository Truth Relevant To This Discussion
+- Current desktop wake lock behavior is effectively configured as a display wake lock.
+- Electron currently uses `prevent-display-sleep`.
+- Tauri currently includes `display: true` in its wake-lock-related configuration.
+- This current setup keeps the screen awake and blocks normal screen lock/display sleep on macOS.
+
+## Facts Established
+- The reported problem is specific to current wake lock behavior preventing screen lock on macOS.
+- The user wants wake lock to allow screen lock while still preventing the device from going to sleep.
+- The requested scope was expanded beyond macOS-only behavior.
+- The user explicitly requested coverage for all desktop apps and web.
+- Browser/web platform limitations may affect how fully the requested behavior can be implemented.
+
+## Requirements Captured
+- Wake lock must allow the display to sleep or lock normally.
+- Wake lock must prevent only system sleep while work is active.
+- On macOS, the screen should be able to turn off and lock while the machine remains awake enough to continue the task.
+- The change should be researched and then applied, not just discussed.
+- Scope should include all desktop apps and web, subject to technical feasibility.
+
+## Constraints
+- The change affects multiple platforms and should not be treated as a macOS-only behavior change.
+- Web support may be constrained by browser capabilities and wake lock API limitations.
+- Platform-specific implementation details may differ between Electron, Tauri, and web.
+
+## Non-Goals
+- Keeping the display continuously awake.
+- Preserving the current display-wake behavior on macOS.
+- Defining a macOS-only special case unless later justified.
+
+## Decisions Made
+- Preferred product direction: allow display sleep/screen lock while preventing only system sleep during active work.
+- Scope direction confirmed by the user: all desktop apps and web.
+- The discussion should move into tracked workflow work with product and technical input before implementation.
+
+## Assumptions
+- “Work is active” refers to periods when the application is performing a task that currently relies on wake lock protection.
+- The intended outcome is continued task execution while the screen is locked or asleep, not continuous visual display.
+- Some platforms may require best-effort behavior rather than identical implementation mechanics.
+
+## Open Questions
+- What exact user-facing definition of “work is active” should trigger wake lock behavior across products?
+- What behavior is achievable on web given browser/API support and permission constraints?
+- If a platform cannot prevent only system sleep without also affecting display sleep, what fallback behavior is acceptable?
+- Should platform-specific differences be exposed to users or documented in product behavior notes?
+
+## Risks Or Concerns
+- Web may not support the requested behavior fully or consistently across browsers.
+- A platform may not offer a clean “prevent system sleep only” mode, creating inconsistent behavior across products.
+- Changing wake lock semantics could affect long-running task reliability if background execution assumptions are wrong.
+
+## Referenced Files Or Areas
+- Electron wake lock implementation using `prevent-display-sleep`
+- Tauri wake lock / `keepawake` configuration currently using `display: true`
+- Cross-platform wake lock behavior for desktop apps
+- Web wake lock behavior and browser capability research areas
+
+## Recommended Workflow Next Step
+- assigned_to: product_manager
+- why: Create a tracked task and SCR-ready handoff for cross-platform research and specification, then route to business analyst and technical architect for requirements and feasibility clarification before implementation.

tasks/todo/055-wake-lock-investigation.md

@@ -0,0 +1,54 @@
+---
+title: Wake Lock Investigation
+complexity: standard
+track: investigation
+slice: logic
+status: active
+assigned_to: tech_lead
+---
+
+# Goal
+
+Understand and explain how wake lock is held across `packages/ui`, `packages/tauri-app`, and `packages/electron-app`, including which layer initiates the request, which native/platform APIs are used, and how acquire/release lifecycle is coordinated.
+
+# Request Context
+
+The Product Owner asked: "Understand how we hold wake lock in packages/ui packages/tauri-app and packages/electron-app".
+
+# Acceptance Criteria
+
+- AC-1: Identify all wake-lock-related code paths in `packages/ui`, `packages/tauri-app`, and `packages/electron-app`.
+- AC-2: Explain which package owns the wake-lock decision and which package executes the platform-specific hold/release behavior.
+- AC-3: Describe the acquire and release lifecycle, including triggering events, cleanup behavior, and any fallback or unsupported-platform handling.
+- AC-4: Note any discrepancies, risks, or unclear behavior discovered during the investigation.
+
+# Instructions For Assigned Agent
+
+1. Read this task file first.
+2. Investigate the repository code paths relevant to wake lock in the three packages named above.
+3. Produce a concise technical report using the specialist output contract sections:
+   - Summary
+   - Work Performed
+   - Acceptance Criteria Coverage
+   - Documentation Impact
+   - Open Risks
+   - Recommended Next Step
+4. Include file paths and function/module names for the relevant wake-lock implementation points.
+5. Update this task file with a `# Post Implementation Task Updates` section and `## Tech Lead: Post Implementation Expectations` bullets describing the observable outputs of your investigation.
+
+# Discussion Record
+
+- Created by PMA to answer a direct user investigation request about wake-lock behavior across UI and native app shells.
+
+# Notes
+
+- This is investigation only. Do not implement changes.
+- Repository has unrelated untracked items in the working tree (`.nomadworks/`, `.playwright-cli/`, `cloudsecrets`, `tmp/`). Treat them as pre-existing and out of scope unless directly relevant.
+
+# Post Implementation Task Updates
+
+## Tech Lead: Post Implementation Expectations
+
+- Deliver a wake-lock investigation report that traces the call flow from `packages/ui/src/App.tsx` through `packages/ui/src/lib/native/wake-lock.ts` into the Electron preload/main IPC path and the Tauri command path.
+- Identify which session states cause the UI to request wake lock and which native APIs actually hold or release the lock on Electron and Tauri.
+- Document lifecycle behavior for acquire, release, fallback handling, unsupported-platform behavior, and any cleanup gaps or discrepancies discovered during review.

tasks/todo/056-wake-lock-behavior-change.md

@@ -0,0 +1,76 @@
+---
+title: Wake Lock Behavior Change
+complexity: complex
+track: spec
+slice: logic
+status: active
+assigned_to: business_analyst
+scr: SCR-2026-04-21-001
+---
+
+# Goal
+
+Research and define the cross-platform wake-lock behavior change so implementation can safely shift from display wake to system-sleep-only behavior wherever feasible.
+
+# Request Context
+
+The Product Owner requested: allow screen lock/display sleep while preventing device sleep during active work, across desktop apps and web, and asked to research options and apply the change.
+
+# Inputs
+
+- `tasks/discussions/DISCUSSION-001-wake-lock-behavior-change-for-macos-sleep-vs-screen-lock.md`
+- `tasks/todo/055-wake-lock-investigation.md`
+- `docs/scrs/SCR-2026-04-21-001-wake-lock-system-sleep-only.md`
+
+# Acceptance Criteria
+
+- AC-1: Define product intent for when wake lock should engage, using explicit user-observable terms.
+- AC-2: Document platform feasibility/options for Electron, Tauri, and web, including unsupported cases.
+- AC-3: Recommend a product-safe fallback policy for any platform that cannot prevent system sleep without also preventing screen lock.
+- AC-4: Update the SCR with clarified scope and implementation-ready acceptance criteria.
+
+# Instructions For Assigned Agents
+
+## Business Analyst
+
+1. Read this task file and all listed inputs in full.
+2. Clarify the product behavior and fallback expectations.
+3. Update the SCR with product-facing scope, terminology, and refined ACs.
+4. Return the specialist output contract sections.
+
+## Tech Lead
+
+1. After BA input, assess technical feasibility and implementation options for Electron, Tauri, and web.
+2. Identify the safest implementation direction and any platform gaps.
+3. Return the specialist output contract sections.
+
+# Discussion Record
+
+- Discussion summary captured in `tasks/discussions/DISCUSSION-001-wake-lock-behavior-change-for-macos-sleep-vs-screen-lock.md`.
+- User confirmed scope should include all desktop apps and web.
+- User asked to research options and apply the resulting change.
+
+# Notes
+
+- This task starts as spec/discovery. Implementation should not begin until product and technical feasibility are clear enough to proceed safely.
+
+# Reviews
+
+- Business Analyst review completed: clarified that product intent is consistent across platforms but platform execution is best-effort, defined "active work" in user-observable terms, and set the fallback rule to prefer no wake lock over display-wake behavior when system-sleep-only support is unavailable.
+- Tech Lead review completed: Electron can switch safely to `powerSaveBlocker.start("prevent-app-suspension")`; Tauri can target `keepawake` with `display: false, idle: true, sleep: false` as the closest cross-platform system-idle-sleep-only mode; web has no viable standards-based system-sleep-only API and must fall back to no wake lock. Scope is implementation-ready with explicit platform limitation notes and verification of long-running background behavior per desktop runtime.
+
+# Post Implementation Task Updates
+
+## Business Analyst: Post Implementation Expectations
+
+- The SCR defines "active work" as only currently running in-app work that should continue without continuous foreground interaction, and excludes idle, paused, completed, cancelled, or waiting-for-input states.
+- The SCR states a consistent product rule across platforms: allow screen lock/display sleep, use system-sleep-only protection where available, and release protection promptly when qualifying work ends.
+- The SCR defines unsupported-platform fallback behavior, including the explicit rule that web or any other unsupported runtime must not use display/screen wake as a substitute and should instead fall back to no wake lock.
+- The SCR leaves final platform feasibility validation to technical review without expanding scope into implementation or new user settings.
+
+## Tech Lead: Post Implementation Expectations
+
+- Electron wake lock behavior changes from `prevent-display-sleep` to `prevent-app-suspension`, so active work keeps the machine awake without intentionally blocking display sleep or screen lock.
+- Tauri wake lock requests use the native `keepawake` path with `display: false, idle: true, sleep: false`, aligning behavior to prevent idle system sleep without requesting display wake or explicit-sleep inhibition.
+- Web no longer attempts `navigator.wakeLock.request("screen")` for this feature path and instead degrades to no wake lock with a documented limitation because the web platform does not expose a true system-sleep-only primitive.
+- Runtime behavior releases protection promptly when qualifying active work ends, pauses, fails, is cancelled, or the app cleans up, and desktop verification confirms long-running work continues while the display can sleep or lock.

tasks/todo/057-implement-system-sleep-only-wake-lock.md

@@ -0,0 +1,64 @@
+---
+title: Implement System-Sleep-Only Wake Lock
+complexity: complex
+track: implementation
+slice: logic
+status: active
+assigned_to: workflow_runner
+scr: SCR-2026-04-21-001
+---
+
+# Goal
+
+Implement the approved wake-lock behavior change so qualifying active work prevents idle system sleep where supported, allows screen lock/display sleep, and degrades to no wake lock on unsupported platforms.
+
+# Scope
+
+- Update wake-lock decision logic in UI so only qualifying active work engages wake lock.
+- Update Electron to use system-sleep-only behavior instead of display wake.
+- Update Tauri to request system-idle-sleep prevention without display wake.
+- Remove the web screen wake-lock fallback for this feature path.
+- Add/adjust tests and documentation impacted by the behavior change.
+
+# Inputs
+
+- `docs/scrs/SCR-2026-04-21-001-wake-lock-system-sleep-only.md`
+- `tasks/todo/055-wake-lock-investigation.md`
+- `tasks/todo/056-wake-lock-behavior-change.md`
+- `tasks/discussions/DISCUSSION-001-wake-lock-behavior-change-for-macos-sleep-vs-screen-lock.md`
+
+# Acceptance Criteria
+
+- AC-1: Wake lock engages only for qualifying active work and does not engage for idle, paused, completed, cancelled, or waiting-for-user-input states.
+- AC-2: Electron uses a system-sleep-only mode that allows screen lock/display sleep while active work is running.
+- AC-3: Tauri requests the closest supported system-idle-sleep prevention mode without requesting display wake.
+- AC-4: Web does not use screen/display wake lock as a fallback for this feature path and instead degrades to no wake lock.
+- AC-5: Wake lock is released promptly when qualifying active work ends or the app cleans up.
+- AC-6: Required verification demonstrates the new desktop behavior and confirms fallback handling/documentation for unsupported web behavior.
+
+# Implementation Guidance
+
+- Align the UI definition of qualifying active work with the SCR. In particular, do not treat waiting-for-input / permission-question states as wake-lock-worthy unless technical review finds a repository truth conflict that must be escalated.
+- Electron target behavior from Tech Lead review: `powerSaveBlocker.start("prevent-app-suspension")`.
+- Tauri target behavior from Tech Lead review: use `keepawake` configuration `display: false, idle: true, sleep: false`.
+- Web fallback from BA/Tech Lead review: no wake lock for this feature path; do not use `navigator.wakeLock.request("screen")` as a substitute.
+- Update product-facing and/or code-adjacent docs as needed to record the supported-platform limitation and resulting behavior.
+- Collect clear verification evidence mapped back to AC-1 through AC-6.
+
+# Specialist Expectations
+
+- Workflow Runner should orchestrate implementation plus verification using the appropriate specialists.
+- Introduce specialist roles in verification feedback.
+- Do not create a final git commit unless PMA explicitly instructs you to do so.
+
+# Notes
+
+- Existing unrelated untracked files in the repository are out of scope unless they block verification.
+
+# Post Implementation Task Updates
+
+## Workflow Runner: Post Implementation Expectations
+
+- UI wake-lock eligibility now follows the SCR definition of qualifying active work and excludes sessions waiting on permission or question input.
+- Electron now requests `prevent-app-suspension`, Tauri now requests `display: false, idle: true, sleep: false`, and web no longer falls back to screen wake lock for this feature path.
+- Verification covers UI eligibility logic, workspace typechecks/build checks, and the documented unsupported web fallback behavior.