---
title: "Proactive cards"
description: "What fox9 may say unprompted (the card), how the announcement governor tiers it, and the answers the operator may give."
type: "living"
source: "docs/contracts/proactive-card.v1.md"
verified: "2026-11-14"
group: "Contracts"
---

> **Living doc**, checked against the code 2026-11-14

proactive-card.v1 — what Vulpine may say unprompted, and what the operator may answer

- Status: **live.** The types, the goldens and the validator are in the protocol crate. The gateway wires the
  governor, the spoken card and the answer grammar. Two producers cut a card: a finished herdr agent's report cuts a
  `herdr_lifecycle` suggestion, `Read it` / `Dismiss` (`herdr_report_card` in `ws/reports.rs`), and the agent door
  turns a linked agent's `show` or `result` into a suggestion with one `Dismiss` action (`agent_door.rs`).
- Relates: ADR 0030 (the announcement governor, which decides WHETHER and WHEN), ADR 0028 (hash-bound approvals) and
  the approval socket (where a `requires_confirm` answer lands).
- Types: `ProactiveCard`, `ProactiveCardKind`, `ProactiveCardAction`, `ProactiveCardVerb`
  in `crates/protocol/src/lib.rs`; ts-rs bindings in `packages/protocol/src/generated/`.
- Goldens: `benchmarks/fixtures/proactive-card.v1/golden/{suggestion,alert,digest}.json`;
  refusals: `invalid/{hex-in-speech,unknown-verb,arg-missing}.json`.
  `cargo test -p vulpine-protocol proactive_card` runs both sets.

## Why a card

A card says **what** an unsolicited announcement is and **what the operator may do about it**. Its text is authored
upstream, but its answers come from a closed set of verbs the gateway already runs, never from a fresh brain turn. A
spoken "shall I?" can never dispatch something the brain invented.


## Shape (schema 1)

| field | type | rule |
|---|---|---|
| `schema` | u32 | `1` |
| `id` | string | 1..=64 chars; the governor candidate id |
| `kind` | `suggestion` \| `alert` \| `digest` | a suggestion asks, an alert tells, a digest sums up |
| `source` | string | a snake_case governor source (`Source::as_str` in `announce_governor.rs`): `background_work`, `herdr_lifecycle`, `agent`, `approval_card`, `camera_event`, `alarm`, … |
| `title` | string | 1..=80 chars; the text surface's headline |
| `spoken_form` | string | 1..=280 chars; exactly what the voice says; **no hex** (sha/UUID-shaped tokens, `sha256:`, citation tokens are refused) |
| `body_md` | string | ≤ 4000 chars; may be empty |
| `actions` | array | 1..=4 of `{ verb, label (1..=40), arg? }` |
| `created_at_ms`, `ttl_ms` | u64 | ttl ≥ 1000 |

### Verbs (closed; an unknown verb fails to deserialise)

| verb | arg | what the gateway does |
|---|---|---|
| `dismiss` | — | drops the card, reaction `ignored` |
| `snooze` | ms (u64) | re-offers after the delay (governor TTL permitting) |
| `sitrep` | — | `GatewayReport::Sitrep` |
| `start_over` | — | `GatewayReport::StartOver` |
| `mic_recalibrate` | — | `GatewayReport::MicRecalibrate` |
| `reading_control` | a `ReadingAction` name | `GatewayReport::ReadingControl` |
| `home_undo` | — | `GatewayReport::HomeUndo` |
| `home_verb` | `"on <subject>"` / `"off <subject>"` | `GatewayReport::HomeVerb` (the candidates-or-ask contract still applies) |
| `approval_card` | ledger seq (u64) | speaks that approval card; the next utterance answers it |
| `herdr_agent_report` | ledger seq (u64) | `GatewayReport::HerdrAgentReport` |
| `herdr_prompt_relay` | ledger seq (u64) | `GatewayReport::HerdrPromptRelay` |

A new verb needs a `GatewayReport` shape first. Nothing here takes free text from the card into a brain turn.


## How a card is spoken and answered

The spoken line and the answer grammar are `crates/voice_gateway/src/proactive_card.rs`. A card answer reaches the
same verb handlers the spoken grammar in `turn.rs` reaches.


**The candidate carries the card.** `Candidate` has `card: Option<ProactiveCard>`. Every producer but the two above
passes `None`, and the gate decides the same for them. The governor decides WHETHER on `{source, score, ttl, reason}`
and never reads the card.

**The exact spoken form.** `spoken_form`, then the labels as one closed question; never the title, never `body_md`:

```
<spoken_form, a full stop added if it has no final punctuation> Say <labels>.
```

The labels are lower-cased at the first letter (unless the second is also upper case) and joined `a` / `a or b` /
`a, b, or c`. The suggestion golden speaks as:

> The agent in pane one three has finished the tracker migration. Shall I read
> its report? Say read the report or not now.

A card is spoken on the session's voice, never through the room verb: the answer has to come back to the mic that
heard the question. It is validated (`ProactiveCard::validate`) and run through `tts_text::normalize_tts_text`, the
no-hex scrub every spoken line gets. A card that fails either is dropped with `outcome: invalid` and a
`proactive_card_refused` row, never half-spoken. A card line gets no age clause: the question is asked now or not at
all.

**The answer grammar.** After a card is spoken the session holds
`pending_card { id, kind, source, tier, actions, deadline_ms, card }` on `LiveSessionState`. It is attached at speak
time and carried across a loadout rebuild. An `over_and_out` rotation drops it. The deadline is the card's `ttl_ms`
clamped to `[5 s, 10 min]`.

The next utterance (STT final or `text_utterance`) is matched before the turn machine, in the seat
`answer_pending_approval_card` takes, so `turn.rs`'s `MIN_ARMED_REQUEST_CHARS` floor never eats a short label ("done",
"not now"). Matching ignores case, punctuation and repeated whitespace, and drops a leading `hey` / `fox9` /
`fox nine` / `fox 9`. The match must consume the whole phrase: a label inside a longer sentence ("read the report from
the overnight lane to me") goes to the brain. Beside the producer's label, each verb answers to its own fixed phrases
(`dismiss` / `not now` / `never mind`, `snooze`, `sitrep`, `start over`, `recalibrate the mic`, `undo that`, …).

| verb | routing | what happens |
|---|---|---|
| `dismiss` | **routes** (local) | card closed, `answered(dismiss)` |
| `snooze` | **routes** (local) | re-admitted to the board after `arg` ms, clamped to `[5 s, 60 min]` (default 10 min), score 0.7, reason `proactive_card_snoozed` |
| `sitrep` | **routes** | `GatewayReport::Sitrep` |
| `start_over` | **routes** | `GatewayReport::StartOver { phrase: StartOver }` |
| `mic_recalibrate` | **routes** | `GatewayReport::MicRecalibrate` |
| `reading_control` | **routes** | `GatewayReport::ReadingControl { action }` from the arg (an unparsable arg is `unrouted`) |
| `home_undo` | **routes** | `GatewayReport::HomeUndo { phrase: <label> }` |
| `home_verb` | `unrouted` | an open subject plus the candidates-or-ask contract; needs its own confirm tier |
| `approval_card` | `unrouted` | the seq lives in a session ledger the answer path does not reach |
| `herdr_agent_report` | **routes** | speaks the ledger line attached to the action at speak time; `unrouted` when the ledger has evicted the seq |
| `herdr_prompt_relay` | `unrouted` | as `approval_card` |

A `requires_confirm` action is not wired and is recorded `unrouted`. **No match is not an answer**: the utterance goes
to the brain as it would without a card. The card stays pending until its deadline, then resolves `ignored` and holds
nothing. Answering a card counts as operator engagement, so the announcement watch resolves `Accepted`.

**Trace.** One `proactive_card { id, kind, source, tier, outcome }` row per state change,
`outcome ∈ admitted | spoken | deferred(<reason>) | answered(<verb>) | ignored | invalid | unrouted(<verb>)`.
`admitted` means a producer put it on the board (tier `none`). A card answered by an utterance also carries
`answered_by: voice | text`. `deferred(...)` rows are written for candidates the governor holds. A card that goes
terminal (notify / drop) is traced by the announcement rows only, because the governor has released it.

## Admin projection

One row per card on Errors & Events, from `AdminEventSink::record_proactive_card(outcome, message, warning)`:
`component_id: gateway.announcements`, the outcome as the `phase`, ids and counts in the message, never a card's text.
A card nobody answered is written `ignored`; no `expired` outcome is written.

`GovernorProjection.cards_by_kind` counts queued and digest-bound candidates by card kind, beside `spoken_last_hour`.
It reaches the panel as `AdminAnnouncementsSnapshot.cards_by_kind?: AdminAnnouncementCardKind[]` (optional, so an
older Admin build reads the snapshot unchanged).

## Validation elsewhere

A non-Rust surface validates a card against the same golden and invalid files. Its TypeScript types are generated
into `packages/protocol`; no TypeScript validator ships.

