@vellumai/assistant 0.4.26 → 0.4.30

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.
@@ -423,34 +433,36 @@ External users who are not the guardian can gain access to the assistant through
 
 **Notification signals:** The flow emits signals at each lifecycle transition via `emitNotificationSignal()`:
 
-- `ingress.access_request` — non-member denied, guardian notified
+- `ingress.access_request` — unknown contact 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.activated` — requester verified, contact 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                                                |
+| Endpoint                    | Method | Description                                                      |
+| --------------------------- | ------ | ---------------------------------------------------------------- |
+| `/v1/contacts`              | GET    | List contacts (filterable by role, search by query/channel/etc.) |
+| `/v1/contacts`              | POST   | Create or update a contact                                       |
+| `/v1/contacts/:id`          | GET    | Get a contact by ID                                              |
+| `/v1/contacts/merge`        | POST   | Merge two contacts                                               |
+| `/v1/contacts/channels/:id` | PATCH  | Update a contact channel's status/policy                         |
 
 **Key source files:**
 
 | File                                                   | Purpose                                                                       |
 | ------------------------------------------------------ | ----------------------------------------------------------------------------- |
-| `src/runtime/routes/inbound-message-handler.ts`        | Ingress ACL, non-member rejection, verification code interception             |
+| `src/runtime/routes/inbound-message-handler.ts`        | Ingress ACL, unknown-contact 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/runtime/routes/contact-routes.ts`                 | HTTP API handlers for contact and channel management                          |
+| `src/runtime/routes/invite-routes.ts`                  | HTTP API handlers for invite management                                       |
+| `src/runtime/invite-service.ts`                        | Business logic for invite operations                                          |
+| `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 +473,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)    │
@@ -472,7 +484,7 @@ A complementary access-granting flow where the guardian proactively creates a sh
 ├─────────────────────────────────────────────────────────────┤
 │  Core Redemption Engine (invite-redemption-service.ts)       │
 │  Channel-agnostic token validation, expiry, use-count,       │
-│  channel-match enforcement, member creation/reactivation     │
+│  channel-match enforcement, contact activation/reactivation  │
 │  Returns: InviteRedemptionOutcome (discriminated union)      │
 │  Reply templates: invite-redemption-templates.ts             │
 └─────────────────────────────────────────────────────────────┘
@@ -481,17 +493,17 @@ 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.
 6. The gateway forwards the message to `/channels/inbound`. The inbound handler calls `getTransport('telegram').extractInboundToken()` to parse the `iv_` token.
-7. The token is redeemed via `invite-redemption-service.ts`, which validates, creates an active member record, and returns a `redeemed` outcome.
+7. The token is redeemed via `invite-redemption-service.ts`, which validates, activates the contact, and returns a `redeemed` outcome.
 8. A deterministic welcome message is delivered to the invitee (bypasses the LLM pipeline).
 
 **Token prefix convention:** The `iv_` prefix distinguishes invite tokens from `gv_` (guardian verification) tokens. Both use the same Telegram `/start` deep-link mechanism but are routed to different handlers.
 
-**Inbound intercept points:** Invite token extraction runs early in the inbound handler, before ACL denial, so valid invites short-circuit the membership check. Two intercept branches handle: (a) non-members — the invite creates their first member record; (b) inactive members (revoked/pending) — the invite reactivates them.
+**Inbound intercept points:** Invite token extraction runs early in the inbound handler, before ACL denial, so valid invites short-circuit the contact check. Two intercept branches handle: (a) unknown contacts — the invite creates their first contact record; (b) inactive contacts (revoked/pending) — the invite reactivates them.
 
 **Channel adapter status:**
 
@@ -508,8 +520,8 @@ Voice invites use a short numeric code (4-10 digits, default 6) instead of a URL
 
 **Creation flow:**
 
-1. Guardian creates a voice invite via `POST /v1/ingress/invites` with `sourceChannel: "voice"` and `expectedExternalUserId` (E.164 phone).
-2. `ingress-service.ts` generates a cryptographically random numeric code (`generateVoiceCode`), hashes it with SHA-256 (`hashVoiceCode`), and stores only the hash.
+1. Guardian creates a voice invite via `POST /v1/contacts/invites` with `sourceChannel: "voice"` and `expectedExternalUserId` (E.164 phone).
+2. `invite-service.ts` generates a cryptographically random numeric code (`generateVoiceCode`), hashes it with SHA-256 (`hashVoiceCode`), and stores only the hash.
 3. The one-time plaintext `voiceCode` is returned in the creation response. The raw token is NOT returned for voice invites — redemption uses the identity-bound code flow exclusively.
 4. Guardian communicates the code to the invitee out-of-band.
 
@@ -518,7 +530,7 @@ Voice invites use a short numeric code (4-10 digits, default 6) instead of a URL
 1. Unknown caller dials in. `relay-server.ts` resolves trust via `resolveActorTrust`. Caller is `unknown`, no pending guardian challenge.
 2. The relay checks `findActiveVoiceInvites` for invites bound to the caller's phone number.
 3. If active, non-expired invites exist, the relay enters the `invite_redemption_pending` state (reuses the `verification_pending` connection state) and prompts the caller with personalized copy: `Welcome <friend-name>. Please enter the 6-digit code that <guardian-name> provided you to verify your identity.`
-4. `redeemVoiceInviteCode` validates: identity match, code hash match, expiry, use count. On success, an active member record is upserted and the call transitions to the normal call flow.
+4. `redeemVoiceInviteCode` validates: identity match, code hash match, expiry, use count. On success, the contact is activated and the call transitions to the normal call flow.
 5. On invalid/expired code, the caller hears deterministic failure copy: `Sorry, the code you provided is incorrect or has since expired. Please ask <guardian-name> for a new code. Goodbye.` and the call ends immediately.
 
 **Security invariants:**
@@ -526,24 +538,24 @@ Voice invites use a short numeric code (4-10 digits, default 6) instead of a URL
 - The plaintext voice code is returned exactly once at creation time and never stored.
 - Voice invites are identity-bound: `expectedExternalUserId` must match the caller's E.164 number. An attacker with the code but the wrong phone number cannot redeem.
 - Failure responses are intentionally generic (`invalid_or_expired`) to prevent oracle attacks.
-- Blocked members cannot bypass the guardian's explicit block via invite redemption.
+- Blocked contacts cannot bypass the guardian's explicit block via invite redemption.
 
 **Key source files:**
 
-| File                                                | Purpose                                                                                                         |
-| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
-| `src/runtime/invite-redemption-service.ts`          | Core redemption engine — token validation, voice code redemption, member creation, discriminated-union outcomes |
-| `src/runtime/invite-redemption-templates.ts`        | Deterministic reply templates for each redemption outcome                                                       |
-| `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/runtime/ingress-service.ts`                    | Shared business logic for invite/member operations (used by both HTTP routes and IPC)                           |
-| `src/runtime/routes/ingress-routes.ts`              | HTTP API handlers for member/invite management including voice invite creation and redemption                   |
-| `src/runtime/routes/inbound-message-handler.ts`     | Invite token intercept in the inbound flow (non-member and inactive-member branches)                            |
-| `src/calls/relay-server.ts`                         | Voice relay state machine — `invite_redemption_pending` subflow (always-on canonical behavior)                  |
-| `src/util/voice-code.ts`                            | Cryptographic voice code generation and SHA-256 hashing                                                         |
-| `src/memory/ingress-invite-store.ts`                | Invite persistence including `findActiveVoiceInvites` for identity-bound lookup                                 |
+| File                                                | Purpose                                                                                                            |
+| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `src/runtime/invite-redemption-service.ts`          | Core redemption engine — token validation, voice code redemption, contact activation, discriminated-union outcomes |
+| `src/runtime/invite-redemption-templates.ts`        | Deterministic reply templates for each redemption outcome                                                          |
+| `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 contacts skill                                      |
+| `src/runtime/invite-service.ts`                     | Shared business logic for invite operations (used by both HTTP routes and IPC)                                     |
+| `src/runtime/routes/invite-routes.ts`               | HTTP API handlers for invite management including voice invite creation and redemption                             |
+| `src/runtime/routes/inbound-message-handler.ts`     | Invite token intercept in the inbound flow (unknown-contact and inactive-contact branches)                         |
+| `src/calls/relay-server.ts`                         | Voice relay state machine — `invite_redemption_pending` subflow (always-on canonical behavior)                     |
+| `src/util/voice-code.ts`                            | Cryptographic voice code generation and SHA-256 hashing                                                            |
+| `src/memory/invite-store.ts`                        | Invite persistence including `findActiveVoiceInvites` for identity-bound lookup                                    |
 
 ### Voice Inbound Security Model (Canonical)
 
@@ -585,7 +597,7 @@ When no invite exists and no pending guardian challenge is active, the relay ent
 2. On name capture, `notifyGuardianOfAccessRequest` creates a canonical guardian request (`kind: 'access_request'`) and notifies the guardian via the notification pipeline.
 3. The relay transitions to `awaiting_guardian_decision` and plays hold music/messaging while polling the canonical request status.
 4. The guardian approves or denies via any channel (Telegram, SMS, desktop). All decisions route through `applyCanonicalGuardianDecision`, which dispatches to the `access_request` resolver in `guardian-request-resolvers.ts`.
-5. On approval: the resolver directly activates the caller as a trusted contact (upserts member with `status: 'active'`, `policy: 'allow'`), the poll detects the approved status, the relay transitions to the normal call flow with the caller's guardian context updated.
+5. On approval: the resolver directly activates the caller as a trusted contact (sets channel `status: 'active'`, `policy: 'allow'`), the poll detects the approved status, the relay transitions to the normal call flow with the caller's guardian context updated.
 6. On denial or timeout: the caller hears a denial message and the call ends.
 
 **Path 3: Inbound guardian verification (pending challenge)**
@@ -878,7 +890,7 @@ graph LR
         C12["tool_permission_simulate<br/>toolName, input, workingDir?,<br/>isInteractive?, forcePromptSideEffects?,<br/>executionTarget?"]
         C13["conversation_search<br/>query, limit?,<br/>maxMessagesPerConversation?"]
         C14["ingress_invite<br/>create / list / revoke / redeem"]
-        C15["ingress_member<br/>list / upsert / revoke / block"]
+        C15["contacts<br/>list / get / update_channel"]
     end
 
     SOCKET["Unix Socket<br/>~/.vellum/vellum.sock<br/>───────────────<br/>Newline-delimited JSON<br/>Max 96MB per message<br/>Ping/pong every 30s<br/>Auto-reconnect<br/>1s → 30s backoff"]
@@ -910,7 +922,7 @@ graph LR
         S22["tool_permission_simulate_response<br/>decision, riskLevel, reason?,<br/>promptPayload?, matchedRuleId?"]
         S23["conversation_search_response<br/>query, results[]: conversationId,<br/>title, updatedAt, matchingMessages[]"]
         S24["ingress_invite_response<br/>invite / invites"]
-        S25["ingress_member_response<br/>member / members"]
+        S25["contacts_response<br/>contact / contacts"]
     end
 
     C0 --> SOCKET
@@ -1103,6 +1115,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 +1406,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 +2080,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 +2109,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 +2136,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.
 
@@ -2104,8 +2206,8 @@ Connected channels are resolved at signal emission time: vellum is always includ
 | Guardian bindings                            | `~/.vellum/workspace/data/db/assistant.db`                        | SQLite                              | Drizzle ORM                        | Permanent; revoked bindings retained                       |
 | Guardian verification challenges             | `~/.vellum/workspace/data/db/assistant.db`                        | SQLite                              | Drizzle ORM                        | Permanent; consumed/expired challenges retained            |
 | Guardian approval requests                   | `~/.vellum/workspace/data/db/assistant.db`                        | SQLite                              | Drizzle ORM                        | Permanent; decision outcome retained                       |
-| Ingress invites                              | `~/.vellum/workspace/data/db/assistant.db`                        | SQLite                              | Drizzle ORM                        | Permanent; token hash stored, raw token never persisted    |
-| Ingress members                              | `~/.vellum/workspace/data/db/assistant.db`                        | SQLite                              | Drizzle ORM                        | Permanent; revoked/blocked members retained                |
+| Contact invites                              | `~/.vellum/workspace/data/db/assistant.db`                        | SQLite                              | Drizzle ORM                        | Permanent; token hash stored, raw token never persisted    |
+| Contacts & channels                          | `~/.vellum/workspace/data/db/assistant.db`                        | SQLite                              | Drizzle ORM                        | Permanent; revoked/blocked contacts retained               |
 | Notification events                          | `~/.vellum/workspace/data/db/assistant.db`                        | SQLite                              | Drizzle ORM                        | Permanent; deduplicated by dedupeKey                       |
 | Notification decisions                       | `~/.vellum/workspace/data/db/assistant.db`                        | SQLite                              | Drizzle ORM                        | Permanent; FK to notification_events                       |
 | Notification deliveries                      | `~/.vellum/workspace/data/db/assistant.db`                        | SQLite                              | Drizzle ORM                        | Permanent; FK to notification_decisions                    |
@@ -2122,7 +2224,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 +2247,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