@vellumai/assistant 0.11.6-dev.202608261918.60eeea2 → 0.11.6-dev.202608261937.a51ea3f

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.11.6-dev.202608261918.60eeea2",
+  "version": "0.11.6-dev.202608261937.a51ea3f",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/plugin-import-boundary-guard.test.ts

@@ -128,7 +128,7 @@ const BASELINE: Record<string, readonly string[]> = {
     "../../../../daemon/embedding-reconcile.js",
     "../../../../daemon/trust-context.js",
     "../../../../daemon/turn-latency-sub-spans.js",
-    "../../../../notifications/emit-signal.js",
+    "../../../../notifications/background-failure-signal.js",
     "../../../../persistence/checkpoints.js",
     "../../../../persistence/conversation-types.js",
     "../../../../persistence/db-connection.js",

package/src/__tests__/schedule-retry.test.ts

@@ -36,11 +36,17 @@ mock.module("../runtime/background-job-runner.js", () => ({
       return { conversationId, ok: true };
     } catch (err) {
       const error = err instanceof Error ? err : new Error(String(err));
+      const classification = runnerFailureClassification ?? {
+        errorKind: "exception" as const,
+      };
       return {
         conversationId,
         ok: false,
         error,
-        ...(runnerFailureClassification ?? { errorKind: "exception" as const }),
+        errorKind: classification.errorKind,
+        ...(classification.failureCode !== undefined
+          ? { turnFailure: { failureCode: classification.failureCode } }
+          : {}),
       };
     }
   },

package/src/daemon/conversation-agent-loop-handlers.ts

@@ -245,6 +245,14 @@ export interface EventHandlerState {
    * the loop persists the failure as an assistant message.
    */
   providerErrorCategory: string | null;
+  /**
+   * Connection and profile attribution of the most recent provider error
+   * (`classifyConversationError(...).connectionName` / `.profileName`).
+   * Carried into the turn's outcome stamp so failure consumers scope
+   * identity by the route the call actually resolved.
+   */
+  providerErrorConnection: string | null;
+  providerErrorProfile: string | null;
   persistProviderErrorAsAssistantMessage: boolean;
   lastAssistantMessageId: string | undefined;
   /**
@@ -599,6 +607,8 @@ export function createEventHandlerState(): EventHandlerState {
     providerErrorUserMessage: null,
     providerErrorCode: null,
     providerErrorCategory: null,
+    providerErrorConnection: null,
+    providerErrorProfile: null,
     persistProviderErrorAsAssistantMessage: false,
     lastAssistantMessageId: undefined,
     assistantRowAwaitingFinalization: false,
@@ -2732,6 +2742,8 @@ function handleError(
   state.providerErrorUserMessage = classified.userMessage;
   state.providerErrorCode = classified.code;
   state.providerErrorCategory = classified.errorCategory;
+  state.providerErrorConnection = classified.connectionName ?? null;
+  state.providerErrorProfile = classified.profileName ?? null;
   state.persistProviderErrorAsAssistantMessage =
     shouldPersistProviderErrorAsAssistantMessage(classified);
 }

package/src/daemon/conversation-agent-loop.ts

@@ -733,8 +733,33 @@ export async function runAgentLoopImpl(
   // the `finally` (before processing clears, so the reporter's settled-turn
   // barrier guarantees the stamp ships with the turn event). Unset = the turn
   // replied normally and carries no stamp.
+  const failedOutcomeFromClassification = (classified: {
+    code: string;
+    userMessage: string;
+    errorCategory: string;
+    connectionName?: string;
+    profileName?: string;
+  }): NonNullable<typeof abnormalOutcome> => ({
+    outcome: "failed",
+    failureCode: classified.code,
+    failureMessage: classified.userMessage,
+    failureCategory: classified.errorCategory,
+    ...(classified.connectionName
+      ? { failureConnection: classified.connectionName }
+      : {}),
+    ...(classified.profileName
+      ? { failureProfile: classified.profileName }
+      : {}),
+  });
   let abnormalOutcome:
-    | { outcome: "failed" | "cancelled"; failureCode?: string }
+    | {
+        outcome: "failed" | "cancelled";
+        failureCode?: string;
+        failureMessage?: string;
+        failureCategory?: string;
+        failureConnection?: string;
+        failureProfile?: string;
+      }
     | undefined;
   // True once a replied terminal SSE (message_complete / generation_handoff)
   // has been emitted. Guards the catch block: an error thrown by the
@@ -777,6 +802,10 @@ export async function runAgentLoopImpl(
       try {
         stampTurnOutcome(userMessageId, abnormalOutcome.outcome, {
           failureCode: abnormalOutcome.failureCode,
+          failureMessage: abnormalOutcome.failureMessage,
+          failureCategory: abnormalOutcome.failureCategory,
+          failureConnection: abnormalOutcome.failureConnection,
+          failureProfile: abnormalOutcome.failureProfile,
         });
       } catch (err) {
         rlog.warn(
@@ -858,6 +887,7 @@ export async function runAgentLoopImpl(
       abnormalOutcome = {
         outcome: "failed",
         failureCode: DISK_PRESSURE_ERROR_CODE,
+        failureMessage: message,
       };
       rlog.warn(
         { reason: diskPressureDecision.reason },
@@ -1382,17 +1412,16 @@ export async function runAgentLoopImpl(
       );
       // Exhausted-overflow exit: the reduction ladder is spent and the turn
       // ends without a real reply, so label it failed for telemetry.
-      abnormalOutcome = { outcome: "failed", failureCode: classified.code };
+      abnormalOutcome = failedOutcomeFromClassification(classified);
       onEvent(buildConversationErrorMessage(ctx.conversationId, classified));
     } else if (
       overflowTerminalReason === "budget_yield_unrecovered" &&
       !abortController.signal.aborted
     ) {
       budgetYieldClassification = budgetYieldUnrecoveredClassification();
-      abnormalOutcome = {
-        outcome: "failed",
-        failureCode: budgetYieldClassification.code,
-      };
+      abnormalOutcome = failedOutcomeFromClassification(
+        budgetYieldClassification,
+      );
       onEvent(
         buildConversationErrorMessage(
           ctx.conversationId,
@@ -1548,6 +1577,16 @@ export async function runAgentLoopImpl(
         ...(state.providerErrorCode
           ? { failureCode: state.providerErrorCode }
           : {}),
+        failureMessage: state.providerErrorUserMessage,
+        ...(state.providerErrorCategory
+          ? { failureCategory: state.providerErrorCategory }
+          : {}),
+        ...(state.providerErrorConnection
+          ? { failureConnection: state.providerErrorConnection }
+          : {}),
+        ...(state.providerErrorProfile
+          ? { failureProfile: state.providerErrorProfile }
+          : {}),
       };
       // Drop any reservation stranded by the failed LLM call. The B3
       // pre-allocation path reserves an empty assistant row at
@@ -1874,7 +1913,7 @@ export async function runAgentLoopImpl(
         ...turnErrorAttribution(),
       });
       if (!turnReplied) {
-        abnormalOutcome = { outcome: "failed", failureCode: classified.code };
+        abnormalOutcome = failedOutcomeFromClassification(classified);
       }
       onEvent({
         type: "error",

package/src/notifications/__tests__/background-failure-signal.test.ts

@@ -0,0 +1,107 @@
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+const emitCalls: Array<Record<string, unknown>> = [];
+mock.module("../emit-signal.js", () => ({
+  emitNotificationSignal: (params: Record<string, unknown>) => {
+    emitCalls.push(params);
+    return Promise.resolve({
+      signalId: "sig-1",
+      deduplicated: false,
+      dispatched: true,
+      reason: "ok",
+      deliveryResults: [],
+      pipelineFailed: false,
+    });
+  },
+}));
+
+const { emitBackgroundFailureSignal } =
+  await import("../background-failure-signal.js");
+
+describe("emitBackgroundFailureSignal", () => {
+  beforeEach(() => {
+    emitCalls.length = 0;
+  });
+
+  test("carried connection leads the dedupe scope and rides the payload", () => {
+    emitBackgroundFailureSignal({
+      jobName: "schedule:job-1",
+      displayName: "schedule:PR scan",
+      sourceChannel: "scheduler",
+      sourceContextId: "job-1",
+      errorKind: "model_provider",
+      errorMessage: "Agent turn failed (PROVIDER_BILLING)",
+      failureCode: "PROVIDER_BILLING",
+      failureSummary: "You're out of credits.",
+      errorCategory: "credits_exhausted",
+      connectionName: "conn-a",
+      profileName: "balanced",
+      fallbackProviderScope: "cost-optimized",
+    });
+
+    expect(emitCalls).toHaveLength(1);
+    const emitted = emitCalls[0];
+    expect(emitted.sourceEventName).toBe("activity.failed");
+    expect(emitted.dedupeKey as string).toMatch(
+      /^activity-failed:cause:PROVIDER_BILLING:conn-a:\d{4}-\d{2}-\d{2}$/,
+    );
+    expect(emitted.contextPayload).toMatchObject({
+      jobName: "schedule:PR scan",
+      errorKind: "model_provider",
+      failureCode: "PROVIDER_BILLING",
+      failureSummary: "You're out of credits.",
+      errorCategory: "credits_exhausted",
+      connectionName: "conn-a",
+    });
+  });
+
+  test("carried profile scopes when no connection is carried", () => {
+    emitBackgroundFailureSignal({
+      jobName: "heartbeat",
+      sourceChannel: "assistant_tool",
+      sourceContextId: "conv-1",
+      errorKind: "model_provider",
+      errorMessage: "rate limited",
+      failureCode: "PROVIDER_RATE_LIMIT",
+      profileName: "balanced",
+      fallbackProviderScope: "cost-optimized",
+    });
+
+    expect(emitCalls[0].dedupeKey as string).toMatch(
+      /^activity-failed:cause:PROVIDER_RATE_LIMIT:balanced:\d{4}-\d{2}-\d{2}$/,
+    );
+  });
+
+  test("recomputed fallback scopes when nothing is carried", () => {
+    emitBackgroundFailureSignal({
+      jobName: "watcher-a",
+      sourceChannel: "assistant_tool",
+      sourceContextId: "conv-2",
+      errorKind: "model_provider",
+      errorMessage: "provider returned 401",
+      fallbackProviderScope: "cost-optimized",
+    });
+
+    expect(emitCalls[0].dedupeKey as string).toMatch(
+      /^activity-failed:cause:model_provider:cost-optimized:\d{4}-\d{2}-\d{2}$/,
+    );
+  });
+
+  test("no scope at all keys per job", () => {
+    emitBackgroundFailureSignal({
+      jobName: "memory.v2.sweep",
+      sourceChannel: "scheduler",
+      sourceContextId: "job-9",
+      errorKind: "exception",
+      errorMessage: "boom",
+    });
+
+    expect(emitCalls[0].dedupeKey as string).toMatch(
+      /^activity-failed:memory\.v2\.sweep:\d{4}-\d{2}-\d{2}$/,
+    );
+    expect(emitCalls[0].contextPayload).toMatchObject({
+      jobName: "memory.v2.sweep",
+      errorKind: "exception",
+    });
+  });
+});

package/src/notifications/__tests__/copy-composer.test.ts

@@ -35,6 +35,89 @@ function makeSignal(
 
 const CHANNELS: NotificationChannel[] = ["vellum" as NotificationChannel];
 
+// ── activity.failed rendering ─────────────────────────────────────────
+
+describe("activity.failed copy", () => {
+  function failedSignal(
+    contextPayload: Record<string, unknown>,
+  ): NotificationSignal {
+    return makeSignal({
+      sourceEventName: "activity.failed",
+      contextPayload,
+    });
+  }
+
+  test("renders the carried classification message verbatim", () => {
+    const copy = composeFallbackCopy(
+      failedSignal({
+        jobName: "schedule:PR scan",
+        errorKind: "model_provider",
+        errorMessage: "Agent turn failed (PROVIDER_BILLING)",
+        failureSummary:
+          "You're out of credits. Add credits in Settings to continue.",
+      }),
+      CHANNELS,
+    );
+    expect(copy.vellum?.title).toBe("Background job failed: schedule:PR scan");
+    expect(copy.vellum?.body).toBe(
+      "You're out of credits. Add credits in Settings to continue.",
+    );
+  });
+
+  test("an oversized carried summary is bounded", () => {
+    const copy = composeFallbackCopy(
+      failedSignal({
+        jobName: "job",
+        errorKind: "model_provider",
+        errorMessage: "irrelevant",
+        failureSummary: "x".repeat(400),
+      }),
+      CHANNELS,
+    );
+    expect((copy.vellum?.body ?? "").length).toBeLessThanOrEqual(303);
+    expect(copy.vellum?.body).toEndWith("...");
+  });
+
+  test("constant-shaped raw detail never reaches the body", () => {
+    const copy = composeFallbackCopy(
+      failedSignal({
+        jobName: "heartbeat",
+        errorKind: "model_provider",
+        errorMessage: "Agent turn failed (PROVIDER_BILLING)",
+      }),
+      CHANNELS,
+    );
+    expect(copy.vellum?.body).toBe("The model provider did not respond.");
+    expect(copy.vellum?.body).not.toContain("PROVIDER_BILLING");
+  });
+
+  test("readable raw detail is appended to the kind prose", () => {
+    const copy = composeFallbackCopy(
+      failedSignal({
+        jobName: "watcher",
+        errorKind: "exception",
+        errorMessage: "The feed endpoint returned an empty document.",
+      }),
+      CHANNELS,
+    );
+    expect(copy.vellum?.body).toBe(
+      "It stopped with an error. The feed endpoint returned an empty document.",
+    );
+  });
+
+  test("timeout renders its own prose", () => {
+    const copy = composeFallbackCopy(
+      failedSignal({
+        jobName: "filing",
+        errorKind: "timeout",
+        errorMessage: "Background job 'filing' timed out after 1800000ms",
+      }),
+      CHANNELS,
+    );
+    expect(copy.vellum?.body).toContain("It ran out of time before finishing.");
+  });
+});
+
 // ── composeFallbackCopy with requestedMessage ─────────────────────────
 
 describe("composeFallbackCopy honors requestedMessage / requestedTitle", () => {

package/src/notifications/background-failure-signal.ts

@@ -0,0 +1,116 @@
+import type { BackgroundJobErrorKind } from "../runtime/background-job-runner.js";
+import { getLogger } from "../util/logger.js";
+import { activityFailedDedupeKey } from "./activity-failed-dedupe.js";
+import { emitNotificationSignal } from "./emit-signal.js";
+import type { NotificationSourceChannel } from "./signal.js";
+
+const log = getLogger("background-failure-signal");
+
+/**
+ * One background failure, as a producer reports it.
+ *
+ * The classification fields are the authored attribution carried out of the
+ * failing turn (`TurnFailure`): `failureSummary` is the classifier's
+ * user-facing message, and `profileName`/`connectionName` name the route the
+ * call actually resolved. Producers whose failures never ran a turn (a
+ * timeout, a bootstrap crash, a data job's own exception) leave them unset
+ * and the signal degrades to the classified kind.
+ */
+export interface BackgroundFailureReport {
+  /** Stable job identifier for logs and per-job dedupe, e.g. `heartbeat`. */
+  jobName: string;
+  /** Human-facing job label for notification copy. Defaults to `jobName`. */
+  displayName?: string;
+  sourceChannel: NotificationSourceChannel;
+  /** Conversation or job id the notification links back to. */
+  sourceContextId: string;
+  errorKind: BackgroundJobErrorKind;
+  /** Raw error text, carried for debugging; copy prefers `failureSummary`. */
+  errorMessage: string;
+  /** Stable classified code (`ConversationErrorCode`), when classified. */
+  failureCode?: string;
+  /** The classification's authored user-facing message, when carried. */
+  failureSummary?: string;
+  /** The classification's machine-readable category, when carried. */
+  errorCategory?: string;
+  /**
+   * Connection row the failing call resolved, when carried. The most precise
+   * route identity, so it leads the dedupe-scope hierarchy.
+   */
+  connectionName?: string;
+  /** Profile key the failing call resolved, when carried. */
+  profileName?: string;
+  /**
+   * Recomputed single-route profile key (see `resolveSingleRouteProfileKey`).
+   * Used only when the failure carries no attribution of its own.
+   */
+  fallbackProviderScope?: string;
+}
+
+/**
+ * The single emission seam for background-job failure notifications.
+ *
+ * Owns the payload shape, the dedupe-key derivation, and the attention hints
+ * so every producer (the background-job runner, the scheduler's
+ * retries-exhausted alert, standalone data jobs) reports the same way and a
+ * new producer cannot invent a divergent one. Fire-and-forget: emission
+ * errors are logged, never thrown, because a notification failure must not
+ * break the job path that reports it.
+ *
+ * The dedupe scope is the most precise route identity the failure carries:
+ * the resolved connection, else the resolved profile, else the recomputed
+ * fallback. Failures carrying less precision can split an incident into an
+ * extra notification (never merge two incidents into one), and the split
+ * shrinks as more paths carry attribution.
+ */
+export function emitBackgroundFailureSignal(
+  report: BackgroundFailureReport,
+): void {
+  const providerScope =
+    report.connectionName ?? report.profileName ?? report.fallbackProviderScope;
+  emitNotificationSignal({
+    sourceChannel: report.sourceChannel,
+    sourceContextId: report.sourceContextId,
+    sourceEventName: "activity.failed",
+    dedupeKey: activityFailedDedupeKey({
+      jobName: report.jobName,
+      errorKind: report.errorKind,
+      ...(report.failureCode !== undefined
+        ? { failureCode: report.failureCode }
+        : {}),
+      ...(providerScope !== undefined ? { providerScope } : {}),
+    }),
+    contextPayload: {
+      jobName: report.displayName ?? report.jobName,
+      errorMessage: report.errorMessage,
+      errorKind: report.errorKind,
+      ...(report.failureCode !== undefined
+        ? { failureCode: report.failureCode }
+        : {}),
+      ...(report.failureSummary !== undefined
+        ? { failureSummary: report.failureSummary }
+        : {}),
+      ...(report.errorCategory !== undefined
+        ? { errorCategory: report.errorCategory }
+        : {}),
+      ...(report.connectionName !== undefined
+        ? { connectionName: report.connectionName }
+        : {}),
+    },
+    attentionHints: {
+      requiresAction: false,
+      urgency: "medium",
+      isAsyncBackground: true,
+      visibleInSourceNow: false,
+    },
+  }).catch((emitErr) => {
+    log.warn(
+      {
+        err: emitErr instanceof Error ? emitErr.message : String(emitErr),
+        jobName: report.jobName,
+        sourceContextId: report.sourceContextId,
+      },
+      "Failed to emit background-failure notification",
+    );
+  });
+}

package/src/notifications/copy-composer.ts

@@ -10,6 +10,7 @@
  */
 
 import { normalizeTitle } from "../util/short-title.js";
+import { truncate } from "../util/truncate.js";
 import {
   accessRequestCardTitle,
   buildAccessRequestContractText,
@@ -41,6 +42,33 @@ import type { NotificationChannel, RenderedChannelCopy } from "./types.js";
 
 type CopyTemplate = (payload: Record<string, unknown>) => RenderedChannelCopy;
 
+/**
+ * Failure prose for an `activity.failed` payload with no authored
+ * classification message. The classified kind supplies the readable part,
+ * and the raw error text is appended only when it reads as prose: a
+ * stack-shaped or constant-shaped message (PROVIDER_BILLING and friends)
+ * says nothing to the person reading the notification and never lands in
+ * the body.
+ */
+function describeUnclassifiedFailure(payload: Record<string, unknown>): string {
+  const kind = str(payload.errorKind, "exception");
+  const opening =
+    kind === "timeout"
+      ? "It ran out of time before finishing."
+      : kind === "model_provider"
+        ? "The model provider did not respond."
+        : "It stopped with an error.";
+  const raw =
+    typeof payload.errorMessage === "string"
+      ? payload.errorMessage.replace(/\s+/g, " ").trim()
+      : "";
+  const readable =
+    raw.length > 0 &&
+    raw.length <= 200 &&
+    !/[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+/.test(raw);
+  return readable ? `${opening} ${raw}` : opening;
+}
+
 function str(value: unknown, fallback: string): string {
   if (typeof value === "string" && value.length > 0) {
     return value;
@@ -335,16 +363,21 @@ const TEMPLATES: Partial<Record<NotificationSourceEventName, CopyTemplate>> = {
 
   "activity.failed": (payload) => {
     const jobName = str(payload.jobName, "background job");
-    const errorKind = str(payload.errorKind, "exception");
-    const rawMessage =
-      typeof payload.errorMessage === "string"
-        ? payload.errorMessage
-        : "no message";
-    const truncated =
-      rawMessage.length > 200 ? rawMessage.slice(0, 200) + "…" : rawMessage;
+    // The classifier's authored user-facing message rides the payload as
+    // `failureSummary` when the failing turn carried its classification;
+    // it already says what happened and what to do about it.
+    // Authored messages are short by construction, but the classifier's
+    // fallback branches can embed provider error text, so bound the body
+    // like any other untrusted payload string.
+    const summary = truncate(
+      typeof payload.failureSummary === "string"
+        ? payload.failureSummary.trim()
+        : "",
+      300,
+    );
     return {
       title: `Background job failed: ${jobName}`,
-      body: `${errorKind}: ${truncated}`,
+      body: summary !== "" ? summary : describeUnclassifiedFailure(payload),
     };
   },
 

package/src/plugins/defaults/memory/substrate/__tests__/consolidation-job.test.ts

@@ -1138,7 +1138,7 @@ describe("memoryV2ConsolidateJob — consecutive-failure state", () => {
       ok: false,
       error: new Error("provider refused"),
       errorKind: "model_provider",
-      ...(failureCode !== undefined ? { failureCode } : {}),
+      ...(failureCode !== undefined ? { turnFailure: { failureCode } } : {}),
     });
   }
 

package/src/plugins/defaults/memory/substrate/consolidation-job.ts

@@ -486,12 +486,14 @@ export async function memoryV2ConsolidateJob(
       // everything else (network blip, model hiccup, timeout) is transient
       // and stays on the short curve.
       const failureKind: ConsolidationFailureKind =
-        runResult.failureCode === "PROVIDER_BILLING" ? "billing" : "transient";
+        runResult.turnFailure?.failureCode === "PROVIDER_BILLING"
+          ? "billing"
+          : "transient";
       log.error(
         {
           conversationId: runResult.conversationId,
           errorKind: runResult.errorKind,
-          failureCode: runResult.failureCode,
+          failureCode: runResult.turnFailure?.failureCode,
           failureKind,
           err: runResult.error?.message,
         },

package/src/plugins/defaults/memory/substrate/sweep-job.ts

@@ -37,7 +37,7 @@ import { z } from "zod";
 import { usesConceptPageMemory } from "../../../../config/memory-v3-gate.js";
 import type { AssistantConfig } from "../../../../config/types.js";
 import { warmGuardianBindings } from "../../../../contacts/guardian-delivery-reader.js";
-import { emitNotificationSignal } from "../../../../notifications/emit-signal.js";
+import { emitBackgroundFailureSignal } from "../../../../notifications/background-failure-signal.js";
 import { getDb } from "../../../../persistence/db-connection.js";
 import type { MemoryJob } from "../../../../persistence/jobs-store.js";
 import {
@@ -199,53 +199,20 @@ export async function memoryV2SweepJob(
   } catch (err) {
     const errorMessage = err instanceof Error ? err.message : String(err);
     log.error({ err }, "memory v2 sweep failed");
-    emitSweepActivityFailed({
-      jobId: job.id,
+    // The sweep is a data job with no LLM turn to classify, so its failures
+    // report as generic exceptions through the shared background-failure
+    // seam, which owns the payload shape and dedupe key.
+    emitBackgroundFailureSignal({
+      jobName: JOB_NAME,
+      sourceChannel: "scheduler",
+      sourceContextId: job.id,
+      errorKind: "exception",
       errorMessage,
     });
     return 0;
   }
 }
 
-/**
- * Emit an `activity.failed` notification for a failed sweep run. Mirrors
- * the shape `runBackgroundJob` produces for its own failures so the home
- * feed and native notifications stay consistent regardless of which code
- * path executed the work. Fire-and-forget — a notification failure must
- * never break sweep operation.
- */
-function emitSweepActivityFailed(args: {
-  jobId: string;
-  errorMessage: string;
-}): void {
-  const day = new Date().toISOString().slice(0, 10);
-  emitNotificationSignal({
-    sourceChannel: "scheduler",
-    sourceContextId: args.jobId,
-    sourceEventName: "activity.failed",
-    dedupeKey: `activity-failed:${JOB_NAME}:${day}`,
-    contextPayload: {
-      jobName: JOB_NAME,
-      errorMessage: args.errorMessage,
-      errorKind: "exception",
-    },
-    attentionHints: {
-      requiresAction: false,
-      urgency: "medium",
-      isAsyncBackground: true,
-      visibleInSourceNow: false,
-    },
-  }).catch((emitErr) => {
-    log.warn(
-      {
-        err: emitErr instanceof Error ? emitErr.message : String(emitErr),
-        jobId: args.jobId,
-      },
-      "Failed to emit activity.failed notification for memory v2 sweep",
-    );
-  });
-}
-
 /**
  * Append each non-empty entry to `memory/buffer.md` + today's archive,
  * using the same format `remember()` produces. Returns the count of entries

package/src/runtime/__tests__/background-job-runner.test.ts

@@ -278,7 +278,7 @@ describe("runBackgroundJob", () => {
     expect(result.conversationId).toBe(STUB_CONVERSATION_ID);
     // The stable classified code rides the result so callers can branch on
     // the failure class without parsing the error message.
-    expect(result.failureCode).toBe("PROVIDER_BILLING");
+    expect(result.turnFailure?.failureCode).toBe("PROVIDER_BILLING");
 
     expect(emitCalls).toHaveLength(1);
     expect(emitCalls[0].sourceEventName).toBe("activity.failed");
@@ -308,6 +308,34 @@ describe("runBackgroundJob", () => {
     );
   });
 
+  test("carried turn attribution scopes the dedupe and rides the payload", async () => {
+    processMessageImpl = async () => ({
+      messageId: "msg-failed-turn",
+      turnFailure: {
+        failureCode: "PROVIDER_BILLING",
+        userMessage: "You're out of credits.",
+        errorCategory: "credits_exhausted",
+        connectionName: "conn-a",
+        profileName: "balanced",
+      },
+    });
+
+    const result = await runBackgroundJob(baseOpts());
+
+    expect(result.ok).toBe(false);
+    expect(result.turnFailure?.userMessage).toBe("You're out of credits.");
+    expect(emitCalls).toHaveLength(1);
+    // The carried connection outranks the call site's recomputed profile.
+    expect(emitCalls[0].dedupeKey as string).toMatch(
+      /^activity-failed:cause:PROVIDER_BILLING:conn-a:\d{4}-\d{2}-\d{2}$/,
+    );
+    expect(emitCalls[0].contextPayload).toMatchObject({
+      failureSummary: "You're out of credits.",
+      errorCategory: "credits_exhausted",
+      connectionName: "conn-a",
+    });
+  });
+
   test("job-specific failure code keeps the per-job dedupe key", async () => {
     // CONTEXT_TOO_LARGE names a defect in this job's own prompt; collapsing
     // it across jobs would hide a second job's unrelated failure.
@@ -319,7 +347,7 @@ describe("runBackgroundJob", () => {
     const result = await runBackgroundJob(baseOpts());
 
     expect(result.ok).toBe(false);
-    expect(result.failureCode).toBe("CONTEXT_TOO_LARGE");
+    expect(result.turnFailure?.failureCode).toBe("CONTEXT_TOO_LARGE");
     expect(emitCalls).toHaveLength(1);
     expect(emitCalls[0].dedupeKey as string).toMatch(
       /^activity-failed:test-job:\d{4}-\d{2}-\d{2}$/,

package/src/runtime/background-job-runner.ts

@@ -24,13 +24,12 @@ import type { LLMCallSite } from "../config/schemas/llm.js";
 import { processMessage } from "../daemon/process-message.js";
 import type { SubagentToolGateMode } from "../daemon/tool-setup-types.js";
 import type { TrustContext } from "../daemon/trust-context-types.js";
-import { activityFailedDedupeKey } from "../notifications/activity-failed-dedupe.js";
-import { emitNotificationSignal } from "../notifications/emit-signal.js";
-import type { AttentionHints } from "../notifications/signal.js";
+import { emitBackgroundFailureSignal } from "../notifications/background-failure-signal.js";
 import { bootstrapConversation } from "../persistence/conversation-bootstrap.js";
 import { addMessage } from "../persistence/conversation-crud.js";
 import type { TitleOrigin } from "../persistence/conversation-title-service.js";
 import { dispatchProviderResolvable } from "../providers/provider-resolvability.js";
+import type { TurnFailure } from "../telemetry/turn-outcome.js";
 import { getLogger } from "../util/logger.js";
 import { hasReceivedUserMessage } from "./pre-first-message-gate.js";
 
@@ -57,12 +56,14 @@ class BackgroundJobTimeoutError extends Error {
  */
 class BackgroundJobTurnFailureError extends Error {
   override name = "BackgroundJobTurnFailureError";
-  readonly failureCode: string | undefined;
-  constructor(failureCode: string | undefined) {
+  readonly turnFailure: TurnFailure;
+  constructor(turnFailure: TurnFailure) {
     super(
-      failureCode ? `Agent turn failed (${failureCode})` : "Agent turn failed",
+      turnFailure.failureCode
+        ? `Agent turn failed (${turnFailure.failureCode})`
+        : "Agent turn failed",
     );
-    this.failureCode = failureCode;
+    this.turnFailure = turnFailure;
   }
 }
 
@@ -203,13 +204,14 @@ export interface RunBackgroundJobResult {
   error?: Error;
   errorKind?: BackgroundJobErrorKind;
   /**
-   * Stable classified error code (`ConversationErrorCode`, e.g.
-   * `"PROVIDER_BILLING"`) when the turn failed without throwing. Absent for
-   * timeouts and thrown exceptions. Lets callers branch on the failure class
-   * (e.g. billing vs transient) without depending on error identity or
-   * message text.
+   * The failing turn's full carried classification (stable failureCode,
+   * authored user message, category, connection/profile attribution), when
+   * the failure was a non-throwing turn failure. Absent for timeouts and
+   * thrown exceptions. The single classification field on the result:
+   * callers branch on `turnFailure?.failureCode` and forward the object
+   * wholesale when reporting the failure onward.
    */
-  failureCode?: string;
+  turnFailure?: TurnFailure;
   /**
    * Set when the runner declined to execute. Callers can distinguish a
    * skipped job from a successful one even though both report `ok: true`.
@@ -381,18 +383,17 @@ export async function runBackgroundJob(
     // Rethrow so it flows through the shared failure path below (logging +
     // `activity.failed` emission) rather than returning `ok: true`.
     if (runResult.turnFailure) {
-      throw new BackgroundJobTurnFailureError(
-        runResult.turnFailure.failureCode,
-      );
+      throw new BackgroundJobTurnFailureError(runResult.turnFailure);
     }
     return { conversationId: conversation.id, ok: true };
   } catch (err) {
     const errorKind = classifyError(err);
     const error = err instanceof Error ? err : new Error(String(err));
-    const failureCode =
+    const turnFailure =
       err instanceof BackgroundJobTurnFailureError
-        ? err.failureCode
+        ? err.turnFailure
         : undefined;
+    const failureCode = turnFailure?.failureCode;
     // Bootstrap can fail before `conversation` is assigned; fall back to ""
     // so the structured failure result still flows to the caller.
     const conversationId = conversation?.id ?? "";
@@ -408,24 +409,17 @@ export async function runBackgroundJob(
     );
 
     if (!opts.suppressFailureNotifications) {
-      const hints: AttentionHints = {
-        requiresAction: false,
-        urgency: "medium",
-        isAsyncBackground: true,
-        visibleInSourceNow: false,
-      };
-      // The provider scope is the profile key the resolver actually used for
-      // this call site (the override when usable, else the site's own
-      // winner), resolved with the same provider-resolvability predicate
-      // dispatch uses, so this recomputation cannot accept a profile that
-      // dispatch rejected (e.g. a pin whose connection was force-deleted).
-      // A mix winner, no named winner, or a config read failing on this path
-      // all yield no scope, and the key falls back to per-job: a mix's arm
-      // is picked per conversation and can span providers, so no single
-      // route can be named for it after the fact.
-      let providerScope: string | undefined;
+      // Fallback scope for failures that carry no attribution: the profile
+      // key the resolver would use for this call site, computed with the
+      // same provider-resolvability predicate dispatch uses so the
+      // recomputation cannot accept a profile dispatch rejected (e.g. a pin
+      // whose connection was force-deleted). A mix winner, no named winner,
+      // or a config read failing on this path all yield no scope, and the
+      // key falls back to per-job. A carried `turnFailure.profileName` is
+      // dispatch's own attribution and takes precedence over all of this.
+      let fallbackProviderScope: string | undefined;
       try {
-        providerScope = resolveSingleRouteProfileKey(
+        fallbackProviderScope = resolveSingleRouteProfileKey(
           opts.callSite,
           getConfig().llm,
           {
@@ -436,34 +430,30 @@ export async function runBackgroundJob(
           },
         );
       } catch {
-        providerScope = undefined;
+        fallbackProviderScope = undefined;
       }
-      const dedupeKey = activityFailedDedupeKey({
+      emitBackgroundFailureSignal({
         jobName: opts.jobName,
-        errorKind,
-        ...(failureCode !== undefined ? { failureCode } : {}),
-        ...(providerScope !== undefined ? { providerScope } : {}),
-      });
-      emitNotificationSignal({
         sourceChannel: "assistant_tool",
         sourceContextId: conversationId,
-        sourceEventName: "activity.failed",
-        dedupeKey,
-        contextPayload: {
-          jobName: opts.jobName,
-          errorMessage: error.message,
-          errorKind,
-        },
-        attentionHints: hints,
-      }).catch((emitErr) => {
-        log.warn(
-          {
-            err: emitErr instanceof Error ? emitErr.message : String(emitErr),
-            jobName: opts.jobName,
-            conversationId,
-          },
-          "Failed to emit activity.failed notification for background job",
-        );
+        errorKind,
+        errorMessage: error.message,
+        ...(failureCode !== undefined ? { failureCode } : {}),
+        ...(turnFailure?.userMessage !== undefined
+          ? { failureSummary: turnFailure.userMessage }
+          : {}),
+        ...(turnFailure?.errorCategory !== undefined
+          ? { errorCategory: turnFailure.errorCategory }
+          : {}),
+        ...(turnFailure?.connectionName !== undefined
+          ? { connectionName: turnFailure.connectionName }
+          : {}),
+        ...(turnFailure?.profileName !== undefined
+          ? { profileName: turnFailure.profileName }
+          : {}),
+        ...(fallbackProviderScope !== undefined
+          ? { fallbackProviderScope }
+          : {}),
       });
     }
 
@@ -472,7 +462,7 @@ export async function runBackgroundJob(
       ok: false,
       error,
       errorKind,
-      ...(failureCode !== undefined ? { failureCode } : {}),
+      ...(turnFailure !== undefined ? { turnFailure } : {}),
     };
   } finally {
     if (timer) {

package/src/schedule/scheduler.ts

@@ -8,7 +8,7 @@ import {
 } from "../daemon/disk-pressure-background-gate.js";
 import { processMessage } from "../daemon/process-message.js";
 import { INTERNAL_GUARDIAN_TRUST_CONTEXT } from "../daemon/trust-context.js";
-import { activityFailedDedupeKey } from "../notifications/activity-failed-dedupe.js";
+import { emitBackgroundFailureSignal } from "../notifications/background-failure-signal.js";
 import { emitNotificationSignal } from "../notifications/emit-signal.js";
 import { getConversation } from "../persistence/conversation-crud.js";
 import { isLifecycleQuiesced } from "../persistence/lifecycle-quiesce.js";
@@ -235,7 +235,12 @@ async function handleExecutionFailure(params: {
    * collapse; absent means a generic exception, which keys per schedule.
    */
   errorKind?: BackgroundJobErrorKind;
-  failureCode?: string;
+  /**
+   * The failing turn's carried classification, when the failure was a
+   * non-throwing turn failure. The exhaustion alert renders its authored
+   * message and scopes by the route that actually served the runs.
+   */
+  turnFailure?: TurnFailure;
 }): Promise<void> {
   const decision = decideRetry(params.job);
   await applyRetryDecision({
@@ -246,16 +251,33 @@ async function handleExecutionFailure(params: {
     failOneShotPermanently,
     resetRetryCount,
     emitAlert: () => {
-      const providerScope = resolveScheduleProviderScope(params.job);
-      emitScheduleActivityFailed({
-        jobId: params.job.id,
-        jobName: params.job.name,
-        errorMessage: params.errorMsg,
+      const fallbackProviderScope = resolveScheduleProviderScope(params.job);
+      const carried = params.turnFailure;
+      emitBackgroundFailureSignal({
+        jobName: `schedule:${params.job.id}`,
+        displayName: `schedule:${params.job.name}`,
+        sourceChannel: "scheduler",
+        sourceContextId: params.job.id,
         errorKind: params.errorKind ?? "exception",
-        ...(params.failureCode !== undefined
-          ? { failureCode: params.failureCode }
+        errorMessage: params.errorMsg,
+        ...(carried?.failureCode !== undefined
+          ? { failureCode: carried.failureCode }
+          : {}),
+        ...(carried?.userMessage !== undefined
+          ? { failureSummary: carried.userMessage }
+          : {}),
+        ...(carried?.errorCategory !== undefined
+          ? { errorCategory: carried.errorCategory }
+          : {}),
+        ...(carried?.connectionName !== undefined
+          ? { connectionName: carried.connectionName }
+          : {}),
+        ...(carried?.profileName !== undefined
+          ? { profileName: carried.profileName }
+          : {}),
+        ...(fallbackProviderScope !== undefined
+          ? { fallbackProviderScope }
           : {}),
-        ...(providerScope !== undefined ? { providerScope } : {}),
       });
     },
     log,
@@ -938,7 +960,7 @@ export async function runDueSchedulesOnce(
     let ok: boolean;
     let errorMsg: string | undefined;
     let errorKind: BackgroundJobErrorKind | undefined;
-    let failureCode: string | undefined;
+    let failedTurn: TurnFailure | undefined;
     const conversationReused = reusedConversationId != null;
     let runConversationId = reusedConversationId;
     const runId = await createScheduleRun(job.id, reusedConversationId);
@@ -973,7 +995,7 @@ export async function runDueSchedulesOnce(
           ok = false;
           errorMsg = describeTurnFailure(turnFailure);
           errorKind = "model_provider";
-          failureCode = turnFailure.failureCode;
+          failedTurn = turnFailure;
         } else {
           ok = true;
         }
@@ -1040,7 +1062,7 @@ export async function runDueSchedulesOnce(
       ok = result.ok;
       errorMsg = result.error?.message;
       errorKind = result.errorKind;
-      failureCode = result.failureCode;
+      failedTurn = result.turnFailure;
     }
 
     if (ok) {
@@ -1070,7 +1092,7 @@ export async function runDueSchedulesOnce(
         errorMsg: errorMsg ?? "Schedule run failed",
         isOneShot,
         ...(errorKind !== undefined ? { errorKind } : {}),
-        ...(failureCode !== undefined ? { failureCode } : {}),
+        ...(failedTurn !== undefined ? { turnFailure: failedTurn } : {}),
       });
 
       // Only skip invalidation when the conversation was *actually* reused,
@@ -1094,55 +1116,3 @@ export async function runDueSchedulesOnce(
 
   return result;
 }
-
-/**
- * Emit an `activity.failed` notification for a schedule whose retries have
- * been exhausted. Fires once when the retry policy has given up. The dedupe
- * key comes from the shared cause-first derivation, so every schedule (and
- * background job) failing for the same classified cause on the same UTC day
- * collapses into one notification, and cause-less failures collapse per
- * schedule per day.
- */
-function emitScheduleActivityFailed(args: {
-  jobId: string;
-  jobName: string;
-  errorMessage: string;
-  errorKind: BackgroundJobErrorKind;
-  failureCode?: string;
-  providerScope?: string;
-}): void {
-  emitNotificationSignal({
-    sourceChannel: "scheduler",
-    sourceContextId: args.jobId,
-    sourceEventName: "activity.failed",
-    dedupeKey: activityFailedDedupeKey({
-      jobName: `schedule:${args.jobId}`,
-      errorKind: args.errorKind,
-      ...(args.failureCode !== undefined
-        ? { failureCode: args.failureCode }
-        : {}),
-      ...(args.providerScope !== undefined
-        ? { providerScope: args.providerScope }
-        : {}),
-    }),
-    contextPayload: {
-      jobName: `schedule:${args.jobName}`,
-      errorMessage: args.errorMessage,
-      errorKind: args.errorKind,
-    },
-    attentionHints: {
-      requiresAction: false,
-      urgency: "medium",
-      isAsyncBackground: true,
-      visibleInSourceNow: false,
-    },
-  }).catch((emitErr) => {
-    log.warn(
-      {
-        err: emitErr instanceof Error ? emitErr.message : String(emitErr),
-        jobId: args.jobId,
-      },
-      "Failed to emit activity.failed notification for exhausted schedule",
-    );
-  });
-}

package/src/telemetry/turn-outcome.ts

@@ -31,6 +31,26 @@ export interface TurnOutcomeExtras {
   batchedInto?: string;
   /** For `"failed"`: stable classified error code (never free-form text). */
   failureCode?: string;
+  /**
+   * For `"failed"`: the classification's authored user-facing message
+   * (`classifyConversationError(...).userMessage`), so downstream failure
+   * reporting (background-job alerts) can render the actionable prose the
+   * chat banner shows instead of reconstructing degraded text from the code.
+   */
+  failureMessage?: string;
+  /** For `"failed"`: the classification's machine-readable category. */
+  failureCategory?: string;
+  /**
+   * For `"failed"`: name of the `provider_connections` row in play when the
+   * failure occurred, when the classifier had it in scope.
+   */
+  failureConnection?: string;
+  /**
+   * For `"failed"`: the resolved profile key the failing call ran under,
+   * when the classifier had it in scope. This is dispatch's own attribution,
+   * so consumers scope failure identity by it instead of re-resolving.
+   */
+  failureProfile?: string;
 }
 
 /**
@@ -49,10 +69,25 @@ export function stampTurnOutcome(
   extras: TurnOutcomeExtras = {},
 ): void {
   try {
+    // The failure* keys are read back by `readTurnFailure` only; the turn
+    // telemetry projection (`queryUnreportedTurnEvents`) extracts none of
+    // them, so nothing here changes the platform wire contract.
     updateMessageMetadata(userMessageId, {
       turnOutcome: outcome,
       ...(extras.batchedInto ? { turnBatchedInto: extras.batchedInto } : {}),
       ...(extras.failureCode ? { turnFailureCode: extras.failureCode } : {}),
+      ...(extras.failureMessage
+        ? { turnFailureMessage: extras.failureMessage }
+        : {}),
+      ...(extras.failureCategory
+        ? { turnFailureCategory: extras.failureCategory }
+        : {}),
+      ...(extras.failureConnection
+        ? { turnFailureConnection: extras.failureConnection }
+        : {}),
+      ...(extras.failureProfile
+        ? { turnFailureProfile: extras.failureProfile }
+        : {}),
     });
   } catch (err) {
     log.warn(
@@ -75,6 +110,14 @@ export function stampTurnOutcome(
 export interface TurnFailure {
   /** Stable classified error code (never free-form text). */
   failureCode?: string;
+  /** The classification's authored user-facing message, when stamped. */
+  userMessage?: string;
+  /** The classification's machine-readable category, when stamped. */
+  errorCategory?: string;
+  /** Connection row in play when the failure occurred, when stamped. */
+  connectionName?: string;
+  /** Resolved profile key the failing call ran under, when stamped. */
+  profileName?: string;
 }
 
 /**
@@ -106,11 +149,39 @@ export function readTurnFailure(userMessageId: string): TurnFailure | null {
   if (typeof parsed !== "object" || parsed === null) {
     return null;
   }
-  const meta = parsed as { turnOutcome?: unknown; turnFailureCode?: unknown };
+  const meta = parsed as {
+    turnOutcome?: unknown;
+    turnFailureCode?: unknown;
+    turnFailureMessage?: unknown;
+    turnFailureCategory?: unknown;
+    turnFailureConnection?: unknown;
+    turnFailureProfile?: unknown;
+  };
   if (meta.turnOutcome !== "failed") {
     return null;
   }
-  return typeof meta.turnFailureCode === "string"
-    ? { failureCode: meta.turnFailureCode }
-    : {};
+  const str = (value: unknown): string | undefined =>
+    typeof value === "string" ? value : undefined;
+  const failure: TurnFailure = {};
+  const failureCode = str(meta.turnFailureCode);
+  if (failureCode !== undefined) {
+    failure.failureCode = failureCode;
+  }
+  const userMessage = str(meta.turnFailureMessage);
+  if (userMessage !== undefined) {
+    failure.userMessage = userMessage;
+  }
+  const errorCategory = str(meta.turnFailureCategory);
+  if (errorCategory !== undefined) {
+    failure.errorCategory = errorCategory;
+  }
+  const connectionName = str(meta.turnFailureConnection);
+  if (connectionName !== undefined) {
+    failure.connectionName = connectionName;
+  }
+  const profileName = str(meta.turnFailureProfile);
+  if (profileName !== undefined) {
+    failure.profileName = profileName;
+  }
+  return failure;
 }