#2023 feat(cli): tell operatives they have swamp-club notifications waiting

Filed against swamp (the CLI). Parent: the swamp-club product-nurture epic. Depends on the swamp-club unread-count endpoint.

What ships

A one-line notice after a command finishes, when the operative has unread swamp-club notifications:

You have 3 unread notifications on swamp-club.com — see them at
https://swamp-club.com/inbox

Follow the update-notice pattern exactly

UpdateNotificationService already solves this problem in this codebase, and the shape is the requirement, not a suggestion:

• getNotification() reads local state only — a cache file, no network. The rendered line costs zero milliseconds.
• backgroundCheck() is fire-and-forget, refreshes the cache only when stale, catches everything, and writes a timestamp even on failure so the cooldown is respected while offline.
• Never break the CLI for it. Every path swallows.

New: src/domain/notifications/notification_notice_service.ts and src/infrastructure/persistence/notification_cache_repository.ts, mirroring AuthNudgeRepository (~/.config/swamp/, atomic write, {} on any read failure).

Gates, all of which already exist for the auth nudge

• outputMode === "log" only. Never with --output json — a stray line in a JSON stream breaks every programmatic consumer.
• Authenticated only. No key, no check, no line, no network call. The auth nudge already covers the logged-out case and must not be shown alongside it.
• Throttled. Refresh at most every 4h (proposed); show at most once per 24h even when the count is unchanged, so a persistently unread inbox does not nag on every command.
• Suppressible. swamp config toggle plus a SWAMP_NO_NOTIFICATION_CHECK environment escape, matching how update checks are opted out of.
• Silent in CI and non-TTY. Same detection the other notices use.

The count is a hint, not a truth

The cache can be up to 4h stale, and that is fine — the line says how many were waiting, and the inbox is authoritative. Do not add a synchronous refresh to make the number exact; that trades the entire latency property for a correctness the operative does not need.

Verification

• Unit: a fresh cache shows nothing; a cache with unread > 0 inside the window shows the line; a stale cache triggers exactly one background refresh; a network failure still writes the timestamp.
• --output json emits nothing extra, asserted on the raw stdout bytes.
• Manually: log in, generate an unread notification from swamp-club, run any command, see the line. Log out, run again, see nothing.