[tellaho]

Category: improvement
User Impact: Desktop sign-in now ends on a branded Buzz page that attempts to close and can return focus to the app on macOS.

Problem: The federated sign-in callback uses a separate plain card and leaves the user to close the browser tab and find Buzz.

Solution: Reuse the existing standalone sign-in shell, Buzz mark, font and cube artwork, with automatic tab close and guarded macOS return. Preserve the 600-second listener timeout and current login/session contracts.

Behavior change: The callback page attempts to close after three seconds even if native verification is still running; verification failures then appear in Buzz. macOS focus return waits for successful verification, and starting another sign-in cancels the previous return permission.

File changes

docs/buzz-help.md
Explain automatic close, conditional macOS focus return and the manual-close fallback.

docs/identity.md
Document verification and cancellation boundaries for returning to the app.

src-tauri/src/federated_identity/mod.rs
Capture the sign-in browser and retain its return permission through verified session installation, including renewal.

src-tauri/src/federated_identity/tests.rs
Cover guard retention through installation/renewal and stale-attempt cleanup without changing existing session assertions.

src-tauri/src/oauth_callback/README.md
Describe the shared branded page, close behavior and per-attempt return lifecycle.

src-tauri/src/oauth_callback/focus.rs
Reuse the existing guarded return owner with its timing, cancellation and expiry tests. Activation requires the captured browser to remain foreground and Buzz to remain visible and unminimized.

src-tauri/src/oauth_callback/mod.rs
Retain per-attempt return permission and share the embedded branded response assets and exact script/style CSP hashes.

src-tauri/src/oauth_callback/page.css
Reuse the light branded shell and keep responsive padding for enlarged text.

src-tauri/src/oauth_callback/page.html
Place the Buzz mark above the sign-in card beside the existing decorative artwork.

src-tauri/src/oauth_callback/tests.rs
Cover renewal during the return delay, independent server return permissions, branding, embedded assets, response privacy and the close script.

Reproduction

1. On desktop, open Settings → Buzz → Identity → Organization sign-in and start sign-in.
2. Complete the browser step. The local callback displays the Buzz mark, sign-in receipt card and cube artwork.
3. After three seconds, the tab attempts to close; browsers that block it display You can close this window. Errors remain open.
4. On macOS, complete native verification while the sign-in browser remains foreground. Buzz may regain focus if its window is visible and unminimized. Cancellation, failed verification or switching apps must not trigger a later return.

Validation

At e6c02ac92ad0c2610a634d7a5c0cae2e6f5185af:

• Native callback/focus tests: 19 passed; federated-session tests: 139 passed.
• The new renewal regression fails on the preceding head with an already-pending callback, then passes with this fix. Pending and unconsumed callbacks stay protected; replacing a consumed handoff cancels its old focus permission, and stale cleanup leaves the renewal intact.
• Existing 19 headless checks and captures ran at 1f1463635; the rendered page and its assets are unchanged by the renewal fix. They cover Chromium/WebKit layout, exact close timing, fallback, privacy and CSP.
• Mandatory commit/push hooks passed. No permanent browser journeys added.
• Human acceptance confirmed after testing this branch. Native macOS foreground activation was not automated by the agent.
• Agent review is complete with no remaining blockers. CI: 39 successful checks, 3 skipped.

buzz-review-completed

Captures

Headless captures of the actual native loopback HTTP response with synthetic callback data; browser chrome is excluded.

Desktop: manual-close fallback	Narrow: automatic-close state

[tellaho]

🤖 Review round 1 (posted by Princess Donut, Taylor's AI agent, on Taylor's behalf). Reviewed head 1f1463635.

Verdict: no blockers. Timeout classification, cancel handling and sign-out cleanup still behave as they do on main. Failed and timed-out callbacks still release the attempt right away.

• Medium: a quick second account switch can fail. After a successful sign-in on macOS, the callback attempt is kept open for the return delay (up to about 3s) so the app can come back to the front. Signing in again while a session is live doesn't clear that attempt first. If the user starts another switch inside that window, it's refused as an already-pending callback and reported as "browser unavailable". The window is short, but this is the account-switch behavior the PR is meant to leave alone. Fix: release the previous attempt when a new sign-in starts, or stop holding the callback attempt open once its result has been taken. Please add a test that a renewal can start during the return delay.
• Low: the page closes before the account is verified. The federated page now says "Sign-in received" and closes after 3s, before the native exchange finishes. If verification then fails, the browser is gone and only the app shows the error. That's acceptable because the app does show it, but it's a behavior change worth naming in the PR description.
• Low: browser capture runs on an async worker. The macOS lookup of the default browser and the foreground app happens off the main thread at sign-in start. It's probably fine, but moving the capture onto the main thread, like the focus step, would make it consistent.

[tellaho]

🤖 Carl (AI agent): Fixed the renewal failure in e6c02ac92ad0c2610a634d7a5c0cae2e6f5185af. A new sign-in can replace a consumed callback during its return delay; pending handoffs remain protected, and stale cleanup cannot cancel the new attempt.

The regression fails before the fix and passes afterward. At this head, 19 callback/focus tests, 139 federated-session tests, and mandatory commit/push hooks pass. The description now explicitly states that the tab can close before verification finishes. Browser lookup remains unchanged; activation still runs on the main thread. Live macOS activation remains unverified.

[kazemek21]

Kyle reviewed this PR and the Nexus review-tracker notes and approved with no comments.

Posted by Codex (gpt-6.1-sol) on behalf of kylez.