@vellumai/assistant 0.10.0 → 0.10.1-dev.202606240317.ea25efe

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

@@ -11,6 +11,7 @@ import type { ModelIntent } from "../providers/types.js";
 import { credentialKey } from "../security/credential-key.js";
 import { getLogger } from "../util/logger.js";
 import { loadRawConfig, saveRawConfig } from "./loader.js";
+import { isDispatchableProfile } from "./profile-dispatchability.js";
 import {
   DEFAULT_CONTEXT_WINDOW_MAX_INPUT_TOKENS,
   type ProfileEntry,
@@ -41,12 +42,12 @@ type ManagedProfileTemplate = Omit<
  * (`preserveProfileNames`) take precedence when present.
  */
 const MANAGED_PROFILE_TEMPLATES: Record<string, ManagedProfileTemplate> = {
-  // Served by MiniMax M3 on Fireworks via managed platform inference: a strong
+  // Served by MiniMax M3 on Together AI via managed platform inference: a strong
   // open model at a lower price point than the managed Anthropic route.
   balanced: {
     intent: "balanced",
-    provider: "fireworks",
-    connectionName: "fireworks-managed",
+    provider: "together",
+    connectionName: "together-managed",
     source: "managed",
     label: "Balanced",
     description: "Good balance of quality, cost, and speed",
@@ -56,12 +57,28 @@ const MANAGED_PROFILE_TEMPLATES: Record<string, ManagedProfileTemplate> = {
     contextWindow: { maxInputTokens: DEFAULT_CONTEXT_WINDOW_MAX_INPUT_TOKENS },
     topP: 0.95,
   },
+  // Served by GLM 5.2 on Fireworks via managed platform inference: a leading
+  // open model. `model` is pinned explicitly rather than resolved via the
+  // `quality-optimized` intent (which still maps to Anthropic Opus for the
+  // `frontier` profile below).
   "quality-optimized": {
+    model: "accounts/fireworks/models/glm-5p2",
+    provider: "fireworks",
+    connectionName: "fireworks-managed",
+    source: "managed",
+    label: "Quality",
+    description: "High-quality results with a leading open model (GLM 5.2)",
+    maxTokens: 32000,
+    effort: "high",
+    thinking: { enabled: true, streamThinking: true },
+    contextWindow: { maxInputTokens: DEFAULT_CONTEXT_WINDOW_MAX_INPUT_TOKENS },
+  },
+  frontier: {
     intent: "quality-optimized",
     provider: "anthropic",
     connectionName: "anthropic-managed",
     source: "managed",
-    label: "Quality",
+    label: "Frontier",
     description: "Best results with the most capable model",
     maxTokens: 32000,
     effort: "high",
@@ -71,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 },
   },
@@ -131,14 +157,6 @@ const USER_PROFILE_TEMPLATES: Record<string, ManagedProfileTemplate> = {
   },
 };
 
-/**
- * The "auto" profile key. When active, the daemon injects the
- * `switch_inference_profile` tool and lets the model self-select a profile
- * per query. No provider/model — the resolver falls through to the call-site
- * default (balanced or custom-balanced for BYOK).
- */
-export const AUTO_PROFILE_KEY = "auto";
-
 export const OS_BETA_PROFILE_KEY = "os-beta";
 export const OS_BETA_FEATURE_FLAG_KEY = "os-beta";
 
@@ -170,9 +188,19 @@ export const OS_BETA_PROFILE_TEMPLATE: ManagedProfileTemplate = {
 export const MANAGED_PROFILE_NAMES = new Set([
   ...Object.keys(MANAGED_PROFILE_TEMPLATES),
   OS_BETA_PROFILE_KEY,
-  AUTO_PROFILE_KEY,
 ]);
 
+// Managed names introduced after profile-ownership metadata existed, so any
+// pre-existing same-named entry must have been user-created. The seed loop
+// protects these from being clobbered: a user may already own a profile under
+// such a name (the settings UI saves custom profiles without a `source`), so an
+// entry that isn't explicitly `source: "managed"` is treated as theirs. The
+// original canonical names (`balanced`/`quality-optimized`/`cost-optimized`)
+// predate ownership metadata — migration 052 seeded them source-less — so they
+// are NOT listed here and always reseed, even when source is absent.
+const NEWLY_RESERVED_MANAGED_NAMES = new Set(["frontier"]);
+const MIX_MIN_ARMS = 2;
+
 export type SeedInferenceProfilesOptions = {
   /**
    * Profile names supplied by the platform/default overlay for this startup.
@@ -289,6 +317,21 @@ export function seedInferenceProfiles(
     if (preservedProfileNames.has(name)) continue;
 
     const previous = readObject(profiles[name]);
+    // Never clobber a custom profile that happens to share a *newly reserved*
+    // managed name (e.g. `frontier`): reseeding would change its provider/model
+    // and mark it managed. Treat anything not explicitly `source: "managed"` as
+    // the user's, since the settings UI saves custom profiles without a `source`
+    // and the source backfill below skips managed names. The original canonical
+    // names are excluded from this guard — they may be source-less *managed*
+    // entries from migration 052, so they must keep reseeding to receive
+    // template updates (see NEWLY_RESERVED_MANAGED_NAMES).
+    if (
+      NEWLY_RESERVED_MANAGED_NAMES.has(name) &&
+      previous &&
+      previous.source !== "managed"
+    ) {
+      continue;
+    }
     const effectiveTemplate: ManagedProfileTemplate = isByokMode
       ? { ...template, label: `${template.label} (Managed)` }
       : template;
@@ -334,25 +377,6 @@ export function seedInferenceProfiles(
     profiles[name] = next as ProfileEntry;
   }
 
-  // 1b. Auto profile — a metadata-only profile with no provider/model. When
-  //     the user selects "Auto", the resolver falls through to the call-site
-  //     default (balanced or custom-balanced), and the agent loop injects the
-  //     switch_inference_profile tool so the model can self-select per query.
-  if (!preservedProfileNames.has(AUTO_PROFILE_KEY)) {
-    const previousAuto = readObject(profiles[AUTO_PROFILE_KEY]);
-    const autoEntry: Record<string, unknown> = {
-      source: "managed",
-      label: "Auto",
-      description:
-        "Automatically routes each query to the best profile — fast for simple questions, capable for complex ones",
-    };
-    if (previousAuto) {
-      if ("label" in previousAuto) autoEntry.label = previousAuto.label;
-      if ("status" in previousAuto) autoEntry.status = previousAuto.status;
-    }
-    profiles[AUTO_PROFILE_KEY] = autoEntry as ProfileEntry;
-  }
-
   // 2. User profiles — only at hatch time for off-platform installations.
   let userConnectionName: string | undefined;
   if (options.isHatch && !isPlatform) {
@@ -394,6 +418,8 @@ export function seedInferenceProfiles(
     }
   }
 
+  pruneNonDispatchableProfiles(llm, profiles);
+
   // Active profile resolution.
   const requestedActiveProfile = readString(llm.activeProfile);
   const requestedActiveEntry =
@@ -414,26 +440,26 @@ export function seedInferenceProfiles(
   }
 
   // Advisor profile: default to the strongest managed profile when unset, so
-  // the advisor consults `quality-optimized` out of the box. Guarded on
-  // existence so it never names a missing profile (superRefine rejects that);
-  // off-platform/BYOK installs can repoint it at one of their own profiles.
-  if (
-    readString(llm.advisorProfile) === undefined &&
-    readObject(profiles["quality-optimized"]) !== null
-  ) {
-    llm.advisorProfile = "quality-optimized";
+  // the advisor consults `frontier` (Anthropic Opus) out of the box, falling
+  // back to `quality-optimized` if `frontier` is unavailable. The `frontier`
+  // arm requires managed ownership: the seed loop above leaves a user-owned
+  // profile named `frontier` in place, and pointing the advisor at that would
+  // consult an arbitrary user model. Guarded on existence so it never names a
+  // missing profile (superRefine rejects that); off-platform/BYOK installs can
+  // repoint it at one of their own profiles.
+  if (readString(llm.advisorProfile) === undefined) {
+    if (readObject(profiles["frontier"])?.source === "managed") {
+      llm.advisorProfile = "frontier";
+    } else if (readObject(profiles["quality-optimized"]) !== null) {
+      llm.advisorProfile = "quality-optimized";
+    }
   }
 
   // Profile ordering — ensure all seeded profiles appear in the order array.
-  // "auto" is prepended so it appears first in the picker.
   const profileOrder = Array.isArray(llm.profileOrder)
     ? (llm.profileOrder as string[])
     : [];
   const orderSet = new Set(profileOrder);
-  if (!orderSet.has(AUTO_PROFILE_KEY)) {
-    profileOrder.unshift(AUTO_PROFILE_KEY);
-    orderSet.add(AUTO_PROFILE_KEY);
-  }
   for (const name of Object.keys(MANAGED_PROFILE_TEMPLATES)) {
     if (!orderSet.has(name)) {
       profileOrder.push(name);
@@ -490,6 +516,77 @@ export function readObject(value: unknown): Record<string, unknown> | null {
     : null;
 }
 
+function pruneNonDispatchableProfiles(
+  llm: Record<string, unknown>,
+  profiles: Record<string, Record<string, unknown>>,
+): void {
+  const removed = new Set<string>();
+  for (const [name, profile] of Object.entries(profiles)) {
+    if (!isDispatchableProfile(profile)) {
+      delete profiles[name];
+      removed.add(name);
+    }
+  }
+  pruneRemovedProfileReferences(llm, profiles, removed);
+}
+
+function pruneRemovedProfileReferences(
+  llm: Record<string, unknown>,
+  profiles: Record<string, Record<string, unknown>>,
+  removed: Set<string>,
+): void {
+  if (removed.size === 0) return;
+
+  let cascading = true;
+  while (cascading) {
+    cascading = false;
+    for (const [name, profile] of Object.entries(profiles)) {
+      if (removed.has(name)) continue;
+      if (!Array.isArray(profile.mix)) continue;
+      const arms = profile.mix as unknown[];
+      const kept = arms.filter((arm) => {
+        const armProfile = readObject(arm)?.profile;
+        return typeof armProfile !== "string" || !removed.has(armProfile);
+      });
+      if (kept.length === arms.length) continue;
+      if (kept.length >= MIX_MIN_ARMS) {
+        profile.mix = kept;
+      } else {
+        delete profiles[name];
+        removed.add(name);
+      }
+      cascading = true;
+    }
+  }
+
+  if (Array.isArray(llm.profileOrder)) {
+    llm.profileOrder = (llm.profileOrder as unknown[]).filter(
+      (name) => typeof name !== "string" || !removed.has(name),
+    );
+  }
+
+  if (
+    typeof llm.advisorProfile === "string" &&
+    removed.has(llm.advisorProfile)
+  ) {
+    delete llm.advisorProfile;
+  }
+
+  const callSites = readObject(llm.callSites);
+  if (callSites) {
+    for (const entry of Object.values(callSites)) {
+      const site = readObject(entry);
+      if (
+        site &&
+        typeof site.profile === "string" &&
+        removed.has(site.profile)
+      ) {
+        delete site.profile;
+      }
+    }
+  }
+}
+
 function readString(value: unknown): string | undefined {
   return typeof value === "string" && value.length > 0 ? value : undefined;
 }

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/config/sync-gated-profiles.ts

@@ -193,7 +193,19 @@ function disableProfile(
     typeof llm.advisorProfile === "string" &&
     removed.has(llm.advisorProfile)
   ) {
-    if (readObject(profiles["quality-optimized"]) !== null) {
+    // Repoint the advisor at the managed Frontier profile (the strongest).
+    // `frontier` is seeded unconditionally every boot, so target it even if it
+    // has not been materialized yet this startup — this reconcile can run before
+    // the seeder in the boot sequence, and the later seeder won't rewrite an
+    // already-set `advisorProfile`. The exception is a user-owned profile named
+    // `frontier`: that is not ours to route to, so fall back to the
+    // always-managed Quality profile, then clear the pointer as a last resort.
+    const frontierEntry = readObject(profiles["frontier"]);
+    const frontierIsUserOwned =
+      frontierEntry !== null && frontierEntry.source !== "managed";
+    if (!frontierIsUserOwned) {
+      llm.advisorProfile = "frontier";
+    } else if (readObject(profiles["quality-optimized"]) !== null) {
       llm.advisorProfile = "quality-optimized";
     } else {
       delete llm.advisorProfile;

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();
+  });
+});