@vellumai/assistant 0.4.2 → 0.4.4

package/.env.example

@@ -20,3 +20,6 @@ OLLAMA_BASE_URL=
 
 # Enable the runtime HTTP server (required for web local mode).
 # RUNTIME_HTTP_PORT=7821
+
+# Platform base URL (defaults to empty string)
+# PLATFORM_BASE_URL=

package/ARCHITECTURE.md

@@ -22,6 +22,43 @@ This document owns assistant-runtime architecture details. The repo-level archit
 - Voice calls mirror the same prompt contract: `CallController` receives guardian context on setup and refreshes it immediately after successful voice challenge verification, so the first post-verification turn is grounded as `actor_role: guardian`.
 - Voice-specific behavior (DTMF/speech verification flow, relay state machine) remains voice-local; only actor-role resolution is shared.
 
+### Vellum Guardian Identity Model (Actor Tokens + Bootstrap)
+
+The vellum channel (macOS desktop, iOS, CLI) uses an identity-bound actor token system to authenticate guardian identity on HTTP routes. This replaces the previous implicit trust model where all local connections were assumed to be the guardian.
+
+**Identity lifecycle:**
+
+1. **Startup migration** — On daemon start, `ensureVellumGuardianBinding()` (in `guardian-vellum-migration.ts`) backfills a `channel='vellum'` guardian binding with a stable `guardianPrincipalId` (format: `vellum-principal-<uuid>`). Existing installations get a binding with `verifiedVia: 'startup-migration'`; new installs get one via bootstrap. This migration is idempotent and preserves bindings for other channels (Telegram, SMS, etc.).
+
+2. **Hatch bootstrap (loopback-only, macOS)** — On every launch, the macOS client calls `POST /v1/integrations/guardian/vellum/bootstrap` with `{ platform: 'macos', deviceId }`. The endpoint is loopback-only: it rejects requests with `X-Forwarded-For` and verifies the peer IP is a loopback address (`127.0.0.1`, `::1`, `::ffff:127.0.0.1`). The endpoint is idempotent: it ensures a vellum guardian principal exists, revokes any prior token for the same device binding, mints a new HMAC-SHA256 signed actor token with a 90-day TTL, stores only the SHA-256 hash, and returns `{ guardianPrincipalId, actorToken, isNew }`. The raw token is returned once and never persisted on the server. macOS re-bootstraps on each startup to refresh its token.
+
+3. **iOS pairing** — iOS devices obtain actor tokens exclusively through the QR pairing flow (re-pairs on credential loss). When an iOS device completes pairing, the pairing response includes an `actorToken` minted against the same vellum guardian principal. The pairing handler in `pairing-routes.ts` calls `mintPairingActorToken()` which looks up the vellum binding and mints a device-specific token. iOS does not call the bootstrap endpoint.
+
+4. **IPC identity** — Local IPC connections (Unix domain socket from the macOS native app) do not send actor tokens. Instead, the daemon assigns a deterministic local actor identity via `resolveLocalIpcGuardianContext()` in `local-actor-identity.ts`. This looks up the vellum guardian binding and routes through the same `resolveGuardianContext` trust pipeline used by HTTP channel ingress. When no vellum binding exists yet (pre-bootstrap), a fallback guardian context is returned since the local macOS user is inherently the guardian of their own machine.
+
+**Actor token format:** `base64url(JSON claims) + '.' + base64url(HMAC-SHA256 signature)`. Claims include `assistantId`, `platform`, `deviceId`, `guardianPrincipalId`, `iat`, `exp` (default: 90 days from issuance), and `jti`.
+
+**Hash-only storage:** Only the SHA-256 hex digest of the raw token is persisted in the `actor_token_records` table. Token verification recomputes the hash and looks it up in the store to check revocation status. Tokens are scoped to `(assistantId, guardianPrincipalId, hashedDeviceId)` with a one-active-per-device invariant.
+
+**Signing key management:** A 32-byte random signing key is generated on first startup and persisted at `~/.vellum/protected/actor-token-signing-key` with `chmod 0o600`. The key is loaded on subsequent startups via `loadOrCreateSigningKey()`.
+
+**Strict HTTP enforcement:** Vellum-channel HTTP routes (POST /v1/messages, POST /v1/confirm, POST /v1/guardian-actions/decision, etc.) require a valid actor token via the `X-Actor-Token` header. The middleware in `middleware/actor-token.ts` verifies the HMAC signature, checks the token is active in the store, and resolves a guardian context through the standard trust pipeline. For backward compatibility with the CLI, requests without an actor token that originate from a loopback address (no `X-Forwarded-For` header) fall back to `resolveLocalIpcGuardianContext()`. Gateway-proxied requests (which carry `X-Forwarded-For`) without an actor token are rejected.
+
+**Notification scoping:** Guardian-sensitive notifications (e.g., approval requests, access request alerts) are annotated with `targetGuardianPrincipalId` so the notification pipeline can scope delivery to the correct guardian identity across devices.
+
+**Key source files:**
+
+| File | Purpose |
+|------|---------|
+| `src/runtime/actor-token-service.ts` | HMAC-SHA256 mint/verify, signing key management, `hashToken` |
+| `src/runtime/actor-token-store.ts` | Hash-only persistence: create, find by hash/device binding, revoke |
+| `src/runtime/middleware/actor-token.ts` | HTTP middleware: `verifyHttpActorToken`, `verifyHttpActorTokenWithLocalFallback`, `isActorBoundGuardian` |
+| `src/runtime/local-actor-identity.ts` | `resolveLocalIpcGuardianContext` — deterministic IPC identity |
+| `src/runtime/guardian-vellum-migration.ts` | `ensureVellumGuardianBinding` — startup binding backfill |
+| `src/runtime/routes/guardian-bootstrap-routes.ts` | `POST /v1/integrations/guardian/vellum/bootstrap` handler |
+| `src/runtime/routes/pairing-routes.ts` | `mintPairingActorToken` — actor token in pairing response |
+| `src/memory/guardian-bindings.ts` | Guardian binding persistence (shared across all channels) |
+
 ### Channel-Agnostic Scoped Approval Grants
 
 Scoped approval grants allow a guardian's approval decision on one channel (e.g., Telegram) to authorize a tool execution on a different channel (e.g., voice). Two scope modes exist: `request_id` (bound to a specific pending request) and `tool_signature` (bound to `toolName` + canonical `inputDigest`). Grants are one-time-use, exact-match, fail-closed, and TTL-bound. Full architecture details (lifecycle flow, security invariants, key files) live in [`docs/architecture/security.md`](docs/architecture/security.md#channel-agnostic-scoped-approval-grants).
@@ -210,7 +247,7 @@ The SMS channel provides text-only messaging via Twilio, sharing the same teleph
 2. The gateway authenticates the request via bearer token (same fail-closed model as `/deliver/telegram`).
 3. The gateway sends the SMS via the Twilio Messages API using the configured `TWILIO_PHONE_NUMBER` as the `From` number.
 
-**Setup**: Twilio credentials (Account SID, Auth Token) and phone number are managed via the `twilio_config` IPC contract and the `twilio-setup` skill. A single phone number is shared across voice and SMS for each assistant. Both `provision_number` and `assign_number` auto-persist the number to config and secure storage, and auto-configure Twilio webhooks (voice URL, status callback, SMS URL) via the Twilio IncomingPhoneNumber API when a public ingress URL is available. When `assistantId` is provided, the number is persisted into the per-assistant mapping at `sms.assistantPhoneNumbers[assistantId]`, and the legacy `sms.phoneNumber` field is only set if it was previously empty/unset (acting as a fallback for single-assistant installs). This prevents multi-assistant assignments from clobbering each other's global outbound number. Without `assistantId`, the legacy field is always updated. Webhook configuration is best-effort — if ingress is not yet set up, the number is still assigned and webhooks can be configured later. Non-fatal webhook failures are surfaced as a `warning` field in the `twilio_config_response`.
+**Setup**: Twilio credentials (Account SID, Auth Token) and phone number are managed via HTTP control-plane endpoints (`/v1/integrations/twilio/*`) exposed by the runtime and proxied by the gateway (see `src/runtime/routes/twilio-routes.ts`). A single phone number is shared across voice and SMS for each assistant. Both `provision` and `assign` endpoints auto-persist the number to config and secure storage, and auto-configure Twilio webhooks (voice URL, status callback, SMS URL) via the Twilio IncomingPhoneNumber API when a public ingress URL is available. When `assistantId` is provided, the number is persisted into the per-assistant mapping at `sms.assistantPhoneNumbers[assistantId]`, and the legacy `sms.phoneNumber` field is only set if it was previously empty/unset (acting as a fallback for single-assistant installs). This prevents multi-assistant assignments from clobbering each other's global outbound number. Without `assistantId`, the legacy field is always updated. Webhook configuration is best-effort — if ingress is not yet set up, the number is still assigned and webhooks can be configured later. Non-fatal webhook failures are surfaced as a `warning` field in the response.
 
 **Phone Number Resolution**: At runtime, `getTwilioConfig()` resolves the phone number using this priority chain: (1) `TWILIO_PHONE_NUMBER` env var — highest priority, explicit override; (2) `sms.phoneNumber` in config — primary source of truth written by `provision_number`/`assign_number`; (3) `credential:twilio:phone_number` secure key — backward-compatible fallback. An error is thrown if no number is found after all sources are checked.
 
@@ -256,9 +293,9 @@ These can be set via environment variables or stored in the credential vault (ke
 
 **Limitations (v1)**: Text-only — non-text message types are acknowledged but not forwarded; rich approval UI (inline buttons) is not supported.
 
-**Channel Readiness**: The `channel_readiness` IPC contract (`ChannelReadinessService` in `src/runtime/channel-readiness-service.ts`) provides a unified readiness subsystem for all channels. Each channel registers a `ChannelProbe` that runs synchronous local checks (credential presence, phone number, ingress config) and optional async remote checks with a 5-minute TTL cache. Built-in probes: SMS (Twilio credentials, phone number, ingress; remote checks query Twilio toll-free verification status for toll-free numbers) and Telegram (bot token, webhook secret, ingress). The `get` action returns cached snapshots; `refresh` invalidates the cache first. Unknown channels return `unsupported_channel`.
+**Channel Readiness**: The channel readiness HTTP endpoints (`GET /v1/channels/readiness`, `POST /v1/channels/readiness/refresh`) backed by `ChannelReadinessService` in `src/runtime/channel-readiness-service.ts` provide a unified readiness subsystem for all channels. Each channel registers a `ChannelProbe` that runs synchronous local checks (credential presence, phone number, ingress config) and optional async remote checks with a 5-minute TTL cache. Built-in probes: SMS (Twilio credentials, phone number, ingress; remote checks query Twilio toll-free verification status for toll-free numbers) and Telegram (bot token, webhook secret, ingress). The GET endpoint returns cached snapshots; the refresh endpoint invalidates the cache first. Unknown channels return `unsupported_channel`. Route handlers live in `src/runtime/routes/channel-readiness-routes.ts`.
 
-**SMS Compliance & Admin**: The `twilio_config` IPC contract extends beyond credential and number management with compliance and admin actions: `sms_compliance_status` detects toll-free vs local number type and fetches verification status; `sms_submit_tollfree_verification`, `sms_update_tollfree_verification`, and `sms_delete_tollfree_verification` manage the Twilio toll-free verification lifecycle; `release_number` removes a phone number from the Twilio account and clears all local references. All compliance actions validate required fields and Twilio enum values before calling the API.
+**SMS Compliance & Admin**: The Twilio HTTP control-plane endpoints extend beyond credential and number management with compliance and admin routes: `GET /v1/integrations/twilio/sms/compliance` detects toll-free vs local number type and fetches verification status; `POST/PATCH/DELETE /v1/integrations/twilio/sms/compliance/tollfree` manage the Twilio toll-free verification lifecycle; `POST /v1/integrations/twilio/numbers/release` removes a phone number from the Twilio account and clears all local references. All compliance actions validate required fields and Twilio enum values before calling the API.
 
 ### Slack Channel (Socket Mode)
 
@@ -397,7 +434,7 @@ A complementary access-granting flow where the guardian proactively creates a sh
 | Channel | Status | Prerequisites |
 |---------|--------|--------------|
 | Telegram | Shipped | Bot username resolved from credential metadata or `TELEGRAM_BOT_USERNAME` env |
-| Voice | Shipped | Identity-bound voice code redemption via DTMF/speech in the relay state machine. Gated behind `feature_flags.voice-invite-redemption.enabled` (default OFF). |
+| Voice | Shipped | Identity-bound voice code redemption via DTMF/speech in the relay state machine. Always-on canonical behavior with personalized friend/guardian name prompts. |
 | SMS | Deferred | Needs a deep-link strategy compatible with SMS (short URL or web redemption page) |
 | Slack | Deferred | Needs DM-safe ingress — Socket Mode handles channel messages but DM-initiated invite flows need routing |
 
@@ -413,10 +450,10 @@ Voice invites use a short numeric code (4-10 digits, default 6) instead of a URL
 
 **Call-time redemption subflow (`invite_redemption_pending`):**
 1. Unknown caller dials in. `relay-server.ts` resolves trust via `resolveActorTrust`. Caller is `unknown`, no pending guardian challenge.
-2. If `feature_flags.voice-invite-redemption.enabled` is ON, the relay checks `findActiveVoiceInvites` for invites bound to the caller's phone number.
-3. If active, non-expired invites exist, the relay enters the `invite_redemption_pending` state (reuses the `verification_pending` connection state) and prompts the caller to enter their invite code via DTMF or speech.
+2. The relay checks `findActiveVoiceInvites` for invites bound to the caller's phone number.
+3. If active, non-expired invites exist, the relay enters the `invite_redemption_pending` state (reuses the `verification_pending` connection state) and prompts the caller with personalized copy: `Welcome <friend-name>. Please enter the 6-digit code that <guardian-name> provided you to verify your identity.`
 4. `redeemVoiceInviteCode` validates: identity match, code hash match, expiry, use count. On success, an active member record is upserted and the call transitions to the normal call flow.
-5. On failure, the caller gets up to 3 attempts. After max attempts, the call is terminated.
+5. On invalid/expired code, the caller hears deterministic failure copy: `Sorry, the code you provided is incorrect or has since expired. Please ask <guardian-name> for a new code. Goodbye.` and the call ends immediately.
 
 **Security invariants:**
 - The plaintext voice code is returned exactly once at creation time and never stored.
@@ -424,8 +461,6 @@ Voice invites use a short numeric code (4-10 digits, default 6) instead of a URL
 - Failure responses are intentionally generic (`invalid_or_expired`) to prevent oracle attacks.
 - Blocked members cannot bypass the guardian's explicit block via invite redemption.
 
-**Feature flag:** `feature_flags.voice-invite-redemption.enabled` (default OFF). When disabled, unknown callers with active voice invites are denied normally — the invite check is skipped entirely.
-
 **Key source files:**
 
 | File | Purpose |
@@ -439,10 +474,76 @@ Voice invites use a short numeric code (4-10 digits, default 6) instead of a URL
 | `src/runtime/ingress-service.ts` | Shared business logic for invite/member operations (used by both HTTP routes and IPC) |
 | `src/runtime/routes/ingress-routes.ts` | HTTP API handlers for member/invite management including voice invite creation and redemption |
 | `src/runtime/routes/inbound-message-handler.ts` | Invite token intercept in the inbound flow (non-member and inactive-member branches) |
-| `src/calls/relay-server.ts` | Voice relay state machine — `invite_redemption_pending` subflow, feature flag gate |
+| `src/calls/relay-server.ts` | Voice relay state machine — `invite_redemption_pending` subflow (always-on canonical behavior) |
 | `src/util/voice-code.ts` | Cryptographic voice code generation and SHA-256 hashing |
 | `src/memory/ingress-invite-store.ts` | Invite persistence including `findActiveVoiceInvites` for identity-bound lookup |
 
+### Voice Inbound Security Model (Canonical)
+
+The voice inbound security model determines how unknown callers are handled when they dial in. Three paths exist, evaluated in priority order by `relay-server.ts` during the `handleSetup` phase. All guardian decisions route through `applyCanonicalGuardianDecision` in the canonical guardian request system.
+
+**Decision tree for inbound unknown callers:**
+
+```
+Unknown caller dials in
+        |
+        v
+resolveActorTrust() → trustClass
+        |
+        ├── guardian / trusted_contact → normal call flow
+        ├── blocked → immediate denial + disconnect
+        ├── policy: deny → immediate denial + disconnect
+        ├── policy: escalate → denial (voice cannot hold for async approval)
+        |
+        └── unknown (no binding) ──┐
+                                   |
+              ┌────────────────────┼──────────────────────┐
+              |                    |                       |
+    pendingChallenge?     activeVoiceInvites?      no invite, no challenge
+              |                    |                       |
+              v                    v                       v
+    Guardian verification   Invite redemption     Name capture +
+    (DTMF/speech code)     (personalized code)   guardian approval wait
+```
+
+**Path 1: Voice invite code redemption (guardian-initiated)**
+
+The guardian proactively creates a voice invite bound to the caller's E.164 phone number. When the unknown caller dials in and has an active, non-expired invite, the relay enters the `invite_redemption_pending` subflow with personalized prompts using the friend's and guardian's names. This is always-on canonical behavior (no feature flag). See [Voice Invite Flow](#voice-invite-flow-invite_redemption_pending) above.
+
+**Path 2: Live in-call guardian approval (friend-initiated)**
+
+When no invite exists and no pending guardian challenge is active, the relay enters the name capture + guardian approval wait flow:
+
+1. The relay transitions to `awaiting_name` state and prompts the caller for their name with a timeout.
+2. On name capture, `notifyGuardianOfAccessRequest` creates a canonical guardian request (`kind: 'access_request'`) and notifies the guardian via the notification pipeline.
+3. The relay transitions to `awaiting_guardian_decision` and plays hold music/messaging while polling the canonical request status.
+4. The guardian approves or denies via any channel (Telegram, SMS, desktop). All decisions route through `applyCanonicalGuardianDecision`, which dispatches to the `access_request` resolver in `guardian-request-resolvers.ts`.
+5. On approval: the resolver directly activates the caller as a trusted contact (upserts member with `status: 'active'`, `policy: 'allow'`), the poll detects the approved status, the relay transitions to the normal call flow with the caller's guardian context updated.
+6. On denial or timeout: the caller hears a denial message and the call ends.
+
+**Path 3: Inbound guardian verification (pending challenge)**
+
+When a pending voice guardian challenge exists (`getPendingChallenge`), the caller enters the DTMF/speech verification flow to complete an outbound-initiated guardian binding. This path is for guardian identity verification, not trusted-contact access.
+
+**Canonical decision routing:**
+
+All guardian decisions for voice access requests flow through:
+- `applyCanonicalGuardianDecision` (canonical guardian request system)
+- `accessRequestResolver` in `guardian-request-resolvers.ts` (kind-specific resolver)
+- For voice approvals: direct trusted-contact activation (no verification session needed since the caller is already on the line)
+- For text-channel access requests: verification session creation with 6-digit code (existing `access-request-decision.ts` path for legacy `channel_guardian_approval_requests`)
+
+**Key source files:**
+
+| File | Purpose |
+|------|---------|
+| `src/calls/relay-server.ts` | Inbound call decision tree, name capture, guardian approval wait polling |
+| `src/runtime/access-request-helper.ts` | Creates canonical access request and notifies guardian |
+| `src/approvals/guardian-decision-primitive.ts` | `applyCanonicalGuardianDecision` — unified decision primitive |
+| `src/approvals/guardian-request-resolvers.ts` | `access_request` resolver — voice direct activation, text-channel verification session |
+| `src/runtime/actor-trust-resolver.ts` | `resolveActorTrust` — caller trust classification |
+| `src/memory/canonical-guardian-store.ts` | Canonical request persistence and CAS resolution |
+
 ### Update Bulletin System
 
 Release-driven update notification system that surfaces release notes to the assistant via the system prompt.
@@ -1954,3 +2055,16 @@ Key files: `src/tools/sensitive-output-placeholders.ts`, `src/tools/executor.ts`
 ### Notifications
 
 For full notification developer guidance and lifecycle details, see [`assistant/src/notifications/README.md`](src/notifications/README.md).
+
+### Assistant Identity Boundary
+
+The daemon uses a single fixed internal scope constant — `DAEMON_INTERNAL_ASSISTANT_ID` (`'self'`), exported from `src/runtime/assistant-scope.ts` — for all assistant-scoped storage and routing within the daemon process. Public/external assistant IDs (e.g., those assigned during hatch, invite links, or platform registration) are an **edge concern** owned by the gateway and platform layers.
+
+**Boundary rule:** Daemon code must never derive internal scoping decisions from externally-provided assistant IDs. When a daemon path needs an assistant scope and none is provided, it defaults to `DAEMON_INTERNAL_ASSISTANT_ID`. The gateway is responsible for mapping public assistant IDs to internal routing before forwarding requests to the daemon.
+
+**Key files:**
+
+| File | Purpose |
+|------|---------|
+| `src/runtime/assistant-scope.ts` | Exports `DAEMON_INTERNAL_ASSISTANT_ID` constant |
+| `src/__tests__/assistant-id-boundary-guard.test.ts` | Guard tests enforcing the identity boundary |

package/README.md

@@ -201,29 +201,29 @@ 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. 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
-
-The daemon handles `twilio_config` messages with the following actions:
-
-| Action | Description |
-|--------|-------------|
-| `get` | Returns current state: `hasCredentials` (boolean) and `phoneNumber` (if assigned) |
-| `set_credentials` | Validates and stores Account SID and Auth Token in secure storage (Keychain / encrypted file). Credentials are retrieved from the credential store internally. |
-| `clear_credentials` | Removes stored Account SID and Auth Token from secure storage. Preserves the phone number in both config (`sms.phoneNumber`) and secure key (`credential:twilio:phone_number`) so that re-entering credentials resumes working without needing to reassign the number. |
-| `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`, 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`).
+Twilio is the shared telephony provider for both voice calls and SMS messaging. Configuration is managed through HTTP control-plane endpoints exposed by the runtime and proxied by the gateway. 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 HTTP Control-Plane Endpoints
+
+The runtime exposes a RESTful HTTP API for Twilio configuration, credential management, phone number operations, and SMS compliance:
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/v1/integrations/twilio/config` | Returns current state: `hasCredentials` (boolean) and `phoneNumber` (if assigned) |
+| POST | `/v1/integrations/twilio/credentials` | Validates and stores Account SID and Auth Token in secure storage (Keychain / encrypted file) |
+| DELETE | `/v1/integrations/twilio/credentials` | Removes stored credentials. Preserves the phone number in both config and secure key so re-entering credentials resumes working without reassigning the number. |
+| GET | `/v1/integrations/twilio/numbers` | Lists all incoming phone numbers on the Twilio account with their capabilities (voice, SMS) |
+| POST | `/v1/integrations/twilio/numbers/provision` | Purchases a new phone number. Accepts optional `areaCode` and `country`. Auto-assigns and configures webhooks when ingress is available. |
+| POST | `/v1/integrations/twilio/numbers/assign` | Assigns an existing Twilio phone number (E.164) and auto-configures webhooks when ingress is available |
+| POST | `/v1/integrations/twilio/numbers/release` | Releases a phone number from the Twilio account and clears local references |
+| GET | `/v1/integrations/twilio/sms/compliance` | Returns SMS compliance posture: number type (toll-free vs 10DLC) and toll-free verification status |
+| POST | `/v1/integrations/twilio/sms/compliance/tollfree` | Submits a new toll-free verification request |
+| PATCH | `/v1/integrations/twilio/sms/compliance/tollfree/:sid` | Updates an existing toll-free verification by SID |
+| DELETE | `/v1/integrations/twilio/sms/compliance/tollfree/:sid` | Deletes a toll-free verification by SID |
+| POST | `/v1/integrations/twilio/sms/test` | Sends a test SMS and polls for delivery status |
+| POST | `/v1/integrations/twilio/sms/doctor` | Runs comprehensive SMS health diagnostics |
+
+All endpoints are bearer-authenticated via the runtime HTTP token. Skills and clients should call the gateway URL (default `http://localhost:7830`) rather than the runtime port directly, as the gateway proxies all `/v1/integrations/twilio/*` routes.
 
 ### Ingress Webhook Reconciliation
 
@@ -241,9 +241,9 @@ Each assistant is assigned a single Twilio phone number that is shared between v
 
 #### Assistant-Scoped Phone Numbers
 
-When `assistantId` is provided in the `twilio_config` request, the `provision_number` and `assign_number` actions persist the phone number into a per-assistant mapping at `sms.assistantPhoneNumbers` (a `Record<string, string>` keyed by assistant ID). The legacy `sms.phoneNumber` field is always updated for backward compatibility.
+When `assistantId` is provided in the Twilio control-plane request, the provision and assign endpoints persist the phone number into a per-assistant mapping at `sms.assistantPhoneNumbers` (a `Record<string, string>` keyed by assistant ID). The legacy `sms.phoneNumber` field is always updated for backward compatibility.
 
-The `get` action, when called with `assistantId`, resolves the phone number by checking `sms.assistantPhoneNumbers[assistantId]` first, falling back to `sms.phoneNumber`. This allows multiple assistants to have distinct phone numbers while preserving existing behavior for single-assistant setups.
+The config endpoint (`GET /v1/integrations/twilio/config`), when called with `assistantId`, resolves the phone number by checking `sms.assistantPhoneNumbers[assistantId]` first, falling back to `sms.phoneNumber`. This allows multiple assistants to have distinct phone numbers while preserving existing behavior for single-assistant setups.
 
 The per-assistant mapping is propagated to the gateway via the config file watcher, enabling phone-number-based routing at the gateway boundary (see Gateway README).
 
@@ -271,6 +271,16 @@ The channel guardian service generates verification challenge instructions with
 - **Rebind requirement:** Creating a new guardian challenge when a binding already exists requires `rebind: true` in the IPC request. Without it, the daemon returns `already_bound`. This prevents accidental guardian replacement.
 - **Takeover prevention:** Verification is rejected when an active binding exists for a different external user. Same-user re-verification is allowed.
 
+### Vellum Guardian Identity (Actor Tokens)
+
+The vellum channel (macOS, iOS, CLI) uses HMAC-SHA256 signed actor tokens to bind guardian identity to HTTP requests. This enables identity-based authentication for the local desktop/mobile channel, paralleling how external channels (Telegram, SMS) use `externalUserId` for guardian identity.
+
+- **Bootstrap**: After hatch, the macOS client calls `POST /v1/integrations/guardian/vellum/bootstrap` with `{ platform, deviceId }`. Returns `{ guardianPrincipalId, actorToken, isNew }`. The endpoint is idempotent -- repeated calls with the same device return the same principal but mint a fresh token (revoking the previous one).
+- **iOS pairing**: The pairing response includes an `actorToken` automatically when a vellum guardian binding exists.
+- **IPC fallback**: Local IPC (Unix socket) connections resolve identity server-side via `resolveLocalIpcGuardianContext()` without requiring an actor token. CLI connections that pass bearer auth but lack an actor token also use this fallback (as long as the request is direct, not proxied through the gateway).
+- **HTTP enforcement**: Vellum HTTP routes require either an `X-Actor-Token` header or a provably-local connection (no `X-Forwarded-For` header). Gateway-proxied requests without an actor token are rejected.
+- **Startup migration**: On daemon start, `ensureVellumGuardianBinding()` backfills a vellum guardian binding for existing installations so the identity system works without requiring a manual bootstrap step.
+
 ## Guardian Verification and Ingress ACL
 
 This section documents the end-to-end flow from guardian verification through ingress membership enforcement, showing how the two systems work together to gate channel access.
@@ -352,18 +362,16 @@ These endpoints share the same business logic as the IPC-based verification flow
 
 ## 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
+Channel readiness is exposed via HTTP control-plane endpoints that provide a unified way to check whether a channel (SMS, Telegram, etc.) is fully configured and operational. Local checks (credential presence, phone number assignment, ingress config) run synchronously; optional remote checks (API reachability) run asynchronously with a 5-minute TTL cache.
 
-| 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. |
+### Channel Readiness HTTP Endpoints
 
-Request fields: `action` (required), `channel` (optional filter), `assistantId` (optional), `includeRemote` (optional boolean).
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/v1/channels/readiness` | Returns readiness snapshots for the specified channel (query param `channel`, optional) or all channels. Local checks always run; remote checks run only when `includeRemote=true` and cache is stale. |
+| POST | `/v1/channels/readiness/refresh` | Invalidates the cache for the specified channel (or all channels), then returns fresh snapshots. Body: `{ channel?: ChannelId, includeRemote?: boolean }` |
 
-Response type: `channel_readiness_response` with `success`, optional `snapshots` array (each with `channel`, `ready`, `checkedAt`, `stale`, `reasons`, `localChecks`, optional `remoteChecks`), and optional `error`.
+All endpoints are bearer-authenticated. Skills and clients should call the gateway URL (default `http://localhost:7830`) rather than the runtime port directly, as the gateway proxies all `/v1/channels/readiness*` routes.
 
 ### Built-in Channel Probes
 
@@ -376,7 +384,7 @@ Response type: `channel_readiness_response` with `success`, optional `snapshots`
 |------|---------|
 | `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 |
+| `src/runtime/routes/channel-readiness-routes.ts` | HTTP route handlers for `/v1/channels/readiness` and `/v1/channels/readiness/refresh` |
 
 ## Ingress Membership + Escalation
 

package/docs/trusted-contact-access.md

@@ -112,6 +112,26 @@ The `assistant_ingress_invites` table supports a parallel invite-based onboardin
 |-------|--------------------------------|
 | `assistant_ingress_invites` | Not used in the guardian-mediated flow. Available as an alternative for direct invite links (e.g., guardian shares a URL instead of going through the approval + verification flow). |
 
+### Voice In-Call Guardian Approval (friend-initiated)
+
+Voice calls have a dedicated in-call guardian approval flow that differs from the text-channel flow. Since the caller is actively on the line, the voice flow captures the caller's name, creates a canonical access request, and holds the call while awaiting the guardian's decision.
+
+**Flow:**
+1. Unknown caller dials in. `relay-server.ts` resolves trust — caller is `unknown`, no pending challenge, no active invite.
+2. Relay enters `awaiting_name` state and prompts the caller for their name (with a timeout).
+3. On name capture, `notifyGuardianOfAccessRequest` creates a canonical guardian request (`kind: 'access_request'`) and notifies the guardian.
+4. Relay transitions to `awaiting_guardian_decision` and polls `canonical_guardian_requests` for status changes.
+5. Guardian approves or denies via any channel. All decisions route through `applyCanonicalGuardianDecision`.
+6. On approval: the `access_request` resolver directly activates the caller as a trusted contact (`upsertMember` with `status: 'active'`, `policy: 'allow'`) — no verification session needed since the caller is already authenticated by their phone number.
+7. On denial or timeout: the caller hears a denial message and the call ends.
+
+**Key difference from text-channel flow:** Voice approvals skip the verification session step because the caller's phone identity is already known from the active call. Text-channel approvals still mint a 6-digit verification code for out-of-band identity confirmation.
+
+| Store | Table | Record |
+|-------|-------|--------|
+| `canonical-guardian-store.ts` | `canonical_guardian_requests` | `kind: 'access_request'`, `status: 'pending'` -> `'approved'` or `'denied'` |
+| `ingress-member-store.ts` | `assistant_ingress_members` | On approval: upserted with `status: 'active'`, `policy: 'allow'` |
+
 ## Sequence Diagram
 
 ```mermaid

package/package.json

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

package/scripts/ipc/generate-swift.ts

@@ -198,6 +198,7 @@ const INT_PATTERNS = [
   /[Ii]ndex$/,
   /[Ee]xpected$/,
   /[Uu]ndos$/,
+  /[Vv]ersion$/,
 ];
 
 function shouldBeInt(propName: string): boolean {

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

@@ -668,22 +668,6 @@ exports[`IPC message snapshots ClientMessage types telegram_config serializes to
 }
 `;
 
-exports[`IPC message snapshots ClientMessage types twilio_config serializes to expected JSON 1`] = `
-{
-  "action": "get",
-  "type": "twilio_config",
-}
-`;
-
-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",
@@ -1157,6 +1141,40 @@ exports[`IPC message snapshots ClientMessage types generate_avatar serializes to
 }
 `;
 
+exports[`IPC message snapshots ClientMessage types guardian_actions_pending_request serializes to expected JSON 1`] = `
+{
+  "conversationId": "conv-guardian-001",
+  "type": "guardian_actions_pending_request",
+}
+`;
+
+exports[`IPC message snapshots ClientMessage types guardian_action_decision serializes to expected JSON 1`] = `
+{
+  "action": "approve_once",
+  "conversationId": "conv-guardian-001",
+  "requestId": "req-guardian-001",
+  "type": "guardian_action_decision",
+}
+`;
+
+exports[`IPC message snapshots ClientMessage types reorder_threads serializes to expected JSON 1`] = `
+{
+  "type": "reorder_threads",
+  "updates": [
+    {
+      "displayOrder": 0,
+      "isPinned": false,
+      "sessionId": "sess-001",
+    },
+    {
+      "displayOrder": 1,
+      "isPinned": true,
+      "sessionId": "sess-002",
+    },
+  ],
+}
+`;
+
 exports[`IPC message snapshots ServerMessage types auth_result serializes to expected JSON 1`] = `
 {
   "success": true,
@@ -1288,6 +1306,30 @@ exports[`IPC message snapshots ServerMessage types confirmation_request serializ
 }
 `;
 
+exports[`IPC message snapshots ServerMessage types confirmation_state_changed serializes to expected JSON 1`] = `
+{
+  "causedByRequestId": "req-003",
+  "decisionText": "approve",
+  "requestId": "req-002",
+  "sessionId": "sess-001",
+  "source": "inline_nl",
+  "state": "approved",
+  "type": "confirmation_state_changed",
+}
+`;
+
+exports[`IPC message snapshots ServerMessage types assistant_activity_state serializes to expected JSON 1`] = `
+{
+  "activityVersion": 1,
+  "anchor": "assistant_turn",
+  "phase": "thinking",
+  "reason": "message_dequeued",
+  "requestId": "req-003",
+  "sessionId": "sess-001",
+  "type": "assistant_activity_state",
+}
+`;
+
 exports[`IPC message snapshots ServerMessage types message_complete serializes to expected JSON 1`] = `
 {
   "attachments": [
@@ -2269,76 +2311,6 @@ 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",
@@ -3122,40 +3094,6 @@ exports[`IPC message snapshots ServerMessage types generate_avatar_response seri
 }
 `;
 
-exports[`IPC message snapshots ClientMessage types guardian_actions_pending_request serializes to expected JSON 1`] = `
-{
-  "conversationId": "conv-guardian-001",
-  "type": "guardian_actions_pending_request",
-}
-`;
-
-exports[`IPC message snapshots ClientMessage types guardian_action_decision serializes to expected JSON 1`] = `
-{
-  "action": "approve_once",
-  "conversationId": "conv-guardian-001",
-  "requestId": "req-guardian-001",
-  "type": "guardian_action_decision",
-}
-`;
-
-exports[`IPC message snapshots ClientMessage types reorder_threads serializes to expected JSON 1`] = `
-{
-  "type": "reorder_threads",
-  "updates": [
-    {
-      "displayOrder": 0,
-      "isPinned": false,
-      "sessionId": "sess-001",
-    },
-    {
-      "displayOrder": 1,
-      "isPinned": true,
-      "sessionId": "sess-002",
-    },
-  ],
-}
-`;
-
 exports[`IPC message snapshots ServerMessage types guardian_actions_pending_response serializes to expected JSON 1`] = `
 {
   "conversationId": "conv-guardian-001",

package/src/__tests__/access-request-decision.test.ts

@@ -31,7 +31,6 @@ mock.module('../util/platform.js', () => ({
   getDbPath: () => join(testDir, 'test.db'),
   getLogPath: () => join(testDir, 'test.log'),
   ensureDataDir: () => {},
-  normalizeAssistantId: (id: string) => id === 'self' ? 'self' : id,
   readHttpToken: () => 'test-bearer-token',
 }));