Add notch hover usage overlay

[wdmitchelluk]

Summary

Adds an opt-in notch usage overlay under Settings → Notch, off by default. It shows enabled provider tiles and an optional agent-session band, supports one to four columns, independently scrolling sections, reordering, and an optional Toggle/Hold shortcut. Agent sessions come from the existing store, not a second scanner.

The feature direction is approved in the owner review. The four original findings are addressed: shortcut registration follows enablement/start-stop, benign settings changes preserve expanded panels, restart does not accumulate handlers, and Codex credits occupy only an otherwise unused fallback slot.

Owner review hold: keep this feature PR open for Peter's review. Direction approval and passing CI do not authorize an unattended merge. Fresh sanitized before/after screenshots and native interaction proof are still pending.

Maintainer click-safety repair

• Keep a notch-sized tracking window separate from an interactive content window entirely below the menu-bar strip. Expanding never widens the trigger across neighboring menu extras.
• Treat both windows as one hover region, preserving the existing dwell/grace and shortcut behavior.
• Disable content mouse handling immediately on collapse, then hide after animation; keep that hide task separate from hover grace.
• Cancel pending transitions and close both windows on disable, stop, or loss of the notched display.
• Make the SwiftUI content helper explicitly main-actor isolated, and keep shortcut unit tests independent of real display/window creation.
• Update the documentation and changelog, preserving contributor credit to @wdmitchelluk. Keep the feature only under Unreleased, removing the stale duplicate from the already-shipped 0.55.0 notes.

Verification

• Red-before-green: ten geometry assertions failed against the prior top-anchored frame, including shifted/negative display origins and oversized content.
• swift test --jobs 4 --filter 'Notch|ProviderArchitectureGatekeeperTests': 78 tests in six suites passed, including new geometry and hover-state coverage and the existing owner-fix tests.
• make check: passed with zero violations across 2,063 Swift files.
• Independent Codex review of the maintainer repair: no actionable blocking findings; native click delivery remains a separate required proof.
• Full make test: passed — 968 selections across 81 groups, all first-pass successful; zero failures, retries, or timeouts (1,010.4 seconds). The final changelog-only follow-up leaves application and test sources identical to this tested tree.
• Prepared matching Developer-ID-signed before/after bundles. Deep/strict signature checks passed locally and on the notched test Mac; headless resource probes passed with networking blocked and the build checkout unreadable. These are packaging checks, not native interaction proof.
• Previous verified-head CI: passed on 046aa94954878200a752854ee61498d3a05c011e. All nine checks passed, including both macOS test shards, Linux x64/arm64/musl, lint, and security checks. That contributor merge commit has the identical complete Git tree as tested candidate 2442d96. Earlier superseded runs are not claimed as final-head CI proof.
• Updated head 5317e595c31b6c6de9d1ee653d48098eae7bc7f4 imports the already-landed fix: publish completed Codex cost history without rescanning #3279 changes without modifying notch source, settings, tests, or visuals. Its complete tree differs from the previously verified build, so the full-suite, whole-repository lint, signed-bundle, and packaging results above are previous-head evidence. CI for this updated head is separate. Before further local suite runs, incorporate the session-file isolation repair from fix: isolate provider session files during tests #3280. Fresh signed-build native interaction evidence and Peter's review remain required before any merge.
• Fresh signed-bundle native before/after proof: pending. The repair must demonstrate neighboring menu extras receiving clicks while the overlay is expanded, trigger/content crossing, hover/shortcut operation, scrolling, and disable/stop behavior before merge.

Routine verification uses a clean environment with Keychain access suppressed, Codex-file isolation enabled, and live provider fetching disabled. No real provider/account request is required for the interaction repair. No release is part of this PR update.

Existing contributor visuals (before the click-safety repair)

These show the feature and settings, not proof of the repaired native click-through boundary.

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed August 30, 2026, 7:34 AM ET / 11:34 UTC.

ClawSweeper review

What this changes

The PR adds a disabled-by-default notch hover overlay for provider usage and optional agent sessions, with settings, shortcut behavior, localized text, tests, and docs.

Merge readiness

⛔ Blocked until stronger real behavior proof is added - 4 items remain

Keep this PR open: the owner has explicitly reserved final review, and the available screenshots do not prove the repaired native click-through and interaction boundary on the current head.

Priority: P2
Reviewed head: 900b1d015ae10cd28472e9f7bd3e0b8494ee07c8
Owner decision: Required. See Decision needed.

Review scores

Measure	Result	What it means
Overall readiness	🦪 silver shellfish (2/6)	The implementation and focused state coverage look solid, but the essential current-head native interaction evidence is not yet present.
Proof confidence	🦪 silver shellfish (2/6)	Needs stronger real behavior proof before merge: The changed production owner is the split AppKit overlay controller, whose interactive panel must stay below the menu-bar strip while the notch-sized trigger preserves hover. The two supplied screenshots visibly show the overlay and settings, but the PR itself says they predate the click-safety repair; no artifact records an after-fix current-head run proving neighboring-click delivery, hover/shortcut transitions, scrolling, or teardown. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Needs proof	Needs stronger real behavior proof before merge: The changed production owner is the split AppKit overlay controller, whose interactive panel must stay below the menu-bar strip while the notch-sized trigger preserves hover. The two supplied screenshots visibly show the overlay and settings, but the PR itself says they predate the click-safety repair; no artifact records an after-fix current-head run proving neighboring-click delivery, hover/shortcut transitions, scrolling, or teardown. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
Evidence reviewed	6 items	Current main does not contain this feature: The checked current-main tree has no notch-overlay controller, geometry, hover-state, hotkey, or settings-pane paths, so the central feature remains PR-owned. Source-level click-boundary design: The controller keeps a notch-sized trigger and a separate interactive content panel; collapse disables content mouse events before hiding it. Focused geometry and state coverage: New tests cover screen-coordinate geometry and the pure hover/hotkey state seams, including preserving hover across the two windows.
Findings	None	None.
Security	None	None.

How this fits together

CodexBar gathers provider usage and optional agent-session state, then renders it in menu-bar and settings surfaces. This PR adds a separate notch-triggered overlay that reads those existing stores and displays the summaries below a notched Mac display.

flowchart LR
A[Provider usage store] --> C[Notch overlay controller]
B[Agent session store] --> C
D[Settings and shortcut] --> C
C --> E[Notch-sized hover trigger]
C --> F[Interactive overlay panel]
F --> G[Provider and session summaries]

Loading

Decision needed

Question	Recommendation
After fresh signed-build interaction evidence is available, should Peter approve this opt-in notch overlay for merge?	Review fresh native proof: Keep the PR open until a current-head signed build demonstrates click-through, hover crossing, shortcut operation, scrolling, and disable/stop teardown.

Why: The owner has approved the direction but explicitly reserved final review of the native menu-bar interaction boundary.

Before merge

• Add real behavior proof - Needs stronger real behavior proof before merge: The changed production owner is the split AppKit overlay controller, whose interactive panel must stay below the menu-bar strip while the notch-sized trigger preserves hover. The two supplied screenshots visibly show the overlay and settings, but the PR itself says they predate the click-safety repair; no artifact records an after-fix current-head run proving neighboring-click delivery, hover/shortcut transitions, scrolling, or teardown. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
• Resolve merge risk (P1) - Merging without fresh native interaction evidence could still let the overlay interfere with neighboring menu extras or fail its hover, shortcut, scrolling, or teardown behavior on a notched display.
• Complete next step (P2) - The owner has explicitly reserved final review, and the remaining blocker is human validation of native interaction evidence rather than a mechanical branch repair.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Diff scope	50 files; +3,587 / -1 lines	This is a substantial new native feature spanning app lifecycle, settings, presentation, localization, tests, and docs.
Production versus tests	production +1,824; tests +851 net	The focused test seams are substantial, but they cannot establish the native menu-bar hit-testing boundary.

Merge-risk options

Maintainer options:

1. Prove native interaction before merge (recommended)
   Capture sanitized current-head signed-build evidence that neighboring menu extras receive clicks while the overlay is expanded and that all stated interaction paths recover correctly.

Technical review

Best possible solution:

Retain the opt-in implementation, then approve it only after a signed current-head build demonstrates the full native interaction boundary on a notched Mac.

Do we have a high-confidence way to reproduce the issue?

Not applicable as a bug reproduction: this is a new feature PR. The remaining question is real native behavior on a notched Mac, which the supplied screenshots do not exercise on the current head.

Is this the best way to solve the issue?

Unclear: the split trigger/content-window design is a focused source-level solution and the feature direction is approved, but its essential native interaction claim still requires the owner-requested signed-build proof.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against efb952e0bf5f.

Labels

Label justifications:

• P2: This is an opt-in usability feature with bounded impact, but it still needs owner review before release.
• merge-risk: 🚨 other: The native AppKit window boundary can affect menu-extra click delivery in a way unit tests and static screenshots do not settle.
• rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🦪 silver shellfish and patch quality is 🐚 platinum hermit.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs stronger real behavior proof before merge: The changed production owner is the split AppKit overlay controller, whose interactive panel must stay below the menu-bar strip while the notch-sized trigger preserves hover. The two supplied screenshots visibly show the overlay and settings, but the PR itself says they predate the click-safety repair; no artifact records an after-fix current-head run proving neighboring-click delivery, hover/shortcut transitions, scrolling, or teardown. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
• proof: 📸 screenshot: Contributor real behavior proof includes screenshot evidence. The changed production owner is the split AppKit overlay controller, whose interactive panel must stay below the menu-bar strip while the notch-sized trigger preserves hover. The two supplied screenshots visibly show the overlay and settings, but the PR itself says they predate the click-safety repair; no artifact records an after-fix current-head run proving neighboring-click delivery, hover/shortcut transitions, scrolling, or teardown.

Evidence

What I checked:

• Current main does not contain this feature: The checked current-main tree has no notch-overlay controller, geometry, hover-state, hotkey, or settings-pane paths, so the central feature remains PR-owned. (efb952e0bf5f)
• Source-level click-boundary design: The controller keeps a notch-sized trigger and a separate interactive content panel; collapse disables content mouse events before hiding it. (Sources/CodexBar/NotchUsageOverlayController.swift:260, 900b1d015ae1)
• Focused geometry and state coverage: New tests cover screen-coordinate geometry and the pure hover/hotkey state seams, including preserving hover across the two windows. (Tests/CodexBarTests/NotchGeometryTests.swift:7, 900b1d015ae1)
• Proof artifacts are not current interaction proof: The supplied overlay and settings images visibly demonstrate the UI, but the PR body identifies them as predating the click-safety repair and neither shows current-head neighboring-menu clicks, hover crossing, shortcut behavior, scrolling, or teardown. (docs/notch-overlay.png, 900b1d015ae1)
• Owner review hold: The repository owner states that the PR remains open pending native interaction proof and Peter's review; no additional contributor code change was requested.
• Introduced diff hygiene: The checked PR delta is whitespace-clean and adds the overlay, settings, localization, documentation, and focused tests as one feature surface. (Sources/CodexBar/NotchUsageOverlayController.swift:1, 900b1d015ae1)

Likely related people:

• steipete: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)

Rank-up moves

Optional improvements that raise the rating; they are not merge blockers.

• Attach sanitized current-head signed-build interaction evidence for neighboring-menu clicks, trigger/content crossing, shortcut modes, scrolling, and disable/stop teardown; redact account, endpoint, and personal data.
• After adding proof, update the PR body for automatic re-review, or ask a maintainer to comment @clawsweeper re-review if needed.
• Obtain the owner’s final review after the native evidence is available.

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

History

Review history (29 earlier review cycles; latest 8 shown)

• reviewed 2026-08-30T02:33:47.912Z sha 7bdce78 :: needs changes before merge. :: [P1] Keep the expanded panel out of the menu-bar hit region
• reviewed 2026-08-30T04:17:51.919Z sha e04d443 :: needs real behavior proof before merge. :: none
• reviewed 2026-08-30T04:27:59.736Z sha 2442d96 :: needs real behavior proof before merge. :: none
• reviewed 2026-08-30T04:56:10.443Z sha 046aa94 :: needs real behavior proof before merge. :: none
• reviewed 2026-08-30T05:26:44.336Z sha 046aa94 :: needs real behavior proof before merge. :: none
• reviewed 2026-08-30T08:33:22.379Z sha 5317e59 :: needs real behavior proof before merge. :: none
• reviewed 2026-08-30T08:41:25.895Z sha 5317e59 :: needs real behavior proof before merge. :: none
• reviewed 2026-08-30T09:38:47.569Z sha 264090d :: needs real behavior proof before merge. :: none

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d2f342ed97

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[wdmitchelluk]

Both review findings are fixed in f3b6fec, and the branch is rebased onto current main (merge state is clean now):

• Shortcut collapse frame — the collapse animation task now restores the collapsed frame whenever the panel is still collapsed, instead of gating on pointer position. A toggle-collapse under a hovering pointer can no longer leave the expanded frame behind as an invisible click target; re-expansion cancels the task, so it never fights a reopened panel.
• Hotkey with no notched screen — handleHotkeyDown() returns before mutating hotkey or view state when no panel exists, so isExpanded can't be stranded while the lid is closed.
• VoiceOver — provider tiles now announce name, status, and every bar via ProviderRow.accessibilitySummary (unit-tested).

make check clean, 27 notch tests pass. @clawsweeper please re-review.

[wdmitchelluk]

Fixed in ab83688: all three bar factories (makeBar, makeCostBar, makeCreditBar) now derive the accessibility label from the visible pieces — title, percentText, and resetText when present — through one shared helper, so VoiceOver hears the same figures a sighted user sees. Tests go through bars() as requested: bar accessibility labels speak the visible values asserts the derived labels (including the reset text and the no-reset case), and the summary test now composes ProviderRow from factory-built bars instead of injecting pre-detailed labels.

make check clean, 28 notch tests pass. @clawsweeper please re-review.

[steipete]

Really nice work overall — the self-reported sizing approach and the no-global-monitor/no-AX design are exactly right, and the focused suites plus make check all pass on a merge with latest main. Four findings before this can land, two of them blocking:

P1 — Disabled feature still registers a global shortcut. NotchUsageOverlayController.swift:54 installs the KeyboardShortcuts handlers unconditionally, and the dependency registers any saved shortcut system-wide the moment a handler is attached. Disabling the overlay never unregisters it, and PreferencesNotchPane.swift:38 allows recording a shortcut while the feature is off. That breaks the off-by-default guarantee and can steal shortcuts from other apps. Handlers should only exist while the overlay is enabled.

P1 — Any settings change destroys an expanded overlay. The activation observation (NotchUsageOverlayController.swift:123) reads a computed property backed by the whole observable defaults struct, so unrelated preference changes re-fire it; at line 143 an existing panel is preserved only when collapsed — an expanded panel is closed and recreated, losing hover/shortcut state. Please narrow the observation to the fields that actually affect activation, and preserve an expanded panel across benign changes.

P2 — Controller restarts accumulate shortcut handlers. Handlers registered at line 71 are never removed on stop; each stop/start adds another callback, and in Toggle mode two callbacks make one press open-and-immediately-close the panel. The dependency ships KeyboardShortcuts.removeHandler(for:) for exactly this lifecycle.

P2 — Codex credits aren't actually a fallback. NotchUsageOverlayModel.swift:191 appends monthly credits whenever fewer than four bars exist, even when the extra window/spend bar was already chosen — a Codex account with two ordinary windows shows both, contradicting the documented mutually-exclusive fallback. Gate the append on the fallback slot being unfilled.

Happy to merge once these are addressed — the feature itself is a great addition.

[wdmitchelluk]

Addressed all four findings in 8fb9030 (rebased onto current main):

1. Disabled feature / global shortcut — handler installation now follows isStarted && notchUsageSummaryEnabled; disabling removes and unregisters the handlers. The shortcut recorder now explicitly drives RecorderCocoa.isEnabled, so it cannot record while the feature is off.
2. Broad activation observation / expanded-panel teardown — the controller observes a dedicated notchActivationRevision, incremented only when enablement actually changes, rather than the whole value-type defaults state. Same-screen activation checks now update collapsed or expanded panels in place; a pure lifecycle seam covers both states.
3. Restart handler accumulation — stop() calls KeyboardShortcuts.removeHandler(for:); installation removes any stale handler before registering and is guarded by hotkeyHandlersInstalled. A serialized regression test verifies disabled → enabled → stop → restart → stop registration state.
4. Credits fallback — monthly Codex credits append only when neither a known extra window nor valid spend projection has occupied the mutually-exclusive other slot. Regression coverage exercises extra-window, spend, and true-credit-fallback cases through the full overlay model.

Verification on the rebased head:

• 32 notch tests across 4 suites pass
• ProviderArchitectureGatekeeperTests: 38 pass
• make check: formatting clean, 22 locale catalogs OK, 0 lint violations

@clawsweeper please re-review the current head.

[wdmitchelluk]

@steipete I have addressed all four findings in 8fb9030 (rebased onto current main).

[steipete]

Thanks @wdmitchelluk — I checked the new merge commit 046aa94954878200a752854ee61498d3a05c011e: its complete Git tree is identical to the tested 2442d96b02fd5cd4b1e8f38f99084240e9d5e28a candidate, so the local verification still applies.

The maintainer repair separates the notch-sized trigger from the interactive window below the menu-bar strip, handles hover across both windows, and disables mouse handling immediately on collapse. The changelog now records the feature only under Unreleased, with contributor credit preserved.

Verification completed: 78 focused tests, the full 968-selection/81-group suite with zero failures/retries/timeouts, clean make check, and independent review of the repair. Matching Developer-ID-signed before/after bundles also passed signature and headless resource checks on a notched Mac; those checks do not establish native click delivery.

The merge-only push superseded the previous CI run, so I am following CI for the new head. I am holding further pushes while that run finishes. The remaining native hover/shortcut/scroll/neighboring-menu click-through proof is maintainer-side, and the PR remains open until it is complete. No additional contributor code change is requested here.