@vellumai/assistant 0.10.1 → 0.10.2-dev.202606241651.2d2b40d

package/src/config/bundled-skills/contacts/tools/contact-merge.ts

@@ -1,4 +1,5 @@
-import type { ContactWithChannels } from "../../../../contacts/types.js";
+import type { ContactRead } from "@vellumai/gateway-client/gateway-ipc-contracts";
+
 import { cliIpcCall } from "../../../../ipc/cli-client.js";
 import { resolveGuardianName } from "../../../../prompts/user-reference.js";
 import type {
@@ -6,6 +7,12 @@ import type {
   ToolExecutionResult,
 } from "../../../../tools/types.js";
 
+function guardianAwareName(contact: Pick<ContactRead, "role" | "displayName">) {
+  return contact.role === "guardian"
+    ? resolveGuardianName(contact.displayName)
+    : contact.displayName;
+}
+
 export async function executeContactMerge(
   input: Record<string, unknown>,
   _context: ToolContext,
@@ -22,10 +29,10 @@ export async function executeContactMerge(
 
   // Validate both contacts exist before merging
   const [keepRes, mergeRes] = await Promise.all([
-    cliIpcCall<{ contact: ContactWithChannels }>("getContact", {
+    cliIpcCall<{ contact: ContactRead }>("getContact", {
       pathParams: { id: keepId },
     }),
-    cliIpcCall<{ contact: ContactWithChannels }>("getContact", {
+    cliIpcCall<{ contact: ContactRead }>("getContact", {
       pathParams: { id: mergeId },
     }),
   ]);
@@ -42,7 +49,7 @@ export async function executeContactMerge(
 
   const mergeResult = await cliIpcCall<{
     ok: boolean;
-    contact: ContactWithChannels;
+    contact: ContactRead;
   }>("merge_contacts", {
     body: { keepId, mergeId },
   });
@@ -51,19 +58,22 @@ export async function executeContactMerge(
     return { content: `Error: ${mergeResult.error}`, isError: true };
   }
 
-  const merged = mergeResult.result!.contact;
-  const displayName =
-    merged.role === "guardian"
-      ? resolveGuardianName(merged.displayName)
-      : merged.displayName;
-  const keepName =
-    keepContact.role === "guardian"
-      ? resolveGuardianName(keepContact.displayName)
-      : keepContact.displayName;
-  const mergeName =
-    mergeContact.role === "guardian"
-      ? resolveGuardianName(mergeContact.displayName)
-      : mergeContact.displayName;
+  const mergedId = mergeResult.result!.contact.id;
+
+  // Re-read the surviving contact through the gateway-relayed read so role and
+  // interactionCount come from the gateway ContactRead.
+  const mergedRes = await cliIpcCall<{ contact: ContactRead }>("getContact", {
+    pathParams: { id: mergedId },
+  });
+
+  if (!mergedRes.ok) {
+    return { content: `Error: ${mergedRes.error}`, isError: true };
+  }
+
+  const merged = mergedRes.result!.contact;
+  const displayName = guardianAwareName(merged);
+  const keepName = guardianAwareName(keepContact);
+  const mergeName = guardianAwareName(mergeContact);
 
   const channelList = merged.channels
     .map(

package/src/config/bundled-skills/contacts/tools/contact-search.ts

@@ -1,4 +1,5 @@
-import type { ContactWithChannels } from "../../../../contacts/types.js";
+import type { ContactRead } from "@vellumai/gateway-client/gateway-ipc-contracts";
+
 import { cliIpcCall } from "../../../../ipc/cli-client.js";
 import { resolveGuardianName } from "../../../../prompts/user-reference.js";
 import type {
@@ -6,7 +7,16 @@ import type {
   ToolExecutionResult,
 } from "../../../../tools/types.js";
 
-function formatContactSummary(c: ContactWithChannels): string {
+// The search route may carry an optional per-channel `externalChatId` not modeled
+// on the gateway `ContactRead` channel contract.
+type SearchChannel = ContactRead["channels"][number] & {
+  externalChatId?: string | null;
+};
+type SearchContact = Omit<ContactRead, "channels"> & {
+  channels: SearchChannel[];
+};
+
+function formatContactSummary(c: SearchContact): string {
   const displayName =
     c.role === "guardian" ? resolveGuardianName(c.displayName) : c.displayName;
   const parts = [`- **${displayName}** (ID: ${c.id})`];
@@ -45,7 +55,7 @@ export async function executeContactSearch(
     };
   }
 
-  const res = await cliIpcCall<ContactWithChannels[]>("search_contacts", {
+  const res = await cliIpcCall<SearchContact[]>("search_contacts", {
     body: { query, channelAddress, channelType, limit },
   });
 

package/src/config/feature-flag-registry.json

@@ -66,14 +66,6 @@
       "description": "Gate per-turn conversation trace (user/assistant/tool-call/tool-response) collection. The daemon attaches a trace to its turn telemetry only when this flag AND the owner's share_diagnostics consent are both on. Defaults off (fail-closed) — the live value is delivered from LaunchDarkly.",
       "defaultEnabled": false
     },
-    {
-      "id": "workspace-tools-watcher",
-      "scope": "assistant",
-      "key": "workspace-tools-watcher",
-      "label": "Workspace tools file watcher",
-      "description": "Hot-reload workspace tool overrides under `<workspaceDir>/tools/` by watching the directory and re-registering tools as files change. When disabled, workspace tools still load from disk once at daemon startup, but live edits require a restart to take effect.",
-      "defaultEnabled": false
-    },
     {
       "id": "settings-developer-nav",
       "scope": "assistant",

package/src/config/loader.ts

@@ -300,14 +300,20 @@ function validateWithSchema(raw: Record<string, unknown>): AssistantConfig {
   }
 
   // Strip invalid fields by setting them to undefined so Zod defaults apply,
-  // then re-parse. We walk the error paths and delete the offending keys.
+  // then re-parse. We walk the error paths and delete the offending keys,
+  // pruning any ancestor object the deletion leaves empty. Pruning matters for
+  // nested overrides like `llm.callSites.<id>.profile`: stripping just the
+  // invalid `.profile` leaf would leave `llm.callSites.<id> = {}`, which the
+  // resolver treats as a present (non-default) override and so skips the
+  // shipped call-site default — silently downgrading the call site to the
+  // active profile. Removing the emptied object lets that default apply.
   const cleaned = structuredClone(raw);
   for (const issue of result.error.issues) {
     if (issue.path.length === 0) {
       // Top-level error — return full defaults
       return cloneDefaultConfig();
     }
-    deleteNestedKey(cleaned, issue.path as (string | number)[]);
+    deleteNestedKey(cleaned, issue.path as (string | number)[], true);
   }
 
   const retry = AssistantConfigSchema.safeParse(cleaned);
@@ -320,17 +326,42 @@ function validateWithSchema(raw: Record<string, unknown>): AssistantConfig {
   return cloneDefaultConfig();
 }
 
+/**
+ * Delete the key at `path` from `obj`. When `pruneEmptyAncestors` is set, also
+ * remove any ancestor object the deletion leaves empty, walking up until the
+ * first ancestor that still holds other keys. Only empty plain objects are
+ * pruned (arrays are left alone), and a still-populated ancestor stops the walk
+ * so a container holding other config is never removed.
+ */
 function deleteNestedKey(
   obj: Record<string, unknown>,
   path: (string | number)[],
+  pruneEmptyAncestors = false,
 ): void {
+  // Record each (container, key) hop on the way down so we can prune upward
+  // after deleting the leaf.
+  const chain: Array<{ container: Record<string, unknown>; key: string }> = [];
   let current: unknown = obj;
   for (let i = 0; i < path.length - 1; i++) {
     if (current == null || typeof current !== "object") return;
-    current = (current as Record<string, unknown>)[String(path[i])];
+    const key = String(path[i]);
+    chain.push({ container: current as Record<string, unknown>, key });
+    current = (current as Record<string, unknown>)[key];
   }
-  if (current != null && typeof current === "object") {
-    delete (current as Record<string, unknown>)[String(path[path.length - 1])];
+  if (current == null || typeof current !== "object") return;
+  delete (current as Record<string, unknown>)[String(path[path.length - 1])];
+
+  if (!pruneEmptyAncestors) return;
+  // Remove ancestors emptied by the deletion, deepest first; stop at the first
+  // that still has keys.
+  for (let i = chain.length - 1; i >= 0; i--) {
+    const { container, key } = chain[i];
+    const child = container[key];
+    if (isPlainObject(child) && Object.keys(child).length === 0) {
+      delete container[key];
+    } else {
+      break;
+    }
   }
 }
 

package/src/config/schemas/__tests__/memory-v3.test.ts

@@ -22,6 +22,7 @@ describe("MemoryV3ConfigSchema", () => {
       needleK: 100,
       denseK: 100,
       replyQueryK: 12,
+      selectorPromptPath: null,
       edge: { hubDegree: 30, seedCount: 18, perSeed: 6, cap: 45 },
     });
   });

package/src/config/schemas/memory-lifecycle.ts

@@ -78,6 +78,17 @@ export const MemoryJobsConfigSchema = MemoryJobsConfigInputSchema.transform(
   },
 ).describe("Memory background job processing configuration");
 
+export const MemoryWorkerConfigSchema = z
+  .object({
+    enabled: z
+      .boolean({ error: "memory.worker.enabled must be a boolean" })
+      .default(false)
+      .describe(
+        "Whether the memory jobs worker runs as a separate OS process spawned at assistant startup (the `assistant memory worker` implementation) instead of on the assistant's main event loop. Only affects startup; shutdown stops whichever worker is actually running.",
+      ),
+  })
+  .describe("Memory jobs worker process configuration");
+
 export const MemoryRetentionConfigSchema = z
   .object({
     keepRawForever: z
@@ -185,6 +196,7 @@ export const MemoryMaintenanceConfigSchema = z
   );
 
 export type MemoryJobsConfig = z.infer<typeof MemoryJobsConfigSchema>;
+export type MemoryWorkerConfig = z.infer<typeof MemoryWorkerConfigSchema>;
 export type MemoryRetentionConfig = z.infer<typeof MemoryRetentionConfigSchema>;
 export type MemoryCleanupConfig = z.infer<typeof MemoryCleanupConfigSchema>;
 export type MemoryMaintenanceConfig = z.infer<

package/src/config/schemas/memory-v3.ts

@@ -259,6 +259,13 @@ export const MemoryV3ConfigSchema = z
       .describe(
         "Per-lane article budget for the reply-query finder pass: needle and dense each re-run over the assistant's previous message as separate queries (never concatenated with the user's message). 0 disables the pass. Deliberately small next to needleK/denseK — the pass adds the assistant-side retrieval signal, not a second full sweep.",
       ),
+    selectorPromptPath: z
+      .string({ error: "memory.v3.selectorPromptPath must be a string" })
+      .nullable()
+      .default(null)
+      .describe(
+        "Optional path to a file whose contents replace the bundled per-turn selector system prompt (the instructions that tell the selector which candidate pages to keep). Absolute paths are used as-is, a leading `~/` is expanded to the home directory, otherwise the path is resolved under the workspace root. The selector prompt takes no placeholders — the candidate pool is supplied separately as the user message — so the file is used verbatim. If the file is missing, unreadable, empty, or over 1 MiB, the bundled prompt is used and a warning is logged.",
+      ),
     edge: MemoryV3EdgeSchema.default(MemoryV3EdgeSchema.parse({})),
   })
   .describe("Memory v3 — section-grain lane retrieval");

package/src/config/schemas/memory.ts

@@ -5,6 +5,7 @@ import {
   MemoryJobsConfigSchema,
   MemoryMaintenanceConfigSchema,
   MemoryRetentionConfigSchema,
+  MemoryWorkerConfigSchema,
 } from "./memory-lifecycle.js";
 import {
   MemoryExtractionConfigSchema,
@@ -39,6 +40,9 @@ export const MemoryConfigSchema = z
       MemorySegmentationConfigSchema.parse({}),
     ),
     jobs: MemoryJobsConfigSchema.default(MemoryJobsConfigSchema.parse({})),
+    worker: MemoryWorkerConfigSchema.default(
+      MemoryWorkerConfigSchema.parse({}),
+    ),
     retention: MemoryRetentionConfigSchema.default(
       MemoryRetentionConfigSchema.parse({}),
     ),

package/src/config/schemas/timeouts.ts

@@ -28,6 +28,14 @@ export const TimeoutConfigSchema = z
       .describe(
         "How long to wait for user permission approval before timing out (seconds)",
       ),
+    questionResponseTimeoutSec: z
+      .number({ error: "timeouts.questionResponseTimeoutSec must be a number" })
+      .finite("timeouts.questionResponseTimeoutSec must be finite")
+      .positive("timeouts.questionResponseTimeoutSec must be a positive number")
+      .default(1800)
+      .describe(
+        "Backstop timeout for an unanswered ask_question prompt (seconds). The primary way an interactive user dismisses a prompt is by moving on — enqueuing another message supersedes it — so this only bounds a prompt left open with no response and no follow-up message.",
+      ),
     toolExecutionTimeoutSec: z
       .number({ error: "timeouts.toolExecutionTimeoutSec must be a number" })
       .finite("timeouts.toolExecutionTimeoutSec must be finite")

package/src/config/seed-inference-profiles.ts

@@ -88,15 +88,24 @@ const MANAGED_PROFILE_TEMPLATES: Record<string, ManagedProfileTemplate> = {
     // profile there's nothing stronger to consult, so the advisor defaults off.
     advisorEnabled: false,
   },
+  // Served by DeepSeek V4 Flash on Fireworks via managed platform inference: a
+  // fast, low-cost open model. `model` is pinned explicitly rather than
+  // resolved via the `latency-optimized` intent (which still maps to Kimi K2.5
+  // on Fireworks and Anthropic Haiku elsewhere).
+  //
+  // `effort: "none"` (not "low") because Fireworks is not thinking-aware: the
+  // disabled `thinking` config is stripped before the request, so a non-"none"
+  // effort would be sent as `reasoning_effort` and make this profile pay for
+  // reasoning despite thinking being off. "none" keeps Speed non-reasoning.
   "cost-optimized": {
-    intent: "latency-optimized",
-    provider: "anthropic",
-    connectionName: "anthropic-managed",
+    model: "accounts/fireworks/models/deepseek-v4-flash",
+    provider: "fireworks",
+    connectionName: "fireworks-managed",
     source: "managed",
     label: "Speed",
-    description: "Fastest responses at lower cost",
+    description: "Fastest responses at lower cost (DeepSeek V4 Flash)",
     maxTokens: 8192,
-    effort: "low",
+    effort: "none",
     thinking: { enabled: false, streamThinking: false },
     contextWindow: { maxInputTokens: DEFAULT_CONTEXT_WINDOW_MAX_INPUT_TOKENS },
   },

package/src/config/skills.ts

@@ -688,6 +688,9 @@ function discoverSkillDirectories(skillsDir: string): string[] {
  * parseable `package.json` whose `name` equals the directory name. This
  * mirrors the external plugin loader's recognition gate, which skips any
  * directory whose `manifest.name` does not match its directory name.
+ *
+ * The caller is responsible for the missing-`package.json` case (it emits a
+ * diagnostic warning); this function only judges a manifest that is present.
  */
 function isRecognizedPluginDir(pluginDir: string, dirName: string): boolean {
   const manifestPath = join(pluginDir, "package.json");
@@ -735,12 +738,31 @@ function discoverPluginResidentSkills(): SkillSummary[] {
   for (const entry of entries) {
     if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
     const pluginDir = join(pluginsDir, entry.name);
+
+    // A directory under `plugins/` with no `package.json` is not a plugin the
+    // runtime can load, so its skills are never surfaced. This is an easy
+    // footgun — a plugin dropped in without its manifest looks installed but
+    // silently contributes nothing — so warn loudly with the path rather than
+    // skipping in silence, to make the misconfiguration diagnosable.
+    if (!existsSync(join(pluginDir, "package.json"))) {
+      log.warn(
+        { pluginDir },
+        "Plugin directory is missing package.json — skipping; its skills will not be available. Add a package.json whose `name` matches the directory.",
+      );
+      continue;
+    }
+
+    // Honor the `.disabled` sentinel the runtime plugin scan checks
+    // (`plugins/mtime-cache.ts`): a disabled plugin contributes no hooks or
+    // tools, so its resident skills must not be loadable either.
+    if (existsSync(join(pluginDir, ".disabled"))) continue;
+
     // Mirror the plugin loader's recognition gate: a directory is a real
-    // installed plugin only if it carries a parseable `package.json` whose
-    // `name` matches the directory. This rejects staging dirs, stray files,
-    // and malformed/mismatched clones (e.g. an un-adapted `caveman-installer`)
-    // that the loader itself would skip, so the catalog never surfaces skills
-    // from a directory the runtime would refuse to load.
+    // installed plugin only if its `package.json` `name` matches the directory.
+    // This rejects staging dirs and malformed/mismatched clones (e.g. an
+    // un-adapted `caveman-installer`) that the loader itself would skip, so the
+    // catalog never surfaces skills from a directory the runtime would refuse
+    // to load.
     if (!isRecognizedPluginDir(pluginDir, entry.name)) continue;
 
     const skillsDir = join(pluginDir, "skills");

package/src/contacts/__tests__/guardian-delivery-reader.test.ts

@@ -0,0 +1,312 @@
+/**
+ * Tests for the gateway-backed guardian delivery reader.
+ *
+ * Guardian binding is near-static, so the reader caches behind a minutes-scale
+ * TTL, clears event-driven on invalidation, and coalesces concurrent cold-cache
+ * reads single-flight. These tests pin the parse contract plus all three cache
+ * behaviors (TTL hit, invalidation, single-flight) and the failure-no-poison
+ * rule.
+ */
+
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+import type { GuardianDelivery } from "@vellumai/gateway-client";
+
+// ── Controllable IPC mock ────────────────────────────────────────────────────
+
+type IpcHandler = (params?: Record<string, unknown>) => unknown;
+
+const ipcHandlers = new Map<string, IpcHandler>();
+const ipcCallLog: Array<{
+  method: string;
+  params?: Record<string, unknown>;
+  timeoutMs?: number;
+}> = [];
+
+mock.module("../../ipc/gateway-client.js", () => ({
+  ipcCall: async (
+    method: string,
+    params?: Record<string, unknown>,
+    timeoutMs?: number,
+  ) => {
+    ipcCallLog.push({ method, params, timeoutMs });
+    const handler = ipcHandlers.get(method);
+    return handler ? handler(params) : undefined;
+  },
+  ipcCallPersistent: async () => undefined,
+  resetPersistentClient: () => {},
+}));
+
+import { emitContactChange } from "../contact-events.js";
+import {
+  __resetGuardianDeliveryCacheForTest,
+  anyGuardian,
+  getGuardianDelivery,
+  getGuardianDeliveryFresh,
+  guardianForChannel,
+  invalidateGuardianDeliveryCache,
+} from "../guardian-delivery-reader.js";
+
+const METHOD = "resolve_guardian_delivery";
+
+function countCalls(method: string): number {
+  return ipcCallLog.filter((c) => c.method === method).length;
+}
+
+const telegramGuardian: GuardianDelivery = {
+  channelType: "telegram",
+  contactId: "contact-123",
+  address: "@guardian",
+  status: "active",
+};
+
+const emailGuardian: GuardianDelivery = {
+  channelType: "email",
+  contactId: "contact-456",
+  address: "guardian@example.com",
+  status: "active",
+};
+
+describe("getGuardianDelivery", () => {
+  beforeEach(() => {
+    __resetGuardianDeliveryCacheForTest();
+    ipcHandlers.clear();
+    ipcCallLog.length = 0;
+  });
+
+  test("returns the parsed guardian list", async () => {
+    ipcHandlers.set(METHOD, () => ({ guardians: [telegramGuardian] }));
+
+    expect(await getGuardianDelivery()).toEqual([telegramGuardian]);
+  });
+
+  test("bounds the IPC read with a short timeout", async () => {
+    ipcHandlers.set(METHOD, () => ({ guardians: [] }));
+
+    await getGuardianDelivery();
+
+    const call = ipcCallLog.find((c) => c.method === METHOD);
+    expect(call?.timeoutMs).toBe(2_000);
+  });
+
+  test("returns null when IPC transport fails (undefined)", async () => {
+    ipcHandlers.set(METHOD, () => undefined);
+    expect(await getGuardianDelivery()).toBeNull();
+  });
+
+  test("returns null when the IPC call throws", async () => {
+    ipcHandlers.set(METHOD, () => {
+      throw new Error("socket exploded");
+    });
+    expect(await getGuardianDelivery()).toBeNull();
+  });
+
+  test("returns null for a malformed response shape", async () => {
+    ipcHandlers.set(METHOD, () => ({ guardians: "not-an-array" }));
+    expect(await getGuardianDelivery()).toBeNull();
+  });
+
+  test("two calls within the TTL issue only ONE IPC call (cache hit)", async () => {
+    ipcHandlers.set(METHOD, () => ({ guardians: [telegramGuardian] }));
+
+    await getGuardianDelivery();
+    await getGuardianDelivery();
+
+    expect(countCalls(METHOD)).toBe(1);
+  });
+
+  test("caches per channelTypes filter key", async () => {
+    ipcHandlers.set(METHOD, () => ({ guardians: [telegramGuardian] }));
+
+    await getGuardianDelivery();
+    await getGuardianDelivery({ channelTypes: ["telegram"] });
+
+    // Distinct keys ("ALL" vs "telegram") miss each other → two IPC calls.
+    expect(countCalls(METHOD)).toBe(2);
+  });
+
+  test("invalidateGuardianDeliveryCache() forces the next call to re-fetch", async () => {
+    ipcHandlers.set(METHOD, () => ({ guardians: [telegramGuardian] }));
+
+    await getGuardianDelivery();
+    invalidateGuardianDeliveryCache();
+    await getGuardianDelivery();
+
+    expect(countCalls(METHOD)).toBe(2);
+  });
+
+  test("a contact-change event clears the cache", async () => {
+    ipcHandlers.set(METHOD, () => ({ guardians: [telegramGuardian] }));
+
+    await getGuardianDelivery();
+    emitContactChange();
+    await getGuardianDelivery();
+
+    expect(countCalls(METHOD)).toBe(2);
+  });
+
+  test("a burst of concurrent cold-cache calls issues only ONE IPC call (single-flight)", async () => {
+    let resolveIpc: ((value: unknown) => void) | undefined;
+    ipcHandlers.set(
+      METHOD,
+      () =>
+        new Promise((resolve) => {
+          resolveIpc = resolve;
+        }),
+    );
+
+    const burst = Promise.all([
+      getGuardianDelivery(),
+      getGuardianDelivery(),
+      getGuardianDelivery(),
+    ]);
+    resolveIpc?.({ guardians: [telegramGuardian] });
+    const results = await burst;
+
+    expect(countCalls(METHOD)).toBe(1);
+    expect(results).toEqual([
+      [telegramGuardian],
+      [telegramGuardian],
+      [telegramGuardian],
+    ]);
+  });
+
+  test("an invalidation DURING an in-flight fetch is not masked — the next call re-fetches", async () => {
+    let resolveIpc: ((value: unknown) => void) | undefined;
+    ipcHandlers.set(
+      METHOD,
+      () =>
+        new Promise((resolve) => {
+          resolveIpc = resolve;
+        }),
+    );
+
+    // Start a cold fetch, invalidate before it resolves, then resolve it.
+    const inFlight = getGuardianDelivery();
+    invalidateGuardianDeliveryCache();
+    resolveIpc?.({ guardians: [telegramGuardian] });
+    expect(await inFlight).toEqual([telegramGuardian]);
+
+    // The pre-invalidation result must NOT have been cached: the next read
+    // issues a fresh IPC rather than serving the now-stale value.
+    ipcHandlers.set(METHOD, () => ({ guardians: [emailGuardian] }));
+    expect(await getGuardianDelivery()).toEqual([emailGuardian]);
+    expect(countCalls(METHOD)).toBe(2);
+  });
+
+  test("a failure does NOT poison the cache — the next call retries", async () => {
+    ipcHandlers.set(METHOD, () => undefined);
+    expect(await getGuardianDelivery()).toBeNull();
+
+    ipcHandlers.set(METHOD, () => ({ guardians: [telegramGuardian] }));
+    expect(await getGuardianDelivery()).toEqual([telegramGuardian]);
+    expect(countCalls(METHOD)).toBe(2);
+  });
+
+  test("fresh read ignores a stale cached entry and re-fetches", async () => {
+    // Seed the cache with an empty list (the stale gateway-side view).
+    ipcHandlers.set(METHOD, () => ({ guardians: [] }));
+    expect(await getGuardianDelivery()).toEqual([]);
+
+    // A cached read still serves the stale empty list (no new IPC)...
+    expect(await getGuardianDelivery()).toEqual([]);
+    expect(countCalls(METHOD)).toBe(1);
+
+    // ...but a fresh read bypasses the cache and sees the now-present guardian.
+    ipcHandlers.set(METHOD, () => ({ guardians: [telegramGuardian] }));
+    expect(await getGuardianDeliveryFresh()).toEqual([telegramGuardian]);
+    expect(countCalls(METHOD)).toBe(2);
+  });
+
+  test("fresh read updates the cache with the fresh result", async () => {
+    ipcHandlers.set(METHOD, () => ({ guardians: [] }));
+    await getGuardianDelivery();
+
+    ipcHandlers.set(METHOD, () => ({ guardians: [telegramGuardian] }));
+    await getGuardianDeliveryFresh();
+
+    // A subsequent cached read serves the refreshed value without a new IPC.
+    expect(await getGuardianDelivery()).toEqual([telegramGuardian]);
+    expect(countCalls(METHOD)).toBe(2);
+  });
+
+  test("getGuardianDeliveryFresh bypasses a stale cached empty list", async () => {
+    ipcHandlers.set(METHOD, () => ({ guardians: [] }));
+    expect(
+      await getGuardianDelivery({ channelTypes: ["telegram"] }),
+    ).toEqual([]);
+
+    ipcHandlers.set(METHOD, () => ({ guardians: [telegramGuardian] }));
+    expect(
+      await getGuardianDeliveryFresh({ channelTypes: ["telegram"] }),
+    ).toEqual([telegramGuardian]);
+    expect(countCalls(METHOD)).toBe(2);
+  });
+
+  test("a burst of forceRefresh reads still coalesces single-flight", async () => {
+    let resolveIpc: ((value: unknown) => void) | undefined;
+    ipcHandlers.set(
+      METHOD,
+      () =>
+        new Promise((resolve) => {
+          resolveIpc = resolve;
+        }),
+    );
+
+    const burst = Promise.all([
+      getGuardianDeliveryFresh(),
+      getGuardianDeliveryFresh(),
+      getGuardianDeliveryFresh(),
+    ]);
+    resolveIpc?.({ guardians: [telegramGuardian] });
+    await burst;
+
+    expect(countCalls(METHOD)).toBe(1);
+  });
+
+  test("a fresh read does NOT coalesce with an in-flight non-force fetch (issues its own IPC)", async () => {
+    // A normal read starts a fetch that will resolve to the pre-write empty
+    // list and is still in flight when the fresh read arrives.
+    let resolveStale: ((value: unknown) => void) | undefined;
+    ipcHandlers.set(
+      METHOD,
+      () =>
+        new Promise((resolve) => {
+          resolveStale = resolve;
+        }),
+    );
+    const stale = getGuardianDelivery();
+
+    // The gateway-side write lands (not reflected in the in-flight fetch). The
+    // fresh read must NOT reuse the stale in-flight promise — it issues its own
+    // IPC observing the post-write guardian.
+    ipcHandlers.set(METHOD, () => ({ guardians: [telegramGuardian] }));
+    const fresh = await getGuardianDeliveryFresh();
+    expect(fresh).toEqual([telegramGuardian]);
+
+    // Release the stale fetch last; it must not have masked the fresh result.
+    resolveStale?.({ guardians: [] });
+    expect(await stale).toEqual([]);
+    expect(countCalls(METHOD)).toBe(2);
+  });
+});
+
+describe("selectors", () => {
+  test("guardianForChannel picks the first active match for the type", () => {
+    const inactive: GuardianDelivery = {
+      ...telegramGuardian,
+      contactId: "contact-999",
+      status: "revoked",
+    };
+    const list = [inactive, telegramGuardian, emailGuardian];
+
+    expect(guardianForChannel(list, "telegram")).toBe(telegramGuardian);
+    expect(guardianForChannel(list, "email")).toBe(emailGuardian);
+    expect(guardianForChannel(list, "phone")).toBeUndefined();
+  });
+
+  test("anyGuardian returns the first overall", () => {
+    expect(anyGuardian([emailGuardian, telegramGuardian])).toBe(emailGuardian);
+    expect(anyGuardian([])).toBeUndefined();
+  });
+});