feat(announcements): render the modal surface with the §D8 gate (PR-5)

[philmerrell]

Fifth and last surface PR in the feature-announcements epic (spec: docs/specs/feature-announcements.md). The spec calls this the highest-risk PR — "everything that can annoy a user lives here." Only PR-6 (/stats) remains after it.

Independent of #976 (PR-4). Branched from develop and touches no file PR-4 touches — the modal is started from app.config.ts, not mounted in app.html. Either can merge first. That is deliberate: per the #419 post-mortem, stacking a PR whose base merges first is how a commit gets stranded.

The gate is the substance

AnnouncementModalService opens the modal on route settle, and only when:

• no active stream (MessageMapService.isLoadingSession() is null)
• no pending tool-approval, OAuth-consent, or MCP-App-consent prompt
• no draft in a focused composer
• the route is not minimal-chrome (don't put a dialog over a shared artifact someone opened from a link)

The consent checks are not redundant with the stream check. Per docs/specs/mid-turn-steering.md (#934), isLoading() is false while a turn is paused on an interrupt — so a stream-only gate would happily throw a dialog over an OAuth consent prompt and steal its focus. The prompt services are asked directly. The spec names tool-approval and oauth-consent; MCP-App consent is the same class of prompt and is included for the same reason.

Every gate input is read untracked, and that is load-bearing. Read reactively, the effect would re-run the instant a stream ended or a consent was answered — firing a modal into the middle of the session, seconds after the user finished a thought. §D8 forbids exactly that: a failed gate leaves the announcement eligible, it does not queue it. The effect therefore tracks only the announcement and a navigation counter and snapshots the rest. There is a spec for this specifically (does NOT fire when the blocker merely clears mid-session), because it is the kind of thing a later refactor would "clean up" by deleting the untracked call.

requiresAck

The confirm button is the only exit: no ✕, disableClose on the overlay, and the in-component Escape and backdrop handlers return without writing an ack. Belt and braces on purpose — the CDK option and the guards fail independently, and being stuck under an undismissable dialog is the worst outcome this feature can produce.

The button label follows the ack it writes — "I understand" → acknowledged, "Got it" → dismissed — so it cannot misdescribe the record it creates.

Smaller things

• Started via provideAppInitializer, same shape as ThemeService. A CDK overlay is not a layout element, and nothing else would ever inject the service.
• Body renders through .message-block, not prose — the typography plugin is not installed, so the older user-menu-link-modal's classes are inert and preflight strips list markers.
• Sanitization stays on (§D10). admin.announcements is delegable, so this body may be authored by someone who is not a platform admin and it is broadcast to every user.

Verification

Unit: 23 specs across the component and the gate, including the #934 shape (consent pending while the stream reads idle) and the mid-session-clear case above.

End to end against dev data with a local app-api:

	Result
requiresAck on load	opens; no ✕; Escape and backdrop clicks leave it open
confirm button	writes acknowledged at rank 3, upgrading the seen row in place rather than duplicating
requiresAck off	✕ and Escape both write dismissed at rank 2
after either	server returns modal: null, both panel entries survive (§D1/§D2)
appearance	light, dark, and 375px bottom-sheet with no horizontal overflow

Full SPA suite: no new failures. The 4 in admin/marketplace/pages/submission-review.page.spec.ts are pre-existing — clean develop fails the same file with 5, the known isolate: false cross-file flake.

Test data created in dev was deleted afterwards; the table is back to just the "Welcome to Dev" announcement.

Still open in the epic

• PR-6 — /stats + ack counters + admin reporting.
• D10 audit logging is still deferred. The spec requires announcement writes to go through the admin.audit trail; AuditAction is a closed namespace of role-only actions and extending it touches the non-delegable admin.audit scope. Worth a decision before requiresAck is used for anything policy-shaped — an acknowledgement record with no audit trail behind the authoring side is a weaker record than it looks.

🤖 Generated with Claude Code