@vellumai/assistant 0.3.13 → 0.3.14

package/src/daemon/recording-intent.ts

@@ -1,8 +1,26 @@
-// Recording intent detection for standalone screen recording routing.
-// Used by task/message handlers to intercept recording-related prompts
+// Recording intent resolution for standalone screen recording routing.
+// Exports `resolveRecordingIntent` as the single public entry point for
+// text-based intent detection. Handlers use this (or structured
+// `commandIntent` payloads) to intercept recording-related prompts
 // before they reach the classifier or create a CU session.
-
-export type RecordingIntentClass = 'start_only' | 'stop_only' | 'mixed' | 'none';
+//
+// Internal helpers (detect/strip/classify) are kept as private utilities
+// consumed only by `resolveRecordingIntent`.
+
+type RecordingIntentClass = 'start_only' | 'stop_only' | 'mixed' | 'none';
+
+export type RecordingIntentResult =
+  | { kind: 'none' }
+  | { kind: 'start_only' }
+  | { kind: 'stop_only' }
+  | { kind: 'start_with_remainder'; remainder: string }
+  | { kind: 'stop_with_remainder'; remainder: string }
+  | { kind: 'start_and_stop_only' }
+  | { kind: 'start_and_stop_with_remainder'; remainder: string }
+  | { kind: 'restart_only' }
+  | { kind: 'restart_with_remainder'; remainder: string }
+  | { kind: 'pause_only' }
+  | { kind: 'resume_only' };
 
 // ─── Start recording patterns ────────────────────────────────────────────────
 
@@ -25,6 +43,29 @@ const STOP_RECORDING_PATTERNS: RegExp[] = [
   /\bhalt\s+(the\s+)?recording\b/i,
 ];
 
+// ─── Restart recording patterns (compound: stop + start a new one) ──────────
+
+const RESTART_RECORDING_PATTERNS: RegExp[] = [
+  /\brestart\s+(the\s+)?recording\b/i,
+  /\bredo\s+(the\s+)?recording\b/i,
+  /\bstop\s+(the\s+)?recording\s+and\s+(start|begin)\s+(a\s+)?(new|fresh|another)\s+(recording|one)\b/i,
+  /\bstop\s+(the\s+)?recording\s+and\s+(start|begin)\s+(a\s+)?(new|fresh|another)[.!?\s]*$/i,
+  /\bstop\s+and\s+restart\s+(the\s+)?recording\b/i,
+  /\bstop\s+recording\s+and\s+start\s+(a\s+)?(new|another|fresh)\s+(recording|one)\b/i,
+  /\bstop\s+recording\s+and\s+start\s+(a\s+)?(new|another|fresh)[.!?\s]*$/i,
+];
+
+// ─── Pause/resume recording patterns ────────────────────────────────────────
+
+const PAUSE_RECORDING_PATTERNS: RegExp[] = [
+  /\bpause\s+(the\s+)?recording\b/i,
+];
+
+const RESUME_RECORDING_PATTERNS: RegExp[] = [
+  /\bresume\s+(the\s+)?recording\b/i,
+  /\bunpause\s+(the\s+)?recording\b/i,
+];
+
 // ─── Stop-recording clause removal for mixed-intent prompts ─────────────────
 
 const STOP_RECORDING_CLAUSE_PATTERNS: RegExp[] = [
@@ -47,17 +88,41 @@ const RECORDING_CLAUSE_PATTERNS: RegExp[] = [
   /\brecord\s+(my\s+|the\s+)?screen\s+while\b/i,
 ];
 
+// ─── Restart clause removal ─────────────────────────────────────────────────
+
+const RESTART_RECORDING_CLAUSE_PATTERNS: RegExp[] = [
+  // Longer compound patterns first — avoids partial matches by shorter patterns
+  /\bstop\s+(the\s+)?recording\s+and\s+(start|begin)\s+(a\s+)?(new|fresh|another)\s+(recording|one)\b/i,
+  /\bstop\s+(the\s+)?recording\s+and\s+(start|begin)\s+(a\s+)?(new|fresh|another)[.!?\s]*$/i,
+  /\bstop\s+and\s+restart\s+(the\s+)?recording\b/i,
+  /\bstop\s+recording\s+and\s+start\s+(a\s+)?(new|another|fresh)\s+(recording|one)\b/i,
+  /\bstop\s+recording\s+and\s+start\s+(a\s+)?(new|another|fresh)[.!?\s]*$/i,
+  /\b(and\s+)?(also\s+)?restart\s+(the\s+)?recording\b/i,
+  /\b(and\s+)?(also\s+)?redo\s+(the\s+)?recording\b/i,
+];
+
+// ─── Pause/resume clause removal ────────────────────────────────────────────
+
+const PAUSE_RECORDING_CLAUSE_PATTERNS: RegExp[] = [
+  /\b(and\s+)?(also\s+)?pause\s+(the\s+)?recording\b/i,
+];
+
+const RESUME_RECORDING_CLAUSE_PATTERNS: RegExp[] = [
+  /\b(and\s+)?(also\s+)?resume\s+(the\s+)?recording\b/i,
+  /\b(and\s+)?(also\s+)?unpause\s+(the\s+)?recording\b/i,
+];
+
 /** Common polite/filler words stripped before checking intent-only status. */
 const FILLER_PATTERN =
   /\b(please|pls|plz|can\s+you|could\s+you|would\s+you|now|right\s+now|thanks|thank\s+you|thx|ty|for\s+me|ok(ay)?|hey|hi|just)\b/gi;
 
-// ─── Public API ──────────────────────────────────────────────────────────────
+// ─── Internal helpers ────────────────────────────────────────────────────────
 
 /**
  * Returns true if the user's message includes any recording-related phrases.
  * Does not distinguish between recording-only and mixed-intent prompts.
  */
-export function detectRecordingIntent(taskText: string): boolean {
+function detectRecordingIntent(taskText: string): boolean {
   return START_RECORDING_PATTERNS.some((p) => p.test(taskText));
 }
 
@@ -67,7 +132,7 @@ export function detectRecordingIntent(taskText: string): boolean {
  * "record my screen while I work" -> false (has CU task component)
  * "open Chrome and record my screen" -> false (has CU task component)
  */
-export function isRecordingOnly(taskText: string): boolean {
+function isRecordingOnly(taskText: string): boolean {
   if (!detectRecordingIntent(taskText)) return false;
 
   // Strip the recording clause and check if anything substantive remains
@@ -84,16 +149,31 @@ export function isRecordingOnly(taskText: string): boolean {
  * Requires explicit "stop/end/finish/halt recording" phrasing --
  * bare "stop", "end it", or "quit" are too ambiguous and will not match.
  */
-export function detectStopRecordingIntent(taskText: string): boolean {
+function detectStopRecordingIntent(taskText: string): boolean {
   return STOP_RECORDING_PATTERNS.some((p) => p.test(taskText));
 }
 
+/** Returns true if any restart compound pattern matches. */
+function detectRestartRecordingIntent(taskText: string): boolean {
+  return RESTART_RECORDING_PATTERNS.some((p) => p.test(taskText));
+}
+
+/** Returns true if any pause pattern matches. */
+function detectPauseRecordingIntent(taskText: string): boolean {
+  return PAUSE_RECORDING_PATTERNS.some((p) => p.test(taskText));
+}
+
+/** Returns true if any resume pattern matches. */
+function detectResumeRecordingIntent(taskText: string): boolean {
+  return RESUME_RECORDING_PATTERNS.some((p) => p.test(taskText));
+}
+
 /**
  * Removes recording-related clauses from a task, returning the cleaned text.
  * Used when a recording intent is embedded in a broader CU task so the
  * recording portion can be handled separately while the task continues.
  */
-export function stripRecordingIntent(taskText: string): string {
+function stripRecordingIntent(taskText: string): string {
   let result = taskText;
   for (const pattern of RECORDING_CLAUSE_PATTERNS) {
     result = result.replace(pattern, '');
@@ -106,7 +186,7 @@ export function stripRecordingIntent(taskText: string): string {
  * Removes stop-recording clauses from a message, returning the cleaned text.
  * Analogous to stripRecordingIntent but for stop-recording phrases.
  */
-export function stripStopRecordingIntent(taskText: string): string {
+function stripStopRecordingIntent(taskText: string): string {
   let result = taskText;
   for (const pattern of STOP_RECORDING_CLAUSE_PATTERNS) {
     result = result.replace(pattern, '');
@@ -114,6 +194,33 @@ export function stripStopRecordingIntent(taskText: string): string {
   return result.replace(/\s{2,}/g, ' ').trim();
 }
 
+/** Removes restart-recording clauses from text. */
+function stripRestartRecordingIntent(taskText: string): string {
+  let result = taskText;
+  for (const pattern of RESTART_RECORDING_CLAUSE_PATTERNS) {
+    result = result.replace(pattern, '');
+  }
+  return result.replace(/\s{2,}/g, ' ').trim();
+}
+
+/** Removes pause-recording clauses from text. */
+function stripPauseRecordingIntent(taskText: string): string {
+  let result = taskText;
+  for (const pattern of PAUSE_RECORDING_CLAUSE_PATTERNS) {
+    result = result.replace(pattern, '');
+  }
+  return result.replace(/\s{2,}/g, ' ').trim();
+}
+
+/** Removes resume-recording clauses from text. */
+function stripResumeRecordingIntent(taskText: string): string {
+  let result = taskText;
+  for (const pattern of RESUME_RECORDING_CLAUSE_PATTERNS) {
+    result = result.replace(pattern, '');
+  }
+  return result.replace(/\s{2,}/g, ' ').trim();
+}
+
 /**
  * Returns true if the prompt is purely about stopping recording with no
  * additional task. Analogous to isRecordingOnly but for stop-recording.
@@ -121,7 +228,7 @@ export function stripStopRecordingIntent(taskText: string): string {
  * "how do I stop recording?" -> false (has additional context)
  * "stop recording and close the browser" -> false (has CU task component)
  */
-export function isStopRecordingOnly(taskText: string): boolean {
+function isStopRecordingOnly(taskText: string): boolean {
   if (!detectStopRecordingIntent(taskText)) return false;
 
   const stripped = stripStopRecordingIntent(taskText);
@@ -130,6 +237,30 @@ export function isStopRecordingOnly(taskText: string): boolean {
   return withoutFillers.replace(/[.,;!?\s]+/g, '').length === 0;
 }
 
+/** Returns true if the text is purely a restart command (no additional task). */
+function isRestartRecordingOnly(taskText: string): boolean {
+  if (!detectRestartRecordingIntent(taskText)) return false;
+  const stripped = stripRestartRecordingIntent(taskText);
+  const withoutFillers = stripped.replace(FILLER_PATTERN, '');
+  return withoutFillers.replace(/[.,;!?\s]+/g, '').length === 0;
+}
+
+/** Returns true if the text is purely a pause command (no additional task). */
+function isPauseRecordingOnly(taskText: string): boolean {
+  if (!detectPauseRecordingIntent(taskText)) return false;
+  const stripped = stripPauseRecordingIntent(taskText);
+  const withoutFillers = stripped.replace(FILLER_PATTERN, '');
+  return withoutFillers.replace(/[.,;!?\s]+/g, '').length === 0;
+}
+
+/** Returns true if the text is purely a resume command (no additional task). */
+function isResumeRecordingOnly(taskText: string): boolean {
+  if (!detectResumeRecordingIntent(taskText)) return false;
+  const stripped = stripResumeRecordingIntent(taskText);
+  const withoutFillers = stripped.replace(FILLER_PATTERN, '');
+  return withoutFillers.replace(/[.,;!?\s]+/g, '').length === 0;
+}
+
 // ─── Dynamic name normalization ─────────────────────────────────────────────
 
 /**
@@ -159,7 +290,7 @@ export function stripDynamicNames(text: string, dynamicNames: string[]): string
  * punctuation, and dynamic assistant names. Used to determine whether
  * remaining text after stripping recording clauses needs further processing.
  */
-export function hasSubstantiveContent(text: string, dynamicNames?: string[]): boolean {
+function hasSubstantiveContent(text: string, dynamicNames?: string[]): boolean {
   let cleaned = text;
   if (dynamicNames && dynamicNames.length > 0) {
     cleaned = stripDynamicNames(cleaned, dynamicNames);
@@ -175,22 +306,68 @@ export function hasSubstantiveContent(text: string, dynamicNames?: string[]): bo
  *  triggering recording side effects in the mixed handler. */
 const WH_INTERROGATIVE = /^\s*(how|what|why|when|where|who|which)\b/i;
 
+/**
+ * Indirect informational patterns that indicate the user is asking *about*
+ * recording rather than commanding a recording action. These catch prompts
+ * where the WH-word is buried after polite filler or an informational verb:
+ *
+ * - "can you tell me how to stop recording?"
+ * - "explain how to stop the recording"
+ * - "is there a way to stop recording?"
+ * - "I'd like to know how to pause the recording"
+ * - "do you know how to start recording?"
+ *
+ * Critical: these must NOT match polite imperatives like "can you stop
+ * recording?" — the key distinction is the intermediary informational
+ * verb/phrase (tell/explain/describe/show + how, "is there a way", etc.).
+ */
+const INDIRECT_INFORMATIONAL_PATTERNS: RegExp[] = [
+  // "tell me how...", "can you explain how...", "show me how..."
+  /^\s*(can\s+you\s+|could\s+you\s+|would\s+you\s+)?(tell|explain|describe|show)\s+(me\s+)?how\b/i,
+  // "is there a way to...", "are there any ways to..."
+  /^\s*(is\s+there|are\s+there)\s+(a\s+|any\s+)?(ways?|methods?|options?|means)\s+to\b/i,
+  // "I'd like to know...", "I want to know..."
+  /^\s*(i('d|\s+would)\s+like\s+to\s+know|i\s+want\s+to\s+know)\b/i,
+  // "do you know how to...", "can I learn how to..."
+  /^\s*(do\s+you\s+know\s+how|can\s+i\s+learn(\s+how)?)\s+to\b/i,
+  // Bare informational verbs at start: "explain how...", "tell me how..."
+  /^\s*(explain|describe)\s+(to\s+me\s+)?how\b/i,
+  // "tell me about..." (informational, not imperative)
+  /^\s*(tell|explain|describe|show)\s+(me\s+)?(about\s+)?(how|what|why|when|where)\b/i,
+];
+
 /**
  * Returns true if the text appears to be a question about recording rather
  * than an imperative command that includes recording.
  *
  * "how do I stop recording?" → true  (question — don't trigger side effects)
+ * "can you tell me how to stop recording?" → true  (informational — don't trigger)
+ * "explain how to stop the recording" → true  (informational — don't trigger)
+ * "is there a way to stop recording?" → true  (capability question — don't trigger)
  * "open Chrome and record my screen" → false  (command — trigger recording)
  * "can you record my screen?" → false  (polite imperative — trigger recording)
+ * "can you stop recording?" → false  (polite imperative — trigger stop)
  */
-export function isInterrogative(text: string, dynamicNames?: string[]): boolean {
+function isInterrogative(text: string, dynamicNames?: string[]): boolean {
   let cleaned = text;
   if (dynamicNames && dynamicNames.length > 0) {
     cleaned = stripDynamicNames(cleaned, dynamicNames);
   }
   // Strip polite prefixes that don't change interrogative status
   cleaned = cleaned.replace(/^\s*(hey|hi|hello|please|pls|plz)[,\s]+/i, '');
-  return WH_INTERROGATIVE.test(cleaned);
+
+  // Direct WH-questions (how/what/why/when/where/who/which)
+  if (WH_INTERROGATIVE.test(cleaned)) {
+    return true;
+  }
+
+  // Indirect informational patterns — checked on cleaned text after
+  // stripping polite prefixes, so "please tell me how..." is caught
+  if (INDIRECT_INFORMATIONAL_PATTERNS.some((p) => p.test(cleaned))) {
+    return true;
+  }
+
+  return false;
 }
 
 // ─── Unified classification ─────────────────────────────────────────────────
@@ -206,7 +383,7 @@ export function isInterrogative(text: string, dynamicNames?: string[]): boolean
  * If `dynamicNames` are provided, they are stripped from the beginning of the
  * text before classification (e.g., "Nova, record my screen" -> "record my screen").
  */
-export function classifyRecordingIntent(
+function classifyRecordingIntent(
   taskText: string,
   dynamicNames?: string[],
 ): RecordingIntentClass {
@@ -231,3 +408,117 @@ export function classifyRecordingIntent(
 
   return 'none';
 }
+
+// ─── Structured intent resolver ─────────────────────────────────────────────
+
+/**
+ * Resolves recording intent from user text into a structured result that
+ * distinguishes pure recording commands from commands with remaining task text.
+ *
+ * Pipeline:
+ * 1. Strip dynamic assistant names (leading vocative)
+ * 2. Strip leading polite wrappers
+ * 3. Interrogative gate — questions return `none`
+ * 3.5. Restart compound detection (before independent start/stop)
+ * 3.6. Pause/resume detection
+ * 4. Detect start/stop patterns (start takes precedence when both present)
+ * 5. Determine if recording-only or has a remainder, stripping from the
+ *    ORIGINAL text to preserve the user's exact phrasing
+ */
+export function resolveRecordingIntent(
+  text: string,
+  dynamicNames?: string[],
+): RecordingIntentResult {
+  // Step 1: Strip dynamic assistant names for normalization
+  let normalized =
+    dynamicNames && dynamicNames.length > 0
+      ? stripDynamicNames(text, dynamicNames)
+      : text;
+
+  // Step 2: Strip leading polite wrappers for normalization
+  normalized = normalized.replace(/^\s*(hey|hi|hello|please|pls|plz)[,\s]+/i, '');
+
+  // Step 3: Interrogative gate — questions (WH-words and indirect
+  // informational patterns) are not commands
+  if (isInterrogative(normalized, dynamicNames)) {
+    return { kind: 'none' };
+  }
+
+  // Step 3.5: Restart compound detection — check BEFORE independent start/stop
+  // so "stop recording and start a new one" is recognized as restart, not
+  // as separate stop + start patterns.
+  if (detectRestartRecordingIntent(normalized)) {
+    if (isRestartRecordingOnly(normalized)) {
+      return { kind: 'restart_only' };
+    }
+    // Strip from the ORIGINAL text to preserve user's exact phrasing
+    const remainder = stripRestartRecordingIntent(text);
+    if (hasSubstantiveContent(remainder, dynamicNames)) {
+      return { kind: 'restart_with_remainder', remainder };
+    }
+    return { kind: 'restart_only' };
+  }
+
+  // Step 3.6: Pause/resume detection — check before start/stop
+  if (detectPauseRecordingIntent(normalized)) {
+    if (isPauseRecordingOnly(normalized)) {
+      return { kind: 'pause_only' };
+    }
+    // Pause with additional text falls through to normal processing
+  }
+
+  if (detectResumeRecordingIntent(normalized)) {
+    if (isResumeRecordingOnly(normalized)) {
+      return { kind: 'resume_only' };
+    }
+    // Resume with additional text falls through to normal processing
+  }
+
+  // Step 4: Detect start and stop patterns on the normalized text
+  const hasStart = detectRecordingIntent(normalized);
+  const hasStop = detectStopRecordingIntent(normalized);
+
+  // Step 5: Resolve
+  if (hasStart) {
+    if (hasStop) {
+      // Both start and stop detected — use combined variants
+      if (isRecordingOnly(normalized)) {
+        // Check if stop-only after stripping start patterns
+        const withoutStart = stripRecordingIntent(normalized);
+        if (isStopRecordingOnly(withoutStart)) {
+          return { kind: 'start_and_stop_only' };
+        }
+      }
+      let remainder = stripRecordingIntent(text);
+      remainder = stripStopRecordingIntent(remainder);
+      if (hasSubstantiveContent(remainder, dynamicNames)) {
+        return { kind: 'start_and_stop_with_remainder', remainder };
+      }
+      return { kind: 'start_and_stop_only' };
+    }
+    // Only start detected
+    if (isRecordingOnly(normalized)) {
+      return { kind: 'start_only' };
+    }
+    // Strip from the ORIGINAL text to preserve user's exact phrasing
+    const remainder = stripRecordingIntent(text);
+    if (hasSubstantiveContent(remainder, dynamicNames)) {
+      return { kind: 'start_with_remainder', remainder };
+    }
+    return { kind: 'start_only' };
+  }
+
+  if (hasStop) {
+    if (isStopRecordingOnly(normalized)) {
+      return { kind: 'stop_only' };
+    }
+    // Strip from the ORIGINAL text to preserve user's exact phrasing
+    const remainder = stripStopRecordingIntent(text);
+    if (hasSubstantiveContent(remainder, dynamicNames)) {
+      return { kind: 'stop_with_remainder', remainder };
+    }
+    return { kind: 'stop_only' };
+  }
+
+  return { kind: 'none' };
+}

package/src/daemon/session-tool-setup.ts

@@ -26,6 +26,7 @@ import type { ProxyApprovalCallback, ProxyApprovalRequest } from '../tools/netwo
 import { getAllToolDefinitions } from '../tools/registry.js';
 import { allUiSurfaceTools } from '../tools/ui-surface/definitions.js';
 import { projectSkillTools, type SkillProjectionCache } from './session-skill-tools.js';
+import type { GuardianRuntimeContext } from './session-runtime-assembly.js';
 import type { SurfaceSessionContext } from './session-surfaces.js';
 import {
   surfaceProxyResolver,
@@ -55,6 +56,8 @@ export interface ToolSetupContext extends SurfaceSessionContext {
   headlessLock?: boolean;
   /** When set, this session is executing a task run. Used to retrieve ephemeral permission rules. */
   taskRunId?: string;
+  /** Guardian runtime context for the session — actorRole is propagated into ToolContext for control-plane policy enforcement. */
+  guardianContext?: GuardianRuntimeContext;
 }
 
 // ── buildToolDefinitions ─────────────────────────────────────────────
@@ -105,6 +108,7 @@ export function createToolExecutor(
       assistantId: ctx.assistantId,
       requestId: ctx.currentRequestId,
       taskRunId: ctx.taskRunId,
+      guardianActorRole: ctx.guardianContext?.actorRole,
       onOutput,
       signal: ctx.abortController?.signal,
       sandboxOverride: ctx.sandboxOverride,

package/src/notifications/README.md

@@ -154,9 +154,66 @@ The macOS/iOS client listens for this event and surfaces the thread in the sideb
 
 `emitNotificationSignal()` accepts an optional `onThreadCreated` callback. This lets producers run domain side effects (for example, creating cross-channel guardian delivery rows) as soon as vellum pairing occurs, without introducing a second thread-creation path.
 
+## Reminder Routing Metadata and Trigger-Time Enforcement
+
+Reminders carry optional routing metadata that controls how notifications fan out across channels when the reminder fires. This enables a single reminder to produce multi-channel delivery without requiring the user to create duplicate reminders per channel.
+
+### Routing Intent Model
+
+The `routing_intent` field on each reminder row specifies the desired channel coverage:
+
+| Intent | Behavior | When to use |
+|--------|----------|-------------|
+| `single_channel` | Default LLM-driven routing (no override) | Standard reminders where the decision engine picks the best channel |
+| `multi_channel` | Ensures delivery on 2+ channels when 2+ are connected | Important reminders the user wants on both desktop and phone |
+| `all_channels` | Forces delivery on every connected channel | Critical reminders that must reach the user everywhere |
+
+The default is `single_channel`, preserving backward compatibility. Routing intent is persisted in the `reminders` table (`routing_intent` column) and carried through the notification signal as `routingIntent`.
+
+### Routing Hints
+
+The `routing_hints` field is free-form JSON metadata passed alongside the routing intent. It flows through the signal as `routingHints` and is included in the decision engine prompt, allowing producers to communicate channel preferences or contextual hints without requiring schema changes.
+
+### Trigger-Time Enforcement Flow
+
+When a reminder fires, the routing metadata flows through the notification pipeline with a post-decision enforcement step:
+
+```
+Reminder fires (scheduler)
+  → emitNotificationSignal({ routingIntent, routingHints })
+    → Decision Engine (LLM selects channels)
+      → enforceRoutingIntent() (post-decision guard)
+        → Deterministic Checks
+          → Broadcaster → Adapters → Delivery
+```
+
+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()`).
+- **`multi_channel`**: If the LLM selected fewer than 2 channels but 2+ are connected, expands `selectedChannels` to all connected channels.
+- **`single_channel`**: No override -- the LLM's selection stands.
+
+When enforcement changes the decision, the updated channel selection is re-persisted to the `notification_decisions` table so the stored decision matches what was actually dispatched. The `reasoningSummary` is annotated with the enforcement action (e.g. `[routing_intent=all_channels enforced: vellum, telegram, sms]`).
+
+### Single-Reminder Fanout
+
+A key design principle: **one reminder produces one notification signal that fans out to multiple channels**. The user never needs to create separate reminders for each channel. The routing intent metadata on the single reminder controls the fanout behavior, and the notification pipeline handles per-channel copy rendering, conversation pairing, and delivery through the existing adapter infrastructure.
+
+### Data Flow
+
+```
+reminders table (routing_intent, routing_hints_json)
+  → scheduler.ts: claimDueReminders() reads routing metadata
+    → lifecycle.ts: notifyReminder({ routingIntent, routingHints })
+      → emitNotificationSignal({ routingIntent, routingHints })
+        → signal.ts: NotificationSignal.routingIntent / routingHints
+          → decision-engine.ts: evaluateSignal() → enforceRoutingIntent()
+            → broadcaster.ts: fan-out to selected channel adapters
+```
+
 ## Channel Delivery Architecture
 
-The notification system delivers to two channel types:
+The notification system delivers to three channel types:
 
 ### Vellum (always connected)
 
@@ -172,12 +229,19 @@ The macOS/iOS client posts a native `UNUserNotificationCenter` notification from
 
 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.
 
+### SMS (when guardian binding exists)
+
+HTTP POST to the gateway's `/deliver/sms` endpoint. The `SmsAdapter` follows the same pattern as the Telegram adapter: it resolves a phone number from the active guardian binding and sends text via the gateway, which forwards to the Twilio Messages API. The adapter resolves message text via a priority chain: `deliveryText` > `body` > `title` > humanized event name. The `assistantId` is threaded through the `ChannelDeliveryPayload` so the gateway can resolve the correct outbound phone number for multi-assistant deployments.
+
+SMS delivery is text-only (no MMS). Graceful degradation: when the gateway is unreachable or SMS is not configured, the adapter returns a failed `DeliveryResult` without throwing, so the broadcaster continues delivering to other channels.
+
 ### Channel Connectivity
 
 Connected channels are resolved at signal emission time by `getConnectedChannels()` in `emit-signal.ts`:
 
 - **Vellum** is always considered connected (IPC socket is always available when the daemon is running)
 - **Telegram** is considered connected only when an active guardian binding exists for the assistant (checked via `getActiveBinding()`)
+- **SMS** is considered connected only when an active guardian binding exists for the assistant (same check as Telegram)
 
 ## Conversation Materialization
 
@@ -211,6 +275,7 @@ For notification flows that create conversations, the conversation must be creat
 | `destination-resolver.ts` | Resolves per-channel endpoints (vellum IPC, Telegram chat ID) |
 | `adapters/macos.ts` | Vellum adapter -- broadcasts `notification_intent` via IPC with deep-link metadata |
 | `adapters/telegram.ts` | Telegram adapter -- POSTs to gateway `/deliver/telegram` |
+| `adapters/sms.ts` | SMS adapter -- POSTs to gateway `/deliver/sms` via Twilio Messages API |
 | `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 |
@@ -237,6 +302,9 @@ await emitNotificationSignal({
     visibleInSourceNow: false,
   },
   contextPayload: { /* arbitrary data for the decision engine */ },
+  // Optional: control multi-channel fanout behavior
+  routingIntent: 'multi_channel',   // 'single_channel' | 'multi_channel' | 'all_channels'
+  routingHints: { preferredChannels: ['telegram', 'sms'] },
 });
 ```
 

package/src/notifications/adapters/sms.ts

@@ -0,0 +1,80 @@
+/**
+ * SMS channel adapter — delivers notifications to phone numbers
+ * via the gateway's SMS delivery endpoint (`/deliver/sms`).
+ *
+ * Follows the same delivery pattern as the Telegram adapter: POST to
+ * the gateway's `/deliver/sms` endpoint with a phone number (as chatId)
+ * and text payload. The gateway forwards the message to the Twilio
+ * Messages API.
+ *
+ * Graceful degradation: when the gateway is unreachable or SMS is not
+ * configured, the adapter returns a failed DeliveryResult without throwing,
+ * so the broadcaster continues delivering to other channels.
+ */
+
+import { getGatewayInternalBaseUrl } from '../../config/env.js';
+import { deliverChannelReply } from '../../runtime/gateway-client.js';
+import { getLogger } from '../../util/logger.js';
+import { readHttpToken } from '../../util/platform.js';
+import { nonEmpty } from '../copy-composer.js';
+import type {
+  ChannelAdapter,
+  ChannelDeliveryPayload,
+  ChannelDestination,
+  DeliveryResult,
+  NotificationChannel,
+} from '../types.js';
+
+const log = getLogger('notif-adapter-sms');
+
+function resolveSmsMessageText(payload: ChannelDeliveryPayload): string {
+  const deliveryText = nonEmpty(payload.copy.deliveryText);
+  if (deliveryText) return deliveryText;
+
+  const body = nonEmpty(payload.copy.body);
+  if (body) return body;
+
+  const title = nonEmpty(payload.copy.title);
+  if (title) return title;
+
+  return payload.sourceEventName.replace(/[._]/g, ' ');
+}
+
+export class SmsAdapter implements ChannelAdapter {
+  readonly channel: NotificationChannel = 'sms';
+
+  async send(payload: ChannelDeliveryPayload, destination: ChannelDestination): Promise<DeliveryResult> {
+    const phoneNumber = destination.endpoint;
+    if (!phoneNumber) {
+      log.warn({ sourceEventName: payload.sourceEventName }, 'SMS destination has no phone number — skipping');
+      return { success: false, error: 'No phone number configured for SMS destination' };
+    }
+
+    const gatewayBase = getGatewayInternalBaseUrl();
+    const deliverUrl = `${gatewayBase}/deliver/sms`;
+
+    const messageText = resolveSmsMessageText(payload);
+
+    try {
+      await deliverChannelReply(
+        deliverUrl,
+        { chatId: phoneNumber, text: messageText, assistantId: payload.assistantId },
+        readHttpToken() ?? undefined,
+      );
+
+      log.info(
+        { sourceEventName: payload.sourceEventName, phoneNumber },
+        'SMS notification delivered',
+      );
+
+      return { success: true };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      log.error(
+        { err, sourceEventName: payload.sourceEventName, phoneNumber },
+        'Failed to deliver SMS notification',
+      );
+      return { success: false, error: message };
+    }
+  }
+}

package/src/notifications/broadcaster.ts

@@ -174,6 +174,7 @@ export class NotificationBroadcaster {
       const payload: ChannelDeliveryPayload = {
         deliveryId,
         sourceEventName: signal.sourceEventName,
+        assistantId: signal.assistantId,
         copy,
         deepLinkTarget,
       };

package/src/notifications/copy-composer.ts

@@ -115,14 +115,14 @@ function applyChannelDefaults(
 ): RenderedChannelCopy {
   const copy: RenderedChannelCopy = { ...baseCopy };
 
-  if (channel === 'telegram') {
-    copy.deliveryText = buildTelegramFallbackDeliveryText(baseCopy, signal);
+  if (channel === 'telegram' || channel === 'sms') {
+    copy.deliveryText = buildChatSurfaceFallbackDeliveryText(baseCopy, signal);
   }
 
   return copy;
 }
 
-function buildTelegramFallbackDeliveryText(
+function buildChatSurfaceFallbackDeliveryText(
   baseCopy: RenderedChannelCopy,
   signal: NotificationSignal,
 ): string {