#3705 Server-driven warning and info messages to CLI users, targeted by swamp version (exploration)

Problem

swamp-club has no way to tell users of a given swamp version something they need to know. The prompt was Lab #3699: once a fixed release ships, users still on a vulnerable release should be told to upgrade, and why. Today:

• The CLI has no generic channel for server-supplied text. It has no notices or messages field, does not read a deprecation, Sunset or warning header, has no 426 or minimum-version handling, and the auth gate only prints its own fixed strings (blockMessage, src/cli/auth_gate.ts).
• swamp-club does not read the client version anywhere, though every swamp-club request carries User-Agent: swamp-cli/<version> (src/cli/load_identity.ts:26), and telemetry reports swampVersion.
• The only upgrade prompt is the local update notice (a daily HEAD to artifacts.swamp-club.com/swamp/stable, and a staleness note at 30 days). It cannot say why an upgrade matters, and it is suppressed in --json, -q, CI and when update checks are turned off.

Releases from v20261001.191636.0-sha.71c25269 require a swamp-club account, so they talk to swamp-club regularly. That makes a server-driven channel reachable, but only for releases that know how to display it.

Goal

A way for swamp-club to send warning and info messages to users, targeted by client version (and possibly by collective or account), that reaches users in time for security fixes and degrades safely.

Open exploration

These are options to weigh, not a decided design.

Delivery channel

1. A notices field on GET /api/whoami, as its own optional top-level field (like collectiveEntitlements, per the AGENTS.md rule on the whoami organizations contract). Reached on login, the weekly proof refresh and hourly CI token checks, but not on every command, because a cached proof skips the network.
2. A response header (for example Swamp-Notice) on any swamp-club response, read by the shared HTTP client. Reaches every command that talks to swamp-club, not only the gate.
3. A dedicated, cacheable endpoint (for example /api/v1/cli/notices?version=) polled on the same cadence as the update check, independent of auth, so unauthenticated and pre-auth-gate flows can get it too.
4. Piggy-back on the update check: publish a small signed notices document next to the stable channel on artifacts.swamp-club.com.
5. Minimum supported version: the server declares a floor (or a per-version advisory) and the CLI renders a fixed, well-worded message, with or without blocking.

Content and safety

• Free text from the server or a fixed set of message kinds rendered by the CLI (for example security-upgrade, deprecation, maintenance). Free text is flexible, but anything printed to a terminal must be sanitised, and an attacker who can tamper with TLS can forge it. A fixed vocabulary with parameters limits what a forged message can say.
• Should notices be signed with the same key the server already uses for verification proofs (sign-verification-proof.ts), so a forged notice is rejected?
• Severity levels, and whether a critical notice can block a run, or only warn. Blocking must always leave swamp update working.

Rendering and frequency

• Where it shows: stderr in log mode, a notices array in --json output, and whether -q and CI suppress it. Agents driving swamp in JSON mode are a large share of users and must see security notices too.
• How often: once per notice id, once per day, or every run until acknowledged. Local dedupe state lives where the update-check cache lives.
• Opt-out rules: info notices can be silenced; security notices probably cannot.

Targeting and measurement

• Version ranges (from the User-Agent or an explicit version parameter), platform, collective.
• Using whoami User-Agent and telemetry swampVersion to measure adoption before and after a notice.

Reaching releases that predate the channel Releases without the new code can only be reached through existing behaviour. Options found while triaging #3699, each with drawbacks:

• the stable-channel update notice (generic text, suppressed in JSON and CI);
• returning a non-401 4xx from whoami to old User-Agents, optionally with short-lived proofs so it bites sooner (fixed, misleading "refused the check" text; never 401 with authenticated false, which deletes the proof and reports revoked credentials);
• an error text on extension registry endpoints, printed verbatim but only on extension commands, and it breaks them.

Out of scope

The 3699 fix itself (Deno bump), and update integrity (#3704).