# Subnet notification primitive

## Status

accepted (2026-06-01)

## Context

Three flows independently needed "deliver something to the user's most-recently-active session and make sure they see it": the **self-update prompt** (CONTEXT §Self-update), the **consent escalation** (CONTEXT §Consent & security gates — both already described as "the registry-resolution precursor to PresenceChannel"), and emerging **subnet events** (node paired, external-subnet pairing request). Each was about to grow its own ad-hoc delivery + "did the user see it?" handling. They are the same thing.

## Decision

Introduce a **notification (notif)** as a first-class kind, distinct from inter-agent messages, and **refactor the self-update prompt and consent escalation to be notif producers** (one primitive, open producer set). A notif is **user-directed, dismissable, and resurfacing**; a message is agent→agent and consumed once.

- **Per-subnet, replicated spool.** Notifs are subnet events; the spool replicates across that subnet's nodes (reusing subnet-registry distribution, ADR-0006). Each notif is subnet-tagged; **dismiss-state replicates subnet-wide**, eventually consistent.
- **Two states:** *seen* (surfaced at least once, tracked per-endpoint) vs *dismissed* (explicit ack — `spt notif dismiss`, or the agent marks it). Surfacing ≠ dismissal.
- **First-fire** → the user's most-recently-active endpoint in that subnet (presence resolution). **Resurface** undismissed notifs at existing reported boundaries — state→active (`wake`), `api boundary clear`, `api boundary compact`, new-session-start — gated by *seen-per-endpoint* plus a **cross-endpoint suppression timeout** (default ~1h) so a notif can't bounce between endpoints. Scoped to subnets the endpoint is **visible in** (ADR-0006).
- **Delivery reuses messaging.** A notif to an agent is a notif-flavored envelope delivered to the agent's perch via the existing path; the agent surfaces it. An optional **`notif_command` manifest template** (on **both** harness-adapter and shell-adapter manifests) renders it endpoint-native (OS toast, GameRobot `alert-symbol`), combinable with agent-surface. If presence resolves to a **Shell** attached to the endpoint, the notif renders via *that shell's* template — the v1 seam and the M5 generalization are one.
- **`spt notify`** lets any agent issue a subnet-wide notif (v1: reaches the user on their active endpoint). The **envelope `from`** carries the issuer's endpoint id + node + subnet (subnet surfaced only to multi-subnet receivers).

## Consequences

- Update-prompt and consent-escalation delivery code collapses onto one primitive; the deferred PresenceChannel later generalizes this primitive's delivery step rather than three separate ones.
- New v1 requirement to register: the notification primitive + `spt notify` + the `notif_command` manifest seam. Lands with M4 (subnet-distributed spool needs the registry-distribution layer); the manifest seam is authored alongside.
- **Forward (cross-user, ADR-0006 seam):** dismissal and the spool key generalize to per-(subnet, user); `spt notify` gains targeting (all subnet users by default, or specific users); the `from` field is what makes attributed/targeted delivery possible.
- Builds on ADR-0006 (subnet distribution, visibility scoping) and the existing presence-resolution + inject-input machinery.