@vellumai/assistant 0.4.26 → 0.4.29

package/.env.example

@@ -9,11 +9,11 @@ OLLAMA_BASE_URL=
 
 # --- Remote Access ---
 
-# Override the daemon socket path (default: ~/.vellum/vellum.sock).
+# Override the assistant socket path (default: ~/.vellum/vellum.sock).
 # Use this to target a forwarded or remote socket.
 # VELLUM_DAEMON_SOCKET=/path/to/remote/vellum.sock
 
-# Control daemon autostart behavior.
+# Control assistant autostart behavior.
 # When VELLUM_DAEMON_SOCKET is set, autostart is disabled by default.
 # Set to 1 to force autostart even with a custom socket path.
 # VELLUM_DAEMON_AUTOSTART=1

package/AGENTS.md

@@ -0,0 +1,5 @@
+# Assistant Service — Agent Instructions
+
+For error handling conventions (throw vs result objects vs null), see [docs/error-handling.md](docs/error-handling.md).
+
+Subdirectory-scoped rules live in local AGENTS.md files: `src/runtime/`, `src/approvals/`, `src/notifications/`.

package/ARCHITECTURE.md

@@ -14,11 +14,11 @@ This document owns assistant-runtime architecture details. The repo-level archit
 
 ### Guardian Actor Context (Unified Across Channels)
 
-- Guardian/non-guardian/unverified classification is centralized in `assistant/src/runtime/guardian-context-resolver.ts`.
+- Guardian/non-guardian/unverified classification is centralized in `assistant/src/runtime/trust-context-resolver.ts`.
 - The same resolver is used by:
   - `/channels/inbound` (Telegram/SMS/WhatsApp path) before run orchestration.
   - Inbound Twilio voice setup (`RelayConnection.handleSetup`) to seed call-time actor context.
-- Runtime channel runs pass this as `guardianContext`, and session runtime assembly injects `<inbound_actor_context>` (via `inboundActorContextFromGuardian()`) into provider-facing prompts.
+- Runtime channel runs pass this as `trustContext`, and session runtime assembly injects `<inbound_actor_context>` (via `inboundActorContextFromTrustContext()`) into provider-facing prompts.
 - 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.
 
@@ -28,34 +28,34 @@ All HTTP API requests use a single `Authorization: Bearer <jwt>` header for auth
 
 **Token schema (JWT claims):**
 
-| Claim | Type | Description |
-|-------|------|-------------|
-| `iss` | `'vellum-auth'` | Issuer — always `vellum-auth` |
-| `aud` | `'vellum-daemon'` or `'vellum-gateway'` | Audience — which service the token targets |
-| `sub` | string | Subject — encodes principal type and identity (see patterns below) |
-| `scope_profile` | string | Named permission bundle (see profiles below) |
-| `exp` | number | Expiry timestamp (seconds since epoch) |
-| `policy_epoch` | number | Policy version — stale tokens are rejected with `refresh_required` |
-| `iat` | number | Issued-at timestamp |
-| `jti` | string | Unique token ID |
+| Claim           | Type                                    | Description                                                        |
+| --------------- | --------------------------------------- | ------------------------------------------------------------------ |
+| `iss`           | `'vellum-auth'`                         | Issuer — always `vellum-auth`                                      |
+| `aud`           | `'vellum-daemon'` or `'vellum-gateway'` | Audience — which service the token targets                         |
+| `sub`           | string                                  | Subject — encodes principal type and identity (see patterns below) |
+| `scope_profile` | string                                  | Named permission bundle (see profiles below)                       |
+| `exp`           | number                                  | Expiry timestamp (seconds since epoch)                             |
+| `policy_epoch`  | number                                  | Policy version — stale tokens are rejected with `refresh_required` |
+| `iat`           | number                                  | Issued-at timestamp                                                |
+| `jti`           | string                                  | Unique token ID                                                    |
 
 **Subject patterns:**
 
-| Pattern | Principal Type | Description |
-|---------|---------------|-------------|
-| `actor:<assistantId>:<actorPrincipalId>` | `actor` | Desktop, iOS, or CLI client |
-| `svc:gateway:<assistantId>` | `svc_gateway` | Gateway service (ingress, webhooks) |
-| `ipc:<assistantId>:<sessionId>` | `ipc` | Internal IPC connections |
-| `svc:daemon:self` | n/a | Daemon self-identification (for internal use) |
+| Pattern                                  | Principal Type | Description                                   |
+| ---------------------------------------- | -------------- | --------------------------------------------- |
+| `actor:<assistantId>:<actorPrincipalId>` | `actor`        | Desktop, iOS, or CLI client                   |
+| `svc:gateway:<assistantId>`              | `svc_gateway`  | Gateway service (ingress, webhooks)           |
+| `ipc:<assistantId>:<sessionId>`          | `ipc`          | Internal IPC connections                      |
+| `svc:daemon:self`                        | n/a            | Daemon self-identification (for internal use) |
 
 **Scope profiles:**
 
-| Profile | Scopes | Used by |
-|---------|--------|---------|
-| `actor_client_v1` | `chat.{read,write}`, `approval.{read,write}`, `settings.{read,write}`, `attachments.{read,write}`, `calls.{read,write}`, `feature_flags.{read,write}` | Desktop, iOS, CLI clients |
-| `gateway_ingress_v1` | `ingress.write`, `internal.write` | Gateway channel inbound + webhook forwarding |
-| `gateway_service_v1` | `settings.read`, `settings.write`, `internal.write` | Gateway service-to-daemon calls |
-| `ipc_v1` | `ipc.all` | Internal IPC connections |
+| Profile              | Scopes                                                                                                                                                | Used by                                      |
+| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
+| `actor_client_v1`    | `chat.{read,write}`, `approval.{read,write}`, `settings.{read,write}`, `attachments.{read,write}`, `calls.{read,write}`, `feature_flags.{read,write}` | Desktop, iOS, CLI clients                    |
+| `gateway_ingress_v1` | `ingress.write`, `internal.write`                                                                                                                     | Gateway channel inbound + webhook forwarding |
+| `gateway_service_v1` | `settings.read`, `settings.write`, `internal.write`                                                                                                   | Gateway service-to-daemon calls              |
+| `ipc_v1`             | `ipc.all`                                                                                                                                             | Internal IPC connections                     |
 
 **Identity lifecycle:**
 
@@ -75,21 +75,21 @@ All HTTP API requests use a single `Authorization: Bearer <jwt>` header for auth
 
 **Key source files:**
 
-| File | Purpose |
-|------|---------|
-| `src/runtime/auth/types.ts` | Core type definitions: `TokenClaims`, `AuthContext`, `ScopeProfile`, `Scope`, `PrincipalType` |
-| `src/runtime/auth/token-service.ts` | JWT signing, verification, and policy epoch management |
-| `src/runtime/auth/credential-service.ts` | Credential pair minting (access token + refresh token) |
-| `src/runtime/auth/scopes.ts` | Scope profile resolver (`resolveScopeProfile`) |
-| `src/runtime/auth/context.ts` | AuthContext builder from JWT claims |
-| `src/runtime/auth/subject.ts` | Subject string parser (`parseSub`) |
-| `src/runtime/auth/middleware.ts` | JWT bearer auth middleware (`authenticateRequest`) |
-| `src/runtime/auth/route-policy.ts` | Route-level scope/principal enforcement |
-| `src/runtime/routes/guardian-bootstrap-routes.ts` | `POST /v1/integrations/guardian/vellum/bootstrap` (initial JWT issuance) |
-| `src/runtime/routes/guardian-refresh-routes.ts` | `POST /v1/integrations/guardian/vellum/refresh` (token rotation) |
-| `src/runtime/routes/pairing-routes.ts` | JWT credential issuance in pairing flow |
-| `src/runtime/local-actor-identity.ts` | `resolveLocalIpcGuardianContext` — deterministic IPC identity |
-| `src/memory/guardian-bindings.ts` | Guardian binding persistence (shared across all channels) |
+| File                                              | Purpose                                                                                       |
+| ------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `src/runtime/auth/types.ts`                       | Core type definitions: `TokenClaims`, `AuthContext`, `ScopeProfile`, `Scope`, `PrincipalType` |
+| `src/runtime/auth/token-service.ts`               | JWT signing, verification, and policy epoch management                                        |
+| `src/runtime/auth/credential-service.ts`          | Credential pair minting (access token + refresh token)                                        |
+| `src/runtime/auth/scopes.ts`                      | Scope profile resolver (`resolveScopeProfile`)                                                |
+| `src/runtime/auth/context.ts`                     | AuthContext builder from JWT claims                                                           |
+| `src/runtime/auth/subject.ts`                     | Subject string parser (`parseSub`)                                                            |
+| `src/runtime/auth/middleware.ts`                  | JWT bearer auth middleware (`authenticateRequest`)                                            |
+| `src/runtime/auth/route-policy.ts`                | Route-level scope/principal enforcement                                                       |
+| `src/runtime/routes/guardian-bootstrap-routes.ts` | `POST /v1/integrations/guardian/vellum/bootstrap` (initial JWT issuance)                      |
+| `src/runtime/routes/guardian-refresh-routes.ts`   | `POST /v1/integrations/guardian/vellum/refresh` (token rotation)                              |
+| `src/runtime/routes/pairing-routes.ts`            | JWT credential issuance in pairing flow                                                       |
+| `src/runtime/local-actor-identity.ts`             | `resolveLocalIpcGuardianContext` — deterministic IPC identity                                 |
+| `src/memory/channel-guardian-store.ts`            | Guardian binding types and re-exports                                                         |
 
 ### Channel-Agnostic Scoped Approval Grants
 
@@ -113,10 +113,20 @@ All guardian approval decisions — regardless of how they arrive — route thro
 - `approve_always` is downgraded to `approve_once` for guardian-on-behalf requests (guardians cannot permanently allowlist tools for requesters).
 - Scoped grant minting only fires on explicit approve for requests with tool metadata.
 
-**Dual-mode approval UX:** Guardians can respond to approval prompts via two modes, both routing through `applyGuardianDecision`:
+**Unified interaction model — buttons first, text fallback:** All guardian approval prompts follow a canonical "buttons first, text fallback" pattern. Structured button UIs are the primary interaction surface, but every prompt also carries deterministic text fallback instructions so guardians can always act even when buttons are unavailable or not used. This applies uniformly across all request kinds (`tool_approval`, `pending_question`, `access_request`) and all channels (macOS desktop, Telegram, SMS, WhatsApp).
 
-1. **Button UI (deterministic):** Desktop clients and channel adapters render structured `GuardianDecisionPrompt` objects as tappable buttons. Desktop clients use HTTP endpoints (`GET /v1/guardian-actions/pending`, `POST /v1/guardian-actions/decision`) or IPC (`guardian_actions_pending_request`, `guardian_action_decision`). Channel adapters (Telegram inline keyboards, WhatsApp) encode actions in callback data.
-2. **Conversational (NL parsing):** Text replies are classified by the conversational approval engine or parsed by the legacy text parser. The resulting `ApprovalDecisionResult` is passed to `applyGuardianDecision` identically.
+**Button-first path (deterministic):**
+
+- Desktop clients (macOS/iOS) render `GuardianDecisionPrompt` objects as tappable card UIs with kind-aware headers and action buttons. The `GuardianDecisionBubble` renders distinct headers for each kind: "Tool Approval Required", "Question Pending", or "Access Request".
+- Desktop clients submit decisions via HTTP (`POST /v1/guardian-actions/decision`) or IPC (`guardian_action_decision`). Both route through `applyCanonicalGuardianDecision`.
+- Channel adapters (Telegram inline keyboards, WhatsApp) encode actions as callback data (`apr:<requestId>:<action>`).
+
+**Text fallback path (always available):**
+
+- Every prompt includes a `requestCode` (6-char alphanumeric). Guardians can reply with `<requestCode> approve` or `<requestCode> reject` on any channel.
+- `access_request` prompts additionally embed explicit text directives in `questionText`: the request-code approve/reject directive and the `"open invite flow"` phrase for starting the Trusted Contacts invite flow.
+- `pending_question` prompts (voice-originated) support `<requestCode> <your answer>` for free-text answers.
+- The `routeGuardianReply` router processes text replies through a priority-ordered pipeline: callback parsing -> request code parsing -> NL classification. All paths converge on `applyCanonicalGuardianDecision`.
 
 **Shared type system:** `GuardianDecisionPrompt` and `GuardianDecisionAction` (in `src/runtime/guardian-decision-types.ts`) define the structured prompt model. `buildDecisionActions()` computes the action set respecting `persistentDecisionsAllowed` and `forGuardianOnBehalf` flags. `buildPlainTextFallback()` generates parser-compatible text instructions. Channel adapters map these to channel-specific formats via `toApprovalActionOptions()` in `channel-approval-types.ts`.
 
@@ -148,12 +158,12 @@ In addition to persistent trust rules (`always_allow` / `always_deny`), the appr
 
 **Key source files:**
 
-| File | Purpose |
-|------|---------|
+| File                                        | Purpose                                                                                                            |
+| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
 | `src/runtime/session-approval-overrides.ts` | In-memory store: `setThreadMode`, `setTimedMode`, `getEffectiveMode`, `clearMode`, `hasActiveOverride`, `clearAll` |
-| `src/permissions/types.ts` | `UserDecision` type (includes `allow_10m`, `allow_thread`, `temporary_override`), `isAllowDecision()` helper |
-| `src/runtime/guardian-decision-types.ts` | `buildDecisionActions()` — controls which temporary options appear in approval prompts |
-| `src/tools/permission-checker.ts` | Permission pipeline integration — checks temporary overrides before prompting |
+| `src/permissions/types.ts`                  | `UserDecision` type (includes `allow_10m`, `allow_thread`, `temporary_override`), `isAllowDecision()` helper       |
+| `src/runtime/guardian-decision-types.ts`    | `buildDecisionActions()` — controls which temporary options appear in approval prompts                             |
+| `src/tools/permission-checker.ts`           | Permission pipeline integration — checks temporary overrides before prompting                                      |
 
 ### Canonical Guardian Request System
 
@@ -169,9 +179,9 @@ The canonical guardian request system provides a channel-agnostic, unified domai
 
 4. **Deterministic API (prompt listing and decision endpoints):** Desktop clients and API consumers use `GET /v1/guardian-actions/pending` and `POST /v1/guardian-actions/decision` (HTTP) or the equivalent IPC messages. These endpoints surface canonical requests alongside legacy pending interactions and channel approval records, with deduplication to avoid double-rendering.
 
-5. **Dual-mode (deterministic + conversational):** Guardians can respond via structured button UIs (deterministic path) or free-text conversation (NL path). Both paths converge on the same canonical primitive. Code-only messages (just a request code without decision text) return clarification instead of auto-approving. Disambiguation with multiple pending requests stays fail-closed — no auto-resolve when the target is ambiguous.
+5. **Buttons first, text fallback:** All request kinds (`tool_approval`, `pending_question`, `access_request`) are rendered as structured button cards when displayed in macOS/iOS guardian threads. Each prompt also embeds deterministic text fallback instructions (request-code-based approve/reject directives, and for `access_request` the "open invite flow" phrase) so text-based channels and manual fallback always work. Code-only messages (just a request code without decision text) return clarification instead of auto-approving. Disambiguation with multiple pending requests stays fail-closed — no auto-resolve when the target is ambiguous.
 
-**Resolver registry:** Kind-specific resolvers (`src/approvals/guardian-request-resolvers.ts`) handle side effects after CAS resolution. Built-in resolvers: `tool_approval` (channel/desktop approval path) and `pending_question` (voice call question path). New request kinds register resolvers without touching the core primitive.
+**Resolver registry:** Kind-specific resolvers (`src/approvals/guardian-request-resolvers.ts`) handle side effects after CAS resolution. Built-in resolvers: `tool_approval` (channel/desktop approval path), `pending_question` (voice call question path), and `access_request` (trusted-contact verification session creation). New request kinds register resolvers without touching the core primitive.
 
 **Expiry sweeps:** Three complementary sweeps run on 60-second intervals to clean up stale requests:
 
@@ -414,7 +424,7 @@ External users who are not the guardian can gain access to the assistant through
 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`.
+6. Requester enters the code; identity binding is verified, the challenge is consumed, and an active contact channel is created in the contacts table.
 7. All subsequent messages are accepted through the ingress ACL.
 
 **Channel-agnostic design:** The entire flow operates on abstract `ChannelId` and `actorExternalId`/`conversationExternalId` fields (DB column names `externalUserId`/`externalChatId` are unchanged). 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.
@@ -448,9 +458,9 @@ External users who are not the guardian can gain access to the assistant through
 | `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/contacts/contact-store.ts`                        | Contact read queries — lookup, search, list, and channel operations           |
 | `src/memory/channel-guardian-store.ts`                 | Approval request and verification challenge persistence                       |
-| `src/config/bundled-skills/trusted-contacts/SKILL.md`  | Skill teaching the assistant to manage contacts via HTTP API                  |
+| `src/config/bundled-skills/contacts/SKILL.md`          | Unified skill for contact management, access control, and invite links        |
 
 ### Guardian-Initiated Invite Links
 
@@ -461,7 +471,7 @@ A complementary access-granting flow where the guardian proactively creates a sh
 ```
 ┌─────────────────────────────────────────────────────────────┐
 │  Conversational Orchestration (guardian-invite-intent.ts)    │
-│  Pattern-based intent detection → forces trusted-contacts    │
+│  Pattern-based intent detection → forces contacts            │
 │  skill load for create / list / revoke actions               │
 ├─────────────────────────────────────────────────────────────┤
 │  Channel Transport Adapters (channel-invite-transport.ts)    │
@@ -481,7 +491,7 @@ A complementary access-granting flow where the guardian proactively creates a sh
 **Invite link flow (Telegram):**
 
 1. Guardian asks the assistant to create an invite via desktop chat.
-2. `guardian-invite-intent.ts` detects the intent and rewrites the message to force-load the `trusted-contacts` skill.
+2. `guardian-invite-intent.ts` detects the intent and rewrites the message to force-load the `contacts` skill.
 3. The skill calls the ingress HTTP API to create an invite token, then calls the Telegram transport adapter to build a deep link: `https://t.me/<bot>?start=iv_<token>`.
 4. Guardian shares the link with the invitee out-of-band.
 5. Invitee clicks the link, opening Telegram which sends `/start iv_<token>` to the bot.
@@ -537,7 +547,7 @@ Voice invites use a short numeric code (4-10 digits, default 6) instead of a URL
 | `src/runtime/channel-invite-transport.ts`           | Transport adapter registry with `buildShareableInvite` / `extractInboundToken` interface                        |
 | `src/runtime/channel-invite-transports/telegram.ts` | Telegram adapter — `t.me/<bot>?start=iv_<token>` deep links, `/start iv_<token>` extraction                     |
 | `src/runtime/channel-invite-transports/voice.ts`    | Voice transport adapter — code-based redemption metadata                                                        |
-| `src/daemon/guardian-invite-intent.ts`              | Intent detection — routes create/list/revoke requests into the trusted-contacts skill                           |
+| `src/daemon/guardian-invite-intent.ts`              | Intent detection — routes create/list/revoke requests into the contacts skill                                   |
 | `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)                            |
@@ -1103,6 +1113,67 @@ sequenceDiagram
 
 ---
 
+## Context Overflow Recovery
+
+The session loop implements a deterministic overflow convergence pipeline that recovers from context-too-large provider rejections without surfacing errors to the user. Instead of the previous behavior where a `CONTEXT_TOO_LARGE` error was emitted as a `session_error`, the pipeline iteratively reduces the context payload until it fits within the provider's limit.
+
+### Two-Phase Architecture
+
+**Phase 1 — Preflight budgeting:** Before calling the provider, the session loop estimates prompt token count and compares it against a preflight budget (`maxInputTokens * (1 - safetyMarginRatio)`). If the estimate exceeds the budget, the reducer runs proactively, avoiding a wasted provider round-trip. This catches overflow caused by large tool results, media payloads, or accumulated history before any network call.
+
+**Phase 2 — Post-rejection convergence:** If the provider returns a context-too-large error despite preflight checks (e.g., due to estimation inaccuracy), the same reducer runs reactively in a bounded loop, retrying the provider after each tier.
+
+### Tiered Reduction
+
+The reducer (`context-overflow-reducer.ts`) applies four monotonically more aggressive tiers, each idempotent:
+
+| Tier                      | Reduction                                                                  | Effect                                                                                       |
+| ------------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| 1. Forced compaction      | Emergency `maybeCompact()` with `force: true`, `minKeepRecentUserTurns: 0` | Summarizes older history more aggressively than normal compaction                            |
+| 2. Tool-result truncation | `truncateToolResultsAcrossHistory()` at 4,000 chars per result             | Shrinks verbose tool outputs (shell, file reads) across all retained messages                |
+| 3. Media/file stubbing    | `stripMediaPayloadsForRetry()`                                             | Replaces image and file content blocks with lightweight text stubs                           |
+| 4. Injection downgrade    | Sets `injectionMode` to `"minimal"`                                        | Drops runtime injections (workspace listing, temporal context, memory recall) to minimal set |
+
+After each tier, the reducer re-estimates tokens. If the estimate is within budget, the loop breaks and the provider call proceeds. The loop is bounded by `maxAttempts` (default 3).
+
+### Overflow Policy and Latest-Turn Compression
+
+When all four reducer tiers are exhausted and the provider still rejects, the overflow policy resolver (`context-overflow-policy.ts`) determines the next action based on config and session interactivity:
+
+| Session Type    | Config Policy           | Action                                                                                                 |
+| --------------- | ----------------------- | ------------------------------------------------------------------------------------------------------ |
+| Interactive     | `"summarize"` (default) | `request_user_approval` — prompt the user via `PermissionPrompter` before compressing the latest turn  |
+| Non-interactive | `"truncate"` (default)  | `auto_compress_latest_turn` — compress without asking                                                  |
+| Any             | `"drop"`                | `fail_gracefully` — fall through to the final context-overflow fallback, which emits a `session_error` |
+
+**Approval gate:** For interactive sessions, the pipeline uses `requestCompressionApproval()` in `context-overflow-approval.ts`, which presents a confirmation prompt through the existing `PermissionPrompter` flow (`POST /v1/confirm`). The prompt uses a reserved pseudo tool name (`context_overflow_compression`) so the UI can display a meaningful label. The decision is one-shot per overflow (no "always allow" option).
+
+**Deny handling:** If the user declines compression, the session emits a graceful assistant explanation message ("The conversation has grown too long...") instead of a `session_error`. The deny message is persisted to conversation history and delivered via `assistant_text_delta` events, so the user sees a normal chat bubble rather than an error toast. The turn ends cleanly without triggering the error classification pipeline.
+
+### Config
+
+All overflow recovery settings live under `contextWindow.overflowRecovery` in the assistant config schema:
+
+| Config key                            |       Default | Purpose                                                                        |
+| ------------------------------------- | ------------: | ------------------------------------------------------------------------------ |
+| `enabled`                             |        `true` | Master switch for the overflow recovery pipeline                               |
+| `safetyMarginRatio`                   |        `0.05` | Fraction of `maxInputTokens` reserved as safety margin for preflight budget    |
+| `maxAttempts`                         |           `3` | Maximum reducer iterations per overflow event (both preflight and convergence) |
+| `interactiveLatestTurnCompression`    | `"summarize"` | Policy for interactive sessions: `"summarize"`, `"truncate"`, or `"drop"`      |
+| `nonInteractiveLatestTurnCompression` |  `"truncate"` | Policy for non-interactive sessions: same options                              |
+
+### Key Source Files
+
+| File                                      | Purpose                                                                          |
+| ----------------------------------------- | -------------------------------------------------------------------------------- |
+| `src/daemon/context-overflow-reducer.ts`  | Tiered reducer: four-tier pipeline with idempotent steps and cumulative state    |
+| `src/daemon/context-overflow-policy.ts`   | Overflow policy resolver: maps config + interactivity to concrete action         |
+| `src/daemon/context-overflow-approval.ts` | Approval gate: prompts user for latest-turn compression via `PermissionPrompter` |
+| `src/daemon/session-agent-loop.ts`        | Integration: preflight budget check, convergence loop, approval/deny flow        |
+| `src/config/core-schema.ts`               | `ContextOverflowRecoveryConfigSchema` with defaults and validation               |
+
+---
+
 ## Task Routing — Voice Source Bypass and Escalation
 
 When a task is submitted via `task_submit`, the daemon classifies it to determine routing. Voice-sourced tasks and slash command candidates bypass the classifier entirely for lower latency and more predictable routing.
@@ -1333,6 +1404,26 @@ graph LR
 
 Skills can expose custom tools via a `TOOLS.json` manifest alongside their `SKILL.md`. When a skill is activated during a session, its tools are dynamically loaded, registered, and made available to the agent loop. Browser, Gmail, Claude Code, Weather, and other capabilities are delivered as **bundled skills** rather than hardcoded tools. Browser tools (previously the core `headless-browser` tool) are now provided by the bundled `browser` skill with system default allow rules that preserve frictionless auto-approval.
 
+### Bundled Skill Retrieval Contract (CLI-First)
+
+Config/status retrieval instructions in bundled `SKILL.md` files are CLI-first. Retrieval should flow through canonical `vellum` CLI surfaces (`vellum config get` for generic settings, secure credential surfaces for secrets, and domain reads where available) instead of direct gateway curl snippets or keychain lookups.
+
+```mermaid
+graph LR
+    SKILL["SKILL.md retrieval instruction"] --> BASH["bash tool"]
+    BASH --> CLI["vellum config get / secure credential surfaces / domain reads"]
+    CLI --> GW["Gateway read route (when needed)"]
+    GW --> RT["Runtime handler/config service"]
+```
+
+Rules enforced by guard tests:
+
+- Retrieval reads use `bash` + canonical CLI surfaces (`vellum config get` and domain read commands where available).
+- Direct gateway `curl` + manual bearer headers are for control-plane writes/actions, not retrieval reads.
+- Bundled skill docs must not instruct direct keychain lookups (`security find-generic-password`, `secret-tool`) for retrieval.
+- `host_bash` is not used for Vellum CLI retrieval commands unless intentionally allowlisted.
+- Outbound credentialed API calls prefer proxied execution (`bash` with `network_mode: "proxied"` + `credential_ids`) so credentials are injected by policy-aware plumbing instead of copied into commands.
+
 ### Skill Directory Structure
 
 Each skill directory (bundled, managed, workspace, or extra) may contain:
@@ -1987,7 +2078,7 @@ The pairing function (`pairDeliveryWithConversation`) is resilient — errors ar
 
 The notification pipeline uses a single conversation materialization path across producers:
 
-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.
+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, messageId }`) so the macOS/iOS client can deep-link to the relevant context when the user taps the notification. When `messageId` is present, the client scrolls to that specific message within the thread (message-level anchoring).
 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 (Creation-Only)
@@ -2016,6 +2107,15 @@ The decision engine produces per-channel thread actions using a candidate-driven
 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 Call Thread Affinity
+
+When a guardian question originates from an active phone call (`callSessionId` present on the signal), the decision engine enforces thread affinity so all questions within the same call land in one vellum thread:
+
+- **First question in a call** (no `conversationAffinityHint`): `enforceGuardianCallThreadAffinity` forces `start_new` for the vellum channel, creating a dedicated thread for the call.
+- **Subsequent questions in the same call** (affinity hint already set by `dispatchGuardianQuestion`): The guard is a no-op, and `enforceConversationAffinity` routes to `reuse_existing` using the hint's `conversationId`.
+
+This guard runs **before** `enforceConversationAffinity` in the post-decision chain so the two cooperate: the first dispatch creates the thread, and subsequent dispatches reuse it via the affinity hint that `dispatchGuardianQuestion` sets after observing the first delivery's `conversationId`.
+
 ### 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**:
@@ -2034,7 +2134,7 @@ Reminders carry optional `routingIntent` (`single_channel` | `multi_channel` | `
 
 Notifications are delivered to three channel types:
 
-- **Vellum (always connected)**: Local IPC via the daemon's broadcast mechanism. The `VellumAdapter` emits a `notification_intent` message with rendered copy and optional `deepLinkMetadata`.
+- **Vellum (always connected)**: Local IPC via the daemon's broadcast mechanism. The `VellumAdapter` emits a `notification_intent` message with rendered copy and optional `deepLinkMetadata` (includes `conversationId` for thread navigation and `messageId` for message-level scroll anchoring).
 - **Telegram (when guardian binding exists)**: HTTP POST to the gateway's `/deliver/telegram` endpoint. Requires an active guardian binding for the assistant.
 - **SMS (when guardian binding exists)**: HTTP POST to the gateway's `/deliver/sms` endpoint. Follows the same pattern as Telegram; the `SmsAdapter` sends text-only messages via the Twilio Messages API. The `assistantId` is threaded through the delivery payload for multi-assistant phone number resolution.
 
@@ -2122,7 +2222,7 @@ Some tool outputs contain values that must reach the user's final reply but shou
 
 3. **Post-generation substitution** (`src/agent/loop.ts`): Before emitting streamed `text_delta` events and before building the final `assistantMessage`, all placeholders are deterministically replaced with their real values. The substitution is chunk-safe for streaming (buffering partial placeholder prefixes across deltas).
 
-Key files: `src/tools/sensitive-output-placeholders.ts`, `src/tools/executor.ts` (extraction hook), `src/agent/loop.ts` (substitution), `src/config/bundled-skills/trusted-contacts/SKILL.md` (invite flow adoption).
+Key files: `src/tools/sensitive-output-placeholders.ts`, `src/tools/executor.ts` (extraction hook), `src/agent/loop.ts` (substitution), `src/config/bundled-skills/contacts/SKILL.md` (invite flow adoption).
 
 ### Notifications
 
@@ -2145,22 +2245,22 @@ The daemon uses a single fixed internal scope constant — `DAEMON_INTERNAL_ASSI
 
 The guardian trust system uses a three-valued `TrustClass` — `'guardian'`, `'trusted_contact'`, or `'unknown'` — as the single vocabulary for actor trust classification across all channels and runtime paths. There is no legacy `actorRole` concept; all trust decisions flow through `TrustClass`.
 
-**`GuardianRuntimeContext`** (in `src/daemon/session-runtime-assembly.ts`) is the single runtime carrier for trust state on channel-originated turns. It carries `trustClass`, guardian identity fields, and requester metadata. The `guardianPrincipalId` field is typed as `?: string` (optional but non-nullable) — a principal ID is present when a guardian binding exists but is never `null`.
+**`TrustContext`** (in `src/daemon/session-runtime-assembly.ts`) is the single runtime carrier for trust state on channel-originated turns. It carries `trustClass`, guardian identity fields, and requester metadata. The `guardianPrincipalId` field is typed as `?: string` (optional but non-nullable) — a principal ID is present when a guardian binding exists but is never `null`.
 
-**Explicit trust gates:** `guardianTrustClass` is a **required** field in `ToolContext` (in `src/tools/types.ts`). Every tool execution must carry a trust classification — the field is not optional. This ensures trust-gated tool policies (guardian control-plane restrictions, host-tool blocking for untrusted actors) cannot be bypassed by omitting the classification.
+**Explicit trust gates:** `trustClass` is a **required** field in `ToolContext` (in `src/tools/types.ts`). Every tool execution must carry a trust classification — the field is not optional. This ensures trust-gated tool policies (guardian control-plane restrictions, host-tool blocking for untrusted actors) cannot be bypassed by omitting the classification.
 
-**Guardian bindings** (in `src/memory/guardian-bindings.ts`) always carry `guardianPrincipalId: string` as a required, non-null field. A binding without a principal ID is invalid and cannot be created.
+**Guardian bindings** (in `src/memory/channel-guardian-store.ts`) always carry `guardianPrincipalId: string` as a required, non-null field. A binding without a principal ID is invalid and cannot be created.
 
-**Strict retry sweep parsing:** The channel retry sweep (`src/runtime/channel-retry-sweep.ts`) uses `parseGuardianRuntimeContext()` which validates `trustClass` against the canonical three-value set. There is no fallback to a legacy `actorRole` field — stored payloads that lack a valid `trustClass` are rejected deterministically to prevent silent privilege escalation. When `guardianCtx` is entirely absent from a stored payload (pre-guardian events), the sweep synthesizes an explicit `trustClass: 'unknown'` context so that replay never proceeds without a trust classification.
+**Strict retry sweep parsing:** The channel retry sweep (`src/runtime/channel-retry-sweep.ts`) uses `parseTrustRuntimeContext()` which validates `trustClass` against the canonical three-value set. There is no fallback to a legacy `actorRole` field — stored payloads that lack a valid `trustClass` are rejected deterministically to prevent silent privilege escalation. When `trustCtx` is entirely absent from a stored payload (pre-guardian events), the sweep synthesizes an explicit `trustClass: 'unknown'` context so that replay never proceeds without a trust classification.
 
 **Rollout note — legacy `actorRole` payloads:** Previously failed events stored with only `actorRole` (no `trustClass`) will be marked as failed on each retry attempt and eventually dead-lettered after exhausting `RETRY_MAX_ATTEMPTS`. This is an intentional security tradeoff: replaying these events with inferred trust would violate the explicit-trust model. If legacy events need to be recovered, they should be repaired (adding a canonical `trustClass` to the stored payload) before replay via `replayDeadLetters()`.
 
 **Key files:**
 
-| File                                         | Purpose                                                |
-| -------------------------------------------- | ------------------------------------------------------ |
-| `src/daemon/session-runtime-assembly.ts`     | `GuardianRuntimeContext` type definition               |
-| `src/tools/types.ts`                         | `ToolContext.guardianTrustClass` (required trust gate) |
-| `src/runtime/channel-retry-sweep.ts`         | Strict `trustClass` parser for retry sweep             |
-| `src/memory/guardian-bindings.ts`            | `GuardianBinding` with required `guardianPrincipalId`  |
-| `src/__tests__/trust-context-guards.test.ts` | Guard tests enforcing trust-context type invariants    |
+| File                                         | Purpose                                               |
+| -------------------------------------------- | ----------------------------------------------------- |
+| `src/daemon/session-runtime-assembly.ts`     | `TrustContext` type definition                        |
+| `src/tools/types.ts`                         | `ToolContext.trustClass` (required trust gate)        |
+| `src/runtime/channel-retry-sweep.ts`         | Strict `trustClass` parser for retry sweep            |
+| `src/memory/channel-guardian-store.ts`       | `GuardianBinding` with required `guardianPrincipalId` |
+| `src/__tests__/trust-context-guards.test.ts` | Guard tests enforcing trust-context type invariants   |

package/Dockerfile

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