@vellumai/assistant 0.3.15 → 0.3.16

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,97 @@ 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:**
+
+The `GET` endpoint reports `connected: true` only when both `hasBotToken` and `hasAppToken` are true. If only one token is stored, a `warning` field describes 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 |
+
 ---
 
 

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

@@ -262,7 +262,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 +274,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 +317,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,252 @@
+# 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 generated at startup and persisted to `~/.vellum/http-token` (mode 0600). 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;
+}
+```
+
+**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 |

package/docs/architecture/memory.md

@@ -366,14 +366,14 @@ The Anthropic provider places `cache_control: { type: 'ephemeral' }` on the **la
 
 ## Temporal Context Injection — Date Grounding
 
-The session injects a `<temporal_context>` block into every user message at runtime, giving the model awareness of the current date, timezone, upcoming weekend/work week windows, and a 14-day horizon of labelled future dates. This enables reliable reasoning about future dates (e.g. "plan a trip for next weekend") without persisting volatile temporal data in conversation history.
+The session injects a `<temporal_context>` block into every user message at runtime, giving the model awareness of the current date, current local time, current UTC time, timezone source metadata, upcoming weekend/work week windows, and a 14-day horizon of labelled future dates. This enables reliable reasoning about future dates (e.g. "plan a trip for next weekend") without persisting volatile temporal data in conversation history.
 
 ### Per-turn flow
 
 ```mermaid
 graph TB
     subgraph "Per-Turn Flow"
-        BUILD["buildTemporalContext(timeZone)<br/>→ compact XML block"]
+        BUILD["buildTemporalContext(timeZone, hostTimeZone, userTimeZone)<br/>→ compact XML block"]
         INJECT["applyRuntimeInjections<br/>prepend temporal block<br/>to user message"]
         AGENT["AgentLoop.run(runMessages)"]
         STRIP["stripTemporalContext<br/>remove block from persisted history"]
@@ -387,7 +387,9 @@ graph TB
 ### Key design decisions
 
 - **Fresh each turn**: `buildTemporalContext()` is called at the start of every agent loop invocation, ensuring the model always sees the current date even in long-running conversations.
-- **Timezone-aware**: Uses `Intl.DateTimeFormat` APIs for DST-safe date arithmetic. The host timezone (`Intl.DateTimeFormat().resolvedOptions().timeZone`) is used by default.
+- **Clock source invariant**: Absolute time (`now`) always comes from the assistant host clock (`Date.now()`), never from channel/client clocks.
+- **Timezone precedence**: If `ui.userTimezone` is configured, temporal context uses it for local-date interpretation. Otherwise it falls back to dynamic profile memory, then assistant host timezone.
+- **Timezone-aware**: Uses `Intl.DateTimeFormat` APIs for DST-safe date arithmetic and timezone validation/canonicalization.
 - **Bounded output**: Hard-capped at 1500 characters and 14 horizon entries to prevent prompt bloat.
 - **Runtime-only**: The injected `<temporal_context>` block is stripped from `this.messages` after the agent loop completes via `stripTemporalContext`. It never persists in conversation history.
 - **Specific strip prefix**: The strip function matches the exact injected prefix (`<temporal_context>\nToday:`) to avoid accidentally removing user-authored text that starts with `<temporal_context>`.
@@ -512,4 +514,3 @@ graph TB
 | `assistant/src/config/schema.ts` | `WorkspaceGitConfigSchema`: timeout, backoff, and enrichment queue configuration |
 
 ---
-

package/docs/architecture/scheduling.md

@@ -91,7 +91,7 @@ The `enforceRoutingIntent()` step runs after the LLM produces a channel selectio
 | Intent | Enforcement Rule |
 |--------|-----------------|
 | `single_channel` | No override. The LLM's channel selection stands. |
-| `multi_channel` | If the LLM selected < 2 channels and 2+ are connected, expand to all connected channels. |
+| `multi_channel` | If the LLM selected < 2 channels and 2+ are connected, expand to at least two connected channels. |
 | `all_channels` | Replace the LLM's selection with all connected channels. |
 
 When enforcement changes the decision, the updated `selectedChannels` and annotated `reasoningSummary` are re-persisted to `notification_decisions` so the audit trail reflects what was actually dispatched.
@@ -189,9 +189,9 @@ graph TD
 
 **Data tables:** `watchers` (config, watermark, status, error tracking) and `watcher_events` (detected events, dedup on `(watcher_id, external_id)`, disposition tracking).
 
-## Task Queue — Queued Task Execution and Review
+## Task Queue — Conversation-Managed Task Execution
 
-The Task Queue builds on top of the existing Tasks system to provide an ordered execution pipeline with human-in-the-loop review.
+The Task Queue provides an ordered execution pipeline with human-in-the-loop review. Task management happens entirely through conversation — the user creates, updates, runs, and reviews tasks by talking to the assistant. There is no standalone Tasks UI window.
 
 ### Terminology
 
@@ -258,19 +258,6 @@ flowchart TD
         DB[(SQLite)]
     end
 
-    subgraph "Daemon IPC Handlers"
-        HC[handleWorkItemCreate]
-        HU[handleWorkItemUpdate]
-        HCo[handleWorkItemComplete]
-        HR[handleWorkItemRunTask]
-        BC[tasks_changed broadcast]
-    end
-
-    subgraph "macOS Client"
-        TW[TasksWindowView]
-        DC[DaemonClient]
-    end
-
     TLA -->|"if_exists check"| DUPE
     DUPE -->|"no match"| WIS
     DUPE -->|"match found → reuse/update"| TLU
@@ -278,81 +265,10 @@ flowchart TD
     RWI --> WIS
     TLS --> WIS
     WIS --> DB
-
-    HC --> WIS
-    HU --> WIS
-    HCo --> WIS
-    HR --> WIS
-    HC --> BC
-    HU --> BC
-    HCo --> BC
-    HR --> BC
-
-    BC -->|"via socket"| DC
-    DC -->|"onTasksChanged"| TW
-    TW -->|"debounced refetch (300ms)"| DC
 ```
 
 **Key behaviors:**
 
+- **Conversation-first management** — All task operations (create, update, run, review, delete) are performed through natural language conversation with the assistant, which invokes the model tools (`task_list_add`, `task_list_update`, `task_list_show`) on the user's behalf.
 - **`task_list_update`** uses `resolveWorkItem` to find the target work item by work item ID, task ID, or title (case-insensitive exact match). When multiple items match by task ID or title, the resolver applies a deterministic tie-break (lowest priority tier, then earliest `createdAt`).
 - **`task_list_add`** has duplicate prevention via the `if_exists` parameter (default: `reuse_existing`). Before creating, it calls `findActiveWorkItemsByTitle` to check for active items with the same title. If a match is found, the tool either returns the existing item (`reuse_existing`), updates it in place (`update_existing`), or proceeds to create a duplicate (`create_duplicate`).
-- **All daemon work-item handlers** (`handleWorkItemCreate`, `handleWorkItemUpdate`, `handleWorkItemComplete`, `handleWorkItemRunTask`) emit a `tasks_changed` broadcast after mutations via `ctx.broadcast({ type: 'tasks_changed' })`. They also emit the more specific `work_item_status_changed` with the affected item's current state.
-- **The macOS Tasks window** (`TasksWindowView`) subscribes to both `tasks_changed` and `work_item_status_changed` callbacks on `DaemonClient`. Both trigger a debounced refetch (300ms) so rapid successive mutations coalesce into a single re-fetch.
-
-### IPC Messages
-
-**Client → Server:**
-
-| Message | Purpose |
-|---------|---------|
-| `work_items_list` | List work items, filterable by status |
-| `work_item_get` | Fetch a single work item with full details |
-| `work_item_create` | Create a new work item pointing to a Task |
-| `work_item_update` | Update title, notes, priority, or sort order |
-| `work_item_complete` | Mark an item as `done` after review |
-| `work_item_run_task` | Trigger execution of a queued work item |
-| `work_item_delete` | Delete a work item from the queue |
-
-**Server → Client (push):**
-
-| Message | Purpose |
-|---------|---------|
-| `work_item_status_changed` | Notify the client when a work item transitions state (includes item snapshot) |
-| `tasks_changed` | Lightweight broadcast after any work-item mutation; triggers client-side refetch |
-
-### Run-Button State Machine
-
-When the user clicks "Run" on a queued work item, the button follows a deterministic state machine:
-
-```
-idle (visible) → in-flight (hidden) → success/failure → re-enabled (via refetch)
-```
-
-**Sequence:**
-
-1. **Idle** — The run button is visible only when `item.status == "queued"`. The `TasksWindowRow` renders it conditionally based on the `WorkItemStatus` enum.
-2. **In-flight** — The client sends `work_item_run_task` with the work item ID. The daemon validates the request, sets the item's status to `running`, and returns `work_item_run_task_response` with `success: true`. It then broadcasts `work_item_status_changed` and `tasks_changed`. The client's debounced refetch picks up the `running` status, which hides the run button and shows a spinner in the status column.
-3. **Completion** — The daemon executes the task asynchronously. On success, the item transitions to `awaiting_review`; on failure, to `failed`. Both trigger another `work_item_status_changed` + `tasks_changed` broadcast, which the client refetches and renders accordingly (showing a "Reviewed" button for `awaiting_review`, or the run button again for `failed` to allow retry).
-
-**Error handling in `work_item_run_task_response`:**
-
-The response includes a typed `errorCode` field (`WorkItemRunTaskErrorCode`) so the client can deterministically decide what to do without parsing error strings:
-
-| `errorCode` | Meaning | Client behavior |
-|-------------|---------|-----------------|
-| `not_found` | Work item does not exist (deleted concurrently) | Refetch removes the stale row |
-| `already_running` | Item is already executing | No-op; status column already shows spinner |
-| `invalid_status` | Item is `done` or `archived` and cannot be run | Refetch updates the row to reflect terminal status |
-| `no_task` | The associated Task template was deleted | Refetch; row may show an error state |
-
-In all error cases, the subsequent `tasks_changed` broadcast triggers a refetch that brings the UI back to a consistent state, so the button is never stuck in a disabled/hidden state without a path to recovery.
-
-### Delete Flow
-
-Deletion uses optimistic UI with rollback:
-
-1. **Optimistic removal** — `TasksWindowViewModel.removeTask()` snapshots the current `items` array, then immediately removes the target item with animation.
-2. **IPC request** — Sends `work_item_delete` with the item ID. The daemon looks up the item; if found, deletes it and responds with `work_item_delete_response { success: true }`, then broadcasts `tasks_changed`.
-3. **Failure rollback** — If the send throws (socket error), the view model restores the snapshot with animation. If the daemon responds with `success: false` (item not found), the `onWorkItemDeleteResponse` callback triggers a full refetch to reconcile.
-