@vellumai/assistant 0.9.0 → 0.10.0-dev.202606192226.8ed8a6a

package/src/memory/__tests__/onboarding-events-store.test.ts

@@ -8,10 +8,10 @@ mock.module("../../util/logger.js", () => ({
     }),
 }));
 
-// Mutable usage-data gate, flipped per-test.
-let collectUsageData = true;
-mock.module("../../config/loader.js", () => ({
-  getConfig: () => ({ collectUsageData }),
+// Mutable consent gate, flipped per-test.
+let shareAnalytics = true;
+mock.module("../../platform/consent-cache.js", () => ({
+  getCachedShareAnalytics: () => shareAnalytics,
 }));
 
 import { getDb } from "../db-connection.js";
@@ -30,7 +30,7 @@ function resetTable(): void {
 
 describe("onboarding-events-store: recordActivationEvent", () => {
   beforeEach(() => {
-    collectUsageData = true;
+    shareAnalytics = true;
     resetTable();
   });
 
@@ -66,8 +66,8 @@ describe("onboarding-events-store: recordActivationEvent", () => {
     expect(rows[0]!.stepIndex).toBe(2);
   });
 
-  test("returns null and writes no row when collectUsageData is disabled", () => {
-    collectUsageData = false;
+  test("returns null and writes no row when share_analytics is disabled", () => {
+    shareAnalytics = false;
     const event = recordActivationEvent({
       stepName: "activation_moment_1_complete",
       sessionId: "conv-3",

package/src/memory/auth-fallback-events-store.ts

@@ -1,7 +1,7 @@
 import { and, asc, eq, gt, or } from "drizzle-orm";
 import { v4 as uuid } from "uuid";
 
-import { getConfig } from "../config/loader.js";
+import { getCachedShareAnalytics } from "../platform/consent-cache.js";
 import { getDb } from "./db-connection.js";
 import { authFallbackEvents } from "./schema.js";
 
@@ -36,7 +36,7 @@ export function recordAuthFallbackCounts(
   windowEnd: number,
   counts: AuthFallbackCount[],
 ): number {
-  if (!getConfig().collectUsageData) return 0;
+  if (!getCachedShareAnalytics()) return 0;
   if (counts.length === 0) return 0;
   const db = getDb();
   const createdAt = Date.now();

package/src/memory/auto-analysis-enqueue.ts

@@ -1,9 +1,7 @@
 import { isAssistantFeatureFlagEnabled } from "../config/assistant-feature-flags.js";
 import { getConfig } from "../config/loader.js";
-import {
-  isUntrustedTrustClass,
-  type TrustClass,
-} from "../runtime/actor-trust-resolver.js";
+import { type TrustClass } from "../runtime/actor-trust-resolver.js";
+import { resolveCapabilities } from "../runtime/capabilities.js";
 import { getLogger } from "../util/logger.js";
 import { isAutoAnalysisConversation } from "./auto-analysis-guard.js";
 import { isMemoryEnabled, upsertAutoAnalysisJob } from "./jobs-store.js";
@@ -118,7 +116,7 @@ export function enqueueAutoAnalysisOnCompaction(
   conversationId: string,
   trustClass: TrustClass | undefined,
 ): void {
-  if (isUntrustedTrustClass(trustClass)) {
+  if (!resolveCapabilities(trustClass).canAccessMemory) {
     return;
   }
   try {

package/src/memory/bookmark-crud.ts

@@ -7,8 +7,7 @@ import { conversations, messageBookmarks, messages } from "./schema.js";
 
 /**
  * Wire-shape representation of a bookmark, joined with the bookmarked
- * message and its parent conversation. Mirrors
- * `clients/shared/Network/BookmarkSummary.swift` — dates are emitted as
+ * message and its parent conversation. Dates are emitted as
  * unix-millisecond integers, and the message preview is capped to keep
  * the list payload bounded.
  */

package/src/memory/canonical-guardian-store.ts

@@ -74,7 +74,7 @@ export interface CanonicalGuardianRequest {
   updatedAt: number;
 }
 
-interface CanonicalGuardianDelivery {
+export interface CanonicalGuardianDelivery {
   id: string;
   requestId: string;
   destinationChannel: string;
@@ -674,6 +674,44 @@ export function listPendingCanonicalGuardianRequestsByDestinationChat(
   return pendingRequests;
 }
 
+/**
+ * Find the pending canonical request whose guardian-facing delivery landed on a
+ * specific channel message (channel + chat + message id).
+ *
+ * This is the addressing key for emoji-reaction decisions: a reaction carries
+ * only the message it is attached to, so the delivered card's message id is how
+ * we recover which request the guardian acted on — even when several cards are
+ * pending in the same chat. Returns null when no delivery matches or the matched
+ * request is no longer pending.
+ */
+export function getPendingCanonicalRequestByDestinationMessage(
+  destinationChannel: string,
+  destinationChatId: string,
+  destinationMessageId: string,
+): CanonicalGuardianRequest | null {
+  const db = getDb();
+
+  const delivery = db
+    .select()
+    .from(canonicalGuardianDeliveries)
+    .where(
+      and(
+        eq(canonicalGuardianDeliveries.destinationChannel, destinationChannel),
+        eq(canonicalGuardianDeliveries.destinationChatId, destinationChatId),
+        eq(
+          canonicalGuardianDeliveries.destinationMessageId,
+          destinationMessageId,
+        ),
+      ),
+    )
+    .get();
+
+  if (!delivery) return null;
+
+  const request = getCanonicalGuardianRequest(delivery.requestId);
+  return request && request.status === "pending" ? request : null;
+}
+
 // ---------------------------------------------------------------------------
 // Conversation scope helpers
 // ---------------------------------------------------------------------------

package/src/memory/conversation-crud.ts

@@ -129,7 +129,7 @@ export const messageMetadataSchema = z
      * and read gate (conversation history loading) to enforce trust-aware access.
      */
     provenanceTrustClass: z
-      .enum(["guardian", "trusted_contact", "unknown"])
+      .enum(["guardian", "trusted_contact", "unverified_contact", "unknown"])
       .optional(),
     provenanceSourceChannel: channelIdSchema.optional(),
     provenanceGuardianExternalUserId: z.string().optional(),
@@ -2575,12 +2575,17 @@ export function getConversationOriginInterface(
  * in the given conversation, or `undefined` if none is found.
  *
  * Used by the pointer message trust resolver to detect conversations
- * whose audience is a guardian or trusted_contact outside desktop-origin
- * conversations.
+ * whose audience is a guardian, trusted_contact, or unverified_contact
+ * outside desktop-origin conversations.
  */
 export function getConversationRecentProvenanceTrustClass(
   conversationId: string,
-): "guardian" | "trusted_contact" | "unknown" | undefined {
+):
+  | "guardian"
+  | "trusted_contact"
+  | "unverified_contact"
+  | "unknown"
+  | undefined {
   const row = rawGet<{ metadata: string | null }>(
     `SELECT metadata FROM messages
      WHERE conversation_id = ? AND role = 'user' AND metadata IS NOT NULL

package/src/memory/conversation-key-store.ts

@@ -135,7 +135,16 @@ export function resolveConversationId(idOrKey: string): string | null {
  */
 export function getOrCreateConversation(
   conversationKey: string,
-  opts?: { conversationType?: "standard" },
+  opts?: {
+    conversationType?: "standard";
+    /**
+     * Caller-supplied title for the conversation, used only when this call
+     * actually creates the row. Treated as a user-set title (`isAutoTitle = 0`)
+     * so the async LLM title generator's safe-overwrite check leaves it
+     * untouched. Ignored when the conversation already exists.
+     */
+    title?: string;
+  },
 ): {
   conversationId: string;
   conversationType: string;
@@ -205,13 +214,19 @@ export function getOrCreateConversation(
 
     const now = Date.now();
     const conversationId = uuid();
-    const title = GENERATING_TITLE;
+    const customTitle = opts?.title?.trim();
+    const title = customTitle || GENERATING_TITLE;
     const memoryScopeId = "default";
 
     tx.insert(conversations)
       .values({
         id: conversationId,
         title,
+        // A caller-supplied title is user-set: mark it non-auto (0) so the
+        // async LLM title generator's `canReplaceTitle` check won't overwrite
+        // it. Without one, omit the column so it takes its default
+        // (AUTO_TITLE_LLM) and follows the auto-generated placeholder flow.
+        ...(customTitle ? { isAutoTitle: 0 } : {}),
         createdAt: now,
         updatedAt: now,
         totalInputTokens: 0,

package/src/memory/conversation-title-service.ts

@@ -166,6 +166,7 @@ export async function generateAndPersistConversationTitle(
     const fallback = deriveFallbackTitle(context) ?? UNTITLED_FALLBACK;
     updateConversationTitle(conversationId, fallback, AUTO_TITLE_DETERMINISTIC);
     publishConversationTitleChanged(conversationId, fallback);
+    logRetryableFallback(params, "no_provider");
     return { title: fallback, updated: true };
   }
 
@@ -206,6 +207,7 @@ export async function generateAndPersistConversationTitle(
   const fallback = deriveFallbackTitle(context) ?? UNTITLED_FALLBACK;
   updateConversationTitle(conversationId, fallback, AUTO_TITLE_DETERMINISTIC);
   publishConversationTitleChanged(conversationId, fallback);
+  logRetryableFallback(params, "empty_output");
   return { title: fallback, updated: true };
 }
 
@@ -230,7 +232,7 @@ export const titleMutex = new Mutex();
 /**
  * Fire-and-forget wrapper for title generation. Failures are logged
  * but do not propagate. On failure, replaces loading placeholder with
- * a stable fallback title so loading state is never permanent.
+ * a retryable fallback title so loading state is never permanent.
  *
  * Calls are serialized via {@link titleMutex} so burst conversation
  * creation does not overwhelm the LLM provider.
@@ -244,16 +246,20 @@ export function queueGenerateConversationTitle(
     })
     .catch((err) => {
       log.warn(
-        { err, conversationId: params.conversationId },
-        "Failed to generate conversation title (non-fatal)",
+        retryableFallbackLogFields(params, "generation_error", err),
+        "Conversation title generation used retryable fallback",
       );
-      // Replace loading placeholder with stable fallback
+      // Replace loading placeholder with a retryable fallback.
       try {
         const conversation = getConversation(params.conversationId);
         if (conversation && conversation.title === GENERATING_TITLE) {
           const fallback =
             deriveFallbackTitle(params.context) ?? UNTITLED_FALLBACK;
-          updateConversationTitle(params.conversationId, fallback);
+          updateConversationTitle(
+            params.conversationId,
+            fallback,
+            AUTO_TITLE_DETERMINISTIC,
+          );
           publishConversationTitleChanged(params.conversationId, fallback);
         }
       } catch {
@@ -268,6 +274,11 @@ export interface RegenerateTitleParams {
   conversationId: string;
   provider?: Provider;
   signal?: AbortSignal;
+  /**
+   * Limit regeneration to placeholder or deterministic titles. Used for retrying
+   * failed initial generation without racing against a successful initial title.
+   */
+  onlyIfReplaceable?: boolean;
 }
 
 /**
@@ -278,12 +289,15 @@ export interface RegenerateTitleParams {
 export async function regenerateConversationTitle(
   params: RegenerateTitleParams,
 ): Promise<{ title: string; updated: boolean }> {
-  const { conversationId, signal } = params;
+  const { conversationId, onlyIfReplaceable, signal } = params;
 
   const conversation = getConversation(conversationId);
   if (!conversation || !conversation.isAutoTitle) {
     return { title: conversation?.title ?? UNTITLED_FALLBACK, updated: false };
   }
+  if (onlyIfReplaceable && !canReplaceTitle(conversation)) {
+    return { title: conversation.title ?? UNTITLED_FALLBACK, updated: false };
+  }
 
   const provider =
     params.provider ?? (await getConfiguredProvider("conversationTitle"));
@@ -317,7 +331,11 @@ export async function regenerateConversationTitle(
   if (title) {
     // Re-check isAutoTitle before persisting (race guard against manual rename)
     const current = getConversation(conversationId);
-    if (!current || !current.isAutoTitle) {
+    if (
+      !current ||
+      !current.isAutoTitle ||
+      (onlyIfReplaceable && !canReplaceTitle(current))
+    ) {
       return { title: current?.title ?? UNTITLED_FALLBACK, updated: false };
     }
 
@@ -408,6 +426,45 @@ function buildTitlePrompt(
   return parts.join("\n");
 }
 
+function titleGenerationLogFields(params: GenerateTitleParams) {
+  return {
+    conversationId: params.conversationId,
+    contextOrigin: params.context?.origin,
+    hasContext: Boolean(params.context),
+    userMessageLength: params.userMessage?.length ?? 0,
+    assistantResponseLength: params.assistantResponse?.length ?? 0,
+  };
+}
+
+type TitleGenerationFallbackReason =
+  | "no_provider"
+  | "empty_output"
+  | "generation_error";
+
+function retryableFallbackLogFields(
+  params: GenerateTitleParams,
+  reason: TitleGenerationFallbackReason,
+  err?: unknown,
+): Record<string, unknown> {
+  const fields: Record<string, unknown> = {
+    ...titleGenerationLogFields(params),
+    reason,
+    fallbackSource: params.context ? "context" : "untitled",
+  };
+  if (err) fields.err = err;
+  return fields;
+}
+
+function logRetryableFallback(
+  params: GenerateTitleParams,
+  reason: TitleGenerationFallbackReason,
+): void {
+  log.warn(
+    retryableFallbackLogFields(params, reason),
+    "Conversation title generation used retryable fallback",
+  );
+}
+
 const META_FAILURE_TITLES = new Set([
   "missing context",
   "no context",

package/src/memory/db-async-query.ts

@@ -61,6 +61,19 @@ export interface RunAsyncSqliteOptions {
    * the runtime pick.
    */
   forceBackend?: AsyncSqliteBackend;
+  /**
+   * Database file to run the statement against. Defaults to the main
+   * assistant DB (`getDbPath()`). Pass `getLogsDbPath()` to target the
+   * secondary append-only file directly.
+   *
+   * This only affects the `sqlite3-cli` backend, which opens the given file
+   * as its own `main` database — so a statement like
+   * `DELETE FROM llm_request_logs` runs against the right file with no ATTACH.
+   * The in-process fallback always runs on the daemon connection, which has
+   * the logs DB ATTACHed, so unqualified table names already resolve to the
+   * correct file regardless of this option.
+   */
+  dbPath?: string;
 }
 
 let warnedAboutFallback = false;
@@ -74,7 +87,12 @@ export async function runAsyncSqlite(
     forced === "in-process-blocking" ? undefined : findSqlite3();
 
   if (sqlite3Path && forced !== "in-process-blocking") {
-    return runViaCli(sqlite3Path, sql, options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    return runViaCli(
+      sqlite3Path,
+      sql,
+      options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+      options.dbPath ?? getDbPath(),
+    );
   }
 
   if (!warnedAboutFallback) {
@@ -97,9 +115,9 @@ async function runViaCli(
   sqlite3Path: string,
   sql: string,
   timeoutMs: number,
+  dbPath: string,
 ): Promise<AsyncSqliteResult> {
   const startMs = Date.now();
-  const dbPath = getDbPath();
 
   log.info(
     { sqlite3Path, dbPath, timeoutMs, sqlPreview: sql.slice(0, 80) },

package/src/memory/db-connection.ts

@@ -5,16 +5,59 @@ import { Database } from "bun:sqlite";
 
 import { drizzle } from "drizzle-orm/bun-sqlite";
 
+import { getLogsDbPath } from "../util/logs-db-path.js";
 import { ensureDataDir, getDbPath } from "../util/platform.js";
-import {
-  clearStoredDb,
-  getStoredDb,
-  setStoredDb,
-} from "./db-singleton.js";
+import { clearStoredDb, getStoredDb, setStoredDb } from "./db-singleton.js";
 import * as schema from "./schema.js";
 
 export type DrizzleDb = ReturnType<typeof drizzle<typeof schema>>;
 
+/**
+ * Schema name under which the secondary append-only database file
+ * (`assistant-logs.db`) is ATTACHed to the main connection. Tables created in
+ * this schema (e.g. `logs.llm_request_logs`) live in the separate file but are
+ * still queryable — and joinable against main-schema tables — over the single
+ * daemon connection. Because no append-only table exists in the `main` schema,
+ * unqualified references (e.g. `llm_request_logs`) resolve to the attached copy.
+ */
+export const LOGS_DB_SCHEMA = "logs";
+
+/**
+ * ATTACH the append-only logs database to an open connection and apply its
+ * per-database PRAGMAs.
+ *
+ * `journal_mode` and `synchronous` are per-database settings, so they must be
+ * set against the attached schema explicitly — the PRAGMAs run on `main` before
+ * the attach do not carry over. `busy_timeout`, `foreign_keys`, `cache_size`,
+ * and `temp_store` are connection-wide and already configured on the connection.
+ *
+ * Best-effort: a failure here (e.g. a filesystem permission problem on the new
+ * file) must not take down the main database. We log and continue in line with
+ * the daemon's "never block startup on a subsystem failure" policy; append-only
+ * tables are simply unavailable until the next successful open.
+ *
+ * The logger is pulled in lazily (dynamic import) only on the error path. This
+ * file is intentionally kept import-light — see `db-singleton.ts` — so it does
+ * not take a static dependency on the logger (and transitively on pino).
+ */
+function attachLogsDb(sqlite: Database): void {
+  const logsPath = getLogsDbPath();
+  try {
+    // Escape single quotes for the SQL string literal (paths can contain them).
+    const escaped = logsPath.replace(/'/g, "''");
+    sqlite.exec(`ATTACH DATABASE '${escaped}' AS ${LOGS_DB_SCHEMA}`);
+    sqlite.exec(`PRAGMA ${LOGS_DB_SCHEMA}.journal_mode=WAL`);
+    sqlite.exec(`PRAGMA ${LOGS_DB_SCHEMA}.synchronous=FULL`);
+  } catch (err) {
+    void import("../util/logger.js").then(({ getLogger }) =>
+      getLogger("db-connection").error(
+        { err, logsPath },
+        "Failed to ATTACH logs database; append-only log tables will be unavailable",
+      ),
+    );
+  }
+}
+
 function canonicalizePathThroughExistingParent(path: string): string {
   const resolvedPath = resolve(path);
   const pendingSegments: string[] = [];
@@ -86,6 +129,7 @@ export function getDb(): DrizzleDb {
   sqlite.exec("PRAGMA foreign_keys = ON");
   sqlite.exec("PRAGMA cache_size=-256000");
   sqlite.exec("PRAGMA temp_store=MEMORY");
+  attachLogsDb(sqlite);
   const db = drizzle(sqlite, { schema });
   setStoredDb(db, () => sqlite.close());
   return db;

package/src/memory/db-init.ts

@@ -40,6 +40,7 @@ import {
   createSkillLoadedEventsTable,
   createTasksAndWorkItemsTables,
   createWatchersAndLogsTables,
+  dropApprovalPromptTsTrackerTable,
   migrate230AcpSessionHistory,
   migrate231RepairMemoryGraphEventDates,
   migrateA2ATasks,
@@ -68,6 +69,7 @@ import {
   migrateChannelInboundDeliveryAttempts,
   migrateChannelInteractionColumns,
   migrateContactChannelsAccessFields,
+  migrateContactChannelsRenormalizeAddresses,
   migrateContactChannelsTypeChatIdIndex,
   migrateContactChannelsUniqueExtUser,
   migrateContactsAssistantId,
@@ -101,6 +103,7 @@ import {
   migrateDropConflicts,
   migrateDropContactInteractionColumns,
   migrateDropEntityTables,
+  migrateDropExternalUserId,
   migrateDropLegacyMemberGuardianTables,
   migrateDropLoopbackPortColumn,
   migrateDropMemoryItemsTables,
@@ -194,7 +197,9 @@ import {
   migrateRenameVerificationSessionIdColumn,
   migrateRenameVerificationTable,
   migrateRenameVoiceToPhone,
+  migrateRewriteBalancedEconomyProfilePins,
   migrateScheduleCapabilities,
+  migrateScheduleDefaultNoReuseConversation,
   migrateScheduleDescription,
   migrateScheduleInferenceProfile,
   migrateScheduleOneShotRouting,
@@ -222,6 +227,7 @@ import {
   migrateUsageLlmCallCount,
   migrateVoiceInviteColumns,
   migrateVoiceInviteDisplayMetadata,
+  migrateWorkflowJournalLeafTokens,
   migrateWorkflowRuns,
   migrateWorkflowRunTrust,
   recoverCrashedMigrations,
@@ -229,6 +235,7 @@ import {
   runLateMigrations,
   validateMigrationState,
 } from "./migrations/index.js";
+import { runMigrationSteps } from "./migrations/run-migrations.js";
 
 // ---------------------------------------------------------------------------
 // Test DB template — run migrations once, reuse across test files
@@ -518,29 +525,22 @@ export function initializeDb(): void {
     migrateBackfillOriginChannelFromBindings,
     migrateContactChannelsUniqueExtUser,
     migrateScheduleCapabilities,
+    migrateContactChannelsRenormalizeAddresses,
+    migrateScheduleDefaultNoReuseConversation,
+    migrateWorkflowJournalLeafTokens,
+    migrateDropExternalUserId,
+    dropApprovalPromptTsTrackerTable,
+    migrateRewriteBalancedEconomyProfilePins,
   ];
 
   // Run each migration step, catching and logging individual failures so one
   // broken migration doesn't prevent independent later ones from succeeding.
-  const failures: string[] = [];
-  for (const step of migrationSteps) {
-    try {
-      log.debug({ migration: step.name }, `Starting migration: ${step.name}`);
-      step(database);
-      log.debug({ migration: step.name }, `Migration succeeded: ${step.name}`);
-    } catch (err) {
-      failures.push(step.name);
-      log.error(
-        { err, migration: step.name },
-        `Migration failed: ${step.name}`,
-      );
-    }
-  }
+  const { failed } = runMigrationSteps(database, migrationSteps);
 
-  if (failures.length > 0) {
+  if (failed.length > 0) {
     log.error(
-      { failedMigrations: failures, count: failures.length },
-      `DB initialization completed with ${failures.length} failed migration(s)`,
+      { failedMigrations: failed, count: failed.length },
+      `DB initialization completed with ${failed.length} failed migration(s)`,
     );
   }
 

package/src/memory/embedding-backend.ts

@@ -7,6 +7,13 @@ import { PLATFORM_PROVIDER_META } from "../providers/platform-proxy/constants.js
 import { resolveManagedProxyContext } from "../providers/platform-proxy/context.js";
 import { getProviderKeyAsync } from "../security/secure-keys.js";
 import { getLogger } from "../util/logger.js";
+import {
+  EmbeddingBillingBlockError,
+  extractHttpStatus,
+  isEmbeddingBillingBreakerOpen,
+  recordBillingBlock,
+  recordBillingSuccess,
+} from "./embedding-billing-breaker.js";
 import { GeminiEmbeddingBackend } from "./embedding-gemini.js";
 import { OllamaEmbeddingBackend } from "./embedding-ollama.js";
 import { OpenAIEmbeddingBackend } from "./embedding-openai.js";
@@ -490,6 +497,20 @@ export async function getMemoryBackendStatus(config: AssistantConfig): Promise<{
   };
 }
 
+/**
+ * Thrown by {@link embedWithBackend} when no embedding backend is configured or
+ * available. This is a PROCESS-WIDE condition (backend selection is effectively
+ * cached for the run), so a caller embedding many items should treat the first
+ * occurrence as fatal to the whole batch rather than a per-item failure — see
+ * `backfillAllSections`, which aborts on it instead of churning through deletes.
+ */
+export class EmbeddingBackendUnavailableError extends Error {
+  constructor(message = "No memory embedding backend configured") {
+    super(message);
+    this.name = "EmbeddingBackendUnavailableError";
+  }
+}
+
 export async function embedWithBackend(
   config: AssistantConfig,
   inputs: EmbeddingInput[],
@@ -499,9 +520,15 @@ export async function embedWithBackend(
   model: string;
   vectors: number[][];
 }> {
+  // Fail-fast when the billing breaker is open — avoids burning a network
+  // round-trip on every caller (embed lane jobs, activation recompute, etc.).
+  if (isEmbeddingBillingBreakerOpen()) {
+    throw new EmbeddingBillingBlockError();
+  }
+
   const selection = await selectEmbeddingBackend(config);
   if (!selection.backend) {
-    throw new Error(
+    throw new EmbeddingBackendUnavailableError(
       selection.reason ?? "No memory embedding backend configured",
     );
   }
@@ -612,6 +639,10 @@ export async function embedWithBackend(
         );
       }
 
+      // A successful backend call proves billing is active — close the
+      // breaker if it was in the probe window.
+      recordBillingSuccess();
+
       if (isPrimary) {
         const merged = [...cached] as number[][];
         for (let i = 0; i < uncachedIndices.length; i++) {
@@ -626,6 +657,12 @@ export async function embedWithBackend(
       return { provider: backend.provider, model: backend.model, vectors };
     } catch (err) {
       lastErr = err;
+      // If ANY backend in the chain returns 402, trip the billing breaker
+      // immediately — fallbacks will hit the same depleted balance.
+      if (extractHttpStatus(err) === 402) {
+        recordBillingBlock();
+        throw err;
+      }
       if (backends.length > 1) {
         log.warn(
           { err, provider: backend.provider },