[nwparker]

Summary

Removes the permanent macOS main-window setBackgroundThrottling(false) workaround from createMainWindow.

• Keeps normal main-window background throttling enabled with setBackgroundThrottling(true) on macOS.
• Preserves the black-surface recovery path by forcing repaint on show, restore, and focus.
• Adds one debounced delayed repaint after visibility transitions so late webview compositor recovery still gets a second paint without stacking timers.
• Adds focused unit coverage that fails if the main window goes back to setBackgroundThrottling(false).

Verification

• pnpm exec vitest run --config config/vitest.config.ts src/main/window/createMainWindow.test.ts
• pnpm lint -- src/main/window/createMainWindow.ts src/main/window/createMainWindow.test.ts
• pnpm typecheck
• git diff --check
• Electron dev validation:
  • launched node config/scripts/run-electron-vite-dev.mjs --remote-debugging-port=9334
  • attached with playwright-cli over CDP
  • confirmed app identity matched /Users/nwparker/orca/workspaces/orca/idle-spinner
  • confirmed renderer booted with window.__store, visible document, and 0 console errors
  • saved local screenshot at /tmp/orca-idle-spinner-validation/main-window.png
• Short idle benchmark smoke:
  • pnpm bench:idle-cpu -- --warmup-ms 3000 --sample-ms 4000 --interval-ms 1000 --worktrees 1 --output /tmp/orca-idle-spinner-validation/idle-cpu.json
  • result had runningAnimationCount: 0; GPU mean CPU was ~0.30% in the 3-sample smoke

Built-in browser restore proof

• Launched the PR build from this worktree with CDP on port 9334 and verified identity: Orca: nwparker/idle-spinner, repo root /Users/nwparker/orca/workspaces/orca/idle-spinner.
• Served a local proof page at http://127.0.0.1:8877/proof.html with markers ORCA_BROWSER_PROOF_5486 and WEBVIEW_RENDERED_OK.
• Loaded that URL in Orca's built-in browser webview and surfaced the actual Browser pane for the idle-spinner worktree. Before restore, the app-window screenshot showed the proof page and WEBVIEW_RENDERED_OK: /tmp/orca-browser-proof/orca-window-browser-before-restore.png (sha256 0b395327e058d63d778227c5710bc7999e7ccb1898cea516343b056debfdba84, 1920x1170).
• Minimized the real Orca window through the app IPC with window.api.ui.minimize(). Full-screen capture immediately after showed Edge in front and Orca absent, confirming the window really left the visible screen: /tmp/orca-browser-proof/screen-after-ui-minimize.png (sha256 76c5be7ee1980eec7e190acc3f297569072ed1074fdc90a576dcf383463715f3, 1920x1200).
• Restored/focused the exact dev app bundle with open -b com.stablyai.orca.dev.25fba5324525. After restore, the renderer reported {"visibilityState":"visible","hidden":false,"hasFocus":true,"activeTabType":"browser"}.
• After restore, both screenshots showed the built-in browser still rendering the proof page rather than a black/blank surface:
  • /tmp/orca-browser-proof/orca-window-browser-after-restore.png (sha256 8a90a36c0b2051618769b213f467a0672d91a7fbe6a7628ba0bccbcec6f24482, 1920x1170)
  • /tmp/orca-browser-proof/screen-after-bundle-activate.png (sha256 36289f5b824d54b4ca7c025f111aa76f972654ac3f7443cc729174545e24dfdd, 1920x1200)
• Post-restore CDP proof from the Electron webview target: type: "webview", title Orca Browser Proof, URL http://127.0.0.1:8877/proof.html; Runtime.evaluate returned marker: "WEBVIEW_RENDERED_OK" and hasText: true (saved at /tmp/orca-browser-proof/webview-after-restore.json, sha256 561b2ec1a5bcf306772e332c631cceeb7e6f10f8b86671152e21a117156c2455).
• Browser capture check: orca console --limit 50 --json returned messages: []. The only Playwright console error was the local proof server's expected /favicon.ico 404, plus dev-only React Grab logs.

Note: I also attempted a short-lived Playwright Electron main-process probe for webContents.getBackgroundThrottling(), but the extra launch hit the single-instance/headless path and did not expose a BrowserWindow. The API-call contract is covered by the unit test instead.

Terminal / agent / notification follow-up proof

• Diff/risk pass: the PR still only changes src/main/window/createMainWindow.ts and src/main/window/createMainWindow.test.ts; no PTY, runtime, agent-hook, browser-bridge, or notification implementation files are changed.
• Terminal / Orca CLI runtime proof:
  • Created Orca-managed terminals through the public CLI. term_37dae822-1894-4849-ae7f-9f2186db14a3 printed ORCA_TERMINAL_BG_TICK_1 through ORCA_TERMINAL_BG_TICK_10 at ~1s intervals while the app was background/minimized during the earlier restore pass, and orca terminal read returned all ticks with cursor metadata after restore.
  • After restore, orca terminal list --worktree path:/Users/nwparker/orca/workspaces/orca/idle-spinner --json showed the validation terminals connected/writable, and orca terminal switch could activate the proof terminal.
• Agent-status proof:
  • Created short synthetic agent-status terminals through orca terminal create that emitted the same OSC 9999 payload shape Orca parses from model-owned terminals: working -> done, agentType: codex, prompt PR5486 synthetic agent status / PR5486 synthetic notification proof.
  • orca worktree ps --limit 1 --json showed both proof rows in agents[] as state: done, agentType: codex, with the expected prompts/messages and terminal handles term_9800582c-3c77-4d45-9512-e278d675c8f2 and term_909dfaf5-6e4a-4128-9323-6af053fea05a.
  • Renderer IPC snapshot after restore agreed with the store: window.api.agentStatus.getSnapshot() and window.__store.getState().agentStatusByPaneKey both contained the same two synthetic done rows.
• Notification proof:
  • window.api.notifications.getPermissionStatus() returned { supported: true, platform: "darwin", requested: true }; local settings had notifications, agent task completion, and terminal bell enabled.
  • Confirming native display with requireDisplayConfirmation: true reached the main-process handler and returned { delivered: false, reason: "not-displayed" } on this dev macOS profile, so I am not claiming a visible native banner from that check.
  • The non-confirming main-process lifecycle succeeded after restore: window.api.notifications.dispatch({ source: "test", notificationId }) returned { delivered: true }, and window.api.notifications.dismiss([notificationId]) returned { dismissed: 1 }.
• Agent-browser / embedded browser automation proof:
  • Standalone agent-browser --session pr5486-deep --profile /tmp/orca-agent-browser-pr5486-profile loaded http://127.0.0.1:8879/deep.html; eval returned marker: "ORCA_DEEP_HTTP_PROOF_5486", clicked: "yes", result: "AGENT_BROWSER_CLICK_OK".
  • Orca CLI browser automation also passed after renderer graph readiness: orca goto --url http://127.0.0.1:8879/deep.html returned title Orca Deep HTTP Proof; orca snapshot exposed heading/input/button refs; orca click --element @e3 succeeded; orca eval returned clicked: "yes" and AGENT_BROWSER_CLICK_OK.
  • During this pass I also saw transient/non-PR environment states: CDP targets disappeared while the renderer graph was temporarily graph_not_ready, then recovered to ready after bringing the app forward; stale browser page ids briefly reported browser_tab_not_found. A pre-existing standalone Chrome for Testing process (PID 41487) was holding /Users/nwparker/.myapp-profile; I did not kill it.
• Focused regression tests added for this deeper pass:
  • pnpm exec vitest run --config config/vitest.config.ts src/main/ipc/notifications.test.ts src/renderer/src/hooks/agent-hook-completion-notifications.test.ts src/shared/agent-status-osc.test.ts -> 3 files / 54 tests passed.
  • pnpm exec vitest run --config config/vitest.config.ts src/main/runtime/orca-runtime.test.ts -t "OSC 9999|stamps SSH connection identity|preserves OSC 9999 parser state" -> 4 matching runtime tests passed, including the SSH connection-identity case.

Orca CLI background browser screenshot proof

• Reproduced the user-requested path through the public Orca CLI on the PR dev build after restarting the dev app with the patched main-process screenshot path: runtime 777da723-721e-4fec-9678-cf137416cb0e, app PID 84165, CDP identity Orca: nwparker/idle-spinner for /Users/nwparker/orca/workspaces/orca/idle-spinner.
• Served deterministic proof content at http://127.0.0.1:8891/proof.html with marker ORCA_BACKGROUND_SCREENSHOT_5486 and large green/red/blue/yellow/cyan blocks.
• Put Orca on a terminal foreground surface before capture. Renderer state immediately before screenshot was activeTabType: "terminal", activeTabId: "4f5448b8-6494-4b6e-9ea5-5f56b24dede9"; the screenshot target was inactive browser page 4eea8dfe-e894-4bbe-b2c2-c3670eb0f0c5.
• orca snapshot --page 4eea8dfe-e894-4bbe-b2c2-c3670eb0f0c5 --worktree path:/Users/nwparker/orca/workspaces/orca/idle-spinner --json returned origin http://127.0.0.1:8891/proof.html and static text for Background Screenshot Proof 5486, ORCA_BACKGROUND_SCREENSHOT_5486, RED, BLUE, YELLOW, CYAN, and content must not be black.
• orca screenshot --page 4eea8dfe-e894-4bbe-b2c2-c3670eb0f0c5 --worktree path:/Users/nwparker/orca/workspaces/orca/idle-spinner --json produced a real PNG at /tmp/orca-bg-final-screenshot-5486.png: 1041x1059, 40,677 bytes, not black. Pixel validation counted green 176,210; red 108,067; blue 108,281; yellow 107,243; cyan 107,918; non-dark pixels 791,009.
• This pass exposed and fixed two adjacent issues needed for the proof: CLI browser creation from the no-active-worktree landing state now activates only from that landing state so the webview can mount, and viewport screenshots now use Orca's direct CDP capture after hidden-webview visibility/re-resolution instead of agent-browser's screenshot command, which was returning a dark inactive surface.

---

[ghost]

Ready to review this PR? Stage has broken it down into 3 individual chapters for you:

	Title
1	Implement debounced visibility repaint for macOS
2	Enable background throttling for macOS main window
3	Verify background throttling and repaint behavior

_{Chapters generated by Stage for commit 284532f on Jun 16, 2026 7:58am UTC.}

[coderabbitai]

📝 Walkthrough

Walkthrough

The macOS compositor repaint workaround in createMainWindow.ts is extracted into a new installMacosVisibilityRepaint() helper. This helper registers listeners on restore, show, and focus events; each triggers an immediate forceRepaint() call and schedules a single 250ms delayed repaint, with the pending timer cleared on closed. The macOS setup block in createMainWindow() is updated to call setBackgroundThrottling(true) and invoke the new helper, replacing the previous inline approach that disabled throttling and attached handlers directly. A new Vitest case is added that uses fake timers and a simulated event handler map to verify the timing, invalidation, and resize behavior on macOS.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately reflects the main change: enabling background throttling on macOS by refactoring the repaint workaround.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description check	✅ Passed	The PR description is extremely comprehensive, including detailed sections on Summary, Verification, Built-in browser restore proof, Terminal/agent/notification follow-up proof, and CLI background browser screenshot proof, with extensive test results and validation evidence.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[AmethystLiang]

Thanks for the contribution — the underlying change is already implemented in main, so we’re closing this PR as superseded.