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 31, 2026, 8:33 AM ET / 12:33 UTC.

ClawSweeper review

What this changes

This PR adds an opt-in macOS notch-hover usage dashboard with provider and agent-session summaries, settings, shortcuts, localization, documentation, and focused tests.

Merge readiness

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

Keep this owner-held feature PR open. Its branch records the overlay under already-shipped v0.56.2 rather than current main’s 0.56.3 Unreleased section, and current native interaction proof is still insufficient.

Priority: P3
Reviewed head: d33314cc4ba9fc228e89880a43314400520f22fe
Owner decision: Required. See Decision needed.

Review scores

Measure	Result	What it means
Overall readiness	🦪 silver shellfish (2/6)	Substantial scoped tests exist, but a release-note defect and insufficient current native proof prevent merge readiness.
Proof confidence	🦪 silver shellfish (2/6)	Needs stronger real behavior proof before merge: The changed AppKit controller is entered by notch hover or shortcut. The prepared screenshots show visual states but predate the click-safety repair and do not demonstrate current click-through, crossing, scrolling, shortcut, disablement, or shutdown behavior; post sanitized native screenshots, recording, or redacted traces are required. 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	🦐 gold shrimp (3/6)	1 actionable review finding remain.

Verification

Check	Result	Evidence
Real behavior	Needs proof	Needs stronger real behavior proof before merge: The changed AppKit controller is entered by notch hover or shortcut. The prepared screenshots show visual states but predate the click-safety repair and do not demonstrate current click-through, crossing, scrolling, shortcut, disablement, or shutdown behavior; post sanitized native screenshots, recording, or redacted traces are required. 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	5 items	Introduced release-note error: The PR adds the feature beneath the 0.56.2 heading, although the PR base is v0.56.2 and current main has opened 0.56.3 as Unreleased. Current-main release context: Current main explicitly starts 0.56.3 development and sets MARKETING_VERSION to 0.56.3. Interaction boundary: The controller keeps the collapsed hit area to the camera housing and positions expanded content below it; this boundary needs native click-through evidence.
Findings	1 actionable finding	[P1] Move the feature note out of the shipped 0.56.2 section
Security	None	None.

How this fits together

CodexBar collects provider usage and active agent-session data, then renders it in its menu bar and settings UI. This change adds an optional overlay below a MacBook camera notch that consumes those existing stores without starting another scan.

flowchart LR
A[Usage and session stores] --> B[Notch overlay model]
C[Notch settings] --> D[Overlay controller]
B --> E[SwiftUI dashboard]
D --> E
F[Notch hover or shortcut] --> D
E --> G[Provider and session summary]

Loading

Decision needed

Question	Recommendation
After the release-note correction and native evidence are available, should this owner-held macOS feature merge?	Merge after proof: Approve once the release note is corrected and built-bundle evidence confirms the overlay preserves neighboring menu-extra clicks.

Why: The owner approved the direction but explicitly reserved final review pending native interaction proof.

Before merge

• Add real behavior proof - Needs stronger real behavior proof before merge: The changed AppKit controller is entered by notch hover or shortcut. The prepared screenshots show visual states but predate the click-safety repair and do not demonstrate current click-through, crossing, scrolling, shortcut, disablement, or shutdown behavior; post sanitized native screenshots, recording, or redacted traces are required. 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.
• Move the feature note out of the shipped 0.56.2 section (P1) - Current main has opened 0.56.3 — Unreleased, while v0.56.2 is this branch’s base and does not contain the overlay. This line would publish an incorrect shipped-version claim; rebase and put it under Unreleased.
• Resolve merge risk (P1) - Merging unchanged would incorrectly claim that the overlay shipped in v0.56.2.
• Resolve merge risk (P1) - The current repaired bundle has no supplied native evidence that it preserves clicks on neighboring menu extras through expansion and collapse.
• Complete next step (P2) - The release-note placement is a narrow mechanical repair; native interaction proof and final owner acceptance remain separate merge gates.

Findings

• [P1] Move the feature note out of the shipped 0.56.2 section — CHANGELOG.md:5

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Changed surface	50 files, +3,584/-1 lines	The feature spans AppKit interaction, settings, model/view code, tests, documentation, and locale catalogs.
Implementation versus tests	production +2,628, tests +852 lines	The sizeable opt-in UI feature has focused coverage, but its native interaction boundary still needs live proof.

Merge-risk options

Maintainer options:

1. Correct release placement and prove interaction (recommended)
   Move the entry to the current Unreleased section and add fresh sanitized proof that neighboring extras remain clickable through expansion and collapse.
2. Pause for review
   Keep the feature open until the owner can review current native interaction evidence on a notched Mac.

Copy recommended automerge instruction

@clawsweeper automerge

Special instructions:
Rebase onto current main, move the notch-overlay changelog entry under 0.56.3 Unreleased, and include fresh sanitized native interaction evidence.

Technical review

Best possible solution:

Rebase onto current main, place the release note under 0.56.3 Unreleased, and attach sanitized built-bundle evidence for the full native interaction lifecycle.

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

Not applicable: this PR adds a new opt-in dashboard. The introduced changelog defect is directly verifiable by comparing the branch with v0.56.2 and current main.

Is this the best way to solve the issue?

No: the direction is approved, but the branch needs an Unreleased release note and real native interaction proof before it is a merge-ready solution.

Full review comments:

• [P1] Move the feature note out of the shipped 0.56.2 section — CHANGELOG.md:5
  Current main has opened 0.56.3 — Unreleased, while v0.56.2 is this branch’s base and does not contain the overlay. This line would publish an incorrect shipped-version claim; rebase and put it under Unreleased.
  Confidence: 0.99

Overall correctness: patch is incorrect
Overall confidence: 0.98

AGENTS.md: found and applied where relevant.

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

Labels

Label justifications:

• P3: This is an optional, off-by-default dashboard feature rather than a repair to an existing workflow.
• merge-risk: 🚨 other: The patch changes native hover-window interaction and release metadata, neither settled by unit tests alone.
• rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🦪 silver shellfish and patch quality is 🦐 gold shrimp.
• 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 AppKit controller is entered by notch hover or shortcut. The prepared screenshots show visual states but predate the click-safety repair and do not demonstrate current click-through, crossing, scrolling, shortcut, disablement, or shutdown behavior; post sanitized native screenshots, recording, or redacted traces are required. 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 AppKit controller is entered by notch hover or shortcut. The prepared screenshots show visual states but predate the click-safety repair and do not demonstrate current click-through, crossing, scrolling, shortcut, disablement, or shutdown behavior; post sanitized native screenshots, recording, or redacted traces are required.

Evidence

Acceptance criteria:

• [P1] git diff --check.
• [P1] make check.

What I checked:

• Introduced release-note error: The PR adds the feature beneath the 0.56.2 heading, although the PR base is v0.56.2 and current main has opened 0.56.3 as Unreleased. (CHANGELOG.md:5, d33314cc4ba9)
• Current-main release context: Current main explicitly starts 0.56.3 development and sets MARKETING_VERSION to 0.56.3. (version.env:1, 8ff81d718cff)
• Interaction boundary: The controller keeps the collapsed hit area to the camera housing and positions expanded content below it; this boundary needs native click-through evidence. (Sources/CodexBar/NotchUsageOverlayController.swift:411, d33314cc4ba9)
• Prepared visual proof: Both prepared screenshots show overlay/settings states, but neither proves the repaired native click-through, hover crossing, scrolling, or teardown behavior. (/home/runner/work/clawsweeper/clawsweeper/artifacts/event/codex/proof-scratch/3164/media-proof-manifest.json:1, d33314cc4ba9)
• Feature-history routing: The owner-authored commit describes the central click-safety repair separating the trigger and interactive content windows. (Sources/CodexBar/NotchUsageOverlayController.swift:411, e04d4430fff4)

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.

• Rebase and move the feature entry under the current Unreleased heading.
• Post sanitized built-bundle interaction evidence, then update the PR body for re-review or ask a maintainer to comment @clawsweeper re-review.

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 (39 earlier review cycles; latest 8 shown)

• reviewed 2026-08-30T20:25:15.780Z sha 65f2b63 :: needs real behavior proof before merge. :: none
• reviewed 2026-08-31T00:43:38.129Z sha a9e501f :: needs real behavior proof before merge. :: none
• reviewed 2026-08-31T01:40:34.565Z sha 7946749 :: needs real behavior proof before merge. :: none
• reviewed 2026-08-31T03:37:51.338Z sha 67580d8 :: needs real behavior proof before merge. :: none
• reviewed 2026-08-31T04:29:36.273Z sha 4c5b091 :: needs real behavior proof before merge. :: none
• reviewed 2026-08-31T06:35:59.488Z sha d2ff8b5 :: needs real behavior proof before merge. :: none
• reviewed 2026-08-31T08:36:56.911Z sha 79cae8b :: needs real behavior proof before merge. :: none
• reviewed 2026-08-31T09:31:48.480Z sha 8c2b161 :: 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).