@vellumai/assistant 0.4.26 → 0.4.30

package/docs/architecture/memory.md

@@ -68,6 +68,17 @@ graph TB
         REPLACE["Replace old messages<br/>with summary in context<br/>(originals stay in DB)"]
     end
 
+    subgraph "Overflow Recovery (context-overflow-reducer.ts)"
+        OVF_PRE["Preflight budget check<br/>estimate > maxInputTokens × (1 − safetyMarginRatio)"]
+        OVF_T1["Tier 1: Forced compaction<br/>force=true, minKeepRecentUserTurns=0"]
+        OVF_T2["Tier 2: Tool-result truncation<br/>4,000 chars per result"]
+        OVF_T3["Tier 3: Media/file stubbing"]
+        OVF_T4["Tier 4: Injection downgrade<br/>→ minimal mode"]
+        OVF_POLICY["Overflow policy resolver<br/>auto_compress / request_approval / fail_gracefully"]
+        OVF_APPROVE["Approval gate<br/>PermissionPrompter"]
+        OVF_DENY["Graceful deny message<br/>(not session_error)"]
+    end
+
     MSG_IN --> STORE
     STORE --> INDEX
     INDEX --> SEGMENT
@@ -120,32 +131,55 @@ graph TB
     COMPACT --> GUARDS
     GUARDS --> SUMMARIZE
     SUMMARIZE --> REPLACE
+
+    %% Overflow recovery flow
+    CTX --> OVF_PRE
+    OVF_PRE --> OVF_T1
+    OVF_T1 --> OVF_T2
+    OVF_T2 --> OVF_T3
+    OVF_T3 --> OVF_T4
+    OVF_T4 --> OVF_POLICY
+    OVF_POLICY -->|"interactive"| OVF_APPROVE
+    OVF_POLICY -->|"non-interactive"| OVF_T1
+    OVF_APPROVE -->|"denied"| OVF_DENY
+    OVF_APPROVE -->|"approved"| OVF_T1
+    OVF_T1 -.->|"uses"| SUMMARIZE
 ```
 
+### Context Compaction and Overflow Recovery Interaction
+
+Normal context compaction (the "Context Window Management" subgraph above) runs proactively as the conversation approaches the token limit, using cooldown guards and a severity-pressure override to balance compaction frequency against cost. This is the primary defense against context overflow.
+
+When compaction alone is insufficient — either because the conversation grew too fast between turns or because a single turn contains extremely large payloads — the overflow recovery pipeline takes over. The pipeline's first tier (forced compaction) reuses the same `maybeCompact()` summarization machinery but with emergency parameters: `force: true` bypasses cooldown guards, `minKeepRecentUserTurns: 0` allows summarizing even the most recent history, and `targetInputTokensOverride` sets a tighter budget. Subsequent tiers (tool-result truncation, media stubbing, injection downgrade) apply progressively more aggressive payload reduction without involving the summarizer.
+
+If all four reducer tiers are exhausted, the overflow policy resolver determines whether to compress the latest user turn. In interactive sessions, the user is prompted for approval before this lossy step. If the user declines, the session emits a graceful assistant explanation message rather than a `session_error`, ending the turn cleanly. Non-interactive sessions auto-compress without prompting.
+
+The key distinction: normal compaction is a cost-optimized background process that preserves conversational quality; overflow recovery is a convergence mechanism that prioritizes session survival over context richness. Both share the same summarization infrastructure but operate under different pressure thresholds and constraints.
+
 ### Memory Retrieval Config Knobs (Defaults)
 
-| Config key | Default | Purpose |
-|---|---:|---|
-| `memory.retrieval.dynamicBudget.enabled` | `true` | Toggle per-turn recall budget calculation from live prompt headroom. |
-| `memory.retrieval.dynamicBudget.minInjectTokens` | `1200` | Lower clamp for computed recall injection budget. |
-| `memory.retrieval.dynamicBudget.maxInjectTokens` | `10000` | Upper clamp for computed recall injection budget. |
-| `memory.retrieval.dynamicBudget.targetHeadroomTokens` | `10000` | Reserved headroom to keep free for response generation/tool traces. |
-| `memory.entity.extractRelations.enabled` | `true` | Enable relation edge extraction and persistence in `memory_entity_relations`. |
-| `memory.entity.extractRelations.backfillBatchSize` | `200` | Batch size for checkpointed `backfill_entity_relations` jobs. |
-| `memory.entity.relationRetrieval.enabled` | `true` | Enable one-hop relation expansion from matched seed entities at recall time. |
-| `memory.entity.relationRetrieval.maxSeedEntities` | `8` | Maximum matched seed entities from the query. |
-| `memory.entity.relationRetrieval.maxNeighborEntities` | `20` | Maximum unique neighbor entities expanded from relation edges. |
-| `memory.entity.relationRetrieval.maxEdges` | `40` | Maximum relation edges traversed during expansion. |
-| `memory.entity.relationRetrieval.neighborScoreMultiplier` | `0.7` | Downweight multiplier for relation-expanded candidates vs direct entity hits. |
-| `memory.conflicts.enabled` | `true` | Enable soft conflict gate for unresolved `memory_item_conflicts`. |
-| `memory.conflicts.reaskCooldownTurns` | `3` | Minimum turn distance before re-asking the same conflict clarification. |
-| `memory.conflicts.resolverLlmTimeoutMs` | `12000` | Timeout bound for clarification resolver LLM fallback. |
-| `memory.conflicts.relevanceThreshold` | `0.3` | Similarity threshold for deciding whether a pending conflict is relevant to the current request. |
-| `memory.conflicts.gateMode` | `'soft'` | Conflict gate strategy. Currently only `'soft'` is supported (asks the user inline). |
-| `memory.conflicts.askOnIrrelevantTurns` | `false` | When `true`, soft-inject irrelevant conflict clarifications into every turn. When `false` (default), only ask when the conflict is topically relevant. |
-| `memory.conflicts.conflictableKinds` | `['preference', 'profile', 'constraint', 'instruction', 'style']` | Memory item kinds eligible for conflict detection. Items with kinds outside this list are auto-dismissed. |
-| `memory.profile.enabled` | `true` | Enable dynamic profile compilation from active trusted profile/preference/constraint/instruction memories. |
-| `memory.profile.maxInjectTokens` | `800` | Hard token cap enforced by `ProfileCompiler` when generating the runtime profile block. |
+| Config key                                                |                                                           Default | Purpose                                                                                                                                                |
+| --------------------------------------------------------- | ----------------------------------------------------------------: | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `memory.retrieval.dynamicBudget.enabled`                  |                                                            `true` | Toggle per-turn recall budget calculation from live prompt headroom.                                                                                   |
+| `memory.retrieval.dynamicBudget.minInjectTokens`          |                                                            `1200` | Lower clamp for computed recall injection budget.                                                                                                      |
+| `memory.retrieval.dynamicBudget.maxInjectTokens`          |                                                           `10000` | Upper clamp for computed recall injection budget.                                                                                                      |
+| `memory.retrieval.dynamicBudget.targetHeadroomTokens`     |                                                           `10000` | Reserved headroom to keep free for response generation/tool traces.                                                                                    |
+| `memory.entity.extractRelations.enabled`                  |                                                            `true` | Enable relation edge extraction and persistence in `memory_entity_relations`.                                                                          |
+| `memory.entity.extractRelations.backfillBatchSize`        |                                                             `200` | Batch size for checkpointed `backfill_entity_relations` jobs.                                                                                          |
+| `memory.entity.relationRetrieval.enabled`                 |                                                            `true` | Enable one-hop relation expansion from matched seed entities at recall time.                                                                           |
+| `memory.entity.relationRetrieval.maxSeedEntities`         |                                                               `8` | Maximum matched seed entities from the query.                                                                                                          |
+| `memory.entity.relationRetrieval.maxNeighborEntities`     |                                                              `20` | Maximum unique neighbor entities expanded from relation edges.                                                                                         |
+| `memory.entity.relationRetrieval.maxEdges`                |                                                              `40` | Maximum relation edges traversed during expansion.                                                                                                     |
+| `memory.entity.relationRetrieval.neighborScoreMultiplier` |                                                             `0.7` | Downweight multiplier for relation-expanded candidates vs direct entity hits.                                                                          |
+| `memory.conflicts.enabled`                                |                                                            `true` | Enable soft conflict gate for unresolved `memory_item_conflicts`.                                                                                      |
+| `memory.conflicts.reaskCooldownTurns`                     |                                                               `3` | Minimum turn distance before re-asking the same conflict clarification.                                                                                |
+| `memory.conflicts.resolverLlmTimeoutMs`                   |                                                           `12000` | Timeout bound for clarification resolver LLM fallback.                                                                                                 |
+| `memory.conflicts.relevanceThreshold`                     |                                                             `0.3` | Similarity threshold for deciding whether a pending conflict is relevant to the current request.                                                       |
+| `memory.conflicts.gateMode`                               |                                                          `'soft'` | Conflict gate strategy. Currently only `'soft'` is supported (asks the user inline).                                                                   |
+| `memory.conflicts.askOnIrrelevantTurns`                   |                                                           `false` | When `true`, soft-inject irrelevant conflict clarifications into every turn. When `false` (default), only ask when the conflict is topically relevant. |
+| `memory.conflicts.conflictableKinds`                      | `['preference', 'profile', 'constraint', 'instruction', 'style']` | Memory item kinds eligible for conflict detection. Items with kinds outside this list are auto-dismissed.                                              |
+| `memory.profile.enabled`                                  |                                                            `true` | Enable dynamic profile compilation from active trusted profile/preference/constraint/instruction memories.                                             |
+| `memory.profile.maxInjectTokens`                          |                                                             `800` | Hard token cap enforced by `ProfileCompiler` when generating the runtime profile block.                                                                |
 
 ### Memory Recall Debugging Playbook
 
@@ -191,13 +225,14 @@ stateDiagram-v2
 ```
 
 Runtime profile flow (per turn):
+
 1. `ProfileCompiler` builds a trusted profile block from active `profile` / `preference` / `constraint` / `instruction` items under strict token cap.
 2. Session injects that block only into runtime prompt state.
 3. Session strips the injected profile block before persisting conversation history, so dynamic profile context never pollutes durable message rows.
 
 ### Provenance-Aware Memory Pipeline
 
-Every persisted message carries provenance metadata (`provenanceTrustClass`, `provenanceSourceChannel`, etc.) derived from the `GuardianRuntimeContext` resolved by `guardian-context-resolver.ts`. This metadata records the trust class of the actor who produced the message and through which channel, enabling downstream trust decisions without re-resolving identity at read time.
+Every persisted message carries provenance metadata (`provenanceTrustClass`, `provenanceSourceChannel`, etc.) derived from the `TrustContext` resolved by `trust-context-resolver.ts`. This metadata records the trust class of the actor who produced the message and through which channel, enabling downstream trust decisions without re-resolving identity at read time.
 
 Two trust gates enforce trust-class-based access control over the memory pipeline:
 
@@ -205,7 +240,7 @@ Two trust gates enforce trust-class-based access control over the memory pipelin
 
 - **Read gate** (`session-memory.ts`): When the current session's actor is untrusted, the memory recall pipeline returns a no-op context — no recall injection, no dynamic profile, no conflict clarification prompts. This ensures untrusted actors cannot surface or exploit previously extracted memory.
 
-Trust policy is **cross-channel and trust-class-based**: decisions use `guardianContext.trustClass`, not the channel string. Desktop/IPC sessions default to `trustClass: 'guardian'`. External channels (Telegram, SMS, WhatsApp, voice) provide explicit guardian context via the resolver. Messages without provenance metadata are treated as trusted (guardian); all new messages carry provenance.
+Trust policy is **cross-channel and trust-class-based**: decisions use `trustContext.trustClass`, not the channel string. Desktop/IPC sessions default to `trustClass: 'guardian'`. External channels (Telegram, SMS, WhatsApp, voice) provide explicit trust context via the resolver. Messages without provenance metadata are treated as trusted (guardian); all new messages carry provenance.
 
 ---
 
@@ -217,10 +252,10 @@ Private threads provide per-conversation memory isolation and stricter tool exec
 
 Two columns on the `conversations` table drive the feature:
 
-| Column | Type | Values | Purpose |
-|---|---|---|---|
-| `thread_type` | `text NOT NULL DEFAULT 'standard'` | `'standard'` or `'private'` | Determines whether the conversation uses shared or isolated memory and permission policies |
-| `memory_scope_id` | `text NOT NULL DEFAULT 'default'` | `'default'` for standard threads; `'private:<uuid>'` for private threads | Scopes all memory writes (items, segments) to this namespace; embeddings are isolated indirectly via their parent item/segment |
+| Column            | Type                               | Values                                                                   | Purpose                                                                                                                        |
+| ----------------- | ---------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
+| `thread_type`     | `text NOT NULL DEFAULT 'standard'` | `'standard'` or `'private'`                                              | Determines whether the conversation uses shared or isolated memory and permission policies                                     |
+| `memory_scope_id` | `text NOT NULL DEFAULT 'default'`  | `'default'` for standard threads; `'private:<uuid>'` for private threads | Scopes all memory writes (items, segments) to this namespace; embeddings are isolated indirectly via their parent item/segment |
 
 ### Memory Isolation
 
@@ -260,9 +295,9 @@ The daemon derives a `SessionMemoryPolicy` from the conversation's `thread_type`
 
 ```typescript
 interface SessionMemoryPolicy {
-  scopeId: string;                // 'default' or 'private:<uuid>'
+  scopeId: string; // 'default' or 'private:<uuid>'
   includeDefaultFallback: boolean; // true for private threads
-  strictSideEffects: boolean;      // true for private threads
+  strictSideEffects: boolean; // true for private threads
 }
 ```
 
@@ -287,17 +322,17 @@ This ensures that file writes, bash commands, host operations, and other mutatin
 
 ### Key Source Files
 
-| File | Role |
-|---|---|
-| `assistant/src/memory/schema.ts` | `conversations` table: `threadType` and `memoryScopeId` column definitions |
-| `assistant/src/daemon/session.ts` | `SessionMemoryPolicy` interface and `DEFAULT_MEMORY_POLICY` constant |
-| `assistant/src/daemon/server.ts` | `deriveMemoryPolicy()` — maps thread type to memory policy |
+| File                                         | Role                                                                                       |
+| -------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| `assistant/src/memory/schema.ts`             | `conversations` table: `threadType` and `memoryScopeId` column definitions                 |
+| `assistant/src/daemon/session.ts`            | `SessionMemoryPolicy` interface and `DEFAULT_MEMORY_POLICY` constant                       |
+| `assistant/src/daemon/server.ts`             | `deriveMemoryPolicy()` — maps thread type to memory policy                                 |
 | `assistant/src/daemon/session-tool-setup.ts` | Propagates `memoryPolicy.strictSideEffects` as `forcePromptSideEffects` into `ToolContext` |
-| `assistant/src/tools/executor.ts` | `forcePromptSideEffects` gate — promotes allow to prompt for side-effect tools |
-| `assistant/src/memory/search/types.ts` | `ScopePolicyOverride` interface for per-call scope control |
-| `assistant/src/memory/retriever.ts` | `buildScopeFilter()` — builds scope ID list from override or global config |
-| `assistant/src/memory/profile-compiler.ts` | Dual-scope profile compilation with `includeDefaultFallback` |
-| `assistant/src/daemon/session-memory.ts` | Wires `scopeId` and `includeDefaultFallback` into recall and profile compilation |
+| `assistant/src/tools/executor.ts`            | `forcePromptSideEffects` gate — promotes allow to prompt for side-effect tools             |
+| `assistant/src/memory/search/types.ts`       | `ScopePolicyOverride` interface for per-call scope control                                 |
+| `assistant/src/memory/retriever.ts`          | `buildScopeFilter()` — builds scope ID list from override or global config                 |
+| `assistant/src/memory/profile-compiler.ts`   | Dual-scope profile compilation with `includeDefaultFallback`                               |
+| `assistant/src/daemon/session-memory.ts`     | Wires `scopeId` and `includeDefaultFallback` into recall and profile compilation           |
 
 ---
 
@@ -354,13 +389,13 @@ The Anthropic provider places `cache_control: { type: 'ephemeral' }` on the **la
 
 ### Key files
 
-| File | Role |
-|------|------|
-| `assistant/src/workspace/top-level-scanner.ts` | Synchronous directory scanner with `MAX_TOP_LEVEL_ENTRIES` cap |
-| `assistant/src/workspace/top-level-renderer.ts` | Renders `TopLevelSnapshot` to `<workspace_top_level>` XML block |
-| `assistant/src/daemon/session-runtime-assembly.ts` | Runtime injections and strip helpers (`<workspace_top_level>`, `<temporal_context>`, `<channel_onboarding_playbook>`, `<onboarding_mode>`) |
-| `assistant/src/onboarding/onboarding-orchestrator.ts` | Builds assistant-owned onboarding runtime guidance from channel playbook + transport metadata |
-| `assistant/src/daemon/session-agent-loop.ts` | Agent loop orchestration, runtime injection wiring, strip chain |
+| File                                                  | Role                                                                                                                                       |
+| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `assistant/src/workspace/top-level-scanner.ts`        | Synchronous directory scanner with `MAX_TOP_LEVEL_ENTRIES` cap                                                                             |
+| `assistant/src/workspace/top-level-renderer.ts`       | Renders `TopLevelSnapshot` to `<workspace_top_level>` XML block                                                                            |
+| `assistant/src/daemon/session-runtime-assembly.ts`    | Runtime injections and strip helpers (`<workspace_top_level>`, `<temporal_context>`, `<channel_onboarding_playbook>`, `<onboarding_mode>`) |
+| `assistant/src/onboarding/onboarding-orchestrator.ts` | Builds assistant-owned onboarding runtime guidance from channel playbook + transport metadata                                              |
+| `assistant/src/daemon/session-agent-loop.ts`          | Agent loop orchestration, runtime injection wiring, strip chain                                                                            |
 
 ---
 
@@ -397,11 +432,11 @@ graph TB
 
 ### Key files
 
-| File | Role |
-|------|------|
-| `assistant/src/daemon/date-context.ts` | `buildTemporalContext()` — generates the `<temporal_context>` XML block |
-| `assistant/src/daemon/session-runtime-assembly.ts` | `injectTemporalContext()` / `stripTemporalContext()` helpers |
-| `assistant/src/daemon/session-agent-loop.ts` | Wiring: computes temporal context, passes to `applyRuntimeInjections`, strips after run |
+| File                                               | Role                                                                                    |
+| -------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| `assistant/src/daemon/date-context.ts`             | `buildTemporalContext()` — generates the `<temporal_context>` XML block                 |
+| `assistant/src/daemon/session-runtime-assembly.ts` | `injectTemporalContext()` / `stripTemporalContext()` helpers                            |
+| `assistant/src/daemon/session-agent-loop.ts`       | Wiring: computes temporal context, passes to `applyRuntimeInjections`, strips after run |
 
 ---
 
@@ -481,9 +516,11 @@ graph TB
     7. `timeout` — the LLM call exceeded `timeoutMs` (AbortController fires)
     8. `provider_error` — the provider threw an exception during the LLM call
     9. `invalid_output` — the LLM returned empty text, the literal string "FALLBACK", or total output > 500 chars
+
     - **Subject line capping**: If the LLM subject line exceeds 72 chars it is deterministically truncated to 72 chars. This is NOT treated as a failure (no breaker penalty, no deterministic fallback).
 
     **Fast model resolution**: The LLM call uses a small/fast model to minimize latency and cost. The model is resolved **before** any provider call as a pre-flight check:
+
     - If `commitMessageLLM.providerFastModelOverrides[provider]` is set, that model is used.
     - Otherwise, a built-in default is used: `anthropic` -> `claude-haiku-4-5-20251001`, `openai` -> `gpt-4o-mini`, `gemini` -> `gemini-2.0-flash`.
     - If the configured provider has no override and no built-in default (e.g., `ollama`, `fireworks`, `openrouter`), the generator returns a deterministic fallback with reason `missing_fast_model` and the provider is never called. To enable LLM commit messages for such providers, set `providerFastModelOverrides[provider]` to the desired model.
@@ -501,16 +538,16 @@ graph TB
 
 ### Key files
 
-| File | Role |
-|------|------|
-| `assistant/src/workspace/git-service.ts` | `WorkspaceGitService`: lazy init, mutex, circuit breaker, `commitIfDirty()`, `getHeadHash()`, `writeNote()`, singleton registry |
-| `assistant/src/workspace/commit-message-provider.ts` | `CommitMessageProvider` interface, `DefaultCommitMessageProvider`, `CommitContext`/`CommitMessageResult` types |
-| `assistant/src/workspace/commit-message-enrichment-service.ts` | `CommitEnrichmentService`: bounded async queue, fire-and-forget enrichment, git notes output |
-| `assistant/src/workspace/turn-commit.ts` | `commitTurnChanges()`: turn-boundary commit with structured metadata + enrichment enqueue |
-| `assistant/src/workspace/provider-commit-message-generator.ts` | `ProviderCommitMessageGenerator`: LLM-based commit message generation with circuit breaker and deterministic fallback |
-| `assistant/src/workspace/heartbeat-service.ts` | `HeartbeatService`: periodic safety-net auto-commits, shutdown commits, enrichment enqueue |
-| `assistant/src/daemon/session-agent-loop.ts` | Integration: turn-boundary commit with `raceWithTimeout` protection in `runAgentLoop` finally block |
-| `assistant/src/daemon/lifecycle.ts` | Integration: `HeartbeatService` start/stop and shutdown commit |
-| `assistant/src/config/schema.ts` | `WorkspaceGitConfigSchema`: timeout, backoff, and enrichment queue configuration |
+| File                                                           | Role                                                                                                                            |
+| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `assistant/src/workspace/git-service.ts`                       | `WorkspaceGitService`: lazy init, mutex, circuit breaker, `commitIfDirty()`, `getHeadHash()`, `writeNote()`, singleton registry |
+| `assistant/src/workspace/commit-message-provider.ts`           | `CommitMessageProvider` interface, `DefaultCommitMessageProvider`, `CommitContext`/`CommitMessageResult` types                  |
+| `assistant/src/workspace/commit-message-enrichment-service.ts` | `CommitEnrichmentService`: bounded async queue, fire-and-forget enrichment, git notes output                                    |
+| `assistant/src/workspace/turn-commit.ts`                       | `commitTurnChanges()`: turn-boundary commit with structured metadata + enrichment enqueue                                       |
+| `assistant/src/workspace/provider-commit-message-generator.ts` | `ProviderCommitMessageGenerator`: LLM-based commit message generation with circuit breaker and deterministic fallback           |
+| `assistant/src/workspace/heartbeat-service.ts`                 | `HeartbeatService`: periodic safety-net auto-commits, shutdown commits, enrichment enqueue                                      |
+| `assistant/src/daemon/session-agent-loop.ts`                   | Integration: turn-boundary commit with `raceWithTimeout` protection in `runAgentLoop` finally block                             |
+| `assistant/src/daemon/lifecycle.ts`                            | Integration: `HeartbeatService` start/stop and shutdown commit                                                                  |
+| `assistant/src/config/schema.ts`                               | `WorkspaceGitConfigSchema`: timeout, backoff, and enrichment queue configuration                                                |
 
 ---

package/docs/error-handling.md

@@ -0,0 +1,71 @@
+# Error Handling Conventions
+
+> Referenced from the root [AGENTS.md](../../AGENTS.md). This is the canonical location for error handling patterns.
+
+Use the right error signaling mechanism for the situation. The codebase has three patterns — pick the one that matches the failure mode:
+
+## 1. Throw for programming errors and unrecoverable failures
+
+Throw an exception (using the error hierarchy from `util/errors.ts`) when:
+
+- A precondition or invariant is violated (indicates a bug in the caller).
+- The failure is unrecoverable and the caller cannot meaningfully continue.
+- An external dependency is completely unavailable and there is no fallback.
+
+Use the existing `VellumError` hierarchy (`ToolError`, `ConfigError`, `ProviderError`, etc.) rather than bare `Error`. This ensures structured error codes propagate to logging and monitoring.
+
+```typescript
+// Good: typed error for a precondition violation
+throw new ConfigError("Missing required provider configuration");
+
+// Good: subagent manager throws when depth limit is exceeded
+throw new AssistantError(
+  "Cannot spawn subagent: parent is itself a subagent",
+  ErrorCode.DAEMON_ERROR
+);
+```
+
+## 2. Result objects for operations that can fail in expected ways
+
+Return a discriminated union or result object when:
+
+- The caller is expected to handle both success and failure paths.
+- The failure is a normal operational outcome, not a bug (e.g., "file not found", "path out of bounds", "ambiguous match").
+
+The codebase uses two result patterns — both are acceptable:
+
+**Discriminated union with `ok` flag** (preferred for new code):
+
+```typescript
+type EditResult =
+  | { ok: true; updatedContent: string }
+  | { ok: false; reason: "not_found" }
+  | { ok: false; reason: "ambiguous"; matchCount: number };
+```
+
+**Content + error flag** (used by tool execution):
+
+```typescript
+interface ToolExecutionResult {
+  content: string;
+  isError: boolean;
+}
+```
+
+Existing examples: `EditEngineResult` in `edit-engine.ts`, `PathResult` in `path-policy.ts`, `ToolExecutionResult` in `tools/types.ts`, `MemoryRecallResult` in `memory/retriever.ts`.
+
+## 3. Never return null/undefined to indicate failure
+
+Do not use `null` or `undefined` as a failure signal. When a function can legitimately fail, use a result object (pattern 2 above) so the caller can distinguish between "no result" and "operation failed, here's why."
+
+Returning `undefined` is acceptable only for **lookup functions** where "not found" is a normal query result rather than a failure — e.g., `Map.get()`, `getState(id): State | undefined`. In these cases, `undefined` means "this entity does not exist," not "something went wrong."
+
+## Where each pattern is used
+
+| Module                                                | Pattern                                                                         | Rationale                                                                                                                      |
+| ----------------------------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| Agent loop (`agent/loop.ts`)                          | Throws + catch-and-emit                                                         | Unrecoverable provider errors break the loop; expected errors (abort, tool-use limits) are caught and emitted as events        |
+| Tool executor (`tools/executor.ts`)                   | Result object (`ToolExecutionResult`)                                           | Tool failures are expected operational outcomes — permission denied, unknown tool, sandbox violations. Never throws to callers |
+| Memory retriever (`memory/retriever.ts`)              | Result object (`MemoryRecallResult`) with degraded/reason fields                | Graceful degradation — embedding failures, search failures degrade quality without crashing                                    |
+| Filesystem tools (`path-policy.ts`, `edit-engine.ts`) | Discriminated union (`{ ok, reason }`)                                          | Validation outcomes that the caller must handle (out of bounds, not found, ambiguous)                                          |
+| Subagent manager (`subagent/manager.ts`)              | Throws for precondition violations, string literal unions for expected outcomes | Depth limit exceeded is a bug; `sendMessage` returns `'not_found' \| 'terminal' \| 'queue_full'` as expected states            |

package/docs/runbook-trusted-contacts.md

@@ -1,12 +1,17 @@
 # Trusted Contacts — Operator Runbook
 
-Operational procedures for inspecting, managing, and debugging the trusted contact access flow. All HTTP commands use the gateway API (default `http://localhost:7830`) with bearer authentication.
+Operational procedures for inspecting, managing, and debugging the trusted contact access flow. HTTP commands use the assistant runtime API (default `http://localhost:7821`) with bearer authentication.
+
+> **Note:** The `/v1/contacts` endpoints are served by the assistant runtime, not
+> the gateway. If you prefer to route through the gateway (`localhost:7830`), set
+> `GATEWAY_RUNTIME_PROXY_ENABLED=true` in the gateway environment — the proxy is
+> disabled by default and these routes will 404 without it.
 
 ## Prerequisites
 
 ```bash
-# Base URL (adjust if using a non-default port)
-BASE=http://localhost:7830
+# Base URL — assistant runtime (adjust if using a non-default port)
+BASE=http://localhost:7821
 
 # Bearer token: if running via the assistant's shell tools, $GATEWAY_AUTH_TOKEN
 # is injected automatically. For manual operator use, mint a token via the CLI
@@ -14,50 +19,74 @@ BASE=http://localhost:7830
 TOKEN=$GATEWAY_AUTH_TOKEN
 ```
 
-## 1. Inspect Trusted Contacts (Members)
+## 1. Inspect Trusted Contacts
 
 ### List all active trusted contacts
 
 ```bash
-curl -s "$BASE/v1/ingress/members?status=active" \
+curl -s "$BASE/v1/contacts?role=contact" \
   -H "Authorization: Bearer $TOKEN" | jq
 ```
 
-### Filter by channel
+### Filter by channel type
 
 ```bash
 # Telegram contacts only
-curl -s "$BASE/v1/ingress/members?sourceChannel=telegram&status=active" \
+curl -s "$BASE/v1/contacts?channelType=telegram" \
   -H "Authorization: Bearer $TOKEN" | jq
 
 # SMS contacts only
-curl -s "$BASE/v1/ingress/members?sourceChannel=sms&status=active" \
+curl -s "$BASE/v1/contacts?channelType=sms" \
   -H "Authorization: Bearer $TOKEN" | jq
 ```
 
-### List all members (including revoked and blocked)
+### List all contacts (including revoked and blocked)
 
 ```bash
-curl -s "$BASE/v1/ingress/members" \
+curl -s "$BASE/v1/contacts" \
   -H "Authorization: Bearer $TOKEN" | jq
 ```
 
+### Via CLI
+
+```bash
+vellum contacts list --role contact
+```
+
 Response shape:
+
 ```json
 {
   "ok": true,
-  "members": [
+  "contacts": [
     {
       "id": "uuid",
-      "sourceChannel": "telegram",
-      "externalUserId": "123456789",
-      "externalChatId": "123456789",
       "displayName": "Alice",
-      "username": "alice_handle",
-      "status": "active",
-      "policy": "allow",
-      "lastSeenAt": 1700000000000,
-      "createdAt": 1699000000000
+      "relationship": "friend",
+      "importance": 0.5,
+      "responseExpectation": null,
+      "preferredTone": null,
+      "lastInteraction": 1700000000000,
+      "interactionCount": 12,
+      "createdAt": 1699000000000,
+      "updatedAt": 1700000000000,
+      "role": "contact",
+      "channels": [
+        {
+          "id": "channel-uuid",
+          "contactId": "uuid",
+          "type": "telegram",
+          "address": "alice_handle",
+          "isPrimary": true,
+          "externalUserId": "123456789",
+          "externalChatId": "123456789",
+          "status": "active",
+          "policy": "allow",
+          "verifiedAt": 1699500000000,
+          "lastSeenAt": 1700000000000,
+          "createdAt": 1699000000000
+        }
+      ]
     }
   ]
 }
@@ -108,29 +137,29 @@ sqlite3 ~/.vellum/workspace/data/db/assistant.db \
 
 ### Via HTTP API
 
-First, find the member's `id` from the list endpoint, then revoke:
+First, find the contact and its channel ID from the list endpoint, then revoke the channel:
 
 ```bash
-# Find the member
-MEMBER_ID=$(curl -s "$BASE/v1/ingress/members?sourceChannel=telegram&status=active" \
-  -H "Authorization: Bearer $TOKEN" | jq -r '.members[] | select(.externalUserId == "TARGET_USER_ID") | .id')
+# Find the contact's channel ID
+CHANNEL_ID=$(curl -s "$BASE/v1/contacts?channelType=telegram" \
+  -H "Authorization: Bearer $TOKEN" | jq -r '.contacts[] | select(.channels[] | select(.externalUserId == "TARGET_USER_ID")) | .channels[] | select(.externalUserId == "TARGET_USER_ID") | .id')
 
 # Revoke with reason
-curl -s -X DELETE "$BASE/v1/ingress/members/$MEMBER_ID" \
+curl -s -X PATCH "$BASE/v1/contacts/channels/$CHANNEL_ID" \
   -H "Authorization: Bearer $TOKEN" \
   -H "Content-Type: application/json" \
-  -d '{"reason": "Revoked by operator"}' | jq
+  -d '{"status": "revoked", "reason": "Revoked by operator"}' | jq
 ```
 
-### Block a member (stronger than revoke)
+### Block a contact channel (stronger than revoke)
 
-Blocking prevents the member from re-entering the flow without explicit unblocking.
+Blocking prevents the contact from re-entering the flow without explicit unblocking.
 
 ```bash
-curl -s -X POST "$BASE/v1/ingress/members/$MEMBER_ID/block" \
+curl -s -X PATCH "$BASE/v1/contacts/channels/$CHANNEL_ID" \
   -H "Authorization: Bearer $TOKEN" \
   -H "Content-Type: application/json" \
-  -d '{"reason": "Blocked by operator"}' | jq
+  -d '{"status": "blocked", "reason": "Blocked by operator"}' | jq
 ```
 
 ### Via SQLite (emergency)
@@ -139,10 +168,10 @@ If the HTTP API is unavailable:
 
 ```bash
 sqlite3 ~/.vellum/workspace/data/db/assistant.db \
-  "UPDATE assistant_ingress_members \
+  "UPDATE contact_channels \
    SET status = 'revoked', revoked_reason = 'Emergency operator revocation', \
    updated_at = $(date +%s)000 \
-   WHERE external_user_id = 'TARGET_USER_ID' AND source_channel = 'telegram';"
+   WHERE external_user_id = 'TARGET_USER_ID' AND type = 'telegram';"
 ```
 
 ## 5. Debug Verification Failures
@@ -182,13 +211,13 @@ sqlite3 ~/.vellum/workspace/data/db/assistant.db \
 
 ### Common verification failure causes
 
-| Symptom | Likely cause | Resolution |
-|---------|-------------|------------|
-| "Invalid or expired code" (correct code) | Identity mismatch: the code was entered from a different user/chat than expected | Verify the requester is using the same account that originally requested access |
-| "Invalid or expired code" (correct code, correct user) | Rate-limited (5+ failures in 15 min window) | Wait 30 minutes or reset rate limits via SQLite |
-| "Invalid or expired code" (old code) | Code TTL expired (10 min) | Guardian must re-approve to generate a new code |
-| Code never delivered to guardian | `deliverChannelReply` failed | Check daemon logs for "Failed to deliver verification code to guardian" |
-| No notification to guardian | No guardian binding for channel | Verify guardian is bound: check `channel_guardian_bindings` table |
+| Symptom                                                | Likely cause                                                                     | Resolution                                                                                                                                 |
+| ------------------------------------------------------ | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| "Invalid or expired code" (correct code)               | Identity mismatch: the code was entered from a different user/chat than expected | Verify the requester is using the same account that originally requested access                                                            |
+| "Invalid or expired code" (correct code, correct user) | Rate-limited (5+ failures in 15 min window)                                      | Wait 30 minutes or reset rate limits via SQLite                                                                                            |
+| "Invalid or expired code" (old code)                   | Code TTL expired (10 min)                                                        | Guardian must re-approve to generate a new code                                                                                            |
+| Code never delivered to guardian                       | `deliverChannelReply` failed                                                     | Check daemon logs for "Failed to deliver verification code to guardian"                                                                    |
+| No notification to guardian                            | No guardian binding for channel                                                  | Verify guardian is bound: check `contacts` table for `role = 'guardian'` with an active `contact_channels` entry matching the channel type |
 
 ## 6. Check Notification Delivery Status
 
@@ -228,35 +257,43 @@ sqlite3 ~/.vellum/workspace/data/db/assistant.db \
 
 ## 7. Manually Add a Trusted Contact (Bypass Verification)
 
-If the verification flow cannot be completed, an operator can directly create an active member:
+If the verification flow cannot be completed, an operator can directly create an active contact:
 
 ```bash
-curl -s -X POST "$BASE/v1/ingress/members" \
+curl -s -X POST "$BASE/v1/contacts" \
   -H "Authorization: Bearer $TOKEN" \
   -H "Content-Type: application/json" \
   -d '{
-    "sourceChannel": "telegram",
-    "externalUserId": "123456789",
-    "externalChatId": "123456789",
     "displayName": "Alice",
-    "policy": "allow",
-    "status": "active"
+    "role": "contact",
+    "channels": [{
+      "type": "telegram",
+      "address": "alice_handle",
+      "externalUserId": "123456789",
+      "externalChatId": "123456789",
+      "status": "active",
+      "policy": "allow"
+    }]
   }' | jq
 ```
 
-For SMS contacts, use the E.164 phone number as the external user/chat ID:
+For SMS contacts, use the E.164 phone number as the address and external user/chat ID:
 
 ```bash
-curl -s -X POST "$BASE/v1/ingress/members" \
+curl -s -X POST "$BASE/v1/contacts" \
   -H "Authorization: Bearer $TOKEN" \
   -H "Content-Type: application/json" \
   -d '{
-    "sourceChannel": "sms",
-    "externalUserId": "+15551234567",
-    "externalChatId": "+15551234567",
     "displayName": "Bob",
-    "policy": "allow",
-    "status": "active"
+    "role": "contact",
+    "channels": [{
+      "type": "sms",
+      "address": "+15551234567",
+      "externalUserId": "+15551234567",
+      "externalChatId": "+15551234567",
+      "status": "active",
+      "policy": "allow"
+    }]
   }' | jq
 ```