docs: define provider notification identity

[steipete]

Summary

• document that current provider notifications already identify the provider in localized, provider-first titles
• record the public macOS limitation: UNMutableNotificationContent has no per-notification sender-icon override
• compare the existing text-only contract with a possible supplementary attachment experiment
• define privacy-safe implementation, test, and Tahoe proof gates if attachments are approved later
• include a conceptual synthetic SVG that does not claim exact system rendering

Decision and scope

Decision-only draft. This does not ship notification behavior, change the app icon, add attachments, or close #1828. Keep #1828 open for maintainer choice on whether supplementary media is an acceptable interpretation.

Recommendation: retain provider-first titles and the CodexBar sender icon. If the requested result specifically requires replacing the sender icon, close the issue as unsupported by the public macOS API. Do not model quota alerts as direct communication to obtain avatar-style presentation.

Evidence

• Current main at c3d33308ac0624424bd8c089d9eff59f3701aefa: session depleted/restored, quota warning, login success, and permission notifications put the provider display name in the title.
• Apple User Notifications exposes title, subtitle, body, attachments, badge, sound, grouping, and delivery metadata, but no sender-icon field. Attachments are content alongside the alert and can prevent scheduling if the media is invalid.
• Active PR audit: docs: define predictive pace warning decision #1818 is documentation-only; no open PR changes the notification runtime or provider icon resources.
• Packaged baseline: ./Scripts/package_app.sh built successfully from c3d33308 (runtime-identical to this docs-only head) on macOS 26.5.2 (25F84). An isolated synthetic bundle was launched and inspected with Peekaboo CLI 3.5.2 / GUI bridge 3.5.3. The macOS notification permission card displayed the CodexBar app icon, confirming the system sender identity.
• Bounded live retry limitation: after permission was enabled in System Settings and only the isolated app was restarted, its packaged Debug action logged enqueuing (prefix=session-codex-depleted) twice, but macOS left the authorization session unresolved. No live synthetic alert appeared, so this draft does not claim banner or Notification Center rendering proof. The isolated process was stopped; another running CodexBar was not touched.
• xmllint --noout docs/screenshots/provider-notification-identity-options.svg
• make docs-list
• make check — 0 SwiftFormat files changed; 0 SwiftLint violations
• make test — all 44 shards passed
• ./Scripts/package_app.sh
• autoreview — clean; no accepted/actionable findings

No screenshot is uploaded: captures were local-only and the conceptual SVG is the sole visual artifact in this branch.

Overlap

#1299 and #1818 propose predictive notifications through the same delivery path. This decision should apply centrally before that feature is implemented; this draft does not alter #1818.

Refs #1828.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed July 1, 2026, 4:40 PM ET / 20:40 UTC.

Summary
This PR adds a provider notification identity decision proposal and a conceptual SVG comparison under docs/.

Reproducibility: not applicable. this is a documentation proposal, not a runtime bug reproduction. Source inspection confirms the current notification runtime is only background context for the documented decision.

Review metrics: 2 noteworthy metrics.

• Docs-only diff: 2 files added, 145 additions, 0 deletions. The patch does not change runtime notification behavior or provider assets.
• Closing reference: 1 detected issue closure. The PR metadata says it will close the provider-icon issue even though the PR body says that issue should stay open.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🌊 off-meta tidepool
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• Remove the accidental closing issue reference from the PR body while keeping a non-closing link to the provider-icon issue.

Risk before merge

• [P1] GitHub currently reports Feature request: Show a provider icon in notification so it's clear to which provider notification related too #1828 as a closing issue reference for this PR, which conflicts with the PR body’s stated intent to keep that provider-icon request open for maintainer choice.
• [P1] The document is explicitly a proposed direction, so merging it before maintainer sign-off would make a policy recommendation look settled.

Maintainer options:

1. Remove the closing reference before merge (recommended)
   Edit the PR body so GitHub no longer detects Feature request: Show a provider icon in notification so it's clear to which provider notification related too #1828 as a closing issue reference while preserving a non-closing link.
2. Accept issue auto-close deliberately
   If maintainers decide this decision spec should close the provider-icon request, merge with the current closing reference and treat that closure as intentional.

Next step before merge

• [P2] Owner-authored draft PR needs maintainer review for the notification identity direction and a PR-body fix for the accidental closing reference.

Security
Cleared: The docs-only diff adds Markdown and an SVG under docs without code execution, dependency, secret, or workflow changes.

Review details

Best possible solution:

Keep the decision spec draft open, remove the accidental closing reference from the PR body, then let a maintainer decide whether the provider-icon issue stays open for supplementary attachment exploration.

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

Not applicable; this is a documentation proposal, not a runtime bug reproduction. Source inspection confirms the current notification runtime is only background context for the documented decision.

Is this the best way to solve the issue?

Mostly yes for the source diff: documenting the platform boundary before changing notification behavior is a narrow maintainable path. The PR body should first be fixed so the linked provider-icon issue is not auto-closed accidentally.

AGENTS.md: found and applied where relevant.

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

Label changes

Label changes:

• add P3: The PR is a low-risk documentation/design proposal for notification identity rather than a runtime fix.
• add merge-risk: 🚨 automation: Merging with the current PR body may automatically close the linked provider-icon issue contrary to the documented scope.
• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: Real behavior proof is not required because this PR only changes files under docs/.

Label justifications:

• P3: The PR is a low-risk documentation/design proposal for notification identity rather than a runtime fix.
• merge-risk: 🚨 automation: Merging with the current PR body may automatically close the linked provider-icon issue contrary to the documented scope.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: Real behavior proof is not required because this PR only changes files under docs/.

Evidence reviewed

What I checked:

• Repository policy read: AGENTS.md was present and read fully; its docs, validation, and read-only review guidance applied to this review. (AGENTS.md:1, c3d33308ac06)
• Docs-only PR diff: The PR adds two docs files, 145 additions, and no runtime source changes. (394ba327a72c)
• Accidental closing reference: GitHub reports Feature request: Show a provider icon in notification so it's clear to which provider notification related too #1828 in closingIssuesReferences even though the PR body says the draft does not close that issue. (394ba327a72c)
• Current notification delivery surface: Current main creates UNMutableNotificationContent and sets title, body, sound, and badge; there is no provider visual argument in the shared post helper. (Sources/CodexBar/AppNotifications.swift:40, c3d33308ac06)
• Provider-first quota/session titles: Session and quota notification copy resolves provider display names and uses them in localized titles before posting through AppNotifications. (Sources/CodexBar/SessionQuotaNotifications.swift:51, c3d33308ac06)
• Login and permission titles: Login and permission notification paths also build provider-named titles before calling the shared notification poster. (Sources/CodexBar/StatusItemController+Actions.swift:4, c3d33308ac06)

Likely related people:

• Peter Steinberger: History shows the original session quota notification implementation and recent session/quota notification hardening in the same product area. (role: feature owner and recent area contributor; confidence: high; commits: 4fc3132c525e, 15f5a3d3ae3f, 0de6cac0a3c8; files: Sources/CodexBar/AppNotifications.swift, Sources/CodexBar/SessionQuotaNotifications.swift, Sources/CodexBar/QuotaWarningAlertOverlayController.swift)
• Alekstodo: Commit 18eb73d added quota warning controls and changed the notification files this decision would govern. (role: introduced adjacent behavior; confidence: high; commits: 18eb73dde236; files: Sources/CodexBar/AppNotifications.swift, Sources/CodexBar/SessionQuotaNotifications.swift, Sources/CodexBar/UsageStore+Refresh.swift)
• SAASEmpiree: Commit d4f245e added an on-screen quota warning alert option in the same notifier code path. (role: recent adjacent contributor; confidence: medium; commits: d4f245e518fa; files: Sources/CodexBar/SessionQuotaNotifications.swift)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

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.

How this review workflow works

• 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.

[steipete]

Owner decision: do not pursue provider-specific notification sender icons.

macOS does not expose a supported per-notification sender-icon replacement for this class of notification. Attachment or communication-avatar workarounds would add the wrong semantics and a second media surface. Closing this non-shipping decision draft without merging.