@vellumai/assistant 0.12.2 → 0.12.3-staging.2

package/src/notifications/README.md

@@ -91,11 +91,12 @@ Each policy defines:
 
 ### Conversation Strategy Types
 
-| Strategy                         | Behavior                                                                                                                                                                                                                                     | Used by                                  |
-| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
-| `start_new_conversation`         | Creates a fresh conversation per delivery. The conversation is surfaced via SSE.                                                                                                                                                             | `vellum`                                 |
-| `continue_existing_conversation` | Looks up a previously bound conversation by binding key (sourceChannel + externalChatId) and appends to it. When no bound conversation exists (first delivery to a destination), creates a new one and upserts the binding for future reuse. | `telegram`, `whatsapp`, `slack`, `email` |
-| `not_deliverable`                | Channel cannot receive notifications. Pairing returns null IDs.                                                                                                                                                                              | `phone`                                  |
+| Strategy                         | Behavior                                                                                                                                                      | Used by                                                                                      |
+| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| `start_new_conversation`         | Pairs the delivery with a new or reused conversation, or appends to the producing one (see Conversation Pairing below).                                       | `vellum`                                                                                     |
+| `continue_existing_conversation` | Resolves the destination chat's home conversation, creating one on first delivery. The delivered post is written there only once the channel acknowledges it. | `telegram`, `slack`, `discord`, and the non-deliverable `whatsapp`, `email`, `a2a`, `plugin` |
+| `push_only`                      | Pairs nothing. The push deep-links through the vellum delivery's conversation.                                                                                | `platform`                                                                                   |
+| `not_deliverable`                | Channel cannot receive notifications. Pairing returns null IDs.                                                                                               | `phone`                                                                                      |
 
 ### Helper Functions
 
@@ -106,31 +107,23 @@ Each policy defines:
 
 ### How to Add a New Channel
 
-1. Add the channel to `CHANNEL_IDS` in `channels/types.ts`.
-2. Add a policy entry in `CHANNEL_POLICIES` in `channels/config.ts`. The compiler will enforce this.
-3. If `deliveryEnabled: true`, add an adapter in `adapters/` and register it in `emit-signal.ts` `getBroadcaster()`.
-4. Add a connectivity check in `getConnectedChannels()` in `emit-signal.ts`.
-5. Add a destination resolver case in `destination-resolver.ts`.
+1. Add the channel to `CHANNEL_IDS` in `packages/service-contracts/src/channels.ts` (re-exported through `channels/types.ts`).
+2. Add its policy to `CHANNEL_POLICIES` in `channels/config.ts`; the compiler requires an entry for every channel. `deliveryEnabled: true` makes it a `NotificationChannel` (`DeliverableChannelId` is derived from these policies), and `conversationStrategy` decides what conversation pairing does for it.
+3. For a deliverable channel, add an adapter in `adapters/` implementing `ChannelAdapter` and register it in `getBroadcaster()` in `emit-signal.ts`.
+4. Add its case to `getConnectedChannels()` in `emit-signal.ts` and to `resolveDestinations()` in `destination-resolver.ts`. Both switch over deliverable channels, so the compiler flags a missing case.
 
-## Conversation Pairing Invariant
+## Conversation Pairing
 
-**Every notification delivery gets a conversation.** Before the adapter sends a notification, `pairDeliveryWithConversation()` (in `conversation-pairing.ts`) materializes a conversation and seed message based on the channel's conversation strategy and the decision engine's per-channel conversation action:
+Before an adapter sends a notification, `pairDeliveryWithConversation()` (in `conversation-pairing.ts`) decides which conversation the delivery belongs to, from the channel's `conversationStrategy` and the decision engine's per-channel conversation action. The module header and the function's inline comments are the source of truth for the details. The rules that hold across them:
 
-### Conversation Reuse Path (`reuse_existing`)
+- **Vellum (`start_new_conversation`)**:
+  - A signal that sets `requiresConversation` gets a conversation of its own, created with its seed message before the send (`standard` unless the producer overrides `conversationType`). An explicit `reuse_existing` action appends to a valid target instead, and falls back to a new conversation (`conversationFallbackUsed: true`) when the target is stale.
+  - A signal that does not set it creates no conversation, except that with `assistant-initiated-threads` on, an `assistant.share` with no `conversationMetadata.source` of its own is promoted to one when its producing conversation is a background or scheduled run, or does not resolve (`withAssistantInitiatedThread()`). Otherwise its body is appended to the conversation that produced it (resolved from `sourceContextId`). A `chat.assistant_reply` appends nothing, because the full reply is already in that transcript.
+- **External channels (`continue_existing_conversation`)**: only the chat's home conversation is resolved, and nothing is written. The broadcaster records the delivered post as an assistant row once the channel acknowledges it (`recordDeliveredChannelPost`), so a failed or pending delivery never reads as something the assistant said.
+- **`push_only`** (platform) and **`not_deliverable`**: nothing is paired. Platform push deep-links through the vellum delivery's conversation.
+- **Guardian-request deliveries to channels** pair nothing either: they are projections of a canonical request, and only their vellum delivery carries a conversation (see `notifications/AGENTS.md`).
 
-When the decision engine selects `reuse_existing` for a channel with a valid candidate `conversationId`:
-
-1. The pairing function looks up the target conversation.
-2. If the conversation exists and has `source: 'notification'`, the seed message is **appended** to the existing conversation (not a new one). The result has `createdNewConversation: false`.
-3. If the target is invalid (does not exist, or has a different `source`), the function falls back to creating a new conversation and sets `conversationFallbackUsed: true` on the result. A warning is logged with the invalid target details.
-
-### New Conversation Path (`start_new` / default)
-
-- **`start_new_conversation`**: Creates a new conversation with `conversationType: 'standard'` and `source: 'notification'`, plus an assistant message containing the conversation seed. Memory indexing is skipped on the seed message to prevent notification copy from polluting conversational recall. The result has `createdNewConversation: true`.
-- **`continue_existing_conversation`**: Looks up a previously bound conversation by binding key (`sourceChannel` + `externalChatId` via `getBindingByChannelChat()`). When a valid bound conversation with `source: 'notification'` exists, the seed message is appended to it and the binding timestamp is refreshed. When no binding exists or the bound conversation is stale/invalid, a new conversation is created and the binding is upserted for future reuse. The result has `createdNewConversation: false` on reuse, `true` on fresh creation.
-- **`not_deliverable`**: Returns `{ conversationId: null, messageId: null }`.
-
-The pairing function is resilient -- errors are caught and logged. A pairing failure never breaks the delivery pipeline.
+Pairing is resilient: errors are caught and logged, and a pairing failure never breaks the delivery pipeline.
 
 ## Multi-Surface Copy Architecture
 
@@ -138,7 +131,7 @@ The system produces **three distinct copy outputs** per notification:
 
 | Output                    | Purpose                                          | Verbosity                |
 | ------------------------- | ------------------------------------------------ | ------------------------ |
-| `title` + `body`          | Native notification popup (macOS banner)         | Short and glanceable     |
+| `title` + `body`          | OS notification banner (desktop and mobile apps) | Short and glanceable     |
 | `deliveryText`            | Channel-native chat message text (Telegram)      | Natural chat phrasing    |
 | Conversation seed message | Opening message in the notification conversation | Richer and context-aware |
 
@@ -146,7 +139,7 @@ The system produces **three distinct copy outputs** per notification:
 
 1. The **decision engine** can produce `title`/`body` (popup copy), `deliveryText` (chat copy), and `conversationSeedMessage` (richer conversation content) per channel.
 2. **Adapters** use the surface-appropriate field:
-   - Vellum/macOS notifications use `title` + `body`.
+   - Vellum notifications use `title` + `body`.
    - Telegram delivery prefers `deliveryText` and falls back to `conversationSeedMessage`, then `body`, then `title`.
 3. **Conversation pairing** uses the conversation seed as the conversation's opening message:
    - If the LLM produced a valid `conversationSeedMessage`, it is used directly (after a sanity check rejects empty, too-short, JSON dumps, or excessively long values).
@@ -190,7 +183,7 @@ Reminder. Take out the trash. Action required.
 
 ## Conversation Surfacing via `notification_conversation_created` Event (Creation-Only)
 
-The `notification_conversation_created` SSE event is emitted **only when a brand-new conversation is actually created** by the broadcaster. Reused conversations do not trigger this event — the macOS client already knows about the conversation from the original creation.
+The `notification_conversation_created` SSE event is emitted **only when a brand-new conversation is actually created** by the broadcaster. Reused conversations do not trigger it.
 
 This is enforced in `broadcaster.ts` by gating the event emission on `pairing.createdNewConversation === true`:
 
@@ -206,20 +199,11 @@ if (
 }
 ```
 
-When a vellum notification conversation **is** newly created (strategy `start_new_conversation`), the broadcaster emits the SSE event **immediately**, before waiting for slower channel deliveries (e.g. Telegram). This avoids a race where a slow Telegram delivery delays the broadcast past the macOS deep-link retry window.
-
-The SSE event payload:
+When a vellum notification conversation **is** newly created (strategy `start_new_conversation`), the broadcaster emits the SSE event **immediately**, before slower channel deliveries such as Telegram, so a slow channel send cannot delay it.
 
-```ts
-{
-  type: 'notification_conversation_created',
-  conversationId: string,
-  title: string,
-  sourceEventName: string,
-}
-```
+The payload is `NotificationConversationCreatedEventSchema` in `api/events/notification-conversation-created.ts`.
 
-The macOS client listens for this event and surfaces the conversation in the sidebar, enabling deep-link navigation to the notification conversation.
+No first-party client acts on this event: the shared web renderer (browser, desktop app, mobile apps) lists it as a no-op in `use-stream-event-handler.ts`.
 
 ### Per-Dispatch Conversation Callback
 
@@ -228,7 +212,7 @@ The macOS client listens for this event and surfaces the conversation in the sid
 **Important distinction between the two callbacks:**
 
 - **Per-dispatch `options.onConversationCreated`**: Fires for **both** new and reused vellum conversation pairings. Callers like `dispatchGuardianQuestion` rely on this to create delivery bookkeeping rows before `emitNotificationSignal()` returns, regardless of whether the conversation was newly created or reused.
-- **Class-level `this.onConversationCreated` (SSE broadcast)**: Fires **only** when a brand-new conversation is created (`createdNewConversation === true && strategy === 'start_new_conversation'`). This emits the `notification_conversation_created` SSE event so macOS clients surface the new conversation in the sidebar. Reused conversations do not trigger this event because the client already knows about the conversation.
+- **Class-level `this.onConversationCreated` (SSE broadcast)**: Fires **only** when a brand-new conversation is created (`createdNewConversation === true && strategy === 'start_new_conversation'`). This emits the `notification_conversation_created` SSE event. Reused conversations do not trigger it.
 
 ## Schedule Routing Metadata and Trigger-Time Enforcement
 
@@ -255,8 +239,8 @@ The `routing_hints_json` field is free-form JSON metadata passed alongside the r
 When a schedule fires in `notify` mode, the routing metadata flows through the notification pipeline with a post-decision enforcement step:
 
 ```
-Schedule fires (scheduler.ts: notify mode)
-  → notifyScheduleOneShot callback (lifecycle.ts)
+Schedule fires (schedule worker: runDueSchedulesOnce in scheduler.ts, notify mode)
+  → emitScheduleNotifySignal (scheduler.ts)
     → emitNotificationSignal({ routingIntent, routingHints })
       → Decision Engine (LLM selects channels)
         → enforceRoutingIntent() (post-decision guard)
@@ -264,6 +248,8 @@ Schedule fires (scheduler.ts: notify mode)
             → Broadcaster → Adapters → Delivery
 ```
 
+`contextPayload.channelAllowlist` is an exclusive channel set. When present, emit-signal intersects it with connected channels, skips urgent vellum/platform force, and skips routing-intent expansion. `--preferred-channels` stays additive and is ignored when an allowlist is present. Access-request signals still force the in-app vellum card.
+
 The `enforceRoutingIntent()` function in `decision-engine.ts` runs after the LLM produces its channel selection but before deterministic checks. It overrides the decision's `selectedChannels` based on the routing intent:
 
 - **`all_channels`**: Replaces `selectedChannels` with all connected channels (from `getConnectedChannels()`).
@@ -280,8 +266,8 @@ A key design principle: **one schedule produces one notification signal that fan
 
 ```
 schedule_jobs table (routing_intent, routing_hints_json)
-  → scheduler.ts: claimDueSchedules() reads routing metadata
-    → lifecycle.ts: notifyScheduleOneShot({ routingIntent, routingHints })
+  → schedule-store.ts: claimDueSchedules() reads routing metadata
+    → scheduler.ts: emitScheduleNotifySignal({ routingIntent, routingHints })
       → emitNotificationSignal({ routingIntent, routingHints })
         → signal.ts: NotificationSignal.routingIntent / routingHints
           → decision-engine.ts: evaluateSignal() → enforceRoutingIntent()
@@ -290,7 +276,7 @@ schedule_jobs table (routing_intent, routing_hints_json)
 
 ## Channel Delivery Architecture
 
-The notification system delivers to three channel types:
+The notification system delivers to five channel types:
 
 ### Vellum (always connected)
 
@@ -300,18 +286,33 @@ Local SSE via the assistant's broadcast mechanism. The `VellumAdapter` emits a `
 - `title` and `body` -- rendered notification copy
 - `deepLinkMetadata` -- optional metadata for navigating to the relevant context (e.g. `{ conversationId }`)
 
-The macOS client posts a native `UNUserNotificationCenter` notification from this payload. When the user taps the notification, the client uses `deepLinkMetadata` to navigate to the relevant conversation.
+Every first-party client runs the shared web renderer (browser, desktop app, mobile apps), which posts a local notification from this payload and acks the delivery. When the user taps the notification, the client uses `deepLinkMetadata` to navigate to the relevant conversation.
+
+A guardian-sensitive notification (approval requests, access requests, channel activation codes) carries `targetGuardianPrincipalId` and is published with `targetActorPrincipalId`, so the event hub delivers it only to connections authenticated as the guardian. The client shows it when the sending assistant is new enough to apply that targeting (`clients/web/src/lib/backwards-compat/guardian-notification-targeting.ts`) and drops it otherwise.
+
+### Platform (always connected)
 
-### Telegram (when guardian binding exists)
+The `PlatformPushAdapter` posts the notification to the platform's `/v1/assistants/{id}/push/dispatch/` endpoint, which fans it out to the bound user's registered devices for native mobile push. Without platform credentials the delivery is recorded as failed.
 
-HTTP POST to the gateway's `/deliver/telegram` endpoint. The `TelegramAdapter` sends channel-native text (`deliveryText` when present) to the guardian's chat ID (resolved from the active guardian binding), with deterministic fallbacks when model copy is unavailable.
+### External channels: Telegram, Slack, Discord
+
+The assistant sends these itself. Each adapter calls the provider's API through the send module in `../messaging/providers/<channel>/`; nothing goes through the gateway.
+
+- **Telegram**: the `TelegramAdapter` sends channel-native text (`deliveryText` when present) to the guardian's chat ID through `telegram-bot/send.ts`, which calls the Telegram Bot API. Approval cards carry inline keyboard buttons and fall back to plain text with typed-reply instructions if the rich send fails.
+- **Slack**: the `SlackAdapter` posts to the guardian's DM through `slack/send.ts`. Approval cards render as a Card block with the approval's action buttons.
+- **Discord**: the `DiscordAdapter` opens the guardian's DM from their user ID through the Discord REST API and sends through `discord/send.ts`. Approval cards render component buttons.
+
+The destination for each comes from the guardian delivery list in `destination-resolver.ts`, with deterministic fallback copy when model copy is unavailable.
 
 ### Channel Connectivity
 
-Connected channels are resolved at signal emission time by `getConnectedChannels()` in `emit-signal.ts`:
+Connected channels are resolved at signal emission time by `getConnectedChannels()` in `emit-signal.ts`, from the guardian delivery list (`getGuardianDelivery()`):
 
-- **Vellum** is always considered connected (HTTP transport is always available when the assistant is running)
-- **Telegram** is considered connected only when an active guardian binding exists for the assistant (checked via `getActiveBinding()`)
+- **Vellum** is always considered connected (the local transport is always available when the assistant is running)
+- **Platform** is always considered connected; a missing credential surfaces as a failed delivery
+- **Telegram** is connected when the guardian has a chat ID on the channel
+- **Slack** is connected when the guardian's chat ID is a DM channel (`D`-prefixed), so a binding made from a shared channel never receives notifications
+- **Discord** is connected when a guardian binding names a user to DM
 
 ## Conversation Materialization
 
@@ -323,9 +324,9 @@ The system uses a single conversation materialization path for **all** notificat
 
 Guardian dispatch follows this same path and uses the optional `onConversationCreated` callback to attach guardian-delivery bookkeeping to the paired vellum conversation.
 
-### Conversation Pairing Invariant
+### Conversation-Before-Event Invariant
 
-For notification flows that create conversations, the conversation must be created **before** the SSE event is emitted. This ensures the macOS client can immediately fetch the conversation contents when it receives the conversation-created event.
+For notification flows that create conversations, the conversation must be created **before** the SSE event is emitted. This ensures a client can immediately fetch the conversation contents when it receives the conversation-created event.
 
 ## Conversation Decision Audit Trail
 
@@ -380,34 +381,23 @@ When the decision engine routes multiple guardian questions to the **same** conv
 
 Each guardian request is assigned a unique 6-character hex code (e.g. `A1B2C3`) at creation time, generated gateway-side during `guardian_requests_create` (`generateRequestCode()` in `gateway/src/db/guardian-request-store.ts`). The guardian sees the code only where they need to type it: in the plain-text fallback a transport appends when it sends a request without buttons, and in the router's disambiguation reply when several requests are pending.
 
-### Disambiguation Flow
-
-The disambiguation logic is identical on all channels — mac/vellum (`conversation-process.ts`) and Telegram (`inbound-message-handler.ts`):
-
-1. **Single pending delivery in the conversation**: The guardian's reply is matched to the sole pending request automatically. No request code prefix is needed. This is the **single-match fast path**.
-
-2. **Multiple pending deliveries in the conversation**: The guardian must prefix their reply with the request code of the question they are answering (e.g. `A1B2C3 yes, allow it`). Matching is case-insensitive.
+### Reply Routing and Disambiguation
 
-3. **No code match**: If the guardian's reply does not start with any active request code, a **disambiguation message** is sent back listing all active request codes so the guardian can retry with the correct prefix.
+Every guardian reply typed in the app, and every reply or button press arriving on a channel, goes through `routeGuardianReply()` in `runtime/guardian-reply-router.ts`: from `conversation-process.ts` and `conversation-routes.ts` for the app, and from `inbound-stages/guardian-reply-intercept.ts` for channels. Buttons on the app's own cards skip the router: `surface-action-routes.ts` and `guardian-action-routes.ts` call `processGuardianDecision()` directly. In priority order the router tries:
 
-### Channel Parity
+1. A channel button callback (`apr:<requestId>:<action>`).
+2. A request-code prefix on the reply. Matching is case-insensitive.
+3. `open invite flow` while an access request is pending, which passes through to the normal assistant turn.
+4. A bare-text answer, when exactly one question is pending in the conversation it was asked in.
+5. An explicit approve or reject phrase, applied when exactly one request is pending.
+6. Natural-language classification, only where the caller passes an `approvalConversationGenerator`: channels do, app sessions do not.
 
-The disambiguation invariant is enforced identically across:
+When several requests are pending and the reply names none of them, the router answers with `composeDisambiguationReply()`, listing each request's code and how to reply to it:
 
-- **Mac/Vellum** (`conversation-process.ts`): Intercepts user messages in conversations with pending guardian action deliveries before the agent loop runs.
-- **Telegram** (`inbound-message-handler.ts`): Intercepts inbound messages matched to conversations with pending guardian action deliveries.
+- for an explicit approve or reject phrase, everywhere;
+- where classification runs, for any reply it does not resolve to one request. `runApprovalConversationTurn()` returns `keep_pending` for indecision and for every failure (generator error, malformed output, a decision with no target), so on those channels any other code-less reply is consumed here.
 
-All three paths use the same pattern: look up pending deliveries by conversation, apply single-match fast path or request-code prefix matching, and send disambiguation messages via the guardian action message composer when ambiguous.
-
-### Disambiguation Message Generation
-
-All disambiguation messages are generated through `composeGuardianActionMessageGenerative()` in `guardian-action-message-composer.ts`, which uses a 2-tier priority chain (LLM generator with deterministic fallback). Three disambiguation scenarios exist:
-
-| Scenario                           | When triggered                                         |
-| ---------------------------------- | ------------------------------------------------------ |
-| `guardian_disambiguation`          | Multiple pending approval requests in a conversation   |
-| `guardian_expired_disambiguation`  | Multiple expired requests with late replies            |
-| `guardian_followup_disambiguation` | Multiple follow-up deliveries awaiting guardian action |
+Where classification does not run, any other code-less reply falls through to the normal message pipeline. With one request pending, a `keep_pending` classification returns the engine's own reply as `nl_keep_pending`: the channel intercept treats it as consumed, while `conversation-routes.ts` lets the message through. Every decision applies through `applyGuardianDecision()`. The end-to-end map is [docs/guardian-request-flow.md](../../docs/guardian-request-flow.md).
 
 ## Key Files
 
@@ -425,12 +415,15 @@ All disambiguation messages are generated through `composeGuardianActionMessageG
 | `broadcaster.ts`                | Fan-out to channel adapters with delivery audit trail; emits `notification_conversation_created` SSE event |
 | `copy-composer.ts`              | Template-based fallback notification copy when LLM copy is unavailable                                     |
 | `conversation-seed-composer.ts` | Surface-aware conversation seed generation (richer than notification copy)                                 |
-| `destination-resolver.ts`       | Resolves per-channel endpoints (vellum SSE, Telegram chat ID)                                              |
+| `destination-resolver.ts`       | Resolves per-channel endpoints (Telegram and Slack chat ID, Discord user ID)                               |
 | `adapters/macos.ts`             | Vellum adapter -- broadcasts `notification_intent` via SSE with deep-link metadata                         |
-| `adapters/telegram.ts`          | Telegram adapter -- POSTs to gateway `/deliver/telegram`                                                   |
+| `adapters/platform.ts`          | Platform adapter: posts to the platform push-dispatch endpoint for native mobile push                      |
+| `adapters/telegram.ts`          | Telegram adapter: calls the Telegram Bot API through `messaging/providers/telegram-bot/send.ts`            |
+| `adapters/slack.ts`             | Slack adapter: posts to the guardian's DM through `messaging/providers/slack/send.ts`                      |
+| `adapters/discord.ts`           | Discord adapter: sends to the guardian's DM through `messaging/providers/discord/send.ts`                  |
 | `preference-extractor.ts`       | Detects notification preferences in conversation messages                                                  |
 | `preference-summary.ts`         | Builds preference context string for the decision engine prompt                                            |
-| `preferences-store.ts`          | CRUD for `notification_preferences` table                                                                  |
+| `preferences-store.ts`          | Create and list for the `notification_preferences` table                                                   |
 | `events-store.ts`               | CRUD for `notification_events` table                                                                       |
 | `decisions-store.ts`            | CRUD for `notification_decisions` table                                                                    |
 | `deliveries-store.ts`           | CRUD for `notification_deliveries` table                                                                   |
@@ -479,15 +472,6 @@ Step 1 suppresses on this hint before anything else runs, and nothing downstream
 - **Never opt in a `guardian.question` producer.** The card _is_ the prompt, so a `true` suppresses the question's only rendering and the tool hangs until the prompt timeout. `runtime/question-request-guardian-bridge.ts` carries the rationale at its hint block, and three regression pins hold the line: `runtime/__tests__/question-request-guardian-bridge.test.ts`, `__tests__/confirmation-request-guardian-bridge.test.ts`, and `__tests__/notification-guardian-path.test.ts`.
 - **A producer running inside the schedule worker cannot read presence at all.** `schedule/worker.ts` is a standalone OS process and the sole runner of schedule execution, while the resolver reads `assistantEventHub` through `isWebConversationFocused()` and that hub's SSE clients exist only in the assistant process. Every presence read from the worker resolves `false`, whatever the user is watching. The trap is in testing: a test that drives the producer and mocks presence in one process passes while the shipped worker suppresses nothing. Tracked as JARVIS-1711.
 
-## How to Add a New Channel
-
-1. Add the channel to `CHANNEL_IDS` in `channels/types.ts`.
-2. Create an adapter in `adapters/` implementing the `ChannelAdapter` interface.
-3. Register the adapter in `emit-signal.ts` `getBroadcaster()`.
-4. Add a connectivity check in `getConnectedChannels()` in `emit-signal.ts`.
-5. Add a destination resolver case in `destination-resolver.ts`.
-6. Add the channel to the `NotificationChannel` union in `types.ts`.
-
 ## Audit Trail
 
 Three SQLite tables form the audit chain:
@@ -498,21 +482,21 @@ Three SQLite tables form the audit chain:
 
 ### Client Delivery Ack
 
-For vellum (macOS) deliveries, the audit trail now extends past the SSE broadcast to the actual OS notification post. The `notification_intent` message carries an optional `deliveryId` that the client echoes back in a `notification_intent_result` ack after `UNUserNotificationCenter.add()` completes (or fails).
+For vellum deliveries, the audit trail extends past the SSE broadcast to the OS notification post. The `notification_intent` message carries an optional `deliveryId`; after posting the notification (or deciding not to, for the conversation already on screen), the client reports the outcome to `POST notification-intent-result` through `sendNotificationIntentAck()` in `clients/web/src/runtime/notifications.ts`.
 
 The ack populates three columns on `notification_deliveries`:
 
-| Column                   | Type    | Description                                                                    |
-| ------------------------ | ------- | ------------------------------------------------------------------------------ |
-| `client_delivery_status` | TEXT    | `'delivered'` if the OS accepted the notification, `'client_failed'` otherwise |
-| `client_delivery_error`  | TEXT    | Error description when the post failed (e.g. authorization denied)             |
-| `client_delivery_at`     | INTEGER | Epoch ms timestamp of when the client reported the outcome                     |
+| Column                   | Type    | Description                                                                                               |
+| ------------------------ | ------- | --------------------------------------------------------------------------------------------------------- |
+| `client_delivery_status` | TEXT    | `'delivered'` if the client handled the intent, `'client_failed'` otherwise. Last writer wins (see below) |
+| `client_delivery_error`  | TEXT    | Error description when the post failed (e.g. authorization denied)                                        |
+| `client_delivery_at`     | INTEGER | Epoch ms timestamp of when the client reported the outcome                                                |
 
-This means the audit trail can now answer three questions for each vellum delivery:
+`'delivered'` covers two outcomes the column cannot tell apart: the OS accepted a posted banner, or the client deliberately showed none (the intent was `silent`, the user was already watching that conversation, or the sending assistant predates guardian targeting and the intent was guardian-scoped). The intent goes to every eligible connection, and each one acks the same `deliveryId`. `handleNotificationIntentResult()` in `runtime/routes/notification-routes.ts` overwrites the row with no client key, so the status holds the last client to report, not an aggregate, and `client_delivery_error` is only ever set, so it can outlive a later success. The audit trail answers three questions for each vellum delivery:
 
 1. **Was the intent broadcast?** -- existing `status` column (`sent`)
-2. **Did the client attempt to post?** -- `client_delivery_status` is non-null
-3. **Did the OS post succeed or fail, and why?** -- `client_delivery_status` + `client_delivery_error`
+2. **Did any client report back?** -- `client_delivery_status` is non-null
+3. **Did the last client to report fail, and why?** -- `client_delivery_status = 'client_failed'` + `client_delivery_error`
 
 Query examples:
 

package/src/notifications/__tests__/broadcaster.test.ts

@@ -140,7 +140,7 @@ function makeSignal(
     createdAt: 1700000000000,
     sourceChannel: "scheduler",
     sourceContextId: "ctx-1",
-    sourceEventName: "user.send_notification",
+    sourceEventName: "assistant.share",
     contextPayload: {},
     attentionHints: {
       requiresAction: false,

package/src/notifications/__tests__/channel-allowlist.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  intersectChannelAllowlist,
+  readChannelAllowlist,
+} from "../channel-allowlist.js";
+import type { NotificationChannel } from "../types.js";
+
+describe("readChannelAllowlist", () => {
+  test("returns trimmed non-empty strings", () => {
+    expect(
+      readChannelAllowlist({
+        channelAllowlist: [" telegram ", "", "slack"],
+      }),
+    ).toEqual(["telegram", "slack"]);
+  });
+
+  test("returns undefined for a missing or empty list", () => {
+    expect(readChannelAllowlist({})).toBeUndefined();
+    expect(readChannelAllowlist({ channelAllowlist: [] })).toBeUndefined();
+    expect(readChannelAllowlist({ channelAllowlist: ["", "  "] })).toBeUndefined();
+  });
+});
+
+describe("intersectChannelAllowlist", () => {
+  test("keeps only available channel ids", () => {
+    const available = ["vellum", "telegram"] as NotificationChannel[];
+    expect(intersectChannelAllowlist(["telegram", "nope"], available)).toEqual([
+      "telegram",
+    ]);
+  });
+
+  test("deduplicates a repeated available channel", () => {
+    const available = ["vellum", "telegram"] as NotificationChannel[];
+    expect(
+      intersectChannelAllowlist(["telegram", "telegram"], available),
+    ).toEqual(["telegram"]);
+  });
+});

package/src/notifications/__tests__/copy-composer.test.ts

@@ -21,7 +21,7 @@ function makeSignal(
     createdAt: Date.now(),
     sourceChannel: "scheduler",
     sourceContextId: "ctx-1",
-    sourceEventName: "user.send_notification",
+    sourceEventName: "assistant.share",
     contextPayload: {},
     attentionHints: {
       requiresAction: false,
@@ -503,6 +503,76 @@ describe("composeFallbackCopy plugin schedule templates", () => {
   });
 });
 
+// ── activity.complete rendering ───────────────────────────────────────
+
+describe("activity.complete copy", () => {
+  function completeSignal(
+    contextPayload: Record<string, unknown>,
+  ): NotificationSignal {
+    return makeSignal({
+      sourceEventName: "activity.complete",
+      contextPayload,
+    });
+  }
+
+  test("a producer-authored title survives the fallback path", () => {
+    // The home feed reads the payload title first; the popup must say the
+    // same thing when the classifier was unreachable.
+    const copy = composeFallbackCopy(
+      completeSignal({
+        title: "Skill updated: Weekly Report Export",
+        summary: "Added the retry after an expired session.",
+      }),
+      CHANNELS,
+    );
+    expect(copy.vellum?.title).toBe("Skill updated: Weekly Report Export");
+    expect(copy.vellum?.body).toBe("Added the retry after an expired session.");
+  });
+
+  test("the pass-through's requestedTitle is honored when no title is set", () => {
+    const copy = composeFallbackCopy(
+      completeSignal({
+        requestedTitle: "Nightly export finished",
+        summary: "Wrote 12 files to the reports folder.",
+      }),
+      CHANNELS,
+    );
+    expect(copy.vellum?.title).toBe("Nightly export finished");
+  });
+
+  test("without an authored title the headline is the summary's first sentence", () => {
+    const copy = composeFallbackCopy(
+      completeSignal({
+        summary:
+          "Added the retry after an expired session. Dropped the login step.",
+      }),
+      CHANNELS,
+    );
+    expect(copy.vellum?.title).toBe(
+      "Added the retry after an expired session.",
+    );
+  });
+
+  test("an authored title the normalizer rejects falls back to the derived one", () => {
+    const copy = composeFallbackCopy(
+      completeSignal({
+        title: "Skill\nupdated",
+        summary: "Added the retry after an expired session.",
+      }),
+      CHANNELS,
+    );
+    expect(copy.vellum?.title).toBe(
+      "Added the retry after an expired session.",
+    );
+  });
+
+  test("neither a title nor a summary still says something happened", () => {
+    const copy = composeFallbackCopy(completeSignal({}), CHANNELS);
+    expect(copy.vellum?.title).toBe("Activity complete");
+    expect(copy.vellum?.body).toBe("An activity has completed");
+  });
+});
+
 // ── deriveTitle ───────────────────────────────────────────────────────
 
 describe("deriveTitle", () => {

package/src/notifications/__tests__/decision-engine.test.ts

@@ -99,7 +99,7 @@ function makeAssistantToolSignal(
     createdAt: Date.now(),
     sourceChannel: "assistant_tool",
     sourceContextId: "tool-call-1",
-    sourceEventName: "user.send_notification",
+    sourceEventName: "assistant.share",
     contextPayload: {
       requestedMessage: "exact verbatim text here",
       requestedTitle: "Custom Title",
@@ -356,6 +356,81 @@ describe("assistant_tool pass-through in notification decision engine", () => {
     expect(decision.selectedChannels).toEqual(["vellum"]);
     expect(decision.renderedCopy.vellum?.body).toBe("fyi");
   });
+
+  test("channelAllowlist replaces the default channel set", async () => {
+    const signal = makeAssistantToolSignal({
+      contextPayload: {
+        requestedMessage: "telegram only",
+        channelAllowlist: ["telegram"],
+      },
+    });
+    const decision = await evaluateSignal(signal, [
+      "vellum",
+      "telegram",
+    ] as NotificationChannel[]);
+
+    expect(decision.selectedChannels).toEqual(["telegram"]);
+    expect(decision.shouldNotify).toBe(true);
+    expect(decision.renderedCopy.telegram?.body).toBe("telegram only");
+  });
+
+  test("channelAllowlist wins over preferredChannels", async () => {
+    const signal = makeAssistantToolSignal({
+      contextPayload: {
+        requestedMessage: "exclusive telegram",
+        preferredChannels: ["slack"],
+        channelAllowlist: ["telegram"],
+      },
+    });
+    const decision = await evaluateSignal(signal, [
+      "vellum",
+      "telegram",
+      "slack",
+    ] as NotificationChannel[]);
+
+    expect(decision.selectedChannels).toEqual(["telegram"]);
+    expect(decision.selectedChannels).not.toContain("vellum");
+    expect(decision.selectedChannels).not.toContain("slack");
+  });
+
+  test("urgent + channelAllowlist stays exclusive", async () => {
+    const signal = makeAssistantToolSignal({
+      contextPayload: {
+        requestedMessage: "urgent telegram only",
+        channelAllowlist: ["telegram"],
+      },
+      attentionHints: {
+        requiresAction: true,
+        urgency: "critical",
+        isAsyncBackground: false,
+        visibleInSourceNow: false,
+      },
+    });
+    const decision = await evaluateSignal(signal, [
+      "vellum",
+      "telegram",
+      "slack",
+    ] as NotificationChannel[]);
+
+    expect(decision.selectedChannels).toEqual(["telegram"]);
+    expect(decision.shouldNotify).toBe(true);
+  });
+
+  test("channelAllowlist with no overlap yields an empty selection", async () => {
+    const signal = makeAssistantToolSignal({
+      contextPayload: {
+        requestedMessage: "nowhere to send",
+        channelAllowlist: ["disconnected_channel"],
+      },
+    });
+    const decision = await evaluateSignal(signal, [
+      "vellum",
+      "telegram",
+    ] as NotificationChannel[]);
+
+    expect(decision.selectedChannels).toEqual([]);
+    expect(decision.shouldNotify).toBe(false);
+  });
 });
 
 describe("chat.assistant_reply pass-through in notification decision engine", () => {
@@ -905,7 +980,9 @@ describe("scheduler requested-message pass-through in notification decision engi
       expect(decision.reasoningSummary).not.toBe(
         "scheduler requested-message pass-through",
       );
-      expect(decision.reasoningSummary).not.toBe("schedule_result pass-through");
+      expect(decision.reasoningSummary).not.toBe(
+        "schedule_result pass-through",
+      );
     } finally {
       providerSendMessage = previousSendMessage;
     }