@vellumai/assistant 0.4.30 → 0.4.31

package/Dockerfile

@@ -16,16 +16,21 @@ RUN apt-get update && apt-get install -y \
 RUN curl -fsSL https://bun.sh/install | bash
 ENV PATH="/root/.bun/bin:${PATH}"
 
-# Copy package files
-COPY package.json bun.lock ./
+# Install assistant and CLI dependencies first for cache reuse
+COPY assistant/package.json assistant/bun.lock ./assistant/
+RUN cd /app/assistant && bun install --frozen-lockfile
 
-# Install dependencies
-RUN bun install --frozen-lockfile
+COPY cli/package.json cli/bun.lock ./cli/
+RUN cd /app/cli && bun install --frozen-lockfile
+
+# Copy source
+COPY assistant ./assistant
+COPY cli ./cli
 
 # Final stage
 FROM debian:trixie@sha256:3615a749858a1cba49b408fb49c37093db813321355a9ab7c1f9f4836341e9db AS runner
 
-WORKDIR /app
+WORKDIR /app/assistant
 
 # Install runtime dependencies for Playwright and tree-sitter
 RUN apt-get update && apt-get install -y \
@@ -47,6 +52,10 @@ RUN apt-get update && apt-get install -y \
 COPY --from=builder /root/.bun/bin/bun /usr/local/bin/bun
 RUN ln -sf /usr/local/bin/bun /usr/local/bin/bunx
 
+# Install a vellum CLI launcher backed by the bundled local cli package
+RUN printf '#!/usr/bin/env sh\nexec bun run /app/cli/src/index.ts "$@"\n' > /usr/local/bin/vellum && \
+    chmod +x /usr/local/bin/vellum
+
 # Create non-root user that also has sudo access so it can like install stuff
 RUN groupadd --system --gid 1001 assistant && \
     useradd --system --uid 1001 --gid assistant --create-home --shell /bin/bash assistant && \
@@ -95,8 +104,5 @@ ENV IS_CONTAINERIZED=true
 # Copy from builder
 COPY --from=builder /app /app
 
-# Copy source
-COPY . .
-
 # Run the daemon + http server
 CMD ["bun", "run", "src/daemon/main.ts"]

package/README.md

@@ -481,7 +481,7 @@ bun run db:push       # Apply migrations
 
 ```bash
 # Build production image
-docker build -t vellum-assistant:local assistant
+docker build -f assistant/Dockerfile -t vellum-assistant:local .
 
 # Run
 docker run --rm -p 3001:3001 \
@@ -489,7 +489,7 @@ docker run --rm -p 3001:3001 \
   vellum-assistant:local
 ```
 
-The image runs as non-root user `assistant` (uid 1001) and exposes port `3001`.
+The image exposes port `3001` and bundles the `vellum` CLI binary.
 
 ## Troubleshooting
 

package/docs/architecture/memory.md

@@ -41,7 +41,7 @@ graph TB
 
     subgraph "Read Path (Memory Recall)"
         QUERY["Recall Query Builder<br/>User request + compacted context summary"]
-        CONFLICT_GATE["Soft Conflict Gate<br/>dismiss non-actionable conflicts (kind + statement policy)<br/>resolve pending conflicts from user turn<br/>relevance + cooldown + configurable ask behavior"]
+        CONFLICT_GATE["Soft Conflict Gate<br/>dismiss non-actionable conflicts (kind + statement + provenance policy)<br/>attempt internal resolution from user turn<br/>relevance-based; never produces user-facing prompts"]
         PROFILE_BUILD["Dynamic Profile Compiler<br/>active trusted profile memories<br/>user_confirmed > user_reported > assistant_inferred"]
         PROFILE_INJECT["Inject profile context block<br/>into runtime user tail<br/>(strict token cap)"]
         BUDGET["Dynamic Recall Budget<br/>computeRecallBudget()<br/>from prompt headroom"]
@@ -158,28 +158,26 @@ The key distinction: normal compaction is a cost-optimized background process th
 
 ### 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.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 (resolves conflicts internally without user prompts). |
+| `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
 
@@ -211,7 +209,7 @@ The key distinction: normal compaction is a cost-optimized background process th
 stateDiagram-v2
     [*] --> ActiveItems : extract_items/check_contradictions
     ActiveItems --> PendingConflict : ambiguous_contradiction\n(candidate -> pending_clarification)
-    PendingConflict --> PendingConflict : soft gate ask\n(reask cooldown + relevance + askOnIrrelevantTurns)
+    PendingConflict --> PendingConflict : internal evaluation\n(relevance check, no user prompt)
     PendingConflict --> Dismissed : non-actionable\n(kind policy + transient statement filter)
     PendingConflict --> ResolvedKeepExisting : clarification resolver\n+ applyConflictResolution
     PendingConflict --> ResolvedKeepCandidate : clarification resolver\n+ applyConflictResolution
@@ -224,6 +222,10 @@ stateDiagram-v2
     SupersededItems --> CleanupItems : cleanup_stale_superseded_items
 ```
 
+### Internal-Only Conflict Handling
+
+Memory conflict resolution is entirely internal and non-interruptive. The conflict gate evaluates pending conflicts on each turn, dismisses non-actionable ones (based on kind policy, statement eligibility, coherence, and provenance), and attempts resolution when user input looks like a natural clarification. At no point does the conflict system produce user-facing clarification prompts, inject conflict instructions into the assistant's response, or block the user's request. The user is never aware that a conflict exists; the runtime response path always continues answering the user's actual request. This invariant is enforced across the conflict gate (`session-conflict-gate.ts`), session memory (`session-memory.ts`), session agent loop (`session-agent-loop.ts`), and runtime assembly (`session-runtime-assembly.ts`).
+
 Runtime profile flow (per turn):
 
 1. `ProfileCompiler` builds a trusted profile block from active `profile` / `preference` / `constraint` / `instruction` items under strict token cap.
@@ -238,7 +240,7 @@ Two trust gates enforce trust-class-based access control over the memory pipelin
 
 - **Write gate** (`indexer.ts`): The `extract_items` and `resolve_conflicts` jobs only run for messages from trusted actors (guardian or undefined provenance). Messages from untrusted actors (`trusted_contact`, `unknown`) are still segmented and embedded — so they appear in conversation context — but no profile extraction or conflict resolution is triggered. This prevents untrusted channels from injecting or mutating long-term memory items.
 
-- **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.
+- **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 resolution. This ensures untrusted actors cannot surface or exploit previously extracted memory.
 
 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.
 
@@ -381,7 +383,7 @@ graph TB
 - **Prepend, not append**: The workspace block is prepended to the user message content so that Anthropic cache breakpoints continue to land on the trailing user text block, preserving prompt cache efficiency.
 - **Runtime-only**: The injected `<workspace_top_level>` block is stripped from `this.messages` after the agent loop completes. It never persists in conversation history or the database.
 - **Dirty-refresh**: The scanner runs once on the first turn, then only re-runs after a successful mutation tool (`file_edit`, `file_write`, `bash`). Failed tool results do not trigger a refresh.
-- **Injection ordering**: Workspace context is injected after other runtime injections (soft conflict instruction, active surface) via `applyRuntimeInjections`, but because it is **prepended** to content blocks, it appears first in the final message.
+- **Injection ordering**: Workspace context is injected after other runtime injections (active surface, etc.) via `applyRuntimeInjections`, but because it is **prepended** to content blocks, it appears first in the final message.
 
 ### Cache compatibility
 
@@ -506,7 +508,6 @@ graph TB
 10. **Provider-aware commit message generation (optional)**: When `workspaceGit.commitMessageLLM.enabled` is `true`, turn-boundary commits attempt to generate a descriptive commit message using the configured LLM provider before falling back to deterministic messages. The feature ships disabled by default and is designed to never degrade turn completion guarantees.
 
     **Commit message LLM fallback chain**: The generator runs a sequence of pre-flight checks before calling the LLM. Each check that fails produces a machine-readable `llmFallbackReason` in the structured log output and immediately returns a deterministic message. The checks, in order:
-
     1. `disabled` — `commitMessageLLM.enabled` is `false` or `useConfiguredProvider` is `false`
     2. `missing_provider_api_key` — the configured provider's API key is not set in `config.apiKeys` (skipped for keyless providers like Ollama that run without an API key)
     3. `breaker_open` — the generator's internal circuit breaker is open after consecutive LLM failures (exponential backoff)
@@ -516,11 +517,9 @@ 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.

package/docs/runbook-trusted-contacts.md

@@ -62,10 +62,7 @@ Response shape:
     {
       "id": "uuid",
       "displayName": "Alice",
-      "relationship": "friend",
-      "importance": 0.5,
-      "responseExpectation": null,
-      "preferredTone": null,
+      "notes": null,
       "lastInteraction": 1700000000000,
       "interactionCount": 12,
       "createdAt": 1699000000000,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.4.30",
+  "version": "0.4.31",
   "type": "module",
   "bin": {
     "vellum": "./src/index.ts"

package/src/__tests__/commit-message-enrichment-service.test.ts

@@ -42,10 +42,6 @@ describe("CommitEnrichmentService", () => {
   beforeEach(() => {
     _resetGitServiceRegistry();
     _resetEnrichmentService();
-    // Previous tests' enrichment jobs may leave a stale index.lock if
-    // the git process exits but the lock file isn't flushed before the
-    // next test runs git operations in the shared testDir.
-    rmSync(join(testDir, ".git", "index.lock"), { force: true });
   });
 
   afterEach(async () => {

package/src/__tests__/config-schema.test.ts

@@ -168,10 +168,8 @@ describe("AssistantConfigSchema", () => {
     expect(result.memory.conflicts).toEqual({
       enabled: true,
       gateMode: "soft",
-      reaskCooldownTurns: 3,
       resolverLlmTimeoutMs: 12000,
       relevanceThreshold: 0.3,
-      askOnIrrelevantTurns: false,
       conflictableKinds: [
         "preference",
         "profile",
@@ -189,13 +187,6 @@ describe("AssistantConfigSchema", () => {
     expect(result.success).toBe(false);
   });
 
-  test("rejects invalid memory.conflicts.askOnIrrelevantTurns", () => {
-    const result = AssistantConfigSchema.safeParse({
-      memory: { conflicts: { askOnIrrelevantTurns: 123 } },
-    });
-    expect(result.success).toBe(false);
-  });
-
   test("rejects invalid memory.conflicts.conflictableKinds entry", () => {
     const result = AssistantConfigSchema.safeParse({
       memory: { conflicts: { conflictableKinds: ["invalid_kind"] } },

package/src/__tests__/conflict-policy.test.ts

@@ -3,9 +3,11 @@ import { describe, expect, test } from "bun:test";
 import {
   isConflictKindEligible,
   isConflictKindPairEligible,
+  isConflictUserEvidenced,
   isDurableInstructionStatement,
   isStatementConflictEligible,
   isTransientTrackingStatement,
+  isUserEvidencedVerificationState,
 } from "../memory/conflict-policy.js";
 
 describe("conflict-policy", () => {
@@ -190,4 +192,78 @@ describe("conflict-policy", () => {
       ).toBe(true);
     });
   });
+
+  describe("isUserEvidencedVerificationState", () => {
+    test("accepts user_reported", () => {
+      expect(isUserEvidencedVerificationState("user_reported")).toBe(true);
+    });
+
+    test("accepts user_confirmed", () => {
+      expect(isUserEvidencedVerificationState("user_confirmed")).toBe(true);
+    });
+
+    test("accepts legacy_import", () => {
+      expect(isUserEvidencedVerificationState("legacy_import")).toBe(true);
+    });
+
+    test("rejects assistant_inferred", () => {
+      expect(isUserEvidencedVerificationState("assistant_inferred")).toBe(
+        false,
+      );
+    });
+
+    test("rejects unknown states", () => {
+      expect(isUserEvidencedVerificationState("")).toBe(false);
+      expect(isUserEvidencedVerificationState("auto_detected")).toBe(false);
+      expect(isUserEvidencedVerificationState("pending")).toBe(false);
+    });
+  });
+
+  describe("isConflictUserEvidenced", () => {
+    test("returns true when existing side is user-evidenced", () => {
+      expect(
+        isConflictUserEvidenced("user_reported", "assistant_inferred"),
+      ).toBe(true);
+      expect(
+        isConflictUserEvidenced("user_confirmed", "assistant_inferred"),
+      ).toBe(true);
+      expect(
+        isConflictUserEvidenced("legacy_import", "assistant_inferred"),
+      ).toBe(true);
+    });
+
+    test("returns true when candidate side is user-evidenced", () => {
+      expect(
+        isConflictUserEvidenced("assistant_inferred", "user_reported"),
+      ).toBe(true);
+      expect(
+        isConflictUserEvidenced("assistant_inferred", "user_confirmed"),
+      ).toBe(true);
+      expect(
+        isConflictUserEvidenced("assistant_inferred", "legacy_import"),
+      ).toBe(true);
+    });
+
+    test("returns true when both sides are user-evidenced", () => {
+      expect(isConflictUserEvidenced("user_reported", "user_confirmed")).toBe(
+        true,
+      );
+      expect(isConflictUserEvidenced("legacy_import", "user_reported")).toBe(
+        true,
+      );
+    });
+
+    test("returns false when neither side is user-evidenced", () => {
+      expect(
+        isConflictUserEvidenced("assistant_inferred", "assistant_inferred"),
+      ).toBe(false);
+    });
+
+    test("returns false for unknown states on both sides", () => {
+      expect(isConflictUserEvidenced("auto_detected", "pending")).toBe(false);
+      expect(
+        isConflictUserEvidenced("assistant_inferred", "auto_detected"),
+      ).toBe(false);
+    });
+  });
 });

package/src/__tests__/conflict-store.test.ts

@@ -33,7 +33,6 @@ import {
   getPendingConflictByPair,
   listPendingConflictDetails,
   listPendingConflicts,
-  markConflictAsked,
   resolveConflict,
 } from "../memory/conflict-store.js";
 import { getDb, initializeDb, resetDb } from "../memory/db.js";
@@ -60,6 +59,10 @@ function resetTables() {
 function insertItemPair(
   suffix: string,
   scopeId = "default",
+  opts?: {
+    existingVerificationState?: string;
+    candidateVerificationState?: string;
+  },
 ): { existingItemId: string; candidateItemId: string } {
   const db = getDb();
   const now = Date.now();
@@ -76,7 +79,8 @@ function insertItemPair(
         confidence: 0.8,
         importance: 0.5,
         fingerprint: `fp-existing-${suffix}`,
-        verificationState: "assistant_inferred",
+        verificationState:
+          opts?.existingVerificationState ?? "assistant_inferred",
         scopeId,
         firstSeenAt: now,
         lastSeenAt: now,
@@ -90,7 +94,8 @@ function insertItemPair(
         confidence: 0.8,
         importance: 0.5,
         fingerprint: `fp-candidate-${suffix}`,
-        verificationState: "assistant_inferred",
+        verificationState:
+          opts?.candidateVerificationState ?? "assistant_inferred",
         scopeId,
         firstSeenAt: now,
         lastSeenAt: now,
@@ -218,24 +223,11 @@ describe("conflict-store", () => {
     expect(pendingDefault[0].status).toBe("pending_clarification");
   });
 
-  test("markConflictAsked updates lastAskedAt", () => {
-    const pair = insertItemPair("asked");
-    const conflict = createOrUpdatePendingConflict({
-      scopeId: "default",
-      existingItemId: pair.existingItemId,
-      candidateItemId: pair.candidateItemId,
-      relationship: "ambiguous_contradiction",
+  test("listPendingConflictDetails joins current statements and verification states", () => {
+    const pair = insertItemPair("details", "workspace-a", {
+      existingVerificationState: "user_confirmed",
+      candidateVerificationState: "assistant_inferred",
     });
-
-    const askedAt = 1_734_000_000_000;
-    expect(markConflictAsked(conflict.id, askedAt)).toBe(true);
-    const updated = getConflictById(conflict.id);
-    expect(updated?.lastAskedAt).toBe(askedAt);
-    expect(updated?.updatedAt).toBe(askedAt);
-  });
-
-  test("listPendingConflictDetails joins current statements", () => {
-    const pair = insertItemPair("details", "workspace-a");
     createOrUpdatePendingConflict({
       scopeId: "workspace-a",
       existingItemId: pair.existingItemId,
@@ -250,6 +242,8 @@ describe("conflict-store", () => {
     expect(details[0].candidateStatement).toBe("Candidate statement details");
     expect(details[0].existingKind).toBe("fact");
     expect(details[0].candidateKind).toBe("fact");
+    expect(details[0].existingVerificationState).toBe("user_confirmed");
+    expect(details[0].candidateVerificationState).toBe("assistant_inferred");
   });
 
   test("applyConflictResolution keeps candidate and resolves conflict row", () => {

package/src/__tests__/contacts-tools.test.ts

@@ -140,17 +140,14 @@ describe("contact_upsert tool", () => {
     expect(result.isError).toBe(false);
     expect(result.content).toContain("Created contact");
     expect(result.content).toContain("Alice");
-    expect(result.content).toContain("Importance: 0.50");
   });
 
   test("creates a contact with all fields", async () => {
     const result = await executeContactUpsert(
       {
         display_name: "Bob",
-        relationship: "colleague",
-        importance: 0.8,
-        response_expectation: "within_hours",
-        preferred_tone: "professional",
+        notes:
+          "Colleague at Acme Corp, prefers professional tone, responds within hours",
         channels: [
           { type: "email", address: "bob@example.com", is_primary: true },
           { type: "slack", address: "@bob" },
@@ -161,10 +158,7 @@ describe("contact_upsert tool", () => {
 
     expect(result.isError).toBe(false);
     expect(result.content).toContain("Bob");
-    expect(result.content).toContain("colleague");
-    expect(result.content).toContain("0.80");
-    expect(result.content).toContain("within_hours");
-    expect(result.content).toContain("professional");
+    expect(result.content).toContain("Notes: Colleague at Acme Corp");
     expect(result.content).toContain("email: bob@example.com");
     expect(result.content).toContain("slack: @bob");
   });
@@ -185,7 +179,7 @@ describe("contact_upsert tool", () => {
       {
         id: contactId,
         display_name: "Charlie Updated",
-        importance: 0.9,
+        notes: "Updated notes for Charlie",
       },
       ctx,
     );
@@ -193,7 +187,7 @@ describe("contact_upsert tool", () => {
     expect(updateResult.isError).toBe(false);
     expect(updateResult.content).toContain("Updated contact");
     expect(updateResult.content).toContain("Charlie Updated");
-    expect(updateResult.content).toContain("0.90");
+    expect(updateResult.content).toContain("Notes: Updated notes for Charlie");
   });
 
   test("auto-matches by channel address on create", async () => {
@@ -239,36 +233,6 @@ describe("contact_upsert tool", () => {
     expect(result.isError).toBe(true);
     expect(result.content).toContain("display_name is required");
   });
-
-  test("rejects importance out of range", async () => {
-    const result = await executeContactUpsert(
-      {
-        display_name: "Test",
-        importance: 1.5,
-      },
-      ctx,
-    );
-
-    expect(result.isError).toBe(true);
-    expect(result.content).toContain(
-      "importance must be a number between 0 and 1",
-    );
-  });
-
-  test("rejects negative importance", async () => {
-    const result = await executeContactUpsert(
-      {
-        display_name: "Test",
-        importance: -0.1,
-      },
-      ctx,
-    );
-
-    expect(result.isError).toBe(true);
-    expect(result.content).toContain(
-      "importance must be a number between 0 and 1",
-    );
-  });
 });
 
 // ── contact_search ──────────────────────────────────────────────────
@@ -305,23 +269,6 @@ describe("contact_search tool", () => {
     expect(result.content).toContain("Charlie");
   });
 
-  test("searches by relationship", async () => {
-    await executeContactUpsert(
-      { display_name: "Diana", relationship: "friend" },
-      ctx,
-    );
-    await executeContactUpsert(
-      { display_name: "Eve", relationship: "colleague" },
-      ctx,
-    );
-
-    const result = await executeContactSearch({ relationship: "friend" }, ctx);
-
-    expect(result.isError).toBe(false);
-    expect(result.content).toContain("Diana");
-    expect(result.content).not.toContain("Eve");
-  });
-
   test("returns no results message when nothing matches", async () => {
     await executeContactUpsert({ display_name: "Existing" }, ctx);
 
@@ -380,7 +327,7 @@ describe("contact_merge tool", () => {
     const r1 = await executeContactUpsert(
       {
         display_name: "Alice (Email)",
-        importance: 0.7,
+        notes: "Prefers email",
         channels: [{ type: "email", address: "alice@example.com" }],
       },
       ctx,
@@ -388,7 +335,7 @@ describe("contact_merge tool", () => {
     const r2 = await executeContactUpsert(
       {
         display_name: "Alice (Slack)",
-        importance: 0.9,
+        notes: "Active on Slack",
         channels: [{ type: "slack", address: "@alice" }],
       },
       ctx,
@@ -407,7 +354,7 @@ describe("contact_merge tool", () => {
 
     expect(result.isError).toBe(false);
     expect(result.content).toContain("Merged");
-    expect(result.content).toContain("Importance: 0.90"); // takes higher importance
+    expect(result.content).toContain("Notes: Prefers email\nActive on Slack"); // concatenated notes
     expect(result.content).toContain("email: alice@example.com");
     expect(result.content).toContain("slack: @alice");
 

package/src/__tests__/contradiction-checker.test.ts

@@ -201,7 +201,11 @@ describe("checkContradictions", () => {
     expect(conflicts[0].existingItemId).toBe("item-existing-ambiguous");
     expect(conflicts[0].candidateItemId).toBe("item-candidate-ambiguous");
     expect(conflicts[0].relationship).toBe("ambiguous_contradiction");
-    expect(conflicts[0].clarificationQuestion).toContain(
+    expect(conflicts[0].clarificationQuestion).toContain("Pending conflict:");
+    expect(conflicts[0].clarificationQuestion).not.toContain(
+      "I have conflicting notes",
+    );
+    expect(conflicts[0].clarificationQuestion).not.toContain(
       "Which one is correct?",
     );
   });

package/src/__tests__/guardian-decision-primitive-canonical.test.ts

@@ -71,7 +71,8 @@ const TEST_PRINCIPAL_ID = "test-principal-id";
 
 function guardianActor(overrides: Partial<ActorContext> = {}): ActorContext {
   return {
-    externalUserId: "guardian-1",
+    actorPrincipalId: TEST_PRINCIPAL_ID,
+    actorExternalUserId: "guardian-1",
     channel: "telegram",
     guardianPrincipalId: TEST_PRINCIPAL_ID,
     ...overrides,
@@ -80,7 +81,8 @@ function guardianActor(overrides: Partial<ActorContext> = {}): ActorContext {
 
 function trustedActor(overrides: Partial<ActorContext> = {}): ActorContext {
   return {
-    externalUserId: undefined,
+    actorPrincipalId: TEST_PRINCIPAL_ID,
+    actorExternalUserId: undefined,
     channel: "desktop",
     guardianPrincipalId: TEST_PRINCIPAL_ID,
     ...overrides,
@@ -254,7 +256,7 @@ describe("applyCanonicalGuardianDecision", () => {
 
     expect(result.applied).toBe(true);
     if (!result.applied) return;
-    // No grant minted because trusted actor has no externalUserId
+    // No grant minted because trusted actor has no actorExternalUserId
     expect(result.grantMinted).toBe(false);
   });
 

package/src/__tests__/guardian-routing-invariants.test.ts

@@ -94,7 +94,8 @@ const TEST_PRINCIPAL_ID = "test-principal-id";
 
 function guardianActor(overrides: Partial<ActorContext> = {}): ActorContext {
   return {
-    externalUserId: "guardian-1",
+    actorPrincipalId: TEST_PRINCIPAL_ID,
+    actorExternalUserId: "guardian-1",
     channel: "telegram",
     guardianPrincipalId: TEST_PRINCIPAL_ID,
     ...overrides,
@@ -103,7 +104,8 @@ function guardianActor(overrides: Partial<ActorContext> = {}): ActorContext {
 
 function trustedActor(overrides: Partial<ActorContext> = {}): ActorContext {
   return {
-    externalUserId: undefined,
+    actorPrincipalId: TEST_PRINCIPAL_ID,
+    actorExternalUserId: undefined,
     channel: "desktop",
     guardianPrincipalId: TEST_PRINCIPAL_ID,
     ...overrides,
@@ -1212,13 +1214,13 @@ describe("routing invariant: destination hints do not bypass tool_approval princ
     });
 
     // No pendingRequestIds passed — identity-based fallback uses
-    // actor.externalUserId which does not match any request's
+    // actor.actorExternalUserId which does not match any request's
     // guardianExternalUserId (since it's null).
     const result = await routeGuardianReply(
       replyCtx({
         messageText: "approve",
         channel: "telegram",
-        actor: guardianActor({ externalUserId: "guardian-tg-user" }),
+        actor: guardianActor({ actorExternalUserId: "guardian-tg-user" }),
         conversationId: "conv-guardian-chat",
         // pendingRequestIds: undefined — no delivery hints
         approvalConversationGenerator: undefined,