@vellumai/assistant 0.3.3 → 0.3.5

package/Dockerfile

@@ -42,11 +42,13 @@ RUN apt-get update && apt-get install -y \
     fonts-freefont-ttf \
     make \
     g++ \
+    git \
     sudo \
     && rm -rf /var/lib/apt/lists/*
 
 # Copy bun binary from builder instead of re-installing
 COPY --from=builder /root/.bun/bin/bun /usr/local/bin/bun
+RUN ln -sf /usr/local/bin/bun /usr/local/bin/bunx
 
 # Create non-root user that also has sudo access so it can like install stuff
 RUN groupadd --system --gid 1001 assistant && \

package/README.md

@@ -46,7 +46,6 @@ cp .env.example .env
 | `OLLAMA_BASE_URL` | No | `http://127.0.0.1:11434/v1` | Ollama base URL |
 | `RUNTIME_HTTP_PORT` | No | — | Enable the HTTP server (required for gateway/web) |
 | `RUNTIME_GATEWAY_ORIGIN_SECRET` | No | — | Dedicated secret for the `X-Gateway-Origin` proof header on `/channels/inbound`. When not set, falls back to the bearer token. Both gateway and runtime must share the same value. |
-| `CHANNEL_APPROVALS_ENABLED` | No | `false` | Enable channel approval flow including interactive approval UX, guardian enforcement (`forceStrictSideEffects`, fail-closed denial), and approval prompt routing. Actor-role classification runs regardless, but enforcement requires this flag. |
 | `VELLUM_DAEMON_SOCKET` | No | `~/.vellum/vellum.sock` | Override the daemon socket path |
 
 ## Usage
@@ -124,7 +123,7 @@ assistant/
 
 ## Channel Approval Flow
 
-When the assistant needs tool-use confirmation during a channel session (e.g., Telegram), the approval flow intercepts the run and surfaces an interactive prompt to the user. This is gated behind the `CHANNEL_APPROVALS_ENABLED=true` environment variable.
+When the assistant needs tool-use confirmation during a channel session (e.g., Telegram), the approval flow intercepts the run and surfaces an interactive prompt to the user. This approval-aware path is always enabled whenever orchestrator + callback context are available.
 
 ### How it works
 
@@ -164,24 +163,17 @@ Channels that do not support rich inline approval UI (e.g., inline keyboards) re
 
 ### Enabling
 
-Set the environment variable before starting the daemon:
-
-```bash
-CHANNEL_APPROVALS_ENABLED=true
-```
-
-When disabled (the default), channel messages follow the standard fire-and-forget processing path without approval interception.
+Channel approvals are always enabled for channel traffic when orchestrator + callback context are available.
 
 ### Guardian-Specific Behavior
 
-Guardian actor-role *classification* (determining whether a sender is guardian, non-guardian, or unverified) runs unconditionally. However, guardian *enforcement* -- `forceStrictSideEffects`, fail-closed denial for unverified channels, and approval prompt routing to guardians -- only executes when `CHANNEL_APPROVALS_ENABLED=true`. When the flag is off, messages go through the standard fire-and-forget processing path (`processChannelMessageInBackground`), which does not apply guardian enforcement.
+Guardian actor-role *classification* (determining whether a sender is guardian, non-guardian, or unverified) runs unconditionally. Guardian *enforcement* for non-guardian/unverified actors (`forceStrictSideEffects`, fail-closed denial for unverified channels, and approval prompt routing to guardians) is always active when orchestrator + callback context are available.
 
 | Flag / Behavior | Description |
 |-----------------|-------------|
-| `CHANNEL_APPROVALS_ENABLED=true` | Enables the full channel approval flow: approval prompts, callback-based decisions, reminder messages, **and** guardian enforcement (`forceStrictSideEffects`, fail-closed denial, approval routing to guardians). Actor-role classification runs regardless. |
-| `forceStrictSideEffects` | Automatically set on runs triggered by non-guardian or unverified-channel senders so all side-effect tools require approval. Only applied when `CHANNEL_APPROVALS_ENABLED=true`. |
-| **Fail-closed no-binding** | When no guardian binding exists for a channel, the sender is classified as `unverified_channel`. Any sensitive action is auto-denied with a notice that no guardian has been configured. Only enforced when `CHANNEL_APPROVALS_ENABLED=true`. |
-| **Fail-closed no-identity** | When `senderExternalUserId` is absent but a guardian binding exists for the channel, the actor is classified as `unverified_channel`. Only enforced when `CHANNEL_APPROVALS_ENABLED=true`. |
+| `forceStrictSideEffects` | Automatically set on runs triggered by non-guardian or unverified-channel senders so all side-effect tools require approval. |
+| **Fail-closed no-binding** | When no guardian binding exists for a channel, the sender is classified as `unverified_channel`. Any sensitive action is auto-denied with a notice that no guardian has been configured. |
+| **Fail-closed no-identity** | When `senderExternalUserId` is absent, the actor is classified as `unverified_channel` (even if no guardian binding exists yet). |
 | **Guardian-only approval** | Non-guardian senders cannot approve their own pending actions. Only the verified guardian can approve or deny. |
 | **Expired approval auto-deny** | A proactive sweep runs every 60 seconds to find expired guardian approval requests (30-minute TTL). Expired approvals are auto-denied, and both the requester and guardian are notified. If a non-guardian interacts before the sweep runs, the expiry is also detected reactively. |
 
@@ -202,7 +194,7 @@ The `/channels/inbound` endpoint requires a valid `X-Gateway-Origin` header to p
 
 ## Twilio Setup Primitive
 
-Twilio is the shared telephony provider for both voice calls and SMS messaging. Configuration is managed through the `twilio_config` IPC contract and the `twilio-setup` skill.
+Twilio is the shared telephony provider for both voice calls and SMS messaging. Configuration is managed through the `twilio_config` IPC contract and the `twilio-setup` skill. For SMS-specific onboarding (including compliance verification and test sending), the `sms-setup` skill provides a guided conversational flow that layers on top of `twilio-setup`.
 
 ### `twilio_config` IPC Contract
 
@@ -216,8 +208,15 @@ The daemon handles `twilio_config` messages with the following actions:
 | `provision_number` | Purchases a new phone number via the Twilio API. Accepts optional `areaCode` and `country` (ISO 3166-1 alpha-2, default `US`). Auto-assigns the number to the assistant (persists to config and secure storage) and configures Twilio webhooks (voice, status callback, SMS) when a public ingress URL is available. |
 | `assign_number` | Assigns an existing Twilio phone number (E.164 format) to the assistant and auto-configures webhooks when ingress is available |
 | `list_numbers` | Lists all incoming phone numbers on the Twilio account with their capabilities (voice, SMS) |
+| `sms_compliance_status` | Returns the SMS compliance posture for the assigned phone number. Determines number type (toll-free vs local 10DLC) and retrieves toll-free verification status from Twilio. |
+| `sms_submit_tollfree_verification` | Submits a new toll-free verification request to Twilio. Validates required fields and enum values. Defaults `businessType` to `SOLE_PROPRIETOR`. |
+| `sms_update_tollfree_verification` | Updates an existing toll-free verification by SID. Requires `verificationSid`. |
+| `sms_delete_tollfree_verification` | Deletes a toll-free verification by SID. Includes warning about queue priority reset. |
+| `release_number` | Releases (deletes) a phone number from the Twilio account. Clears the number from config and secure storage. Includes warning about toll-free verification context loss. |
+| `sms_send_test` | Sends a test SMS to the specified `phoneNumber` with the given `text`, polls Twilio for delivery status (up to 3 retries at 2-second intervals), and returns the result in `testResult`. Stores the last result in memory for use by `sms_doctor`. |
+| `sms_doctor` | Runs a comprehensive SMS health diagnostic. Checks channel readiness, compliance/toll-free verification status, and the last `sms_send_test` result. Returns structured diagnostics in `diagnostics` with an overall `status` ("healthy", "degraded", or "unhealthy") and actionable `items`. |
 
-Response type: `twilio_config_response` with `success`, `hasCredentials`, optional `phoneNumber`, optional `numbers` array, optional `error`, and optional `warning` (for non-fatal webhook sync failures).
+Response type: `twilio_config_response` with `success`, `hasCredentials`, optional `phoneNumber`, optional `numbers` array, optional `error`, optional `warning` (for non-fatal webhook sync failures), optional `compliance` object (for compliance status actions, containing `numberType`, `verificationSid`, `verificationStatus`, `rejectionReason`, `rejectionReasons`, `errorCode`, `editAllowed`, `editExpiration`), optional `testResult` (for `sms_send_test`), and optional `diagnostics` (for `sms_doctor`).
 
 ### Ingress Webhook Reconciliation
 
@@ -259,6 +258,34 @@ Guardian bindings, verification challenges, and approval requests are all scoped
 
 The channel guardian service generates verification challenge instructions with channel-appropriate wording. The `channelLabel()` function maps `sourceChannel` values to human-readable labels (e.g., `"telegram"` -> `"Telegram"`, `"sms"` -> `"SMS"`), so challenge prompts reference the correct channel name.
 
+## Channel Readiness
+
+The `channel_readiness` IPC contract provides a unified way to check whether a channel (SMS, Telegram, etc.) is fully configured and operational. It runs local checks (credential presence, phone number assignment, ingress config) synchronously and optional remote checks (API reachability) asynchronously with a 5-minute TTL cache.
+
+### `channel_readiness` IPC Contract
+
+| Action | Description |
+|--------|-------------|
+| `get` | Returns readiness snapshots for the specified channel (or all channels if omitted). Local checks always run; remote checks run only when `includeRemote=true` and cache is stale. |
+| `refresh` | Invalidates the cache for the specified channel (or all channels), then returns fresh snapshots. |
+
+Request fields: `action` (required), `channel` (optional filter), `assistantId` (optional), `includeRemote` (optional boolean).
+
+Response type: `channel_readiness_response` with `success`, optional `snapshots` array (each with `channel`, `ready`, `checkedAt`, `stale`, `reasons`, `localChecks`, optional `remoteChecks`), and optional `error`.
+
+### Built-in Channel Probes
+
+- **SMS**: Checks Twilio credentials, phone number assignment, and public ingress URL.
+- **Telegram**: Checks bot token, webhook secret, and public ingress URL.
+
+### Key modules
+
+| File | Purpose |
+|------|---------|
+| `src/runtime/channel-readiness-types.ts` | Shared types: `ChannelId`, `ReadinessCheckResult`, `ChannelReadinessSnapshot`, `ChannelProbe` |
+| `src/runtime/channel-readiness-service.ts` | Service class with probe registration, cached readiness evaluation, and built-in SMS/Telegram probes |
+| `src/daemon/handlers/config.ts` | `handleChannelReadiness` — IPC handler for `channel_readiness` messages |
+
 ## Database
 
 SQLite via Drizzle ORM, stored at `~/.vellum/workspace/data/db/assistant.db`. Key tables include conversations, messages, tool invocations, attachments, memory segments (with FTS5), memory items, entities, reminders, and recurrence schedules (cron + RRULE).
@@ -293,9 +320,9 @@ The image runs as non-root user `assistant` (uid 1001) and exposes port `3001`.
 | Symptom | Cause | Resolution |
 |---------|-------|------------|
 | 403 `GATEWAY_ORIGIN_REQUIRED` on `/channels/inbound` | Missing or invalid `X-Gateway-Origin` header | Ensure `RUNTIME_GATEWAY_ORIGIN_SECRET` is set to the same value on both gateway and runtime. If not using a dedicated secret, ensure the bearer token (`RUNTIME_BEARER_TOKEN` or `~/.vellum/http-token`) is shared. |
-| Non-guardian actions silently denied | No guardian binding for the channel and `CHANNEL_APPROVALS_ENABLED=true`. The system is fail-closed when enforcement is active. | Run the guardian verification flow from the desktop UI to bind a guardian. |
+| Non-guardian actions silently denied | No guardian binding for the channel. The system is fail-closed for unverified channels. | Run the guardian verification flow from the desktop UI to bind a guardian. |
 | Guardian approval expired | The 30-minute TTL elapsed. The proactive sweep auto-denied the approval and notified both parties. | The requester must re-trigger the action. |
-| `forceStrictSideEffects` unexpectedly active | The sender is classified as `non-guardian` or `unverified_channel` (requires `CHANNEL_APPROVALS_ENABLED=true`) | Verify the sender's `externalUserId` matches the guardian binding, or set up a guardian binding for the channel. |
+| `forceStrictSideEffects` unexpectedly active | The sender is classified as `non-guardian` or `unverified_channel` | Verify the sender's `externalUserId` matches the guardian binding, or set up a guardian binding for the channel. |
 
 ### Invalid RRULE set expressions
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "type": "module",
   "bin": {
     "vellum": "./src/index.ts"

package/scripts/ipc/generate-swift.ts

@@ -405,6 +405,19 @@ function emitStruct(s: SwiftStruct): string {
     lines.push(`    public let ${p.swiftName}: ${p.swiftType}`);
   }
 
+  // Emit public memberwise init (Swift only auto-generates internal inits for public structs)
+  if (s.properties.length > 0) {
+    lines.push('');
+    const params = s.properties
+      .map((p) => `${p.swiftName}: ${p.swiftType}${p.isOptional ? ' = nil' : ''}`)
+      .join(', ');
+    lines.push(`    public init(${params}) {`);
+    for (const p of s.properties) {
+      lines.push(`        self.${p.swiftName} = ${p.swiftName}`);
+    }
+    lines.push('    }');
+  }
+
   if (needsCodingKeys(s.properties)) {
     lines.push('');
     lines.push('    private enum CodingKeys: String, CodingKey {');

package/src/__tests__/__snapshots__/ipc-snapshot.test.ts.snap

@@ -601,6 +601,15 @@ exports[`IPC message snapshots ClientMessage types twilio_config serializes to e
 }
 `;
 
+exports[`IPC message snapshots ClientMessage types channel_readiness serializes to expected JSON 1`] = `
+{
+  "action": "get",
+  "channel": "sms",
+  "includeRemote": true,
+  "type": "channel_readiness",
+}
+`;
+
 exports[`IPC message snapshots ClientMessage types guardian_verification serializes to expected JSON 1`] = `
 {
   "action": "create_challenge",
@@ -908,6 +917,20 @@ exports[`IPC message snapshots ClientMessage types tool_names_list serializes to
 }
 `;
 
+exports[`IPC message snapshots ClientMessage types dictation_request serializes to expected JSON 1`] = `
+{
+  "context": {
+    "appName": "Example App",
+    "bundleIdentifier": "com.example.app",
+    "cursorInTextField": true,
+    "selectedText": "some selected text",
+    "windowTitle": "Main Window",
+  },
+  "transcription": "Hello world",
+  "type": "dictation_request",
+}
+`;
+
 exports[`IPC message snapshots ServerMessage types auth_result serializes to expected JSON 1`] = `
 {
   "success": true,
@@ -1323,6 +1346,14 @@ exports[`IPC message snapshots ServerMessage types task_routed serializes to exp
 }
 `;
 
+exports[`IPC message snapshots ServerMessage types ride_shotgun_progress serializes to expected JSON 1`] = `
+{
+  "message": "Observing user activity...",
+  "type": "ride_shotgun_progress",
+  "watchId": "watch-shotgun-001",
+}
+`;
+
 exports[`IPC message snapshots ServerMessage types ride_shotgun_result serializes to expected JSON 1`] = `
 {
   "observationCount": 5,
@@ -1929,13 +1960,74 @@ exports[`IPC message snapshots ServerMessage types telegram_config_response seri
 
 exports[`IPC message snapshots ServerMessage types twilio_config_response serializes to expected JSON 1`] = `
 {
+  "compliance": {
+    "numberType": "toll_free",
+    "verificationSid": "TF_VER_001",
+    "verificationStatus": "TWILIO_APPROVED",
+  },
+  "diagnostics": {
+    "actionItems": [],
+    "compliance": {
+      "detail": "Toll-free verification: TWILIO_APPROVED",
+      "status": "TWILIO_APPROVED",
+    },
+    "overallStatus": "healthy",
+    "readiness": {
+      "issues": [],
+      "ready": true,
+    },
+  },
   "hasCredentials": true,
   "phoneNumber": "+15551234567",
   "success": true,
+  "testResult": {
+    "finalStatus": "delivered",
+    "initialStatus": "queued",
+    "messageSid": "SM-test-001",
+    "to": "+15559876543",
+  },
   "type": "twilio_config_response",
 }
 `;
 
+exports[`IPC message snapshots ServerMessage types channel_readiness_response serializes to expected JSON 1`] = `
+{
+  "snapshots": [
+    {
+      "channel": "sms",
+      "checkedAt": 1700000000000,
+      "localChecks": [
+        {
+          "message": "Twilio credentials are not configured",
+          "name": "twilio_credentials",
+          "passed": false,
+        },
+        {
+          "message": "Phone number is assigned",
+          "name": "phone_number",
+          "passed": true,
+        },
+        {
+          "message": "Public ingress URL is configured",
+          "name": "ingress",
+          "passed": true,
+        },
+      ],
+      "ready": false,
+      "reasons": [
+        {
+          "code": "twilio_credentials",
+          "text": "Twilio credentials are not configured",
+        },
+      ],
+      "stale": false,
+    },
+  ],
+  "success": true,
+  "type": "channel_readiness_response",
+}
+`;
+
 exports[`IPC message snapshots ServerMessage types guardian_verification_response serializes to expected JSON 1`] = `
 {
   "instruction": "Send this code to the Telegram bot",
@@ -2499,3 +2591,11 @@ exports[`IPC message snapshots ServerMessage types tool_names_list_response seri
   "type": "tool_names_list_response",
 }
 `;
+
+exports[`IPC message snapshots ServerMessage types dictation_response serializes to expected JSON 1`] = `
+{
+  "mode": "dictation",
+  "text": "Hello world",
+  "type": "dictation_response",
+}
+`;

package/src/__tests__/approval-hardcoded-copy-guard.test.ts

@@ -0,0 +1,41 @@
+/**
+ * Guard test: ensures no production hard-coded approval lifecycle copy creeps
+ * back into route/service files outside of the composer module.
+ *
+ * The composer file (`approval-message-composer.ts`) is intentionally excluded
+ * since that is where deterministic fallback copy legitimately lives.
+ */
+
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import { describe, test, expect } from 'bun:test';
+
+const SCANNED_FILES = [
+  'runtime/channel-approvals.ts',
+  'runtime/routes/channel-routes.ts',
+  'runtime/channel-guardian-service.ts',
+];
+
+const BANNED_PATTERNS: { pattern: RegExp; description: string }[] = [
+  { pattern: /The assistant wants to use/i, description: 'old standard prompt' },
+  { pattern: /Do you want to allow this/i, description: 'old approval question' },
+  { pattern: /['"`]I'm still waiting/i, description: 'old reminder prefix (string literal)' },
+  { pattern: /['"`].*is requesting to run/i, description: 'old guardian prompt (string literal)' },
+  { pattern: /['"`]Sent to guardian/i, description: 'old forwarding notice (string literal)' },
+  { pattern: /['"`]Guardian verified successfully/i, description: 'old verify success (string literal)' },
+  { pattern: /['"`]Verification failed/i, description: 'old verify failure (string literal)' },
+  { pattern: /['"`]Your request has been sent/i, description: 'old request forwarded notice (string literal)' },
+  { pattern: /['"`]No guardian is configured/i, description: 'old no-binding notice (string literal)' },
+];
+
+describe('approval hardcoded copy guard', () => {
+  for (const file of SCANNED_FILES) {
+    test(`${file} does not contain banned approval copy literals`, () => {
+      const content = readFileSync(join(__dirname, '..', file), 'utf-8');
+      for (const { pattern, description: _description } of BANNED_PATTERNS) {
+        const match = content.match(pattern);
+        expect(match).toBeNull();
+      }
+    });
+  }
+});

package/src/__tests__/approval-message-composer.test.ts

@@ -0,0 +1,253 @@
+import { describe, test, expect } from 'bun:test';
+import {
+  composeApprovalMessage,
+  getFallbackMessage,
+} from '../runtime/approval-message-composer.js';
+import type {
+  ApprovalMessageScenario,
+  ApprovalMessageContext,
+} from '../runtime/approval-message-composer.js';
+
+// ---------------------------------------------------------------------------
+// Every scenario must produce a non-empty string
+// ---------------------------------------------------------------------------
+
+const ALL_SCENARIOS: ApprovalMessageScenario[] = [
+  'standard_prompt',
+  'guardian_prompt',
+  'reminder_prompt',
+  'guardian_delivery_failed',
+  'guardian_request_forwarded',
+  'guardian_disambiguation',
+  'guardian_identity_mismatch',
+  'request_pending_guardian',
+  'guardian_decision_outcome',
+  'guardian_expired_requester',
+  'guardian_expired_guardian',
+  'guardian_verify_success',
+  'guardian_verify_failed',
+  'guardian_verify_challenge_setup',
+  'guardian_verify_status_bound',
+  'guardian_verify_status_unbound',
+  'guardian_deny_no_identity',
+  'guardian_deny_no_binding',
+];
+
+describe('approval-message-composer', () => {
+  // -----------------------------------------------------------------------
+  // Fallback messages — every scenario produces non-empty output
+  // -----------------------------------------------------------------------
+
+  describe('getFallbackMessage', () => {
+    for (const scenario of ALL_SCENARIOS) {
+      test(`scenario "${scenario}" produces a non-empty string`, () => {
+        const msg = getFallbackMessage({ scenario });
+        expect(typeof msg).toBe('string');
+        expect(msg.trim().length).toBeGreaterThan(0);
+      });
+    }
+
+    test('standard_prompt includes toolName when provided', () => {
+      const msg = getFallbackMessage({
+        scenario: 'standard_prompt',
+        toolName: 'execute_shell',
+      });
+      expect(msg).toContain('execute_shell');
+    });
+
+    test('guardian_prompt includes requester identifier and toolName', () => {
+      const msg = getFallbackMessage({
+        scenario: 'guardian_prompt',
+        toolName: 'write_file',
+        requesterIdentifier: 'alice',
+      });
+      expect(msg).toContain('alice');
+      expect(msg).toContain('write_file');
+    });
+
+    test('guardian_delivery_failed includes toolName when provided', () => {
+      const msg = getFallbackMessage({
+        scenario: 'guardian_delivery_failed',
+        toolName: 'execute_shell',
+      });
+      expect(msg).toContain('execute_shell');
+    });
+
+    test('guardian_request_forwarded includes toolName', () => {
+      const msg = getFallbackMessage({
+        scenario: 'guardian_request_forwarded',
+        toolName: 'execute_shell',
+      });
+      expect(msg).toContain('execute_shell');
+    });
+
+    test('guardian_disambiguation includes pendingCount', () => {
+      const msg = getFallbackMessage({
+        scenario: 'guardian_disambiguation',
+        pendingCount: 3,
+      });
+      expect(msg).toContain('3');
+    });
+
+    test('guardian_decision_outcome includes decision and toolName', () => {
+      const msg = getFallbackMessage({
+        scenario: 'guardian_decision_outcome',
+        decision: 'approved',
+        toolName: 'read_file',
+      });
+      expect(msg).toContain('approved');
+      expect(msg).toContain('read_file');
+    });
+
+    test('guardian_expired_requester includes toolName', () => {
+      const msg = getFallbackMessage({
+        scenario: 'guardian_expired_requester',
+        toolName: 'deploy',
+      });
+      expect(msg).toContain('deploy');
+      expect(msg).toContain('expired');
+    });
+
+    test('guardian_expired_guardian includes requester and toolName', () => {
+      const msg = getFallbackMessage({
+        scenario: 'guardian_expired_guardian',
+        requesterIdentifier: 'bob',
+        toolName: 'delete_file',
+      });
+      expect(msg).toContain('bob');
+      expect(msg).toContain('delete_file');
+    });
+
+    test('guardian_verify_failed includes failureReason', () => {
+      const msg = getFallbackMessage({
+        scenario: 'guardian_verify_failed',
+        failureReason: 'Code did not match.',
+      });
+      expect(msg).toContain('Code did not match.');
+    });
+
+    test('guardian_verify_challenge_setup includes verifyCommand and ttlSeconds', () => {
+      const msg = getFallbackMessage({
+        scenario: 'guardian_verify_challenge_setup',
+        verifyCommand: '/verify abc123',
+        ttlSeconds: 30,
+      });
+      expect(msg).toContain('/verify abc123');
+      expect(msg).toContain('30');
+    });
+  });
+
+  // -----------------------------------------------------------------------
+  // composeApprovalMessage — layered source selection
+  // -----------------------------------------------------------------------
+
+  describe('composeApprovalMessage', () => {
+    test('returns assistantPreface when provided (primary source)', () => {
+      const preface = 'The assistant already said something helpful.';
+      const msg = composeApprovalMessage({
+        scenario: 'standard_prompt',
+        toolName: 'execute_shell',
+        assistantPreface: preface,
+      });
+      expect(msg).toBe(preface);
+    });
+
+    test('ignores empty assistantPreface and falls back to template', () => {
+      const msg = composeApprovalMessage({
+        scenario: 'standard_prompt',
+        toolName: 'execute_shell',
+        assistantPreface: '',
+      });
+      expect(msg).toContain('execute_shell');
+      expect(msg).not.toBe('');
+    });
+
+    test('ignores whitespace-only assistantPreface', () => {
+      const msg = composeApprovalMessage({
+        scenario: 'standard_prompt',
+        toolName: 'execute_shell',
+        assistantPreface: '   ',
+      });
+      expect(msg).toContain('execute_shell');
+    });
+
+    test('falls back to deterministic template when no assistantPreface', () => {
+      const msg = composeApprovalMessage({
+        scenario: 'guardian_prompt',
+        toolName: 'write_file',
+        requesterIdentifier: 'charlie',
+      });
+      expect(msg).toContain('charlie');
+      expect(msg).toContain('write_file');
+    });
+
+    test('fallback matches getFallbackMessage output', () => {
+      const ctx: ApprovalMessageContext = {
+        scenario: 'reminder_prompt',
+      };
+      expect(composeApprovalMessage(ctx)).toBe(getFallbackMessage(ctx));
+    });
+  });
+
+  // -----------------------------------------------------------------------
+  // Verification scenario resilience — composed messages contain key facts
+  // -----------------------------------------------------------------------
+
+  describe('verification scenario resilience', () => {
+    test('guardian_verify_challenge_setup includes verify command and TTL', () => {
+      const msg = composeApprovalMessage({
+        scenario: 'guardian_verify_challenge_setup',
+        verifyCommand: '/guardian_verify abc123def456',
+        ttlSeconds: 600,
+      });
+      expect(typeof msg).toBe('string');
+      expect(msg.length).toBeGreaterThan(0);
+      expect(msg).toContain('/guardian_verify abc123def456');
+      expect(msg).toContain('600');
+    });
+
+    test('guardian_verify_failed includes failure reason', () => {
+      const msg = composeApprovalMessage({
+        scenario: 'guardian_verify_failed',
+        failureReason: 'Too many attempts. Please try again later.',
+      });
+      expect(typeof msg).toBe('string');
+      expect(msg.length).toBeGreaterThan(0);
+      expect(msg).toContain('Too many attempts');
+    });
+
+    test('guardian_verify_failed with invalid-or-expired reason includes that reason', () => {
+      const msg = composeApprovalMessage({
+        scenario: 'guardian_verify_failed',
+        failureReason: 'The verification code is invalid or has expired.',
+      });
+      expect(typeof msg).toBe('string');
+      expect(msg.length).toBeGreaterThan(0);
+      expect(msg).toContain('invalid or has expired');
+    });
+
+    test('guardian_verify_success produces a non-empty success message', () => {
+      const msg = composeApprovalMessage({
+        scenario: 'guardian_verify_success',
+      });
+      expect(typeof msg).toBe('string');
+      expect(msg.length).toBeGreaterThan(0);
+    });
+
+    test('guardian_verify_status_bound produces a non-empty message', () => {
+      const msg = composeApprovalMessage({
+        scenario: 'guardian_verify_status_bound',
+      });
+      expect(typeof msg).toBe('string');
+      expect(msg.length).toBeGreaterThan(0);
+    });
+
+    test('guardian_verify_status_unbound produces a non-empty message', () => {
+      const msg = composeApprovalMessage({
+        scenario: 'guardian_verify_status_unbound',
+      });
+      expect(typeof msg).toBe('string');
+      expect(msg.length).toBeGreaterThan(0);
+    });
+  });
+});

package/src/__tests__/call-domain.test.ts

@@ -34,10 +34,10 @@ mock.module('../util/logger.js', () => ({
 }));
 
 mock.module('../calls/twilio-config.js', () => ({
-  getTwilioConfig: () => ({
+  getTwilioConfig: (assistantId?: string) => ({
     accountSid: 'AC_test',
     authToken: 'test_token',
-    phoneNumber: '+15550001111',
+    phoneNumber: assistantId === 'ast-alpha' ? '+15550003333' : '+15550001111',
     webhookBaseUrl: 'https://test.example.com',
     wssBaseUrl: 'wss://test.example.com',
   }),
@@ -97,6 +97,16 @@ describe('resolveCallerIdentity — strict implicit-default policy', () => {
     }
   });
 
+  test('assistant_number resolves from assistant-scoped Twilio number when assistantId is provided', async () => {
+    const result = await resolveCallerIdentity(makeConfig(), undefined, 'ast-alpha');
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.mode).toBe('assistant_number');
+      expect(result.fromNumber).toBe('+15550003333');
+      expect(result.source).toBe('implicit_default');
+    }
+  });
+
   test('explicit user_number succeeds when eligible', async () => {
     const result = await resolveCallerIdentity(
       makeConfig({ userNumber: '+15550002222' }),