fix: show specificity category badge in dashboard Recent Messages

The Overview dashboard was rendering STANDARD (the complexity tier) for
messages routed via specificity — the Messages log on the same rows
correctly showed CODING. Root cause was a hand-written SELECT projection
in getRecentActivity() that omitted the specificity_category column,
while getMessages() selected it correctly.

Extract selectMessageRowColumns() in query-helpers.ts as the single
source of truth for the columns projected to rows rendered by the
shared frontend MessageTable/ModelCell component. Both endpoints now
call it; MessageLog chains its six extra fields (description,
service_type, cache_read_tokens, cache_creation_tokens, duration_ms,
error_http_status) after the helper. New UI columns get added once.

A query-helpers.spec.ts test pins the required alias set so the two
endpoints cannot drift silently again, plus regression assertions in
both service specs cover the specificity_category passthrough.
CLAUDE.md documents the contract under Domain Terminology.

Author: brunobuddy

.changeset/fix-dashboard-spec-badge.md

@@ -0,0 +1,5 @@
+---
+"manifest": patch
+---
+
+Fix dashboard Recent Messages showing the complexity tier (e.g. `STANDARD`) instead of the specificity category (e.g. `CODING`) for messages routed by specificity. The Overview analytics endpoint now projects `specificity_category` alongside `routing_tier`, matching the full Messages log.

CLAUDE.md

@@ -370,6 +370,17 @@ See `packages/backend/.env.example` for all variables. Key ones:
 - **Tenant**: A user's data boundary. Created from `user.id` on first agent creation.
 - **Agent**: An AI agent owned by a tenant. Has a unique OTLP ingest key.
 
+### Message list endpoints (shared projection contract)
+
+Any backend endpoint that returns rows rendered by the frontend `MessageTable` / `ModelCell` component **must** project its SELECT through `selectMessageRowColumns()` in `packages/backend/src/analytics/services/query-helpers.ts`. The helper is the single source of truth for the columns the shared badge/provider/auth rendering reads (including `specificity_category`, `routing_tier`, `routing_reason`, `auth_type`, `fallback_from_model`).
+
+- Adding a new column the UI needs → edit the helper once, never duplicate the projection across query services.
+- Endpoint-specific fields that don't belong to the shared `MessageRow` contract (e.g. `description`, `service_type`, `cache_read_tokens`, `duration_ms` for the full Messages log) stay as explicit `.addSelect` chained after the helper call.
+- Current call sites: `getRecentActivity()` in `timeseries-queries.service.ts` (Overview "Recent Messages") and `getMessages()` in `messages-query.service.ts` (Messages log).
+- A `query-helpers.spec.ts` test pins the required alias set — it fails loudly if anyone drops a field from the helper. Don't bypass it by hand-rolling a new SELECT chain.
+
+This rule exists because the Overview and Messages pages previously drifted and the Recent Messages badge read `STANDARD` instead of the specificity category (`CODING` etc.) — the frontend already shares the rendering code, so the divergence was purely backend projection drift.
+
 ## Content Security Policy (CSP)
 
 Helmet enforces a strict CSP in `main.ts`. The policy only allows `'self'` origins — **no external CDNs are permitted**.

packages/backend/src/analytics/services/messages-query.service.spec.ts

@@ -874,4 +874,33 @@ describe('MessagesQueryService', () => {
       expect(result.items).toEqual([]);
     });
   });
+
+  // Shared contract with TimeseriesQueriesService.getRecentActivity:
+  // both endpoints must project `specificity_category` so the frontend
+  // MessageTable/ModelCell badge renders the specificity category instead of
+  // falling back to the complexity tier. See selectMessageRowColumns helper.
+  it('propagates specificity_category rows returned by the helper projection', async () => {
+    mockGetRawOne.mockResolvedValueOnce({ total: 1 });
+    mockGetRawMany
+      .mockResolvedValueOnce([
+        {
+          id: 'msg-spec',
+          timestamp: '2026-02-16 10:00:00',
+          model: 'claude-opus-4-6',
+          cost: 0.1,
+          routing_tier: 'standard',
+          routing_reason: 'specificity',
+          specificity_category: 'coding',
+        },
+      ])
+      .mockResolvedValueOnce([{ model: 'claude-opus-4-6' }]);
+
+    const result = await service.getMessages({
+      range: '24h',
+      userId: 'test-user',
+      limit: 20,
+    });
+
+    expect(result.items[0]).toHaveProperty('specificity_category', 'coding');
+  });
 });

packages/backend/src/analytics/services/messages-query.service.ts

@@ -3,7 +3,7 @@ import { InjectRepository } from '@nestjs/typeorm';
 import { Brackets, DataSource, Repository } from 'typeorm';
 import { AgentMessage } from '../../entities/agent-message.entity';
 import { rangeToInterval } from '../../common/utils/range.util';
-import { addTenantFilter, formatTimestamp } from './query-helpers';
+import { addTenantFilter, formatTimestamp, selectMessageRowColumns } from './query-helpers';
 import { TenantCacheService } from '../../common/services/tenant-cache.service';
 import {
   DbDialect,
@@ -103,32 +103,13 @@ export class MessagesQueryService {
 
     // Data (with cursor) — treat negative costs as NULL (invalid pricing)
     const costExpr = sqlCastFloat(sqlSanitizeCost('at.cost_usd'), this.dialect);
-    const dataQb = baseQb
-      .clone()
-      .select('at.id', 'id')
-      .addSelect('at.timestamp', 'timestamp')
-      .addSelect('at.agent_name', 'agent_name')
-      .addSelect('at.model', 'model')
-      .addSelect('at.provider', 'provider')
-      .addSelect('at.model', 'display_name')
+    const dataQb = selectMessageRowColumns(baseQb.clone(), costExpr)
       .addSelect('at.description', 'description')
       .addSelect('at.service_type', 'service_type')
-      .addSelect('at.input_tokens', 'input_tokens')
-      .addSelect('at.output_tokens', 'output_tokens')
-      .addSelect('at.status', 'status')
-      .addSelect('at.input_tokens + at.output_tokens', 'total_tokens')
-      .addSelect(costExpr, 'cost')
-      .addSelect('at.routing_tier', 'routing_tier')
-      .addSelect('at.routing_reason', 'routing_reason')
-      .addSelect('at.specificity_category', 'specificity_category')
       .addSelect('at.cache_read_tokens', 'cache_read_tokens')
       .addSelect('at.cache_creation_tokens', 'cache_creation_tokens')
       .addSelect('at.duration_ms', 'duration_ms')
-      .addSelect('at.error_message', 'error_message')
-      .addSelect('at.error_http_status', 'error_http_status')
-      .addSelect('at.auth_type', 'auth_type')
-      .addSelect('at.fallback_from_model', 'fallback_from_model')
-      .addSelect('at.fallback_index', 'fallback_index');
+      .addSelect('at.error_http_status', 'error_http_status');
 
     if (params.cursor) {
       const sepIdx = params.cursor.indexOf('|');

packages/backend/src/analytics/services/query-helpers.spec.ts

@@ -1,4 +1,11 @@
-import { computeTrend, downsample, formatTimestamp, addTenantFilter } from './query-helpers';
+import {
+  computeTrend,
+  downsample,
+  formatTimestamp,
+  addTenantFilter,
+  selectMessageRowColumns,
+  MESSAGE_ROW_SELECT_ALIASES,
+} from './query-helpers';
 import { SelectQueryBuilder } from 'typeorm';
 
 describe('computeTrend', () => {
@@ -170,3 +177,71 @@ describe('addTenantFilter', () => {
     expect(mockAndWhere).toHaveBeenCalledTimes(2);
   });
 });
+
+describe('selectMessageRowColumns', () => {
+  function makeMockQb() {
+    const selectCalls: Array<[string, string]> = [];
+    const addSelectCalls: Array<[string, string]> = [];
+    const qb = {
+      select: jest.fn().mockImplementation((expr: string, alias: string) => {
+        selectCalls.push([expr, alias]);
+        return qb;
+      }),
+      addSelect: jest.fn().mockImplementation((expr: string, alias: string) => {
+        addSelectCalls.push([expr, alias]);
+        return qb;
+      }),
+    };
+    return { qb: qb as unknown as SelectQueryBuilder<never>, selectCalls, addSelectCalls };
+  }
+
+  it('projects exactly the columns declared in MESSAGE_ROW_SELECT_ALIASES', () => {
+    const { qb, selectCalls, addSelectCalls } = makeMockQb();
+    selectMessageRowColumns(qb, 'CAST(at.cost_usd AS FLOAT)');
+
+    expect(selectCalls).toHaveLength(1);
+    expect(addSelectCalls).toHaveLength(MESSAGE_ROW_SELECT_ALIASES.length - 1);
+
+    const emittedAliases = [selectCalls[0]![1], ...addSelectCalls.map(([, alias]) => alias)];
+    expect(emittedAliases).toEqual([...MESSAGE_ROW_SELECT_ALIASES]);
+  });
+
+  it('uses the caller-supplied cost expression so dialect handling stays at the call site', () => {
+    const { qb, addSelectCalls } = makeMockQb();
+    const costExpr = 'SOME_DIALECT_SPECIFIC_CAST(at.cost_usd)';
+    selectMessageRowColumns(qb, costExpr);
+
+    const costCall = addSelectCalls.find(([, alias]) => alias === 'cost');
+    expect(costCall).toEqual([costExpr, 'cost']);
+  });
+
+  it('computes total_tokens from input_tokens + output_tokens', () => {
+    const { qb, addSelectCalls } = makeMockQb();
+    selectMessageRowColumns(qb, 'cost');
+
+    const totalCall = addSelectCalls.find(([, alias]) => alias === 'total_tokens');
+    expect(totalCall).toEqual(['at.input_tokens + at.output_tokens', 'total_tokens']);
+  });
+
+  it('aliases display_name from at.model', () => {
+    const { qb, addSelectCalls } = makeMockQb();
+    selectMessageRowColumns(qb, 'cost');
+
+    const displayNameCall = addSelectCalls.find(([, alias]) => alias === 'display_name');
+    expect(displayNameCall).toEqual(['at.model', 'display_name']);
+  });
+
+  it('projects specificity_category so the frontend badge can render it', () => {
+    const { qb, addSelectCalls } = makeMockQb();
+    selectMessageRowColumns(qb, 'cost');
+
+    const specCall = addSelectCalls.find(([, alias]) => alias === 'specificity_category');
+    expect(specCall).toEqual(['at.specificity_category', 'specificity_category']);
+  });
+
+  it('returns the query builder for chaining', () => {
+    const { qb } = makeMockQb();
+    const result = selectMessageRowColumns(qb, 'cost');
+    expect(result).toBe(qb);
+  });
+});

packages/backend/src/analytics/services/query-helpers.ts

@@ -55,3 +55,60 @@ export function addTenantFilter<T extends ObjectLiteral>(
   }
   return qb;
 }
+
+/**
+ * Single source of truth for the columns projected by any endpoint that
+ * returns rows rendered by the frontend `MessageTable` / `ModelCell` component.
+ * The frontend `MessageRow` type (packages/frontend/src/components/message-table-types.ts)
+ * is the downstream contract — every field it declares must be selected here so
+ * the shared badge/provider rendering works identically across every call site.
+ *
+ * Assumes the query builder aliases `agent_messages` as `at`. Callers pass a
+ * dialect-specific `costExpr` (e.g. `sqlCastFloat(sqlSanitizeCost('at.cost_usd'), dialect)`)
+ * so per-service dialect handling stays at the call site.
+ */
+export const MESSAGE_ROW_SELECT_ALIASES = [
+  'id',
+  'timestamp',
+  'agent_name',
+  'model',
+  'provider',
+  'display_name',
+  'input_tokens',
+  'output_tokens',
+  'status',
+  'total_tokens',
+  'cost',
+  'routing_tier',
+  'routing_reason',
+  'specificity_category',
+  'error_message',
+  'auth_type',
+  'fallback_from_model',
+  'fallback_index',
+] as const;
+
+export function selectMessageRowColumns<T extends ObjectLiteral>(
+  qb: SelectQueryBuilder<T>,
+  costExpr: string,
+): SelectQueryBuilder<T> {
+  return qb
+    .select('at.id', 'id')
+    .addSelect('at.timestamp', 'timestamp')
+    .addSelect('at.agent_name', 'agent_name')
+    .addSelect('at.model', 'model')
+    .addSelect('at.provider', 'provider')
+    .addSelect('at.model', 'display_name')
+    .addSelect('at.input_tokens', 'input_tokens')
+    .addSelect('at.output_tokens', 'output_tokens')
+    .addSelect('at.status', 'status')
+    .addSelect('at.input_tokens + at.output_tokens', 'total_tokens')
+    .addSelect(costExpr, 'cost')
+    .addSelect('at.routing_tier', 'routing_tier')
+    .addSelect('at.routing_reason', 'routing_reason')
+    .addSelect('at.specificity_category', 'specificity_category')
+    .addSelect('at.error_message', 'error_message')
+    .addSelect('at.auth_type', 'auth_type')
+    .addSelect('at.fallback_from_model', 'fallback_from_model')
+    .addSelect('at.fallback_index', 'fallback_index');
+}

packages/backend/src/analytics/services/timeseries-queries.service.spec.ts

@@ -10,12 +10,28 @@ describe('TimeseriesQueriesService', () => {
   let service: TimeseriesQueriesService;
   let mockGetRawMany: jest.Mock;
   let mockGetMany: jest.Mock;
+  let mockTurnQb: {
+    select: jest.Mock;
+    addSelect: jest.Mock;
+    leftJoin: jest.Mock;
+    where: jest.Mock;
+    andWhere: jest.Mock;
+    orWhere: jest.Mock;
+    groupBy: jest.Mock;
+    addGroupBy: jest.Mock;
+    orderBy: jest.Mock;
+    addOrderBy: jest.Mock;
+    limit: jest.Mock;
+    getRawMany: jest.Mock;
+    getRawOne: jest.Mock;
+    getMany: jest.Mock;
+  };
 
   beforeEach(async () => {
     mockGetRawMany = jest.fn().mockResolvedValue([]);
     mockGetMany = jest.fn().mockResolvedValue([]);
 
-    const mockTurnQb = {
+    mockTurnQb = {
       select: jest.fn().mockReturnThis(),
       addSelect: jest.fn().mockReturnThis(),
       leftJoin: jest.fn().mockReturnThis(),
@@ -157,6 +173,35 @@ describe('TimeseriesQueriesService', () => {
       mockGetRawMany.mockResolvedValue([]);
       expect(await service.getRecentActivity('24h', 'u1', 10)).toEqual([]);
     });
+
+    it('propagates specificity_category rows returned by the helper projection', async () => {
+      mockGetRawMany.mockResolvedValue([
+        {
+          id: '1',
+          timestamp: '2026-02-16T10:00:00',
+          agent_name: 'bot-1',
+          model: 'claude-opus-4-6',
+          routing_tier: 'standard',
+          routing_reason: 'specificity',
+          specificity_category: 'coding',
+        },
+      ]);
+      const rows = (await service.getRecentActivity('24h', 'u1')) as Array<Record<string, unknown>>;
+      expect(rows[0]!['specificity_category']).toBe('coding');
+    });
+
+    it('projects specificity_category through the shared helper (regression: dashboard badge drift)', async () => {
+      mockGetRawMany.mockResolvedValue([]);
+      await service.getRecentActivity('24h', 'u1');
+
+      const projectedAliases = [
+        ...mockTurnQb.select.mock.calls.map((call) => call[1]),
+        ...mockTurnQb.addSelect.mock.calls.map((call) => call[1]),
+      ];
+      expect(projectedAliases).toContain('specificity_category');
+      expect(projectedAliases).toContain('routing_tier');
+      expect(projectedAliases).toContain('routing_reason');
+    });
   });
 
   describe('getTimeseries', () => {

packages/backend/src/analytics/services/timeseries-queries.service.ts

@@ -4,7 +4,7 @@ import { DataSource, Repository } from 'typeorm';
 import { AgentMessage } from '../../entities/agent-message.entity';
 import { Agent } from '../../entities/agent.entity';
 import { rangeToInterval } from '../../common/utils/range.util';
-import { addTenantFilter } from './query-helpers';
+import { addTenantFilter, selectMessageRowColumns } from './query-helpers';
 import { TenantCacheService } from '../../common/services/tenant-cache.service';
 import {
   DbDialect,
@@ -126,26 +126,10 @@ export class TimeseriesQueriesService {
 
     const costExpr = sqlCastFloat(sqlSanitizeCost('at.cost_usd'), this.dialect);
 
-    const qb = this.turnRepo
-      .createQueryBuilder('at')
-      .select('at.id', 'id')
-      .addSelect('at.timestamp', 'timestamp')
-      .addSelect('at.agent_name', 'agent_name')
-      .addSelect('at.model', 'model')
-      .addSelect('at.provider', 'provider')
-      .addSelect('at.model', 'display_name')
-      .addSelect('at.input_tokens', 'input_tokens')
-      .addSelect('at.output_tokens', 'output_tokens')
-      .addSelect('at.status', 'status')
-      .addSelect('at.input_tokens + at.output_tokens', 'total_tokens')
-      .addSelect(costExpr, 'cost')
-      .addSelect('at.routing_tier', 'routing_tier')
-      .addSelect('at.routing_reason', 'routing_reason')
-      .addSelect('at.error_message', 'error_message')
-      .addSelect('at.auth_type', 'auth_type')
-      .addSelect('at.fallback_from_model', 'fallback_from_model')
-      .addSelect('at.fallback_index', 'fallback_index')
-      .where('at.timestamp >= :cutoff', { cutoff });
+    const qb = selectMessageRowColumns(this.turnRepo.createQueryBuilder('at'), costExpr).where(
+      'at.timestamp >= :cutoff',
+      { cutoff },
+    );
     addTenantFilter(qb, userId, agentName, resolved);
     return qb.orderBy('at.timestamp', 'DESC').limit(limit).getRawMany();
   }