@vellumai/assistant 0.3.15 → 0.3.18

package/ARCHITECTURE.md

@@ -65,6 +65,57 @@ The policy is implemented in `src/tools/guardian-control-plane-policy.ts`, which
 
 The `guardian-verify-setup` skill is the exclusive handler for guardian verification intents in the system prompt. Other skills (e.g., `phone-calls`) hand off to `guardian-verify-setup` rather than orchestrating verification directly.
 
+### Guardian Action Timeout-to-Follow-Up Lifecycle
+
+When a voice call's ASK_GUARDIAN consultation times out before the guardian responds, the system enters a follow-up lifecycle that allows the guardian to act on their late answer after the call has moved on. The entire flow uses LLM-generated copy (never hardcoded user-facing strings) to maintain a natural, conversational tone across voice and text channels.
+
+**Lifecycle stages:**
+
+```
+ ASK_GUARDIAN fires on call
+         |
+         v
+ [pending] -- guardian answers in time --> [answered] (normal flow)
+         |
+         | (timeout expires)
+         v
+ [expired, followup_state=none]
+         |
+         | (guardian replies late)
+         v
+ [expired, followup_state=awaiting_guardian_choice]
+         |
+         | (conversation engine classifies intent)
+         v
+ call_back / message_back / decline
+         |                        |
+         v                        v
+ [dispatching]              [declined] (terminal)
+         |
+         | (executor runs action)
+         v
+ [completed] or [failed] (terminal)
+```
+
+**Generated messaging requirement:** All user-facing copy in the guardian timeout/follow-up path is generated through the `guardian-action-message-composer.ts` composition system, which uses a 2-tier priority chain: (1) daemon-injected LLM generator for natural, varied text; (2) deterministic fallback templates for reliability. No hardcoded user-facing strings exist in the flow files (call-controller, inbound-message-handler, session-process) outside of internal log messages and LLM-instruction prompts. A guard test (`guardian-action-no-hardcoded-copy.test.ts`) enforces this invariant.
+
+**Callback/message-back branch:** When the conversation engine classifies the guardian's intent as `call_back`, the executor starts an outbound call to the counterparty with context about the guardian's answer. When classified as `message_back`, the executor sends an SMS to the counterparty via the gateway's `/deliver/sms` endpoint. The counterparty phone number is resolved from the original call session by call direction (inbound: `fromNumber`; outbound: `toNumber`).
+
+**Key source files:**
+
+| File | Purpose |
+|------|---------|
+| `src/memory/guardian-action-store.ts` | Follow-up state machine with atomic transitions (`startFollowupFromExpiredRequest`, `progressFollowupState`, `finalizeFollowup`) and query helpers for pending/expired/follow-up deliveries |
+| `src/runtime/guardian-action-message-composer.ts` | 2-tier text generation: daemon-injected LLM generator with deterministic fallback templates. Covers all scenarios from timeout acknowledgment through follow-up completion |
+| `src/runtime/guardian-action-conversation-turn.ts` | Follow-up decision engine: classifies guardian replies into `call_back`, `message_back`, `decline`, or `keep_pending` dispositions using LLM tool calling |
+| `src/runtime/guardian-action-followup-executor.ts` | Action dispatch: resolves counterparty from call session, executes `message_back` (SMS via gateway) or `call_back` (outbound call via `startCall`), finalizes follow-up state |
+| `src/daemon/guardian-action-generators.ts` | Daemon-injected generator factories: `createGuardianActionCopyGenerator` (latency-optimized text rewriting) and `createGuardianFollowUpConversationGenerator` (tool-calling intent classification) |
+| `src/calls/call-controller.ts` | Voice timeout handling: marks requests as timed out, sends expiry notices, injects `[GUARDIAN_TIMEOUT]` instruction for generated voice response |
+| `src/runtime/routes/inbound-message-handler.ts` | Late reply interception for Telegram/SMS channels: matches late answers to expired requests, routes follow-up conversation turns, dispatches actions |
+| `src/daemon/session-process.ts` | Late reply interception for mac/IPC channel: same logic as inbound-message-handler but using conversation-ID-based delivery lookup |
+| `src/calls/guardian-action-sweep.ts` | Periodic sweep for stale pending requests; sends expiry notices to guardian destinations |
+| `src/memory/migrations/030-guardian-action-followup.ts` | Schema migration adding follow-up columns (`followup_state`, `late_answer_text`, `late_answered_at`, `followup_action`, `followup_completed_at`) |
+
 ### SMS Channel (Twilio)
 
 The SMS channel provides text-only messaging via Twilio, sharing the same telephony provider as voice calls. It follows the same ingress/egress pattern as Telegram but uses Twilio's HMAC-SHA1 signature validation instead of a secret header.
@@ -134,6 +185,124 @@ These can be set via environment variables or stored in the credential vault (ke
 
 **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.
 
+### Slack Channel (Socket Mode)
+
+The Slack channel provides text-based messaging via Slack's Socket Mode API. Unlike other channels that use HTTP webhooks, Slack uses a persistent WebSocket connection managed by the gateway — no public ingress URL is required. The assistant-side manages credential storage and validation through HTTP config endpoints.
+
+**Control-plane endpoints** (`/v1/integrations/slack/channel/config`):
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/v1/integrations/slack/channel/config` | GET | Returns current config status: `hasBotToken`, `hasAppToken`, `connected`, plus workspace metadata (`teamId`, `teamName`, `botUserId`, `botUsername`) |
+| `/v1/integrations/slack/channel/config` | POST | Validates and stores credentials. Body: `{ botToken?: string, appToken?: string }` |
+| `/v1/integrations/slack/channel/config` | DELETE | Clears all Slack channel credentials from secure storage and credential metadata |
+
+All endpoints are bearer-authenticated via the runtime HTTP token (`~/.vellum/http-token`).
+
+**Credential storage pattern:**
+
+Both tokens are stored in the secure key store (macOS Keychain with encrypted file fallback):
+
+| Secure key | Content |
+|-----------|---------|
+| `credential:slack_channel:bot_token` | Slack bot token (used for `chat.postMessage` and `auth.test`) |
+| `credential:slack_channel:app_token` | Slack app token (`xapp-...`, used for Socket Mode `apps.connections.open`) |
+
+Workspace metadata (team ID, team name, bot user ID, bot username) is stored as JSON in the credential metadata store under `('slack_channel', 'bot_token')`.
+
+**Token validation via `auth.test`:**
+
+When a bot token is provided via `POST /v1/integrations/slack/channel/config`, the handler calls `POST https://slack.com/api/auth.test` with the token before storing it. A successful response yields workspace metadata (`team_id`, `team`, `user_id`, `user`) that is persisted alongside the token. If `auth.test` fails, the token is rejected and not stored.
+
+The app token is validated by format only — it must start with `xapp-`.
+
+**Connection status:**
+
+Both `GET` and `POST` endpoints report `connected: true` only when both `hasBotToken` and `hasAppToken` are true. The `POST` endpoint additionally returns a `warning` field when only one token is stored, describing which token is missing.
+
+**Key source files:**
+
+| File | Purpose |
+|------|---------|
+| `src/daemon/handlers/config-slack-channel.ts` | Business logic for get/set/clear Slack channel config |
+| `src/runtime/routes/integration-routes.ts` | HTTP route handlers for `/v1/integrations/slack/channel/config` |
+
+### Trusted Contact Access (Channel-Agnostic)
+
+External users who are not the guardian can gain access to the assistant through a guardian-mediated verification flow. The flow is channel-agnostic — it works identically on Telegram, SMS, voice, and any future channel.
+
+**Full design doc:** [`docs/trusted-contact-access.md`](docs/trusted-contact-access.md)
+
+**Flow summary:**
+1. Unknown user messages the assistant on any channel.
+2. Ingress ACL (`inbound-message-handler.ts`) rejects the message and emits an `ingress.access_request` notification signal to the guardian.
+3. Guardian approves or denies via callback button or conversational intent (routed through `guardian-approval-interception.ts`).
+4. On approval, an identity-bound verification session with a 6-digit code is created (`access-request-decision.ts` → `channel-guardian-service.ts`).
+5. Guardian gives the code to the requester out-of-band.
+6. Requester enters the code; identity binding is verified, the challenge is consumed, and an active member record is created in `assistant_ingress_members`.
+7. All subsequent messages are accepted through the ingress ACL.
+
+**Channel-agnostic design:** The entire flow operates on abstract `ChannelId` and `externalUserId`/`externalChatId` fields. Identity binding adapts per channel: Telegram uses chat IDs, SMS/voice use E.164 phone numbers, HTTP API uses caller-provided identity. No channel-specific branching exists in the trusted contact code paths.
+
+**Lifecycle states:** `requested → pending_guardian → verification_pending → active | denied | expired`
+
+**Notification signals:** The flow emits signals at each lifecycle transition via `emitNotificationSignal()`:
+- `ingress.access_request` — non-member denied, guardian notified
+- `ingress.trusted_contact.guardian_decision` — guardian approved or denied
+- `ingress.trusted_contact.verification_sent` — code created and delivered
+- `ingress.trusted_contact.activated` — requester verified, member active
+- `ingress.trusted_contact.denied` — guardian explicitly denied
+
+**HTTP API (for management):**
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/v1/ingress/members` | GET | List trusted contacts (filterable by channel, status, policy) |
+| `/v1/ingress/members` | POST | Upsert a member (add/update trusted contact) |
+| `/v1/ingress/members/:id` | DELETE | Revoke a trusted contact |
+| `/v1/ingress/members/:id/block` | POST | Block a member |
+
+**Key source files:**
+
+| File | Purpose |
+|------|---------|
+| `src/runtime/routes/inbound-message-handler.ts` | Ingress ACL, non-member rejection, verification code interception |
+| `src/runtime/routes/access-request-decision.ts` | Guardian decision → verification session creation |
+| `src/runtime/routes/guardian-approval-interception.ts` | Routes guardian decisions (button + conversational) to access request handler |
+| `src/runtime/channel-guardian-service.ts` | Verification challenge lifecycle, identity binding, rate limiting |
+| `src/runtime/routes/ingress-routes.ts` | HTTP API handlers for member/invite management |
+| `src/runtime/ingress-service.ts` | Business logic for member CRUD |
+| `src/memory/ingress-member-store.ts` | Member record persistence |
+| `src/memory/channel-guardian-store.ts` | Approval request and verification challenge persistence |
+| `src/config/vellum-skills/trusted-contacts/SKILL.md` | Skill teaching the assistant to manage contacts via HTTP API |
+
+### Update Bulletin System
+
+Release-driven update notification system that surfaces release notes to the assistant via the system prompt.
+
+**Data flow:**
+1. **Bundled template** (`src/config/templates/UPDATES.md`) — source of release notes, maintained per-release in the repo.
+2. **Startup sync** (`syncUpdateBulletinOnStartup()` in `src/config/update-bulletin.ts`) — materializes the bundled template into the workspace `UPDATES.md` on daemon boot. Uses atomic write (temp + rename) for crash safety.
+3. **System prompt injection** — `buildSystemPrompt()` reads workspace `UPDATES.md` and injects it as a `## Recent Updates` section with judgment-based handling instructions.
+4. **Completion by deletion** — the assistant deletes `UPDATES.md` when it has actioned all updates. Next startup detects the deletion and marks those releases as completed in checkpoint state.
+5. **Cross-release merge** — if pending updates from a prior release exist when a new release lands, both release blocks coexist in the same file.
+
+**Checkpoint keys** (in `memory_checkpoints` table):
+- `updates:active_releases` — JSON array of version strings currently active.
+- `updates:completed_releases` — JSON array of version strings already completed.
+
+**Key source files:**
+
+| File | Purpose |
+|------|---------|
+| `src/config/templates/UPDATES.md` | Bundled release-note template |
+| `src/config/update-bulletin.ts` | Startup sync logic (materialize, delete-complete, merge) |
+| `src/config/update-bulletin-format.ts` | Release block formatter/parser helpers |
+| `src/config/update-bulletin-state.ts` | Checkpoint state helpers for active/completed releases |
+| `src/config/system-prompt.ts` | Prompt injection of updates section |
+| `src/daemon/config-watcher.ts` | File watcher — evicts sessions on UPDATES.md changes |
+| `src/permissions/defaults.ts` | Auto-allow rules for file_read/write/edit + rm UPDATES.md |
+
 ---
 
 
@@ -1401,9 +1570,10 @@ Keep-alive heartbeats (every 30 s by default):
 The notification module (`assistant/src/notifications/`) uses a signal-based architecture where producers emit free-form events and an LLM-backed decision engine determines whether, where, and how to notify the user. See `assistant/src/notifications/README.md` for the full developer guide.
 
 ```
-Producer → NotificationSignal → Decision Engine (LLM) → Deterministic Checks → Broadcaster → Conversation Pairing → Adapters → Delivery
-                                       ↑                                                            ↓
-                               Preference Summary                                    notification_thread_created IPC
+Producer → NotificationSignal → Candidate Generation → Decision Engine (LLM) → Deterministic Checks → Broadcaster → Conversation Pairing → Adapters → Delivery
+                                                              ↑                                                            ↓
+                                                      Preference Summary                                    notification_thread_created IPC
+                                                      Thread Candidates                                     (creation-only — not emitted on reuse)
 ```
 
 ### Channel Policy Registry
@@ -1418,13 +1588,18 @@ Producer → NotificationSignal → Decision Engine (LLM) → Deterministic Chec
 
 Helper functions: `getDeliverableChannels()`, `getChannelPolicy()`, `isNotificationDeliverable()`, `getConversationStrategy()`.
 
-### Conversation Pairing
+### Conversation Pairing and Thread Routing
+
+Every notification delivery materializes a conversation + seed message **before** the adapter sends it (`conversation-pairing.ts`). The pairing function now accepts a `threadAction` from the decision engine:
+
+- **`reuse_existing`**: Looks up the target conversation. If valid (exists with `source: 'notification'`), the seed message is appended to the existing thread. If invalid, falls back to creating a new conversation with `threadDecisionFallbackUsed: true`.
+- **`start_new` (default)**: Creates a fresh conversation per delivery.
 
-Every notification delivery materializes a conversation + seed message **before** the adapter sends it (`conversation-pairing.ts`). This ensures:
+This ensures:
 
 1. Every delivery has an auditable conversation trail in the conversations table
 2. The macOS/iOS client can deep-link directly into the notification thread
-3. Delivery audit rows in `notification_deliveries` carry `conversation_id`, `message_id`, and `conversation_strategy` columns
+3. Delivery audit rows in `notification_deliveries` carry `conversation_id`, `message_id`, `conversation_strategy`, `thread_action`, `thread_target_conversation_id`, and `thread_decision_fallback_used` columns
 
 The pairing function (`pairDeliveryWithConversation`) is resilient — errors are caught and logged without breaking the delivery pipeline.
 
@@ -1435,19 +1610,42 @@ The notification pipeline uses a single conversation materialization path across
 1. **Canonical pipeline** (`emitNotificationSignal` → decision engine → broadcaster → conversation pairing → adapters): The broadcaster pairs each delivery with a conversation, then dispatches a `notification_intent` IPC event via the Vellum adapter. The IPC payload includes `deepLinkMetadata` (e.g. `{ conversationId }`) so the macOS/iOS client can deep-link to the relevant context when the user taps the notification.
 2. **Guardian bookkeeping** (`dispatchGuardianQuestion`): Guardian dispatch creates `guardian_action_request` / `guardian_action_delivery` audit rows derived from pipeline delivery results and the per-dispatch `onThreadCreated` callback — there is no separate thread-creation path.
 
-### Thread Surfacing via `notification_thread_created` IPC
+### Thread Surfacing via `notification_thread_created` IPC (Creation-Only)
 
-When a vellum notification thread is paired with a conversation (strategy `start_new_conversation`), the broadcaster emits a `notification_thread_created` IPC event **immediately** (before waiting for slower channel deliveries like Telegram). This pushes the thread to the macOS/iOS client so it can display the notification thread in the sidebar and deep-link to it.
+The `notification_thread_created` IPC event is emitted **only when a brand-new conversation is created** by the broadcaster. Reusing an existing thread does not trigger this event — the macOS/iOS client already knows about the conversation from the original creation. This is enforced in `broadcaster.ts` by gating on `pairing.createdNewConversation === true`.
+
+When a new vellum notification thread is created (strategy `start_new_conversation`), the broadcaster emits the IPC event **immediately** (before waiting for slower channel deliveries like Telegram). This pushes the thread to the macOS/iOS client so it can display the notification thread in the sidebar and deep-link to it.
 
 ### IPC Thread-Created Events
 
 Two IPC push events surface new threads in the macOS/iOS client sidebar:
 
-- **`notification_thread_created`** — Emitted by `broadcaster.ts` when a notification delivery creates a vellum conversation (strategy `start_new_conversation`). Payload: `{ conversationId, title, sourceEventName }`.
+- **`notification_thread_created`** — Emitted by `broadcaster.ts` when a notification delivery **creates** a new vellum conversation (strategy `start_new_conversation`, `createdNewConversation: true`). **Not** emitted when a thread is reused. Payload: `{ conversationId, title, sourceEventName }`.
 - **`task_run_thread_created`** — Emitted by `work-item-runner.ts` when a task run creates a conversation. Payload: `{ conversationId, workItemId, title }`.
 
 All events follow the same pattern: the daemon creates a server-side conversation, persists an initial message, and broadcasts the IPC event so the macOS `ThreadManager` can create a visible thread in the sidebar.
 
+### Thread Routing Decision Flow
+
+The decision engine produces per-channel thread actions using a candidate-driven approach:
+
+1. **Candidate generation** (`thread-candidates.ts`): Queries recent notification-sourced conversations (24-hour window, up to 5 per channel) and enriches them with guardian context (pending request counts).
+2. **LLM decision**: The candidate set is serialized into the system prompt. The LLM chooses `start_new` or `reuse_existing` (with a candidate `conversationId`) per channel.
+3. **Strict validation** (`validateThreadActions`): Reuse targets must exist in the candidate set. Invalid targets are downgraded to `start_new`.
+4. **Pairing execution**: `pairDeliveryWithConversation` executes the thread action — appending to an existing conversation on reuse, creating a new one otherwise.
+5. **IPC gating**: `notification_thread_created` fires only on actual creation, not on reuse.
+6. **Audit trail**: Thread actions are persisted in both `notification_decisions.validation_results` and `notification_deliveries` columns (`thread_action`, `thread_target_conversation_id`, `thread_decision_fallback_used`).
+
+### Guardian Multi-Request Disambiguation in Reused Threads
+
+When the decision engine routes multiple guardian questions to the same conversation (via `reuse_existing`), those questions share a single thread. The guardian disambiguates which question they are answering using **request-code prefixes**:
+
+- **Single pending delivery**: Matched automatically (single-match fast path).
+- **Multiple pending deliveries**: The guardian must prefix their reply with the 6-char hex request code (e.g. `A1B2C3 yes, allow it`). Case-insensitive matching.
+- **No match**: A disambiguation message is sent listing all active request codes.
+
+This invariant is enforced identically on mac/vellum (`session-process.ts`), Telegram, and SMS (`inbound-message-handler.ts`). All disambiguation messages are generated through the guardian action message composer (LLM with deterministic fallback).
+
 ### Reminder Routing Metadata
 
 Reminders carry optional `routingIntent` (`single_channel` | `multi_channel` | `all_channels`) and free-form `routingHints` metadata. When a reminder fires, this metadata flows through the notification signal into a post-decision enforcement step (`enforceRoutingIntent()` in `decision-engine.ts`) that overrides the LLM's channel selection to match the requested coverage. This enables single-reminder fanout: one reminder can produce multi-channel delivery without duplicate reminders. See `assistant/docs/architecture/scheduling.md` for the full trigger-time data flow.
@@ -1470,8 +1668,9 @@ Connected channels are resolved at signal emission time: vellum is always includ
 | `assistant/src/notifications/emit-signal.ts` | Single entry point for all producers; orchestrates the full pipeline |
 | `assistant/src/notifications/decision-engine.ts` | LLM-based routing decisions with deterministic fallback |
 | `assistant/src/notifications/deterministic-checks.ts` | Hard invariant checks (dedupe, source-active suppression, channel availability) |
-| `assistant/src/notifications/broadcaster.ts` | Dispatches decisions to channel adapters; emits `notification_thread_created` IPC |
-| `assistant/src/notifications/conversation-pairing.ts` | Materializes conversation + message per delivery based on channel strategy |
+| `assistant/src/notifications/broadcaster.ts` | Dispatches decisions to channel adapters; emits `notification_thread_created` IPC (creation-only) |
+| `assistant/src/notifications/conversation-pairing.ts` | Materializes conversation + message per delivery; executes thread reuse decisions |
+| `assistant/src/notifications/thread-candidates.ts` | Builds per-channel candidate set of recent conversations for the decision engine |
 | `assistant/src/notifications/adapters/macos.ts` | Vellum adapter — broadcasts `notification_intent` via IPC with deep-link metadata |
 | `assistant/src/notifications/adapters/telegram.ts` | Telegram adapter — POSTs to gateway `/deliver/telegram` |
 | `assistant/src/notifications/adapters/sms.ts` | SMS adapter — POSTs to gateway `/deliver/sms` via Twilio Messages API |
@@ -1482,7 +1681,7 @@ Connected channels are resolved at signal emission time: vellum is always includ
 | `assistant/src/config/bundled-skills/messaging/tools/send-notification.ts` | Explicit producer tool for user-requested notifications; emits signals into the same routing pipeline |
 | `assistant/src/calls/guardian-dispatch.ts` | Guardian question dispatch that reuses canonical notification pairing and records guardian delivery bookkeeping from pipeline results |
 
-**Audit trail (SQLite):** `notification_events` → `notification_decisions` → `notification_deliveries` (with `conversation_id`, `message_id`, `conversation_strategy`)
+**Audit trail (SQLite):** `notification_events` → `notification_decisions` (with `threadActions` in validation results) → `notification_deliveries` (with `conversation_id`, `message_id`, `conversation_strategy`, `thread_action`, `thread_target_conversation_id`, `thread_decision_fallback_used`)
 
 **Configuration:** `notifications.decisionModelIntent` in `config.json`.
 

package/Dockerfile

@@ -89,7 +89,7 @@ RUN echo 'Dir::State "/data/dpkg";' > /etc/apt/apt.conf.d/99data-dir && \
 ENV PATH="/data/usr/bin:/data/usr/sbin:${PATH}"
 ENV LD_LIBRARY_PATH="/data/usr/lib:/data/usr/lib/x86_64-linux-gnu:${LD_LIBRARY_PATH}"
 
-USER assistant
+USER root
 
 EXPOSE 3001
 

package/README.md

@@ -50,6 +50,12 @@ cp .env.example .env
 | `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. |
 | `VELLUM_DAEMON_SOCKET` | No | `~/.vellum/vellum.sock` | Override the daemon socket path |
 
+## Update Bulletin
+
+When a release includes relevant updates, the daemon materializes release notes from the bundled `src/config/templates/UPDATES.md` into `~/.vellum/workspace/UPDATES.md` on startup. The assistant uses judgment to surface updates to the user when relevant, and deletes the file when done.
+
+**For release maintainers:** Update `assistant/src/config/templates/UPDATES.md` with release notes before each relevant release. Leave the template empty (or comment-only) for releases with no user/assistant-facing changes.
+
 ## Usage
 
 ### Start the daemon
@@ -262,7 +268,7 @@ The channel guardian service generates verification challenge instructions with
 
 ### Operator Notes
 
-- **Verify command formats:** The `/guardian_verify` command accepts both `/guardian_verify <code>` and `/guardian_verify@BotName <code>` (Telegram appends the bot username in group chats). The handler normalizes both formats automatically.
+- **Verification input format:** Channel verification accepts a bare code reply only (6-digit numeric for identity-bound sessions; 64-char hex for unbound inbound/bootstrap compatibility).
 - **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.
 
@@ -274,9 +280,9 @@ This section documents the end-to-end flow from guardian verification through in
 
 Guardian verification establishes a cryptographic trust binding between a human identity and an `(assistantId, channel)` pair. The flow is:
 
-1. **Challenge creation** — The owner initiates verification from the desktop UI, which sends a `guardian_verify` IPC message (action: `create_challenge`) to the daemon. The daemon generates a random secret (32-byte hex for text channels, 6-digit numeric for voice), hashes it with SHA-256, stores the hash with a 10-minute TTL, and returns the raw secret to the desktop.
-2. **Secret sharing** — The desktop displays the secret and instructs the owner to send `/guardian_verify <secret>` to the bot on the target channel (e.g., Telegram).
-3. **Verification** — When the message arrives at `/channels/inbound`, the handler intercepts the `/guardian_verify` prefix before normal message processing. It hashes the provided secret, looks up a matching pending challenge, validates expiry, and consumes the challenge (preventing replay).
+1. **Challenge creation** — The owner initiates verification from the desktop UI, which sends a guardian-verification IPC message (`create_challenge` action) to the daemon. The daemon generates a random secret (32-byte hex for unbound inbound/bootstrap sessions, 6-digit numeric for identity-bound sessions), hashes it with SHA-256, stores the hash with a 10-minute TTL, and returns the raw secret to the desktop.
+2. **Code sharing** — The desktop displays the code and instructs the owner to reply with that code in the target channel conversation (e.g., Telegram or SMS).
+3. **Verification** — When the message arrives at `/channels/inbound`, the handler intercepts valid verification-code replies before normal message processing. It hashes the provided code, looks up a matching pending challenge, validates expiry, and consumes the challenge (preventing replay).
 4. **Binding** — On success, any existing active binding for the `(assistantId, channel)` pair is revoked, and a new guardian binding is created with the verifier's `externalUserId` and `chatId`. The verifier receives a confirmation message.
 
 Rate limiting protects against brute-force attempts: 5 invalid attempts within 15 minutes trigger a 30-minute lockout per `(assistantId, channel, actor)` tuple. The same generic failure message is returned for both invalid codes and rate-limited attempts to avoid leaking state.
@@ -317,7 +323,7 @@ Guardian verification and ingress membership are complementary but independent s
 |------|---------|
 | `src/runtime/channel-guardian-service.ts` | Challenge lifecycle: `createVerificationChallenge`, `validateAndConsumeChallenge`, `getGuardianBinding`, `isGuardian` |
 | `src/runtime/guardian-context-resolver.ts` | Actor role classification: guardian / non-guardian / unverified_channel |
-| `src/runtime/routes/inbound-message-handler.ts` | Ingress ACL enforcement, `/guardian_verify` command intercept, escalation creation |
+| `src/runtime/routes/inbound-message-handler.ts` | Ingress ACL enforcement, verification-code intercept, escalation creation |
 | `src/memory/ingress-member-store.ts` | Member CRUD: `findMember`, `upsertMember`, `revokeMember`, `blockMember` |
 | `src/memory/ingress-invite-store.ts` | Invite lifecycle: `createInvite`, `redeemInvite` (atomically creates member record) |
 | `src/memory/channel-guardian-store.ts` | Persistence for guardian bindings, verification challenges, and approval requests |

package/docs/architecture/http-token-refresh.md

@@ -0,0 +1,274 @@
+# HTTP Token Refresh Protocol
+
+Design for how the daemon notifies clients of bearer token rotation and how clients recover from stale tokens.
+
+## Current State
+
+The daemon's HTTP bearer token is resolved at startup and persisted to `~/.vellum/http-token` (mode 0600). The startup token resolution order is: (1) the `RUNTIME_PROXY_BEARER_TOKEN` env var if set, (2) the existing token read from `~/.vellum/http-token` if the file is readable and non-empty, (3) a newly generated random token as a last resort. Clients read this file at connection time:
+
+- **macOS (local)**: Reads `~/.vellum/http-token` from disk via `resolveHttpTokenPath()` / `readHttpToken()`. Has direct filesystem access to the token file.
+- **iOS (remote)**: Receives the bearer token during the QR-code pairing flow. The token is stored in the iOS Keychain and used for all subsequent HTTP/SSE requests.
+- **Chrome extension**: User manually pastes the token from `~/.vellum/http-token` into the extension popup.
+
+Token regeneration today (macOS Settings > Connect > Regenerate Bearer Token):
+1. macOS client writes a new random token to `~/.vellum/http-token`.
+2. macOS client kills the daemon process.
+3. The health monitor restarts the daemon, which reads the new token from disk.
+4. macOS client re-reads the token from disk on next health check.
+5. **iOS clients are broken** -- they still hold the old token and get 401s. The only recovery is to re-pair via QR code.
+
+## Problem
+
+When the bearer token is rotated (manually or programmatically), remote clients (iOS, Chrome extension) have no way to learn about the new token. They receive 401 responses and cannot recover without manual re-configuration.
+
+## Design
+
+### 1. SSE Token Rotation Event
+
+When the daemon detects that its bearer token has changed, it emits a `token_rotated` SSE event to all connected clients **before** the old token is invalidated. This gives clients a window to capture the new token and seamlessly reconnect.
+
+**Event format** (delivered as an `AssistantEvent` envelope wrapping a new `ServerMessage` type):
+
+```typescript
+// New ServerMessage variant
+interface TokenRotatedMessage {
+  type: 'token_rotated';
+  newToken: string;     // The replacement bearer token
+  expiresOldAt: number; // Unix timestamp (ms) -- old token stops working after this
+}
+```
+
+**Grace period**: The daemon accepts both old and new tokens for a configurable grace window (default: 30 seconds) after emitting the event. This gives slow clients time to process the event and switch tokens. After the grace period, only the new token is valid.
+
+**Sequence diagram (routine rotation)**:
+
+```mermaid
+sequenceDiagram
+    participant Trigger as Rotation Trigger
+    participant Daemon as Daemon
+    participant SSE as SSE Stream
+    participant Client as iOS / Chrome Client
+
+    Trigger->>Daemon: Rotate token (manual, API, periodic)
+    Daemon->>Daemon: Generate new token, write to ~/.vellum/http-token
+    Daemon->>Daemon: Enter grace period (accept old + new)
+    Daemon->>SSE: Emit token_rotated {newToken, expiresOldAt}
+    SSE->>Client: token_rotated event
+    Client->>Client: Store new token (Keychain / localStorage)
+    Client->>Client: Update Authorization header
+    Client->>Daemon: Reconnect SSE with new token
+    Note over Daemon: Grace period expires
+    Daemon->>Daemon: Reject old token (401)
+```
+
+**Sequence diagram (revocation rotation)**:
+
+```mermaid
+sequenceDiagram
+    participant Trigger as Security Event
+    participant Daemon as Daemon
+    participant SSE as SSE Stream
+    participant Client as iOS / Chrome Client
+
+    Trigger->>Daemon: Rotate token (revoke: true)
+    Daemon->>Daemon: Generate new token, immediately invalidate old token
+    Daemon->>SSE: Terminate all old-token connections
+    Daemon->>Daemon: Write new token to ~/.vellum/http-token
+    Note over SSE: No token_rotated event emitted
+    Client->>Daemon: Next request with old token → 401
+    Client->>Client: Trigger fallback recovery (re-pair / re-read / re-paste)
+```
+
+### 2. Client 401 Recovery (Stale Token Detection)
+
+If a client misses the SSE event (network partition, app backgrounded, SSE disconnected at rotation time), it needs a fallback recovery mechanism.
+
+**401 response handling**:
+
+When a client receives a `401 Unauthorized` response:
+
+1. **macOS (local)**: Re-reads `~/.vellum/http-token` from disk. If the token differs from the in-memory token, updates and retries. This already works implicitly since macOS re-reads the token on most HTTP calls via `resolveLocalDaemonHTTPEndpoint()`.
+
+2. **iOS (remote)**: Cannot read the token file. Must re-pair via QR code. The 401 response triggers the client to surface a "Session expired -- re-pair required" UI prompt. This is the expected behavior when the SSE notification is missed.
+
+3. **Chrome extension**: Surfaces an error message directing the user to paste the new token.
+
+**Retry logic**: Clients should retry at most once after a 401 before surfacing the error UI. This prevents retry storms during legitimate auth failures (wrong token, not just stale).
+
+### 3. Token Rotation Triggers
+
+The token can be rotated via:
+
+| Trigger | Description | Current | Proposed | Mode |
+|---------|-------------|---------|----------|------|
+| Manual (macOS Settings) | User clicks "Regenerate Bearer Token" | Yes (kills daemon) | Graceful rotation via daemon API | Routine |
+| API endpoint | `POST /v1/auth/rotate-token` | No | New endpoint | Routine (default) or Revocation (`revoke: true`) |
+| Periodic rotation | Automatic rotation on a configurable schedule | No | Future consideration | Routine |
+| Security event | Forced rotation after suspicious activity | No | Future consideration | Revocation |
+
+**`POST /v1/auth/rotate-token`** (new endpoint):
+
+Allows programmatic token rotation without restarting the daemon.
+
+Request body (optional): `{ "revoke": boolean }` (default: `false`).
+
+**Routine mode** (`revoke: false`, default):
+1. Generates a new random token.
+2. Writes it to `~/.vellum/http-token`.
+3. Emits the `token_rotated` SSE event with grace period.
+4. Starts accepting both tokens during the grace period.
+5. After grace period, rejects the old token.
+
+**Revocation mode** (`revoke: true`):
+1. Generates a new random token.
+2. Immediately invalidates the old token in memory (no grace period).
+3. Terminates all SSE connections authenticated with the old token.
+4. Writes the new token to `~/.vellum/http-token`.
+5. Does **not** emit `token_rotated` -- the new token is never sent to old-token sessions.
+6. Clients must recover via their platform-specific fallback (re-read from disk, re-pair, or re-paste).
+
+This eliminates the current "kill and restart" approach for token rotation.
+
+### 4. Daemon-Side Implementation
+
+**Grace period token validation**: During routine rotation, `verifyBearerToken()` accepts either the old or new token. The `RuntimeHttpServer` holds both tokens:
+
+```typescript
+// Conceptual extension to RuntimeHttpServer
+private currentToken: string;
+private previousToken: string | null = null;
+private graceDeadline: number | null = null;
+
+// Modified auth check
+private isValidToken(provided: string): boolean {
+  if (verifyBearerToken(provided, this.currentToken)) return true;
+  if (this.previousToken && this.graceDeadline && Date.now() < this.graceDeadline) {
+    return verifyBearerToken(provided, this.previousToken);
+  }
+  return false;
+}
+
+// Rotation has two ordering strategies depending on revoke mode:
+//   - Revocation: invalidate in-memory FIRST (security-critical), then persist.
+//     A disk write failure must never leave a compromised token valid.
+//   - Routine: persist to disk FIRST, then update in-memory state.
+//     A disk write failure aborts rotation — clients keep the old token
+//     rather than being locked out by an in-memory-only switch.
+private rotateToken(revoke: boolean): string {
+  const newToken = generateToken();
+
+  if (revoke) {
+    // Revocation: invalidate the compromised token immediately.
+    // Even if the disk write below fails, the old token is gone from memory.
+    this.currentToken = newToken;
+    this.previousToken = null;
+    this.graceDeadline = null;
+    this.terminateOldTokenSSEConnections();
+    writeTokenToDisk(newToken);
+  } else {
+    // Routine: persist to disk first — if this throws, auth state is untouched
+    writeTokenToDisk(newToken);
+    this.previousToken = this.currentToken;
+    this.currentToken = newToken;
+    this.graceDeadline = Date.now() + GRACE_PERIOD_MS;
+    this.emitTokenRotatedEvent(newToken, this.graceDeadline);
+  }
+  return newToken;
+}
+```
+
+**Failure semantics — routine vs. revocation**:
+
+The two rotation modes have deliberately different failure ordering to match their security requirements:
+
+| | Routine (`revoke: false`) | Revocation (`revoke: true`) |
+|---|---|---|
+| **Order** | Persist to disk first, then update in-memory state | Update in-memory state first, then persist to disk |
+| **Disk write failure** | Rotation aborts cleanly — in-memory auth state is untouched, clients keep working with the old token | Old token is already invalidated in memory; the API endpoint returns an error to the caller |
+| **Rationale** | Availability: don't lock out clients if persistence fails | Security: a potentially compromised token must never remain valid, even briefly |
+
+**Revocation disk-write failure in detail**: If `writeTokenToDisk` throws after the in-memory switch during revocation, the system enters a degraded state:
+
+1. **In-memory state**: `currentToken` holds the new (unpersisted) token. The old token is rejected. All old-token SSE connections have been terminated.
+2. **Disk state**: `~/.vellum/http-token` still contains the old (now-invalid) token.
+3. **API response**: The `POST /v1/auth/rotate-token` endpoint returns an error indicating the persistence failure. The response body includes the new token so the caller can manually persist or distribute it if needed.
+4. **Client impact by platform**:
+   - **macOS**: Re-reading the token file yields the stale old token, which is rejected (401). Recovery requires a daemon restart (which generates a fresh token and persists it) or a successful retry of the rotation API call.
+   - **iOS**: Already disconnected (old-token SSE terminated). Cannot recover until the daemon restarts or the rotation is retried successfully, at which point re-pairing is required.
+   - **Chrome extension**: Same as iOS — the pasted token is stale and rejected.
+5. **Daemon restart recovery**: A daemon restart does **not** automatically heal this state. At startup, the daemon first checks for the `RUNTIME_PROXY_BEARER_TOKEN` env var, then tries to read the existing token from `~/.vellum/http-token`, and only generates a new random token if both are unavailable (see `assistant/src/daemon/lifecycle.ts`, lines 110-124). In the degraded state described here — where the disk still holds the old (now-invalid) token — a restart would reload that stale token, making it the active bearer token again. To actually recover, the operator must either: (a) manually delete or overwrite `~/.vellum/http-token` before restarting the daemon, (b) set `RUNTIME_PROXY_BEARER_TOKEN` to a known-good value, or (c) successfully retry the `POST /v1/auth/rotate-token` endpoint while the daemon is still running with the new in-memory token.
+6. **Why this is acceptable**: Revocation is a security-critical operation triggered when the old token is suspected compromised. The invariant — "a compromised token must not remain valid" — takes precedence over client convenience. The degraded state requires manual intervention but disk write failures are rare in practice (permissions, disk full), and the API response includes the new token so the caller can retry or manually persist it.
+
+**SSE event emission** (routine rotation only): The `token_rotated` event is published to `assistantEventHub` as a `ServerMessage`, reaching all connected SSE subscribers across all conversations. This event is never emitted during revocation rotations.
+
+### 5. iOS Client Implementation
+
+**SSE event handler** (in `HTTPTransport`):
+
+```swift
+// In parseSSEData, handle the new message type
+case .tokenRotated(let msg):
+    // Persist the new token to Keychain
+    DaemonConfigStore.shared.updateBearerToken(msg.newToken)
+    // Update in-memory token
+    self.bearerToken = msg.newToken
+    // Reconnect SSE with the new token
+    self.stopSSE()
+    self.startSSE()
+```
+
+**401 response handler**:
+
+```swift
+// In any HTTP request that receives 401
+if http.statusCode == 401 {
+    // Token is stale and we missed the rotation event
+    // Surface re-pairing UI
+    onMessage?(.sessionError(SessionErrorMessage(
+        sessionId: sessionId,
+        code: .authenticationRequired,
+        userMessage: "Session expired. Please re-pair your device.",
+        retryable: false
+    )))
+}
+```
+
+### 6. Security Considerations
+
+- **Rotation modes**: Token rotation has two distinct modes with different security requirements:
+
+  1. **Routine rotation** (manual refresh, periodic schedule): The old token is not compromised -- the goal is seamless credential rollover. The SSE `token_rotated` event delivers the new token to connected clients, and the grace period allows them to transition. This is safe because the SSE channel is authenticated, and any session holding the old token is a legitimate client.
+
+  2. **Revocation rotation** (security event, suspected compromise): The old token may be in the hands of an attacker. In this mode, the daemon **must not** push the replacement token to old-token SSE sessions -- doing so would hand the new credential to the very sessions being revoked. Instead:
+     - The daemon immediately invalidates the old token (no grace period).
+     - All SSE connections authenticated with the old token are terminated.
+     - The `POST /v1/auth/rotate-token` endpoint accepts an optional `revoke: true` flag to select this mode.
+     - Legitimate clients recover via their fallback path: macOS re-reads `~/.vellum/http-token` from disk; iOS prompts for re-pairing; Chrome extension prompts for a new token.
+
+  The `token_rotated` SSE event is only emitted during routine rotations. The rotation trigger determines the mode.
+
+- **Grace period length**: 30 seconds is long enough for clients to process the event but short enough to limit the window where both tokens are valid. Only applies to routine rotations.
+- **No token in logs**: The `token_rotated` event payload must be excluded from any server-side event logging. Use the existing log-redaction patterns.
+- **Constant-time comparison**: The existing `verifyBearerToken()` using `timingSafeEqual` continues to be used for both old and new token checks during the grace period.
+
+### 7. Migration Path
+
+This design is additive and backward-compatible:
+
+1. **Phase 1**: Add `POST /v1/auth/rotate-token` endpoint and `token_rotated` SSE event to the daemon. Update macOS Settings to call the API endpoint instead of kill-and-restart.
+2. **Phase 2**: Add `token_rotated` handler to `HTTPTransport.swift` (shared between macOS and iOS). Add 401 retry-once logic.
+3. **Phase 3** (future): Add periodic rotation and security-event-triggered rotation.
+
+Clients that do not understand the `token_rotated` event will simply ignore it (SSE events with unknown types are safe to skip). They will eventually get 401s after the grace period and fall back to their existing recovery path (re-read from disk for macOS, re-pair for iOS).
+
+## Key Files
+
+| File | Role |
+|------|------|
+| `assistant/src/runtime/http-server.ts` | Auth check, grace period logic, rotation endpoint |
+| `assistant/src/runtime/middleware/auth.ts` | `verifyBearerToken()` -- constant-time token comparison |
+| `assistant/src/runtime/assistant-event.ts` | `AssistantEvent` envelope, SSE framing |
+| `assistant/src/daemon/lifecycle.ts` | Token generation and persistence at startup |
+| `clients/shared/IPC/HTTPDaemonClient.swift` | `HTTPTransport` -- SSE stream, 401 handling |
+| `clients/shared/IPC/DaemonClient.swift` | `readHttpToken()`, `resolveHttpTokenPath()` |
+| `clients/macos/.../SettingsConnectTab.swift` | Manual token regeneration UI |