From 55679fa234505efbebf407d87f925c4356046608 Mon Sep 17 00:00:00 2001
From: Algis Dumbris <a.dumbris@gmail.com>
Date: Fri, 2 Oct 2026 16:06:48 +0300
Subject: [PATCH 1/6] fix(web): label Home token savings as an estimate and
 show Get started on a fresh instance (Spec fix-ux-residuals)

---
 frontend/src/views/Home.vue                   |  86 +++++++-
 frontend/tests/unit/home-attention.spec.ts    |   4 +-
 .../tests/unit/home-getting-started.spec.ts   | 204 ++++++++++++++++++
 .../unit/home-token-savings-estimate.spec.ts  | 171 +++++++++++++++
 4 files changed, 460 insertions(+), 5 deletions(-)
 create mode 100644 frontend/tests/unit/home-getting-started.spec.ts
 create mode 100644 frontend/tests/unit/home-token-savings-estimate.spec.ts

diff --git a/frontend/src/views/Home.vue b/frontend/src/views/Home.vue
index 077cecee0..bd71d649c 100644
--- a/frontend/src/views/Home.vue
+++ b/frontend/src/views/Home.vue
@@ -9,12 +9,42 @@
     <!-- Spec 109 FR-051/FR-001/FR-003: the ONE needs-attention list, replacing
          the two bespoke Dashboard.vue banners (servers needing attention,
          tools pending approval) that duplicated FR-001's logic locally. -->
-    <AttentionList data-test="home-attention-list" />
+    <AttentionList v-if="!showGettingStarted && !holdAllClear" data-test="home-attention-list" />
+
+    <!-- A fresh instance (no server configured) has nothing to be "all clear"
+         about: the green banner would be false reassurance. Any attention item
+         still wins (showGettingStarted needs an empty list). -->
+    <div
+      v-if="showGettingStarted"
+      class="card bg-base-100 border border-primary/30 shadow-sm"
+      data-test="home-getting-started"
+    >
+      <div class="card-body p-4 gap-3">
+        <div>
+          <h3 class="font-bold text-lg">Get started</h3>
+          <p class="text-sm text-base-content/70">MCPProxy has no servers yet. Add one and connect an AI client to start using tools through the proxy.</p>
+        </div>
+        <ol class="space-y-2 text-sm">
+          <li class="flex flex-wrap items-center gap-3">
+            <span class="font-medium">1. Add a server</span>
+            <button type="button" class="btn btn-xs btn-primary" data-test="home-getting-started-add-server" @click="router.push('/add-server')">Add a server</button>
+          </li>
+          <li class="flex flex-wrap items-center gap-3">
+            <span class="font-medium">2. Connect a client</span>
+            <button type="button" class="btn btn-xs btn-primary btn-outline" data-test="home-getting-started-connect-client" @click="router.push('/clients')">Connect a client</button>
+            <span v-if="clientConnected" class="badge badge-success badge-sm" data-test="home-getting-started-client-done">&#10003; connected</span>
+          </li>
+        </ol>
+        <div>
+          <button type="button" class="link link-hover text-sm" data-test="home-getting-started-wizard" @click="onboardingStore.openWizard()">Run setup wizard</button>
+        </div>
+      </div>
+    </div>
 
     <!-- Usage summary strip: normally sits below the topology, but moves
          above it when the attention list is empty (FR-051) so an otherwise-
          calm landing page still opens on something live. -->
-    <UsageSummaryStrip v-if="authStore.principalKind !== 'tenant' && attentionStore.loaded && attentionStore.count === 0" data-test="home-usage-strip-top" />
+    <UsageSummaryStrip v-if="authStore.principalKind !== 'tenant' && attentionStore.loaded && attentionStore.count === 0 && !showGettingStarted" data-test="home-usage-strip-top" />
 
     <!-- Topology (moved from Dashboard.vue's Overview panel). Always shown —
          Home no longer switches between an Overview and a Usage panel;
@@ -150,6 +180,12 @@
             </svg>
             <span class="text-lg font-bold">{{ tokenSavingsData.saved_tokens_percentage >= 99.995 ? '99.99' : tokenSavingsData.saved_tokens_percentage >= 10 ? tokenSavingsData.saved_tokens_percentage.toFixed(1) : tokenSavingsData.saved_tokens_percentage.toFixed(0) }}%</span>
             <span class="text-xs font-medium">smaller tool context per request</span>
+            <span
+              v-if="tokenSavingsData.estimated"
+              class="badge badge-ghost badge-xs"
+              data-test="dashboard-token-savings-estimate"
+              :title="TOKEN_ESTIMATE_TITLE"
+            >estimate</span>
           </button>
         </div>
 
@@ -296,7 +332,7 @@
           <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M13 7h8m0 0v8m0-8l-8 8-4-4-6 6" />
         </svg>
         Token Savings Details
-        <span class="badge badge-success badge-sm ml-auto">{{ formatNumber(tokenSavingsData.saved_tokens) }} saved</span>
+        <span class="badge badge-success badge-sm ml-auto" data-test="dashboard-token-savings-saved-badge">{{ formatNumber(tokenSavingsData.saved_tokens) }} saved{{ tokenSavingsData.estimated ? ' · estimate' : '' }}</span>
       </div>
       <div class="collapse-content">
         <div class="grid grid-cols-1 lg:grid-cols-2 gap-6 pt-2">
@@ -305,7 +341,15 @@
             <div class="grid grid-cols-3 gap-4">
               <div :title="tokensSavedExplainer">
                 <div class="text-sm opacity-60">Tokens Saved / request</div>
-                <div class="text-2xl font-bold text-success">{{ formatNumber(tokenSavingsData.saved_tokens) }}</div>
+                <div class="text-2xl font-bold text-success">
+                  {{ formatNumber(tokenSavingsData.saved_tokens) }}
+                  <span
+                    v-if="tokenSavingsData.estimated"
+                    class="badge badge-ghost badge-sm align-middle"
+                    data-test="dashboard-token-savings-details-estimate"
+                    :title="TOKEN_ESTIMATE_TITLE"
+                  >estimate</span>
+                </div>
                 <div class="text-xs opacity-60">{{ tokenSavingsData.saved_tokens_percentage.toFixed(1) }}% reduction</div>
               </div>
               <div>
@@ -566,6 +610,11 @@ const tokensSavedExplainer =
   'returns for one query. It is a property of your current tool catalog, so it ' +
   'changes when you add, remove or reconnect servers — not with each call.'
 
+// Same wording as Usage.vue and the macOS Home. Kept local because hoisting it
+// into a shared constant touches Usage.vue (follow-up).
+const TOKEN_ESTIMATE_TITLE =
+  'No retrieve_tools call has been observed yet — this is a simulated estimate from the current tool catalog, not a measured average'
+
 const tokenDetailsOpen = ref(false)
 const tokenSavingsDetails = ref<HTMLElement | null>(null)
 
@@ -577,6 +626,35 @@ const openTokenSavingsDetails = () => {
   })
 }
 
+// --- Fresh instance (no server configured) ---
+//
+// "All clear" with zero servers is false reassurance, so the getting-started
+// card takes its place. The trigger is "no server configured" alone; the client
+// state is a checklist step. Any attention item wins, and nothing renders until
+// both the server list and the attention list have loaded.
+const showGettingStarted = computed(
+  () =>
+    authStore.principalKind !== 'tenant' &&
+    serversStore.loaded &&
+    serversStore.serverCount.total === 0 &&
+    attentionStore.loaded &&
+    attentionStore.count === 0
+)
+
+// While the server count is still unknown an empty attention list would flash
+// "All clear" only to be replaced by the card, so hold the list back. A failed
+// server fetch does not hold it back forever.
+const holdAllClear = computed(
+  () =>
+    authStore.principalKind !== 'tenant' &&
+    attentionStore.loaded &&
+    attentionStore.count === 0 &&
+    !serversStore.loaded &&
+    !serversStore.loading.error
+)
+
+const clientConnected = computed(() => onboardingStore.hasConnectedClient || liveClients.value.length > 0)
+
 // --- Disabled server count ---
 //
 // Disabled and quarantined must be MUTUALLY EXCLUSIVE here (audit finding F27,
diff --git a/frontend/tests/unit/home-attention.spec.ts b/frontend/tests/unit/home-attention.spec.ts
index 37a90e672..38d7b8bb1 100644
--- a/frontend/tests/unit/home-attention.spec.ts
+++ b/frontend/tests/unit/home-attention.spec.ts
@@ -34,7 +34,9 @@ vi.mock('@/services/api', () => {
   }
   const base: Record<string, unknown> = {
     getAttention: attentionSpy,
-    getServers: ok({ servers: [] }),
+    // One ready server: with none, Home shows the getting-started card
+    // instead of "All clear" (Spec 109 T170).
+    getServers: ok({ servers: [{ name: 'notes', enabled: true, connected: true, tool_count: 3 }] }),
     getActivitySummary: ok({ call_count: 5, blocked_count: 1, call_error_count: 2 }),
     createEventSource: vi.fn(() => fakeEventSource),
     hasAPIKey: vi.fn(() => true),
diff --git a/frontend/tests/unit/home-getting-started.spec.ts b/frontend/tests/unit/home-getting-started.spec.ts
new file mode 100644
index 000000000..98b1233b3
--- /dev/null
+++ b/frontend/tests/unit/home-getting-started.spec.ts
@@ -0,0 +1,204 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { ref } from 'vue'
+import { shallowMount, flushPromises } from '@vue/test-utils'
+import { createPinia, setActivePinia } from 'pinia'
+import { createRouter, createMemoryHistory } from 'vue-router'
+
+// Spec 109 FR-051 / US1-4 (T170): a fresh instance (no server configured)
+// shows a "Get started" card instead of the green "All clear" banner, which
+// would be false reassurance. Any attention item still wins; the CLI is
+// unchanged.
+
+const state = vi.hoisted(() => ({
+  servers: [] as unknown[],
+  attention: { count: 0, items: [] as unknown[] },
+  onboarding: { has_connected_client: false } as Record<string, unknown>,
+  serversPending: false,
+}))
+
+vi.mock('@/services/api', () => {
+  const ok = (data: unknown = null) => vi.fn().mockResolvedValue({ success: true, data })
+  const fakeEventSource = {
+    onopen: null,
+    onmessage: null,
+    onerror: null,
+    addEventListener() {},
+    removeEventListener() {},
+    close() {},
+  }
+  const base: Record<string, unknown> = {
+    getAttention: vi.fn(async () => ({ success: true, data: state.attention })),
+    getServers: vi.fn(() =>
+      state.serversPending
+        ? new Promise(() => {})
+        : Promise.resolve({ success: true, data: { servers: state.servers } })
+    ),
+    getOnboardingState: vi.fn(async () => ({
+      success: true,
+      data: { should_show_wizard: false, state: { engaged: false }, ...state.onboarding },
+    })),
+    getActivitySummary: ok({ call_count: 0, blocked_count: 0, call_error_count: 0 }),
+    createEventSource: vi.fn(() => fakeEventSource),
+    hasAPIKey: vi.fn(() => true),
+    getAPIKeyPreview: vi.fn(() => 'test…'),
+    onAuthError: vi.fn(() => () => {}),
+  }
+  return {
+    default: new Proxy(base, {
+      get(target: Record<string, unknown>, prop: string) {
+        if (prop in target) return target[prop]
+        target[prop] = ok()
+        return target[prop]
+      },
+    }),
+  }
+})
+
+vi.mock('@/composables/useSecurityScannerStatus', () => ({
+  refreshSecurityScannerStatus: vi.fn().mockResolvedValue(undefined),
+  useSecurityScannerStatus: () => ({
+    totalFindings: ref(0),
+    totalScans: ref(0),
+    loaded: ref(true),
+  }),
+}))
+
+import Home from '@/views/Home.vue'
+import api from '@/services/api'
+import { useAuthStore } from '@/stores/auth'
+import { useOnboardingStore } from '@/stores/onboarding'
+
+class FakeEventSource {
+  close() {}
+  addEventListener() {}
+  onmessage: ((e: unknown) => void) | null = null
+  onerror: ((e: unknown) => void) | null = null
+}
+
+const ATTENTION_ITEM = {
+  id: 'server_review:server:github',
+  kind: 'server_review',
+  rank: 50,
+  subject: { type: 'server', id: 'github', name: 'github' },
+  summary: 'github: waiting for review',
+  fix: { verb: 'review', label: 'Review', target: '/review/github' },
+  since: '2026-09-25T06:00:00Z',
+}
+
+async function mountHome(opts: { tenant?: boolean } = {}) {
+  const router = createRouter({
+    history: createMemoryHistory(),
+    routes: [
+      { path: '/', name: 'home', component: Home },
+      { path: '/add-server', name: 'add-server', component: { template: '<div />' } },
+      { path: '/clients', name: 'clients', component: { template: '<div />' } },
+      { path: '/activity', name: 'activity', component: { template: '<div />' } },
+      { path: '/usage', name: 'usage', component: { template: '<div />' } },
+      { path: '/:pathMatch(.*)*', name: 'other', component: { template: '<div />' } },
+    ],
+  })
+  router.push('/')
+  await router.isReady()
+  const pinia = createPinia()
+  setActivePinia(pinia)
+  if (opts.tenant) {
+    const auth = useAuthStore()
+    auth.isTeamsEdition = true
+    auth.user = {
+      id: 'carol',
+      email: 'carol@example.com',
+      display_name: 'Carol',
+      role: 'user',
+      provider: 'oidc',
+      created_at: '',
+      last_login_at: '',
+    }
+    ;(api.hasAPIKey as unknown as ReturnType<typeof vi.fn>).mockReturnValue(false)
+  }
+  const wrapper = shallowMount(Home, {
+    global: {
+      plugins: [pinia, router],
+      stubs: { RouterLink: false, AttentionList: false, UsageSummaryStrip: false },
+    },
+  })
+  await flushPromises()
+  return { wrapper, router, pinia }
+}
+
+const CARD = '[data-test="home-getting-started"]'
+const ALL_CLEAR = '[data-test="attention-all-clear"]'
+
+describe('Home getting-started card (Spec 109 FR-051, T170)', () => {
+  beforeEach(() => {
+    state.servers = []
+    state.attention = { count: 0, items: [] }
+    state.onboarding = { has_connected_client: false }
+    state.serversPending = false
+    ;(api.hasAPIKey as unknown as ReturnType<typeof vi.fn>).mockReturnValue(true)
+    ;(globalThis as unknown as { EventSource: unknown }).EventSource = FakeEventSource
+  })
+
+  it('replaces "All clear" and hides the top usage strip when no server is configured', async () => {
+    const { wrapper, router, pinia } = await mountHome()
+
+    expect(wrapper.find(CARD).exists()).toBe(true)
+    expect(wrapper.find(CARD).text()).toContain('Get started')
+    expect(wrapper.find(CARD).text()).toContain('MCPProxy has no servers yet')
+    expect(wrapper.find(ALL_CLEAR).exists()).toBe(false)
+    expect(wrapper.find('[data-test="home-usage-strip-top"]').exists()).toBe(false)
+
+    await wrapper.find('[data-test="home-getting-started-add-server"]').trigger('click')
+    await flushPromises()
+    expect(router.currentRoute.value.fullPath).toBe('/add-server')
+
+    await router.push('/')
+    await wrapper.find('[data-test="home-getting-started-connect-client"]').trigger('click')
+    await flushPromises()
+    expect(router.currentRoute.value.fullPath).toBe('/clients')
+
+    const onboarding = useOnboardingStore(pinia)
+    const openWizard = vi.spyOn(onboarding, 'openWizard')
+    await wrapper.find('[data-test="home-getting-started-wizard"]').trigger('click')
+    expect(openWizard).toHaveBeenCalled()
+  })
+
+  it('lets an attention item win over the card', async () => {
+    state.attention = { count: 1, items: [ATTENTION_ITEM] }
+    const { wrapper } = await mountHome()
+
+    expect(wrapper.find(CARD).exists()).toBe(false)
+    expect(wrapper.find('[data-test="attention-list-card"]').exists()).toBe(true)
+  })
+
+  it('keeps "All clear" once a server is configured', async () => {
+    state.servers = [{ name: 'notes', enabled: true, connected: true, tool_count: 3 }]
+    const { wrapper } = await mountHome()
+
+    expect(wrapper.find(CARD).exists()).toBe(false)
+    expect(wrapper.find(ALL_CLEAR).exists()).toBe(true)
+    expect(wrapper.find('[data-test="home-usage-strip-top"]').exists()).toBe(true)
+  })
+
+  it('does not flash the card or "All clear" before the server list has loaded', async () => {
+    state.serversPending = true
+    const { wrapper } = await mountHome()
+
+    expect(wrapper.find(CARD).exists()).toBe(false)
+    // The server count is unknown, so "All clear" would be a guess too.
+    expect(wrapper.find(ALL_CLEAR).exists()).toBe(false)
+  })
+
+  it('shows the client step as done once a client is connected', async () => {
+    state.onboarding = { has_connected_client: true }
+    const { wrapper } = await mountHome()
+
+    const step = wrapper.find('[data-test="home-getting-started-client-done"]')
+    expect(step.exists()).toBe(true)
+    expect(step.text()).toContain('connected')
+  })
+
+  it('shows no card to a tenant principal', async () => {
+    const { wrapper } = await mountHome({ tenant: true })
+    expect(wrapper.find(CARD).exists()).toBe(false)
+  })
+})
diff --git a/frontend/tests/unit/home-token-savings-estimate.spec.ts b/frontend/tests/unit/home-token-savings-estimate.spec.ts
new file mode 100644
index 000000000..431925f23
--- /dev/null
+++ b/frontend/tests/unit/home-token-savings-estimate.spec.ts
@@ -0,0 +1,171 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { ref } from 'vue'
+import { shallowMount, flushPromises } from '@vue/test-utils'
+import { createPinia, setActivePinia } from 'pinia'
+import { createRouter, createMemoryHistory } from 'vue-router'
+
+// Spec 109 FR-073 (T166, #1394 item 1): the Home hub chip, the Token Savings
+// Details stat and the details title badge say "estimate" while the core
+// reports `ServerTokenMetrics.estimated`, exactly as Usage.vue already does.
+
+const tokenStatsSpy = vi.hoisted(() => vi.fn())
+
+function tokenStats(over: Record<string, unknown> = {}) {
+  return {
+    success: true,
+    data: {
+      saved_tokens: 4200,
+      saved_tokens_percentage: 92.5,
+      total_server_tool_list_size: 4540,
+      average_query_result_size: 340,
+      per_server_tool_list_sizes: { notes: 4540 },
+      ...over,
+    },
+  }
+}
+
+vi.mock('@/services/api', () => {
+  const ok = (data: unknown = null) => vi.fn().mockResolvedValue({ success: true, data })
+  const fakeEventSource = {
+    onopen: null,
+    onmessage: null,
+    onerror: null,
+    addEventListener() {},
+    removeEventListener() {},
+    close() {},
+  }
+  const base: Record<string, unknown> = {
+    getAttention: ok({ count: 0, items: [] }),
+    getTokenStats: tokenStatsSpy,
+    getServers: ok({ servers: [{ name: 'notes', enabled: true, connected: true, tool_count: 3 }] }),
+    getActivitySummary: ok({ call_count: 0, blocked_count: 0, call_error_count: 0 }),
+    createEventSource: vi.fn(() => fakeEventSource),
+    hasAPIKey: vi.fn(() => true),
+    getAPIKeyPreview: vi.fn(() => 'test…'),
+    onAuthError: vi.fn(() => () => {}),
+  }
+  return {
+    default: new Proxy(base, {
+      get(target: Record<string, unknown>, prop: string) {
+        if (prop in target) return target[prop]
+        target[prop] = ok()
+        return target[prop]
+      },
+    }),
+  }
+})
+
+vi.mock('@/composables/useSecurityScannerStatus', () => ({
+  refreshSecurityScannerStatus: vi.fn().mockResolvedValue(undefined),
+  useSecurityScannerStatus: () => ({
+    totalFindings: ref(0),
+    totalScans: ref(0),
+    loaded: ref(true),
+  }),
+}))
+
+import Home from '@/views/Home.vue'
+import api from '@/services/api'
+import { useAuthStore } from '@/stores/auth'
+
+class FakeEventSource {
+  close() {}
+  addEventListener() {}
+  onmessage: ((e: unknown) => void) | null = null
+  onerror: ((e: unknown) => void) | null = null
+}
+
+async function mountHome(tenant = false) {
+  const router = createRouter({
+    history: createMemoryHistory(),
+    routes: [
+      { path: '/', name: 'home', component: Home },
+      { path: '/:pathMatch(.*)*', name: 'other', component: { template: '<div />' } },
+    ],
+  })
+  router.push('/')
+  await router.isReady()
+  const pinia = createPinia()
+  setActivePinia(pinia)
+  if (tenant) {
+    const auth = useAuthStore()
+    auth.isTeamsEdition = true
+    auth.user = {
+      id: 'carol',
+      email: 'carol@example.com',
+      display_name: 'Carol',
+      role: 'user',
+      provider: 'oidc',
+      created_at: '',
+      last_login_at: '',
+    }
+    // A tenant has no local API key.
+    ;(api.hasAPIKey as unknown as ReturnType<typeof vi.fn>).mockReturnValue(false)
+  }
+  const wrapper = shallowMount(Home, {
+    global: {
+      plugins: [pinia, router],
+      stubs: { RouterLink: { template: '<a><slot /></a>' }, AttentionList: false },
+    },
+  })
+  await flushPromises()
+  return wrapper
+}
+
+const CHIP = '[data-test="dashboard-token-savings-chip"]'
+const CHIP_ESTIMATE = '[data-test="dashboard-token-savings-estimate"]'
+const DETAILS_ESTIMATE = '[data-test="dashboard-token-savings-details-estimate"]'
+const SAVED_BADGE = '[data-test="dashboard-token-savings-saved-badge"]'
+
+describe('Home token savings estimate label (Spec 109 FR-073)', () => {
+  beforeEach(() => {
+    setActivePinia(createPinia())
+    tokenStatsSpy.mockReset()
+    ;(api.hasAPIKey as unknown as ReturnType<typeof vi.fn>).mockReturnValue(true)
+    ;(globalThis as unknown as { EventSource: unknown }).EventSource = FakeEventSource
+  })
+
+  it('marks the hub chip, the details stat and the title badge as an estimate', async () => {
+    tokenStatsSpy.mockResolvedValue(tokenStats({ estimated: true }))
+    const wrapper = await mountHome()
+
+    const chipMarker = wrapper.find(`${CHIP} ${CHIP_ESTIMATE}`)
+    expect(chipMarker.exists()).toBe(true)
+    expect(chipMarker.text()).toBe('estimate')
+    expect(chipMarker.attributes('title')).toContain('simulated estimate')
+
+    const detailsMarker = wrapper.find(DETAILS_ESTIMATE)
+    expect(detailsMarker.exists()).toBe(true)
+    expect(detailsMarker.text()).toBe('estimate')
+
+    expect(wrapper.find(SAVED_BADGE).text()).toMatch(/· estimate$/)
+  })
+
+  it('renders no estimate marker once the figure is measured', async () => {
+    tokenStatsSpy.mockResolvedValue(tokenStats({ estimated: false }))
+    const wrapper = await mountHome()
+
+    expect(wrapper.find(CHIP).exists()).toBe(true)
+    expect(wrapper.find(CHIP_ESTIMATE).exists()).toBe(false)
+    expect(wrapper.find(DETAILS_ESTIMATE).exists()).toBe(false)
+    expect(wrapper.find(SAVED_BADGE).text()).toBe('4.2K saved')
+  })
+
+  it('treats an absent `estimated` (an older core) as measured', async () => {
+    tokenStatsSpy.mockResolvedValue(tokenStats())
+    const wrapper = await mountHome()
+
+    expect(wrapper.find(CHIP).exists()).toBe(true)
+    expect(wrapper.find(CHIP_ESTIMATE).exists()).toBe(false)
+    expect(wrapper.find(DETAILS_ESTIMATE).exists()).toBe(false)
+    expect(wrapper.find(SAVED_BADGE).text()).toBe('4.2K saved')
+  })
+
+  it('never requests token stats, and renders no chip, for a tenant principal', async () => {
+    tokenStatsSpy.mockResolvedValue(tokenStats({ estimated: true }))
+    const wrapper = await mountHome(true)
+
+    expect(tokenStatsSpy).not.toHaveBeenCalled()
+    expect(wrapper.find(CHIP).exists()).toBe(false)
+  })
+})

From 639244d52117c3bdebfce1c6fad70ae2a33a8f60 Mon Sep 17 00:00:00 2001
From: Algis Dumbris <a.dumbris@gmail.com>
Date: Fri, 2 Oct 2026 16:06:49 +0300
Subject: [PATCH 2/6] fix(web): refetch once when clearing an Activity
 server/tool conflict and surface blocked attempts (Spec fix-ux-residuals)

---
 frontend/src/views/Activity.vue               |  49 +++++-
 .../activity-blocked-in-calls-view.spec.ts    | 144 ++++++++++++++++++
 .../activity-scope-conflict-clear.spec.ts     | 144 ++++++++++++++++++
 3 files changed, 334 insertions(+), 3 deletions(-)
 create mode 100644 frontend/tests/unit/activity-blocked-in-calls-view.spec.ts
 create mode 100644 frontend/tests/unit/activity-scope-conflict-clear.spec.ts

diff --git a/frontend/src/views/Activity.vue b/frontend/src/views/Activity.vue
index 3c3c7c680..cd75d070b 100644
--- a/frontend/src/views/Activity.vue
+++ b/frontend/src/views/Activity.vue
@@ -110,6 +110,7 @@
                   filterStatus === part.status && part.status !== '' ? 'font-semibold underline' : '',
                 ]"
                 :aria-pressed="filterStatus === part.status"
+                :title="part.key === 'blocked' && activeView === 'calls' ? BLOCKED_CALLS_TITLE : undefined"
                 @click="applySummaryFilter(part)"
               >
                 {{ part.label }}
@@ -260,7 +261,7 @@
         -->
         <div class="stat-title">Events (24h)</div>
         <div class="stat-value text-2xl">{{ summary.total_count }}</div>
-        <div class="stat-desc">{{ summary.call_count }} calls</div>
+        <div class="stat-desc">{{ summary.call_count }} {{ summary.call_count === 1 ? 'call' : 'calls' }}</div>
       </button>
       <button
         v-for="tile in statusTiles"
@@ -543,6 +544,20 @@
           </svg>
           <p class="text-lg">{{ hasActiveFilters || scopeApplied ? 'No matching activities' : 'No activity records found' }}</p>
           <p class="text-sm mt-1">{{ hasActiveFilters || scopeApplied ? 'Try adjusting your filters, or remove a profile, client or token chip above' : 'Activity will appear here as tools are called and actions are taken' }}</p>
+          <!-- T168: a refused attempt is a `policy_decision` row, which the Tool
+               calls view lists only under status=blocked. When the window holds
+               some, say so instead of leaving a bare empty table. -->
+          <div v-if="showBlockedOffer" class="mt-3" data-test="activity-empty-blocked-offer">
+            <p class="text-sm">Refused attempts are not tool calls that ran; they are listed under Blocked.</p>
+            <button
+              type="button"
+              class="btn btn-sm btn-outline mt-2"
+              data-test="activity-empty-show-blocked"
+              @click="filterStatus = 'blocked'"
+            >
+              Show {{ blockedAttemptCount }} blocked attempt{{ blockedAttemptCount === 1 ? '' : 's' }}
+            </button>
+          </div>
         </div>
 
         <!-- Activity Table.
@@ -2038,6 +2053,15 @@ watch(showFilterPanel, expanded => {
 /** "54 calls · 6 errors · 1 blocked" — zeros omitted. */
 const summaryParts = computed(() => compactSummaryParts(summary.value))
 
+// T168: refused attempts (`policy_decision`, status `blocked`) are listed in the
+// Tool calls view only under status=blocked, so the blocked chip says so there.
+const BLOCKED_CALLS_TITLE =
+  'Blocked call attempts in the last 24 h, including calls a profile or token refused. Click to list them.'
+const blockedAttemptCount = computed(() => summary.value?.blocked_count ?? 0)
+const showBlockedOffer = computed(
+  () => activeView.value === 'calls' && !filterStatus.value && blockedAttemptCount.value > 0
+)
+
 /**
  * The status tiles, as a partition of the Events total beside them (F2, #1046).
  * The list — including whether the "Other / internal" tile is warranted — is
@@ -2109,10 +2133,22 @@ const clearChip = (chip: ActiveFilterChip) => {
       void clearParentFilter()
       break
     case 'server':
-      filterServer.value = ''
+      // Removing either side of a server/tool conflict resolves the
+      // contradiction (contract rule 8). The conflicting `tool` is the raw
+      // "server:tool" value, so split it the way the URL round trip would:
+      // one request for what remains, not a stuck empty state.
+      if (scopeConflict.value) {
+        const split = splitScopeTool(filterTool.value, undefined)
+        filterServer.value = split.server ?? ''
+        filterTool.value = split.tool ?? ''
+        scopeConflict.value = false
+      } else {
+        filterServer.value = ''
+      }
       break
     case 'tool':
       filterTool.value = ''
+      scopeConflict.value = false
       break
     case 'status':
       filterStatus.value = ''
@@ -2605,6 +2641,10 @@ const loadActivities = async () => {
 
 // Clear filters
 const clearFilters = () => {
+  // First, so the conflict banner leaves in the same tick and the refetch
+  // watch (which also tracks scopeConflict) runs loadActivities() once, past
+  // its conflict guard.
+  scopeConflict.value = false
   selectedTypes.value = []
   filterServer.value = ''
   filterTool.value = ''
@@ -2947,7 +2987,10 @@ watch([effectiveTypes, filterServer, filterTool, filterStatus, filterSensitiveDa
 // applyRouteFilters() already ran during setup (top of this file), so the
 // initial values it wrote never trigger this watch — only a later, genuine
 // change does; the first fetch is onMounted's explicit call below.
-watch([effectiveTypes, filterServer, filterTool, filterStatus, filterStartDate, filterEndDate], () => {
+// `scopeConflict` is a source too: a conflict that resolves without any other
+// filter ref changing (a URL edit, or "Clear filters" setting everything in one
+// tick) must refetch, and a callback runs once per flush so it never doubles up.
+watch([effectiveTypes, filterServer, filterTool, filterStatus, filterStartDate, filterEndDate, scopeConflict], () => {
   void loadActivities()
 }, { deep: true })
 
diff --git a/frontend/tests/unit/activity-blocked-in-calls-view.spec.ts b/frontend/tests/unit/activity-blocked-in-calls-view.spec.ts
new file mode 100644
index 000000000..82f2afe86
--- /dev/null
+++ b/frontend/tests/unit/activity-blocked-in-calls-view.spec.ts
@@ -0,0 +1,144 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { mount, flushPromises } from '@vue/test-utils'
+import { createPinia, setActivePinia } from 'pinia'
+import { createRouter, createMemoryHistory } from 'vue-router'
+
+// Spec 109 FR-070 / US6-6 (T168): a refused attempt is stored as a
+// `policy_decision` row (status `blocked`). The Tool calls view lists it only
+// under `status=blocked`, so the "N blocked" chip must open that filter, and an
+// empty Tool calls table with blocked attempts in the window must offer it.
+
+const CALL = {
+  id: 'c1',
+  type: 'tool_call',
+  status: 'success',
+  timestamp: '2026-09-20T10:04:00Z',
+  server_name: 'fixture',
+  tool_name: 'read',
+  request_id: 'r1',
+  duration_ms: 10,
+}
+const REFUSAL = {
+  id: 'p1',
+  type: 'policy_decision',
+  status: 'blocked',
+  timestamp: '2026-09-20T10:06:00Z',
+  server_name: 'fixture',
+  tool_name: 'write',
+  request_id: 'r2',
+  metadata: { block_reason: 'profile refused' },
+}
+
+const mockState = vi.hoisted(() => ({
+  rows: [] as unknown[],
+  summary: {} as Record<string, unknown>,
+}))
+
+vi.mock('@/services/api', () => {
+  const ok = (data: unknown) => Promise.resolve({ success: true, data })
+  return {
+    default: {
+      getActivities: vi.fn((params?: { type?: string; status?: string }) => {
+        const types = params?.type ? params.type.split(',') : null
+        let rows = mockState.rows as Array<{ type: string; status: string }>
+        if (types) rows = rows.filter(a => types.includes(a.type))
+        if (params?.status) rows = rows.filter(a => a.status === params.status)
+        return ok({ activities: rows, total: rows.length, limit: 200, offset: 0 })
+      }),
+      getActivitySummary: vi.fn(() => ok(mockState.summary)),
+      getSessions: vi.fn(() => ok({ sessions: [] })),
+      getActivityExportUrl: vi.fn(() => 'http://localhost/api/v1/activity/export?format=json'),
+    },
+  }
+})
+
+async function mountActivityAt(path: string) {
+  const api = (await import('@/services/api')).default as unknown as { getActivities: ReturnType<typeof vi.fn> }
+  const Activity = (await import('@/views/Activity.vue')).default
+  const router = createRouter({
+    history: createMemoryHistory(),
+    routes: [
+      { path: '/activity', component: Activity },
+      { path: '/servers/:serverName', component: { template: '<div/>' } },
+    ],
+  })
+  await router.push(path)
+  await router.isReady()
+  const wrapper = mount(Activity, { global: { plugins: [createPinia(), router] } })
+  await flushPromises()
+  await flushPromises()
+  return { wrapper, router, api }
+}
+
+describe('Activity - blocked attempts in the Tool calls view (T168)', () => {
+  beforeEach(() => {
+    setActivePinia(createPinia())
+    vi.clearAllMocks()
+    window.localStorage.clear()
+    mockState.rows = [CALL, REFUSAL]
+    mockState.summary = { period: '24h', total_count: 3, call_count: 1, success_count: 1, blocked_count: 1 }
+  })
+
+  it('the "1 blocked" chip names refused calls and opens the blocked rows', async () => {
+    const { wrapper, router, api } = await mountActivityAt('/activity')
+    expect(wrapper.findAll('[data-test="activity-row"]')).toHaveLength(1)
+    expect(wrapper.text()).not.toContain('profile refused')
+
+    const chip = wrapper.find('[data-test="activity-compact-blocked"]')
+    expect(chip.attributes('title')).toContain('refused')
+
+    api.getActivities.mockClear()
+    await chip.trigger('click')
+    await flushPromises()
+    await flushPromises()
+
+    expect(api.getActivities).toHaveBeenCalledTimes(1)
+    expect(api.getActivities).toHaveBeenCalledWith(
+      expect.objectContaining({ type: 'tool_call,internal_tool_call,policy_decision', status: 'blocked' })
+    )
+    expect(router.currentRoute.value.query.status).toBe('blocked')
+    expect(wrapper.findAll('[data-test="activity-row"]')).toHaveLength(1)
+    expect(wrapper.findAll('[data-test="activity-row"]')[0].text()).toContain('write')
+  })
+
+  it('an empty Tool calls table with blocked attempts offers "Show 1 blocked attempt"', async () => {
+    mockState.rows = [REFUSAL]
+    mockState.summary = { period: '24h', total_count: 1, call_count: 0, blocked_count: 1 }
+    const { wrapper, router } = await mountActivityAt('/activity?view=calls')
+
+    const button = wrapper.find('[data-test="activity-empty-show-blocked"]')
+    expect(button.exists()).toBe(true)
+    expect(button.text()).toBe('Show 1 blocked attempt')
+
+    await button.trigger('click')
+    await flushPromises()
+    await flushPromises()
+    expect(router.currentRoute.value.query.status).toBe('blocked')
+    expect(wrapper.findAll('[data-test="activity-row"]')).toHaveLength(1)
+  })
+
+  it('pluralises the offer for several blocked attempts', async () => {
+    mockState.rows = []
+    mockState.summary = { period: '24h', total_count: 2, call_count: 0, blocked_count: 2 }
+    const { wrapper } = await mountActivityAt('/activity?view=calls')
+    expect(wrapper.find('[data-test="activity-empty-show-blocked"]').text()).toBe('Show 2 blocked attempts')
+  })
+
+  it('offers nothing on the All view, which already lists refusals', async () => {
+    mockState.rows = [REFUSAL]
+    const { wrapper } = await mountActivityAt('/activity?view=all')
+    expect(wrapper.findAll('[data-test="activity-row"]')).toHaveLength(1)
+    expect(wrapper.find('[data-test="activity-empty-show-blocked"]').exists()).toBe(false)
+  })
+
+  it('says "1 call", not "1 calls", on the Events tile', async () => {
+    window.localStorage.setItem('mcpproxy.activity.filtersExpanded', 'true')
+    mockState.summary = { period: '24h', total_count: 3, call_count: 1, success_count: 1, blocked_count: 1 }
+    const one = await mountActivityAt('/activity')
+    expect(one.wrapper.find('[data-test="kpi-card-total"] .stat-desc').text()).toBe('1 call')
+
+    mockState.summary = { period: '24h', total_count: 3, call_count: 2, success_count: 2, blocked_count: 1 }
+    const two = await mountActivityAt('/activity')
+    expect(two.wrapper.find('[data-test="kpi-card-total"] .stat-desc').text()).toBe('2 calls')
+  })
+})
diff --git a/frontend/tests/unit/activity-scope-conflict-clear.spec.ts b/frontend/tests/unit/activity-scope-conflict-clear.spec.ts
new file mode 100644
index 000000000..69f62661a
--- /dev/null
+++ b/frontend/tests/unit/activity-scope-conflict-clear.spec.ts
@@ -0,0 +1,144 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { mount, flushPromises } from '@vue/test-utils'
+import { createPinia, setActivePinia } from 'pinia'
+import { createRouter, createMemoryHistory } from 'vue-router'
+
+// Spec 109 url-filter-contract rule 8 / US6-8 (T167, #1394 item 2): clearing a
+// server/tool conflict - "Clear filters", or removing either conflicting chip -
+// issues exactly one request for what remains and leaves the page on rows, not
+// on "No activity records found".
+
+const FS_READ = {
+  id: 'a1',
+  type: 'tool_call',
+  status: 'success',
+  timestamp: '2026-09-20T10:04:00Z',
+  server_name: 'fixture',
+  tool_name: 'read',
+  request_id: 'r1',
+  duration_ms: 10,
+}
+const OTHER = {
+  id: 'a2',
+  type: 'tool_call',
+  status: 'success',
+  timestamp: '2026-09-20T10:05:00Z',
+  server_name: 'other',
+  tool_name: 'x',
+  request_id: 'r2',
+  duration_ms: 10,
+}
+const ALL = [FS_READ, OTHER]
+
+vi.mock('@/services/api', () => {
+  const ok = (data: unknown) => Promise.resolve({ success: true, data })
+  return {
+    default: {
+      getActivities: vi.fn((params?: { server?: string; tool?: string }) => {
+        let rows = ALL
+        if (params?.server) rows = rows.filter(a => a.server_name === params.server)
+        if (params?.tool) rows = rows.filter(a => a.tool_name === params.tool)
+        return ok({ activities: rows, total: rows.length, limit: 200, offset: 0 })
+      }),
+      getActivitySummary: vi.fn(() =>
+        ok({ period: '24h', total_count: 2, success_count: 2, error_count: 0, blocked_count: 0, rejected_count: 0 })
+      ),
+      getSessions: vi.fn(() => ok({ sessions: [] })),
+      getActivityExportUrl: vi.fn(() => 'http://localhost/api/v1/activity/export?format=json'),
+    },
+  }
+})
+
+async function mountActivityAt(path: string) {
+  const api = (await import('@/services/api')).default as unknown as { getActivities: ReturnType<typeof vi.fn> }
+  const Activity = (await import('@/views/Activity.vue')).default
+  const router = createRouter({
+    history: createMemoryHistory(),
+    routes: [
+      { path: '/activity', component: Activity },
+      { path: '/servers/:serverName', component: { template: '<div/>' } },
+    ],
+  })
+  await router.push(path)
+  await router.isReady()
+  const wrapper = mount(Activity, { global: { plugins: [createPinia(), router] } })
+  await flushPromises()
+  await flushPromises()
+  return { wrapper, router, api }
+}
+
+const CONFLICT = '/activity?view=all&server=fixture&tool=other:x'
+
+describe('Activity - clearing a server/tool conflict refetches once (T167)', () => {
+  beforeEach(() => {
+    setActivePinia(createPinia())
+    vi.clearAllMocks()
+  })
+
+  it('"Clear filters" on the banner issues one unfiltered request and shows rows', async () => {
+    const { wrapper, router, api } = await mountActivityAt(CONFLICT)
+    expect(api.getActivities).not.toHaveBeenCalled()
+    expect(wrapper.find('[data-test="activity-scope-conflict"]').exists()).toBe(true)
+
+    await wrapper.find('[data-test="activity-scope-conflict-clear"]').trigger('click')
+    await flushPromises()
+    await flushPromises()
+
+    expect(api.getActivities).toHaveBeenCalledTimes(1)
+    const params = api.getActivities.mock.calls[0][0] as Record<string, unknown>
+    expect(params.server).toBeUndefined()
+    expect(params.tool).toBeUndefined()
+    expect(params.type).toBeUndefined()
+    expect(wrapper.find('[data-test="activity-scope-conflict"]').exists()).toBe(false)
+    expect(wrapper.findAll('[data-test="activity-row"]')).toHaveLength(2)
+    expect(wrapper.text()).not.toContain('No activity records found')
+    expect(router.currentRoute.value.query).toEqual({ view: 'all' })
+  })
+
+  it('removing only the tool chip requests the remaining server once', async () => {
+    const { wrapper, router, api } = await mountActivityAt(CONFLICT)
+    await wrapper.find('[data-test="activity-filter-chip-tool"]').trigger('click')
+    await flushPromises()
+    await flushPromises()
+
+    expect(api.getActivities).toHaveBeenCalledTimes(1)
+    const params = api.getActivities.mock.calls[0][0] as Record<string, unknown>
+    expect(params.server).toBe('fixture')
+    expect(params.tool).toBeUndefined()
+    expect(wrapper.find('[data-test="activity-scope-conflict"]').exists()).toBe(false)
+    expect(router.currentRoute.value.query.server).toBe('fixture')
+    expect(router.currentRoute.value.query.tool).toBeUndefined()
+    expect(wrapper.findAll('[data-test="activity-row"]')).toHaveLength(1)
+  })
+
+  it('removing only the server chip requests the remaining "server:tool" once', async () => {
+    const { wrapper, api } = await mountActivityAt(CONFLICT)
+    await wrapper.find('[data-test="activity-filter-chip-server"]').trigger('click')
+    await flushPromises()
+    await flushPromises()
+
+    expect(api.getActivities).toHaveBeenCalledTimes(1)
+    const params = api.getActivities.mock.calls[0][0] as Record<string, unknown>
+    // The tool's own server prefix carries the server once the explicit one is gone.
+    expect(params.server).toBe('other')
+    expect(params.tool).toBe('x')
+    expect(wrapper.find('[data-test="activity-scope-conflict"]').exists()).toBe(false)
+  })
+
+  it('editing the URL to resolve the conflict requests once', async () => {
+    const { wrapper, router, api } = await mountActivityAt(CONFLICT)
+    await router.replace('/activity?view=all&server=fixture')
+    await flushPromises()
+    await flushPromises()
+
+    expect(api.getActivities).toHaveBeenCalledTimes(1)
+    expect((api.getActivities.mock.calls[0][0] as { server?: string }).server).toBe('fixture')
+    expect(wrapper.find('[data-test="activity-scope-conflict"]').exists()).toBe(false)
+  })
+
+  it('agreeing servers are not a conflict and request once on mount', async () => {
+    const { wrapper, api } = await mountActivityAt('/activity?view=all&server=fixture&tool=fixture:read')
+    expect(wrapper.find('[data-test="activity-scope-conflict"]').exists()).toBe(false)
+    expect(api.getActivities).toHaveBeenCalledTimes(1)
+  })
+})

From 52ca29f71ac10efc5b3a546d3087cce64d6c981d Mon Sep 17 00:00:00 2001
From: Algis Dumbris <a.dumbris@gmail.com>
Date: Fri, 2 Oct 2026 16:06:49 +0300
Subject: [PATCH 3/6] fix(web): colour Server Detail health by status (Spec
 fix-ux-residuals)

---
 frontend/src/views/ServerDetail.vue           |  54 ++++-
 ...server-detail-health-status-colour.spec.ts | 185 ++++++++++++++++++
 2 files changed, 238 insertions(+), 1 deletion(-)
 create mode 100644 frontend/tests/unit/server-detail-health-status-colour.spec.ts

diff --git a/frontend/src/views/ServerDetail.vue b/frontend/src/views/ServerDetail.vue
index 7a3c18eaf..e7fdebb00 100644
--- a/frontend/src/views/ServerDetail.vue
+++ b/frontend/src/views/ServerDetail.vue
@@ -1207,7 +1207,7 @@
                 <dl class="grid grid-cols-[max-content_1fr] gap-x-6 gap-y-2 mt-2 text-sm">
                   <dt class="text-base-content/60">Status</dt>
                   <dd data-test="server-config-health-status">
-                    <span :class="healthLevelBadgeClass(server.health.level)">{{ configHealthStatusLabel(server.health) }}</span>
+                    <span :class="healthStatusBadgeClass(server.health)">{{ configHealthStatusLabel(server.health) }}</span>
                   </dd>
                   <dt class="text-base-content/60">Admin State</dt>
                   <dd><span class="badge badge-ghost badge-sm">{{ server.health.admin_state }}</span></dd>
@@ -1604,6 +1604,7 @@ import { refName } from '@/utils/secretRef'
 import { isTerminalScanStatus, decideScanReconcile, finalizeToastKind } from '@/utils/scanState'
 import { selectQuarantinedTools } from '@/utils/toolQuarantine'
 import { oauthSignInState, healthStatusLabel, healthActionLabel, healthStatusText } from '@/utils/health'
+import type { HealthStatusValue } from '@/types/contracts'
 import { describeIsolation } from '@/utils/isolationState'
 import { computeToolDiffSections } from '@/utils/toolDiff'
 import { groupFindingsByTool, type FlaggedToolGroup } from '@/utils/toolLocation'
@@ -1841,6 +1842,11 @@ const signInState = computed(() => {
 // can no longer read green here while the tiles say something else.
 const statusBadgeClass = computed(() => {
   const health = server.value?.health
+  // Health-vocabulary contract, "Colors": colour keys on `status`, never on
+  // `level`, wherever a status label is rendered. `level` only colours a
+  // payload without a known `status` (an older core).
+  const tone = healthStatusTone(health)
+  if (tone) return TONE_BADGE[tone]
   if (health) {
     switch (health.admin_state) {
       case 'disabled':
@@ -1918,6 +1924,11 @@ const healthLevelLabel = computed(() => {
   // with a "Sign-in required" sub-line. A non-enabled admin state therefore wins
   // the tile's word; the observed health keeps its own vocabulary on the
   // sub-line below ("Quarantined for review", "Disabled", "Sign-in required").
+  // Contract: a payload with a `status` speaks the one label table in every
+  // admin state ("Needs review", "Disabled"), so this tile never gives a second,
+  // different reading of the same server as the badges beside it.
+  const knownStatus = server.value?.health?.status
+  if (knownStatus && HEALTH_STATUS_TONE[knownStatus as HealthStatusValue]) return healthStatusLabel(knownStatus)
   switch (adminStateLabel.value) {
     case 'Quarantined':
       return 'Blocked'
@@ -1948,6 +1959,8 @@ const healthLevelLabel = computed(() => {
 // signal), not the FR-011 status label text above, so an unrecognized/missing
 // status still gets a sensible color.
 const healthLevelTone = computed(() => {
+  const tone = healthStatusTone(server.value?.health)
+  if (tone) return TONE_TEXT[tone]
   if (adminStateLabel.value === 'Disabled') return 'text-base-content/50'
   if (adminStateLabel.value === 'Quarantined') return 'text-base-content/50'
   const level = server.value?.health?.level
@@ -3524,6 +3537,45 @@ function formatConfigTime(isoString: string | null | undefined): string {
   return formatDateTime(isoString, isoString)
 }
 
+// Health-vocabulary contract, "Colors": one tone per `status`, shared by the
+// header badge, the Health tile and the Configuration -> Health badge.
+// Hoisting this into utils/health.ts (and ServerCard.vue) is a follow-up.
+type HealthTone = 'success' | 'neutral' | 'warning' | 'error'
+const HEALTH_STATUS_TONE: Record<HealthStatusValue, HealthTone> = {
+  ready: 'success',
+  connecting: 'neutral',
+  disabled: 'neutral',
+  sign_in_required: 'warning',
+  needs_review: 'warning',
+  needs_secret: 'warning',
+  needs_config: 'warning',
+  error: 'error',
+}
+const TONE_BADGE: Record<HealthTone, string> = {
+  success: 'badge-success',
+  neutral: 'badge-neutral',
+  warning: 'badge-warning',
+  error: 'badge-error',
+}
+const TONE_TEXT: Record<HealthTone, string> = {
+  success: 'text-success',
+  neutral: 'text-base-content/50',
+  warning: 'text-warning',
+  error: 'text-error',
+}
+
+/** The tone of a known `health.status`, or undefined for a payload without one. */
+function healthStatusTone(health: HealthStatus | undefined): HealthTone | undefined {
+  return health?.status ? HEALTH_STATUS_TONE[health.status as HealthStatusValue] : undefined
+}
+
+// healthStatusBadgeClass colours the Configuration -> Health badge by `status`,
+// falling back to the level colours for a payload that has none.
+function healthStatusBadgeClass(health: HealthStatus): string {
+  const tone = healthStatusTone(health)
+  return tone ? `badge ${TONE_BADGE[tone]} badge-sm` : healthLevelBadgeClass(health.level)
+}
+
 // healthLevelBadgeClass returns the daisyUI class set for a Health.Level
 // badge, mirroring the existing color choices used elsewhere in the app
 // (see e.g. server-list dot color logic).
diff --git a/frontend/tests/unit/server-detail-health-status-colour.spec.ts b/frontend/tests/unit/server-detail-health-status-colour.spec.ts
new file mode 100644
index 000000000..d65fb9087
--- /dev/null
+++ b/frontend/tests/unit/server-detail-health-status-colour.spec.ts
@@ -0,0 +1,185 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { mount, flushPromises } from '@vue/test-utils'
+import { createPinia, setActivePinia } from 'pinia'
+import { createRouter, createMemoryHistory } from 'vue-router'
+
+// Spec 109 health-vocabulary contract, "Colors" (T169): colour keys on
+// `health.status`, never on `level`, on every Server Detail element that
+// renders a status label. A quarantined server has `level: healthy` (being off
+// is intentional), so the Configuration -> Health badge used to read a green
+// "Needs review" and the tile said "Blocked" in grey for the same server.
+// `level` colours only a payload that carries no `status` (an older core).
+
+type ServerOverrides = Record<string, unknown>
+
+const state = { server: {} as ServerOverrides }
+
+vi.mock('@/services/api', () => {
+  const ok = (data: unknown = {}) => Promise.resolve({ success: true, data })
+  return {
+    default: {
+      getServers: vi.fn(() => ok({ servers: [state.server] })),
+      getServerTools: vi.fn(() => ok({ tools: [] })),
+      getToolApprovals: vi.fn(() => ok({ tools: [], count: 0 })),
+      getToolDiff: vi.fn(() => ok({})),
+      getSecurityOverview: vi.fn(() => ok({})),
+      listScanners: vi.fn(() => ok({ scanners: [] })),
+      getScanReport: vi.fn(() => ok({})),
+      getServerLogs: vi.fn(() => ok({ logs: [] })),
+      discoverServerTools: vi.fn(() => ok({})),
+    },
+  }
+})
+
+async function mountDetail(server: ServerOverrides) {
+  state.server = server
+  const ServerDetail = (await import('@/views/ServerDetail.vue')).default
+  const router = createRouter({
+    history: createMemoryHistory(),
+    routes: [{ path: '/servers/:serverName', component: { template: '<div/>' } }],
+  })
+  await router.push('/servers/probe?tab=config')
+  await router.isReady()
+  const wrapper = mount(ServerDetail, {
+    props: { serverName: 'probe' },
+    global: { plugins: [createPinia(), router] },
+  })
+  await flushPromises()
+  return wrapper
+}
+
+const base = {
+  name: 'probe',
+  protocol: 'http',
+  enabled: true,
+  connected: true,
+  quarantined: false,
+  tool_count: 2,
+}
+
+const configBadge = (w: Awaited<ReturnType<typeof mountDetail>>) =>
+  w.find('[data-test="server-config-health-status"] span')
+
+describe('ServerDetail — health colour keys on status (T169)', () => {
+  beforeEach(() => {
+    setActivePinia(createPinia())
+  })
+
+  const cases: Array<[string, string, string]> = [
+    ['ready', 'healthy', 'badge-success'],
+    ['connecting', 'healthy', 'badge-neutral'],
+    ['disabled', 'healthy', 'badge-neutral'],
+    ['sign_in_required', 'degraded', 'badge-warning'],
+    ['needs_review', 'healthy', 'badge-warning'],
+    ['needs_secret', 'degraded', 'badge-warning'],
+    ['needs_config', 'degraded', 'badge-warning'],
+    ['error', 'unhealthy', 'badge-error'],
+  ]
+
+  it.each(cases)('Configuration health badge for status %s (level %s) is %s', async (status, level, cls) => {
+    const wrapper = await mountDetail({
+      ...base,
+      health: {
+        level,
+        admin_state: 'enabled',
+        summary: status,
+        action: '',
+        status,
+        usable: status === 'ready',
+        actions: [],
+      },
+    })
+    const badge = configBadge(wrapper)
+    expect(badge.exists()).toBe(true)
+    expect(badge.classes()).toContain(cls)
+    if (cls !== 'badge-success') expect(badge.classes()).not.toContain('badge-success')
+  })
+
+  it('colours a quarantined, level=healthy server warning in badge, tile and header, and never says Blocked', async () => {
+    const wrapper = await mountDetail({
+      ...base,
+      connected: false,
+      quarantined: true,
+      health: {
+        level: 'healthy',
+        admin_state: 'quarantined',
+        summary: 'Quarantined for review',
+        action: 'approve',
+        status: 'needs_review',
+        usable: false,
+        actions: ['approve'],
+      },
+    })
+    const badge = configBadge(wrapper)
+    expect(badge.classes()).toContain('badge-warning')
+    expect(badge.classes()).not.toContain('badge-success')
+
+    const tile = wrapper.find('[data-test="server-health-level"]')
+    expect(tile.text()).toBe('Needs review')
+    expect(tile.classes()).toContain('text-warning')
+    expect(tile.text()).not.toContain('Blocked')
+
+    const header = wrapper.find('[data-test="server-status-badge"]')
+    expect(header.classes()).toContain('badge-warning')
+    // The header badge text stays the summary.
+    expect(header.text()).toContain('Quarantined for review')
+  })
+
+  it('reads "Sign-in required" in warning for a quarantined OAuth server', async () => {
+    const wrapper = await mountDetail({
+      ...base,
+      connected: false,
+      quarantined: true,
+      health: {
+        level: 'healthy',
+        admin_state: 'quarantined',
+        summary: 'Quarantined for review',
+        action: 'login',
+        status: 'sign_in_required',
+        usable: false,
+        actions: ['login'],
+      },
+    })
+    const tile = wrapper.find('[data-test="server-health-level"]')
+    expect(tile.text()).toBe('Sign-in required')
+    expect(tile.classes()).toContain('text-warning')
+  })
+
+  it('reads "Disabled" (not "Off") in neutral for a disabled server, never success', async () => {
+    const wrapper = await mountDetail({
+      ...base,
+      enabled: false,
+      connected: false,
+      health: {
+        level: 'healthy',
+        admin_state: 'disabled',
+        summary: 'Disabled',
+        action: 'enable',
+        status: 'disabled',
+        usable: false,
+        actions: ['enable'],
+      },
+    })
+    const tile = wrapper.find('[data-test="server-health-level"]')
+    expect(tile.text()).toBe('Disabled')
+    expect(tile.text()).not.toBe('Off')
+    expect(tile.classes()).toContain('text-base-content/50')
+    expect(tile.classes()).not.toContain('text-success')
+  })
+
+  it('keeps the level-based reading for an old core that sends no status', async () => {
+    const wrapper = await mountDetail({
+      ...base,
+      connected: false,
+      quarantined: true,
+      health: {
+        level: 'healthy',
+        admin_state: 'quarantined',
+        summary: 'Quarantined for review',
+        action: 'approve',
+      },
+    })
+    expect(configBadge(wrapper).classes()).toContain('badge-success')
+    expect(wrapper.find('[data-test="server-health-level"]').text()).toBe('Blocked')
+  })
+})

From 828ce98ef6383503c65b61da96d9aafc42d8cc79 Mon Sep 17 00:00:00 2001
From: Algis Dumbris <a.dumbris@gmail.com>
Date: Fri, 2 Oct 2026 16:06:49 +0300
Subject: [PATCH 4/6] fix(macos): mark the Home hub token savings badge as an
 estimate (Spec fix-ux-residuals)

---
 .../MCPProxy/MCPProxy/Views/HomeView.swift    | 44 ++++++++++-
 .../HomeTokenSavingsBadgeTests.swift          | 75 +++++++++++++++++++
 2 files changed, 116 insertions(+), 3 deletions(-)
 create mode 100644 native/macos/MCPProxy/MCPProxyTests/HomeTokenSavingsBadgeTests.swift

diff --git a/native/macos/MCPProxy/MCPProxy/Views/HomeView.swift b/native/macos/MCPProxy/MCPProxy/Views/HomeView.swift
index d711d0c4d..7d0eef2e4 100644
--- a/native/macos/MCPProxy/MCPProxy/Views/HomeView.swift
+++ b/native/macos/MCPProxy/MCPProxy/Views/HomeView.swift
@@ -23,6 +23,31 @@ enum DashboardConnectControl {
     }
 }
 
+// MARK: - Token Savings Badge
+
+/// The Home hub's token-savings badge presentation (Spec 109 FR-073/T166).
+/// The figure is a structural estimate until a real `retrieve_tools` call has
+/// completed, so the hub badge says "estimate" exactly as the Token Savings
+/// card below it and the Web Home chip do. Kept as a plain value so the
+/// formatting and the shared wording are testable without rendering the view.
+struct HomeTokenSavingsBadge {
+    let metrics: TokenMetrics
+
+    static let estimateLabel = "estimate"
+    static let estimateHelp = "No retrieve_tools call has been observed yet — this is a simulated estimate from the current tool catalog, not a measured average"
+
+    var percentText: String {
+        let percent = metrics.savedTokensPercentage
+        return "\(percent >= 99.995 ? "99.99" : String(format: "%.1f", percent))%"
+    }
+
+    var showsEstimate: Bool { metrics.estimated }
+
+    var accessibilityLabel: String {
+        "\(percentText) tokens saved" + (showsEstimate ? ", \(Self.estimateLabel)" : "")
+    }
+}
+
 // MARK: - Home View
 
 struct HomeView: View {
@@ -218,15 +243,28 @@ struct HomeView: View {
         VStack(spacing: 12) {
             // Token savings badge — top center
             if let stats = appState.tokenMetrics {
+                let badge = HomeTokenSavingsBadge(metrics: stats)
                 HStack(spacing: 4) {
                     Image(systemName: "arrow.down.right")
                         .font(.system(size: 10 * fontScale))
-                    Text("\(stats.savedTokensPercentage >= 99.995 ? "99.99" : String(format: "%.1f", stats.savedTokensPercentage))%")
+                    Text(badge.percentText)
                         .font(.scaled(.title2, scale: fontScale))
                         .fontWeight(.bold)
                     Text("tokens saved")
                         .font(.scaled(.caption, scale: fontScale))
+                    if badge.showsEstimate {
+                        Text(HomeTokenSavingsBadge.estimateLabel)
+                            .font(.scaled(.caption2, scale: fontScale))
+                            .foregroundStyle(.secondary)
+                            .padding(.horizontal, 6)
+                            .padding(.vertical, 2)
+                            .background(Color.secondary.opacity(0.15))
+                            .clipShape(Capsule())
+                            .help(HomeTokenSavingsBadge.estimateHelp)
+                    }
                 }
+                .accessibilityElement(children: .combine)
+                .accessibilityLabel(badge.accessibilityLabel)
                 .foregroundStyle(.green)
                 .padding(.horizontal, 14)
                 .padding(.vertical, 6)
@@ -538,14 +576,14 @@ struct HomeView: View {
                             // showed the same simulated figure with no such
                             // indication at all.
                             if stats.estimated {
-                                Text("estimate")
+                                Text(HomeTokenSavingsBadge.estimateLabel)
                                     .font(.scaled(.caption2, scale: fontScale))
                                     .foregroundStyle(.secondary)
                                     .padding(.horizontal, 6)
                                     .padding(.vertical, 2)
                                     .background(Color.secondary.opacity(0.15))
                                     .clipShape(Capsule())
-                                    .help("No retrieve_tools call has been observed yet — this is a simulated estimate from the current tool catalog, not a measured average")
+                                    .help(HomeTokenSavingsBadge.estimateHelp)
                             }
                         }
                         Text(formatTokenCount(stats.savedTokens))
diff --git a/native/macos/MCPProxy/MCPProxyTests/HomeTokenSavingsBadgeTests.swift b/native/macos/MCPProxy/MCPProxyTests/HomeTokenSavingsBadgeTests.swift
new file mode 100644
index 000000000..fa55bdf36
--- /dev/null
+++ b/native/macos/MCPProxy/MCPProxyTests/HomeTokenSavingsBadgeTests.swift
@@ -0,0 +1,75 @@
+import XCTest
+@testable import MCPProxy
+
+/// Spec 109 FR-073 (T166, #1394 item 1): the Home hub badge says "estimate"
+/// while the core reports `ServerTokenMetrics.estimated`, exactly as the Token
+/// Savings card and the Web Home chip do. Both Home surfaces read the one
+/// `HomeTokenSavingsBadge`, so they cannot drift apart.
+final class HomeTokenSavingsBadgeTests: XCTestCase {
+
+    private func metrics(percent: Double, estimated: Bool) -> TokenMetrics {
+        TokenMetrics(
+            totalServerToolListSize: 4540,
+            averageQueryResultSize: 340,
+            savedTokens: 4200,
+            savedTokensPercentage: percent,
+            perServerToolListSizes: nil,
+            estimated: estimated
+        )
+    }
+
+    func testPercentTextFormatting() {
+        XCTAssertEqual(HomeTokenSavingsBadge(metrics: metrics(percent: 99.996, estimated: false)).percentText, "99.99%")
+        XCTAssertEqual(HomeTokenSavingsBadge(metrics: metrics(percent: 42.04, estimated: false)).percentText, "42.0%")
+    }
+
+    func testShowsEstimateFollowsMetrics() {
+        let estimated = HomeTokenSavingsBadge(metrics: metrics(percent: 92.5, estimated: true))
+        XCTAssertTrue(estimated.showsEstimate)
+        XCTAssertEqual(HomeTokenSavingsBadge.estimateLabel, "estimate")
+
+        let measured = HomeTokenSavingsBadge(metrics: metrics(percent: 92.5, estimated: false))
+        XCTAssertFalse(measured.showsEstimate)
+    }
+
+    func testAccessibilityLabelNamesTheEstimate() {
+        let estimated = HomeTokenSavingsBadge(metrics: metrics(percent: 92.5, estimated: true))
+        XCTAssertTrue(estimated.accessibilityLabel.contains("estimate"))
+
+        let measured = HomeTokenSavingsBadge(metrics: metrics(percent: 92.5, estimated: false))
+        XCTAssertFalse(measured.accessibilityLabel.contains("estimate"))
+        XCTAssertTrue(measured.accessibilityLabel.contains("92.5%"))
+    }
+
+    /// Source-reading guard (same style as `HomeRoutingTests`): the hub badge and
+    /// the Token Savings card both go through the shared presentation, so the
+    /// help text literal exists exactly once.
+    func testHubBadgeUsesThePresentation() throws {
+        let source = try homeSource()
+        let hub = try XCTUnwrap(section(of: source, from: "private var hubSection", to: "private var"))
+        XCTAssertTrue(hub.contains("HomeTokenSavingsBadge"),
+                      "hubSection must render the shared HomeTokenSavingsBadge")
+        XCTAssertTrue(hub.contains("HomeTokenSavingsBadge.estimateHelp"),
+                      "the hub estimate capsule must use the shared help text")
+        XCTAssertTrue(source.contains("HomeTokenSavingsBadge.estimateLabel"),
+                      "the Token Savings card must reuse the shared estimate label")
+        XCTAssertEqual(source.components(separatedBy: "simulated estimate from the current tool catalog").count - 1, 1,
+                       "the estimate help text must live in one place")
+    }
+
+    private func section(of source: String, from start: String, to end: String) -> String? {
+        guard let startRange = source.range(of: start) else { return nil }
+        let rest = source[startRange.upperBound...]
+        guard let endRange = rest.range(of: end) else { return String(rest) }
+        return String(rest[..<endRange.lowerBound])
+    }
+
+    private func homeSource() throws -> String {
+        let packageRoot = URL(fileURLWithPath: #filePath)
+            .deletingLastPathComponent()   // MCPProxyTests
+            .deletingLastPathComponent()   // package root
+        let url = packageRoot.appendingPathComponent("MCPProxy/Views/HomeView.swift")
+        XCTAssertTrue(FileManager.default.fileExists(atPath: url.path), "missing source file at \(url.path)")
+        return try String(contentsOf: url, encoding: .utf8)
+    }
+}

From 0ffee2035e45a939b69c282ece089f5bb5b1ae77 Mon Sep 17 00:00:00 2001
From: Algis Dumbris <a.dumbris@gmail.com>
Date: Fri, 2 Oct 2026 16:06:55 +0300
Subject: [PATCH 5/6] docs(spec-109): record fix-ux-residuals decisions,
 contracts and acceptance refs

---
 ROADMAP.md                                      |  2 +-
 docs/web-ui/dashboard.md                        |  6 +++---
 .../acceptance-index.json                       |  8 +++++++-
 .../contracts/health-vocabulary.md              |  2 +-
 .../contracts/url-filter-contract.md            |  4 ++--
 .../parity-matrix.json                          | 13 +++++++++----
 .../109-ux-navigation-consistency/quickstart.md |  1 +
 specs/109-ux-navigation-consistency/research.md | 17 +++++++++++++++++
 specs/109-ux-navigation-consistency/spec.md     |  8 ++++----
 specs/109-ux-navigation-consistency/tasks.md    | 13 ++++++++++++-
 10 files changed, 57 insertions(+), 17 deletions(-)

diff --git a/ROADMAP.md b/ROADMAP.md
index 78ac342af..2051c7d4c 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -1036,6 +1036,6 @@ Legend: `shipped` ≥95% checked · `in-flight` 1–94% · `drafted` 0% · `—`
 | [106-security-residual-fixes](./specs/106-security-residual-fixes/) | `shipped` | 18/19 (95%) |
 | [107-server-edition-sso-hardening](./specs/107-server-edition-sso-hardening/) | `shipped` | 126/126 (100%) |
 | [108-profiles-v3](./specs/108-profiles-v3/) | `shipped` | 185/186 (99%) |
-| [109-ux-navigation-consistency](./specs/109-ux-navigation-consistency/) | `shipped` | 200/201 (100%) |
+| [109-ux-navigation-consistency](./specs/109-ux-navigation-consistency/) | `shipped` | 206/207 (100%) |
 | [110-catalog-popularity](./specs/110-catalog-popularity/) | `in-flight` | 19/23 (83%) |
 | [112-client-header-forwarding](./specs/112-client-header-forwarding/) | `shipped` | 38/40 (95%) |
diff --git a/docs/web-ui/dashboard.md b/docs/web-ui/dashboard.md
index a73b0297a..f633245b0 100644
--- a/docs/web-ui/dashboard.md
+++ b/docs/web-ui/dashboard.md
@@ -31,9 +31,9 @@ The tray application opens the Web UI with the API key automatically.
 
 Home answers one question first: **what needs me?**
 
-- **Needs attention** is the one list MCPProxy computes for every surface: sign-in prompts, servers waiting for review, missing secrets, configuration problems and clients that connected but were never seen. Items are ordered by rank, each with one button that goes to the screen that fixes it (Sign in, Review, Add secret). With nothing to do Home reads "All clear" and the usage strip moves to the top. See [Needs Attention](/features/needs-attention).
-- The **usage strip** shows calls today, blocked calls, errors and the estimated tokens kept out of every request; each number links to the matching [Activity](/web-ui/activity-log) view.
-- The **topology** shows your clients, MCPProxy and your servers.
+- **Needs attention** is the one list MCPProxy computes for every surface: sign-in prompts, servers waiting for review, missing secrets, configuration problems and clients that connected but were never seen. Items are ordered by rank, each with one button that goes to the screen that fixes it (Sign in, Review, Add secret). With nothing to do Home reads "All clear" and the usage strip moves to the top, except on a fresh instance with no servers, where a "Get started" card (Add a server, Connect a client, Run setup wizard) replaces it. See [Needs Attention](/features/needs-attention).
+- The **usage strip** shows calls, blocked calls and errors; each number links to the matching [Activity](/web-ui/activity-log) view.
+- The **topology** shows your clients, MCPProxy and your servers. The chip above the hub shows the estimated per-request token saving, marked "estimate" until a real `retrieve_tools` call has been observed.
 
 The same count appears on the **header pill** (hidden at 0) and as the **badge** on the sidebar's Home entry. `mcpproxy attention` and the macOS tray show the same list; see [Attention Command](/cli/attention-command).
 
diff --git a/specs/109-ux-navigation-consistency/acceptance-index.json b/specs/109-ux-navigation-consistency/acceptance-index.json
index 23dca7dba..7ac2002da 100644
--- a/specs/109-ux-navigation-consistency/acceptance-index.json
+++ b/specs/109-ux-navigation-consistency/acceptance-index.json
@@ -30,6 +30,7 @@
       "summary": "All clear on Home, pill and badge hidden, CLI prints All clear",
       "tests": [
         "vitest:frontend/tests/unit/home-attention.spec.ts",
+        "vitest:frontend/tests/unit/home-getting-started.spec.ts",
         "go:cmd/mcpproxy/attention_cmd_test.go#TestAttentionCmd_AllClear"
       ]
     },
@@ -150,6 +151,7 @@
         "vitest:frontend/tests/unit/health-status-labels.spec.ts",
         "vitest:frontend/tests/unit/sc003-forbidden-renderings.spec.ts",
         "vitest:frontend/tests/unit/server-detail-health-admin-state.spec.ts",
+        "vitest:frontend/tests/unit/server-detail-health-status-colour.spec.ts",
         "go:cmd/mcpproxy/upstream_list_forbidden_words_test.go#TestUpstreamListForbiddenWords",
         "xctest:native/macos/MCPProxy/MCPProxyTests/CrossSurfaceRenderedLabelParityTests.swift#testTrayFirstLineNeverReadsHealthyForUnusableStatuses"
       ]
@@ -268,6 +270,7 @@
         "vitest:frontend/tests/unit/activity-views.spec.ts",
         "vitest:frontend/tests/unit/activity-system-folding.spec.ts",
         "vitest:frontend/tests/unit/activity-empty-columns.spec.ts",
+        "vitest:frontend/tests/unit/activity-blocked-in-calls-view.spec.ts",
         "xctest:native/macos/MCPProxy/MCPProxyTests/ActivityFoldingTests.swift"
       ]
     },
@@ -275,7 +278,9 @@
       "summary": "Usage shows an indexed-tools savings estimate and integer ticks",
       "tests": [
         "vitest:frontend/tests/unit/usage-tokens-saved-estimate.spec.ts",
-        "vitest:frontend/tests/unit/usage-chart-ticks.spec.ts"
+        "vitest:frontend/tests/unit/usage-chart-ticks.spec.ts",
+        "vitest:frontend/tests/unit/home-token-savings-estimate.spec.ts",
+        "xctest:native/macos/MCPProxy/MCPProxyTests/HomeTokenSavingsBadgeTests.swift"
       ]
     },
     "US6-8": {
@@ -284,6 +289,7 @@
         "vitest:frontend/tests/unit/scope-query.spec.ts",
         "vitest:frontend/tests/unit/scope-chips.spec.ts",
         "vitest:frontend/tests/unit/scope-filters-url-writeback.spec.ts",
+        "vitest:frontend/tests/unit/activity-scope-conflict-clear.spec.ts",
         "xctest:native/macos/MCPProxy/MCPProxyTests/ScopeFilterTests.swift",
         "pw:e2e/web-ui-sweep/navigation-consistency.spec.ts"
       ]
diff --git a/specs/109-ux-navigation-consistency/contracts/health-vocabulary.md b/specs/109-ux-navigation-consistency/contracts/health-vocabulary.md
index d638f1e2e..b7601d648 100644
--- a/specs/109-ux-navigation-consistency/contracts/health-vocabulary.md
+++ b/specs/109-ux-navigation-consistency/contracts/health-vocabulary.md
@@ -59,7 +59,7 @@ The macOS Servers row, the tray server submenu's first line and the Server Detai
 
 Button labels per action: `login` Sign in · `set_secret` Add secret · `configure` Fix config · `edit_url` Edit URL · `approve` Review (opens the review screen; never approves directly, FR-005) · `restart` Restart · `view_logs` View logs · `enable` Enable.
 
-Colors (Web DaisyUI / macOS): `ready` success/green · `connecting` neutral/gray · `sign_in_required`, `needs_review`, `needs_secret`, `needs_config` warning/orange · `error` error/red · `disabled` neutral/gray. The tray badge keeps its Spec 044 rules (it reads `level` and diagnostics, not `status`).
+Colors (Web DaisyUI / macOS): `ready` success/green · `connecting` neutral/gray · `sign_in_required`, `needs_review`, `needs_secret`, `needs_config` warning/orange · `error` error/red · `disabled` neutral/gray. Colour keys on `status`, never `level`, on every element that renders a status label (Server Detail header badge, Health tile, Configuration → Health badge). `level` colours only a payload without `status`. The tray badge keeps its Spec 044 rules (it reads `level` and diagnostics, not `status`).
 
 ## CLI
 
diff --git a/specs/109-ux-navigation-consistency/contracts/url-filter-contract.md b/specs/109-ux-navigation-consistency/contracts/url-filter-contract.md
index ccb507169..570e9db7c 100644
--- a/specs/109-ux-navigation-consistency/contracts/url-filter-contract.md
+++ b/specs/109-ux-navigation-consistency/contracts/url-filter-contract.md
@@ -58,7 +58,7 @@ useScopeQuery(page: PageId): {
 
 | `view` | Request | Contract parameters that apply |
 |---|---|---|
-| `calls` | `GET /activity?type=tool_call,internal_tool_call` | all Activity parameters |
+| `calls` | `GET /activity?type=tool_call,internal_tool_call` (+ `policy_decision` when `status=blocked`: Web `effectiveTypes`, macOS `ScopeFilter`) | all Activity parameters |
 | `system` | `GET /activity?type=<every other type>` | all Activity parameters |
 | `all` | `GET /activity` (no `type`) | all Activity parameters |
 | `sessions` | `GET /sessions` (existing route and its own `limit`/`status` paging; no `/activity` request, no `type`) | `session` selects and highlights that session row; `from`/`to` stay in the URL and render as disabled "not applicable here" chips (rule 5); `server`, `tool`, `status`, `type`, `auth_type` likewise stay in the URL as disabled chips. `profile`, `client` and `token` (once available) **are** sent to `GET /sessions` (Spec 108 FR-031) |
@@ -74,7 +74,7 @@ An explicit `type` overrides the `view` mapping for `calls`/`system`/`all` and i
 5. A page that does not support a sticky parameter keeps it in the URL and shows it as a disabled chip reading "not applicable here". A parameter a page supports only client-side (Tools/Servers `status`) is applied in the page and never sent to REST; a value a page cannot apply (a Usage range other than the three `window` presets) is shown as a disabled chip that says so — no chip ever implies server-side filtering the backend does not perform (codex round 3).
 6. Unknown parameters are preserved untouched. Legacy `?session=` links on Activity keep working, and `?risk=` maps to `tier`.
 7. A parameter or link row whose `requires` feature is absent from `GET /api/v1/status` `features` is hidden (rule in the parameter section); it becomes visible without a reload when the status refresh lists it.
-8. **Contradictory parameters** (today exactly one case: a URL `server` that differs from the `tool` prefix): `toRest()` returns `null`; the page issues no request, shows the conflict empty state and marks both chips; removing either chip resolves it and triggers the normal fetch. The CLI exits 1 before any request and macOS `ScopeFilter.restQuery()` returns `nil` with the same empty state, so no surface shows rows under filters it did not apply. A future parameter pair that can contradict follows this rule; precedence (one value silently winning) is never used.
+8. **Contradictory parameters** (today exactly one case: a URL `server` that differs from the `tool` prefix): `toRest()` returns `null`; the page issues no request, shows the conflict empty state and marks both chips; removing either chip resolves it and triggers the normal fetch. Clearing either conflicting filter, or "Clear filters", issues exactly one request for what remains. The CLI exits 1 before any request and macOS `ScopeFilter.restQuery()` returns `nil` with the same empty state, so no surface shows rows under filters it did not apply. A future parameter pair that can contradict follows this rule; precedence (one value silently winning) is never used.
 
 ## Link map (owned by Spec 109)
 
diff --git a/specs/109-ux-navigation-consistency/parity-matrix.json b/specs/109-ux-navigation-consistency/parity-matrix.json
index b15377c02..dde5695ad 100644
--- a/specs/109-ux-navigation-consistency/parity-matrix.json
+++ b/specs/109-ux-navigation-consistency/parity-matrix.json
@@ -1180,19 +1180,24 @@
         "web": {
           "status": "must",
           "ids": [
-            "component:frontend/src/components/UsageSummaryStrip.vue"
+            "route:home",
+            "component:frontend/src/views/Home.vue",
+            "component:frontend/src/views/Usage.vue"
           ],
           "tests": [
-            "vitest:frontend/tests/unit/usage-tokens-saved-estimate.spec.ts"
+            "vitest:frontend/tests/unit/usage-tokens-saved-estimate.spec.ts",
+            "vitest:frontend/tests/unit/home-token-savings-estimate.spec.ts"
           ]
         },
         "macos": {
           "status": "must",
           "ids": [
-            "symbol:native/macos/MCPProxy/MCPProxy/Views/HomeView.swift#HomeView"
+            "symbol:native/macos/MCPProxy/MCPProxy/Views/HomeView.swift#HomeView",
+            "symbol:native/macos/MCPProxy/MCPProxy/Views/HomeView.swift#HomeTokenSavingsBadge"
           ],
           "tests": [
-            "xctest:native/macos/MCPProxy/MCPProxyTests/HomeRoutingTests.swift"
+            "xctest:native/macos/MCPProxy/MCPProxyTests/HomeRoutingTests.swift",
+            "xctest:native/macos/MCPProxy/MCPProxyTests/HomeTokenSavingsBadgeTests.swift"
           ]
         },
         "cli": {
diff --git a/specs/109-ux-navigation-consistency/quickstart.md b/specs/109-ux-navigation-consistency/quickstart.md
index 6e0b4ec21..79b1ff9e3 100644
--- a/specs/109-ux-navigation-consistency/quickstart.md
+++ b/specs/109-ux-navigation-consistency/quickstart.md
@@ -128,6 +128,7 @@ Every REST call below carries the admin key unless it names another credential:
 | 109-l | The "before Spec 108" half cannot run at 109-l's own merge point (its prerequisites include 108-f, which follows 108-e, so `features.scope_filters` is already listed); it is run on the build right after 109-k, before any Spec 108 PR — `/activity?client=cursor` keeps the parameter in the URL but shows no chip and sends no `client` to REST — and at every later build by T111/T116 with a status stub. At 109-l (Spec 108-f/i/j/k merged): bind Cursor, then use the Clients row links, the Viewing chip in the header slot, and hand-edit `anonymous_profile` away so Spec 108's binding guard warns | the hidden parameters and links appear without code changes once `features.scope_filters` is present; `?client=cursor` links work; the attention list shows `anonymous_denied_by_binding_guard` first and `client_holds_admin_key` for a seeded admin-key config (open `GET /clients/cursor`, or the Clients row, once before expecting `client_holds_admin_key`: the item needs an observed credential state, FR-093); the expanded Clients row shows Activity · Sessions · Tools it sees · Usage, the Tokens tab shows Activity · Usage on agent rows, and `/ui/servers?profile=<p>` lists only that profile's servers with a removable chip; all at 900 and 390 px |
 | demo-ux-fixes (109 half) | Scratch config adds `allow_private_registry_fetch`, a `slowreg` registry served by a node stub that sleeps 8 s while `$RUN/slow` exists, and no `quarantine_enabled`; prime Web Add server -> Catalog (empty query), `touch $RUN/slow`, search "github" on Web, `mp catalog search github -o json`, MCP `search_servers {search:"github"}` and macOS Catalog; Settings -> Security; Settings header; ⌘K "work", "cursor", "qa"; Catalog with an empty query on a cold and a warm popularity cache | The `slow/github-a` hit appears in the same order on every surface and is marked "From cached list" / `from_cache` / `(cached)`, the notice reads "slowreg: live search unavailable (timeout after 5s); showing matches from its cached list", the answer returns in at most 5.5 s, and a second search after `rm $RUN/slow` has no marker; the Quarantine toggle is ON and agrees with the posture chip, toggling it asks for confirmation and PATCHes `quarantine_enabled:false` only; the header names "Save changes"; the palette shows one `/profiles`, `/clients` and `/tokens` request after the first keystroke and none on open, and Enter lands on the profile editor, `/clients?client=cursor` and `/clients?tab=tokens&token=qa-ro`; cold Official starts with filesystem, memory, everything, then alternates official and docker, warm shows Popular above Official (Web, macOS and `mp catalog search`) |
 | 109-leftovers | `mp tools list --help`, `mp activity export --help`, `mp activity export -o json`, `mp --help`; edit `$TD/notes.json` (description → `changed`, add `search_notes_2` → `pending`) and open Web `/tools`; Web `/clients` → Connect N clients (scratch HOME with `.cursor/mcp.json`, `.codex/config.toml`); `initialize` with `clientInfo.name: "cursor"` while telemetry is off, restart the core; macOS Servers + tray + detail; `website/build/cli/review-commands/index.html` | `--approval` help names the three labels; export help explains `--format` vs `-o`, and `-o json` still fails with `unknown shorthand flag: 'o'`; Tools rows read "Changed, needs review" / "New, needs review" with a Review link to `/review/notes?change=…`, approved rows have none; the bulk preview lists each client with its `~/…` path, entry and backup notice, no `POST /connect/*` before Confirm, and Cancel leaves both files byte-identical; `client_last_seen.cursor` is set and survives the restart, a reconnect clears it until the next `initialize`; a connected server needing sign-in reads "Sign-in required" (never "Connected") in the row, the tray submenu's first line and the detail header; the review CLI page exists and matches `mp review list` output |
+| fix-ux-residuals | Fresh scratch core (`{"mcpServers":[]}`, empty HOME): Web Home; add the notes fixture via `POST /servers`; on the §2 instance before any MCP call read `/api/v1/stats/tokens` (`estimated`), Home chip and details, macOS Home hub; one real `retrieve_tools`; `/activity?view=all&server=filesystem&tool=notes:search_notes` then Clear filters (and, again, remove only the tool chip); one refused `call_tool_read` on quarantined `filesystem`, then `/activity`; `/servers/filesystem`, `scratch`, `notes` | no servers: Home shows "Get started" (no "All clear", no top usage strip) while `mp attention` prints `All clear`, and adding a server replaces the card; the chip reads "… per request · estimate" with the stat and title badge marked, the macOS hub capsule shows `estimate`, `mp status` prints `(estimate)`, and after the real call `estimated` is false and every marker is gone; the conflict banner issues no `/api/v1/activity` request, Clear filters issues exactly one unfiltered request and shows rows, removing the tool chip issues one with `server=filesystem`; the compact strip shows "1 blocked" with a title naming refused calls, clicking it requests `type=tool_call,internal_tool_call,policy_decision&status=blocked` and lists the refusal; with no other calls the empty Tool calls table offers "Show 1 blocked attempt"; the Events tile reads "1 call"; `filesystem` (quarantined) shows a warning header badge, "Needs review" in warning in the tile and a warning Configuration badge, `scratch` reads "Disabled" in grey, `notes` "Online" in green |
 
 For **109-h**, also inspect the API payload and network requests: `GET /clients` must carry `active_sessions` counts and no `sessions` key on any row; expanding Claude Code must issue one `GET /clients/claude-code` and show its session rows, with no detail fetch for collapsed rows. The personal-edition sidebar must already link to Clients in its current grouping. Seed an unknown `clientInfo.name` such as `zed`: the observed `other:zed` row appears separately from the always-available manual "Other client" snippet, which does not appear in the API payload. After Cursor has been seen, successfully reconnect it; before its next `initialize`, assert `connected_never_seen`, no current-generation session count, and no Cursor `client_last_seen` alias, while a failed reconnect would leave its prior state intact. A subsequent Cursor `initialize` must change it to `connected_seen`. If 108-c merged first, verify the extracted `ClientConnectList` still shows the profile picker and mode choice, masked credential, management notice, and the administrator-only connect reads; run `connect-profile-fields.spec.ts` and `connect_profile_flags_test.go` to preserve the CLI's profile/lock/switchable/keyless flags.
 
diff --git a/specs/109-ux-navigation-consistency/research.md b/specs/109-ux-navigation-consistency/research.md
index 3484e6f90..c250ec2ee 100644
--- a/specs/109-ux-navigation-consistency/research.md
+++ b/specs/109-ux-navigation-consistency/research.md
@@ -330,3 +330,20 @@ A live demo of `main` at `b3191a059` found nine gaps. These are the five Spec 10
 **A9 browse order (finding 6).** The empty-query Official section was the merged pool's first twelve official hits in source order. The official source paginates alphabetically by reverse-DNS id, so it filled with obscure `ac.inference.sh/...` entries and the curated reference servers never appeared. Official is now: the curated source's hits first (`CatalogHit.Curated`, set from the built-in reference protocol), then the remaining official hits round-robin across sources in registry-list order, each keeping its native order, capped at 12. It is still never popularity-ordered, so Spec 110's "Popular differs from Official" guarantee holds. Every surface renders Popular first when it has entries and Official after it; an empty section is not printed (the CLI used to print an empty table). Amends Spec 110 FR-005 and US1-3.
 
 **A10 palette (finding 5).** The palette gains Profiles, Clients and Agent tokens groups, each needle-only. One `Promise.allSettled` of `GET /profiles`, `GET /clients` (direct, unscoped: the `clients` store is page-scoped) and `GET /tokens` runs on the first non-empty input after opening, never on open, and is cached for that open. A failure gives an empty group. Links come from `frontend/src/utils/scopeLinks.ts` and carry no sticky params: a palette jump is a fresh navigation, and a sticky `profile` filter could hide the target row. A client opens `/clients?client=<id>` (or `?focus=<id>` without scope filters), an agent token `/clients?tab=tokens&token=<name>`, a profile its editor. Client credentials and revoked tokens are not listed. A tenant and the server edition get none of the three groups.
+
+
+## D36 - fix-ux-residuals decisions (final done-check items; 2026-10-02)
+
+The last residuals of the Spec 109 done check. Each stays inside the files Spec 109 owns (Home, Activity, Server Detail, macOS Home).
+
+**B1 blocked attempts (T168): the chip opens the blocked rows, the default view's type set does not change.** Every `policy_decision` emitter writes `status: "blocked"`, and Web `effectiveTypes` and macOS `ScopeFilter` already add `policy_decision` to the Tool calls view when `status=blocked`. Adding it to the default view would change the `view -> REST` row, the CLI `activityCallTypes`, `ScopeFilter.callTypes` and `ACTIVITY_CALL_TYPES` together; doing it on Web alone would break Web/macOS parity. So the existing path is made explicit (chip title, an empty-state button, the contract note) and the cross-surface change is a follow-up issue. Known gap: the default Tool calls view still omits refusals.
+
+**B2 health colour (T169).** Colour keys on `status` with one local map: `ready` success; `connecting` and `disabled` neutral; `sign_in_required`, `needs_review`, `needs_secret`, `needs_config` warning; `error` error. It drives the header badge, the Health tile and the Configuration badge, and the tile also takes its word from the status label ("Needs review", "Disabled") when `status` is present. A payload without `status` keeps the old `level` and Blocked/Off logic, so an older core renders as before. Only `ready` is success, so the tile never reads success for `usable=false`. The header badge text stays the summary.
+
+**B3 fresh instance (T170).** The trigger is "no server configured", not "no server and no client": without servers, "All clear" is false reassurance whatever the client state, which becomes a checklist step. Any attention item wins, because a pending item is actionable. Home holds the attention list back until the server list has loaded (and the card shows only then), so neither card nor banner flashes; a failed server fetch does not hold the list back. `mcpproxy attention` keeps `All clear`: the CLI answers "is anything wrong". macOS Home hides an empty attention section and never shows "All clear", so it has no false-reassurance bug; its getting-started card is a follow-up.
+
+**B4 conflict clear (T167).** `clearFilters()` emptied the filters while `scopeConflict` was still true, so the refetch hit the conflict guard and returned nothing; the URL round trip then reset the flag but changed no watched source. `scopeConflict` is now a source of the refetch watch (a callback runs once per flush) and the clear paths reset it. Removing only the server chip splits the remaining `server:tool` value the way the URL round trip does, so it also costs one request.
+
+**B5 estimate label (T166).** The Web tooltip constant is local to `Home.vue` (same wording as `Usage.vue` and macOS) because `Usage.vue` is out of this PR's files; hoisting it is a follow-up. macOS gets `HomeTokenSavingsBadge`, shared by the hub badge and the Token Savings card.
+
+**Follow-ups left out.** Refused attempts in the default Tool calls view on Web, macOS and CLI together; `ProfileCard.vue` "1 calls" (Spec 108-owned); hoisting the status-to-tone map into `utils/health.ts` for `ServerCard.vue`, and the estimate tooltip into a shared constant; a macOS Home getting-started card; the low items left in #1394.
diff --git a/specs/109-ux-navigation-consistency/spec.md b/specs/109-ux-navigation-consistency/spec.md
index a2a4b045d..2801b8872 100644
--- a/specs/109-ux-navigation-consistency/spec.md
+++ b/specs/109-ux-navigation-consistency/spec.md
@@ -94,7 +94,7 @@ A user opens MCPProxy (Web UI, macOS app or CLI) and sees one ordered list of wh
 1. **Given** the fixture above, **When** the user opens `/` in the Web UI, **Then** Home shows "Needs attention · 5" first, with items ordered by the rank in [contracts/rest-api.md](contracts/rest-api.md#attention) (sign-in before review for the same server), each with one fix button (Sign in, Review, Add secret, Review change, How to restart). The topology and a usage summary strip appear below the list.
 2. **Given** the same state, **Then** the header attention pill reads `⚠ 5`, the sidebar Home badge reads `5`, the macOS tray "Needs Attention (5)" group lists the same items, and `mcpproxy status` prints `Needs attention: 5 (run 'mcpproxy attention')`.
 3. **Given** the user signs in to the OAuth server, **When** the server reconnects, **Then** within 1 s every open surface drops the sign-in item (SSE `attention.changed`), and the review item stays and now reads "github: waiting for review".
-4. **Given** no items, **Then** Home reads "All clear", the pill and badge are hidden, the usage strip moves up, and `mcpproxy attention` prints `All clear` and exits 0.
+4. **Given** no items, **Then** Home reads "All clear", the pill and badge are hidden, the usage strip moves up, and `mcpproxy attention` prints `All clear` and exits 0 — unless no server is configured: then Home shows a "Get started" card (Add a server, Connect a client, Run setup wizard) in place of "All clear", and the top usage strip is hidden. `mcpproxy attention` still prints `All clear`.
 5. **Given** `mcpproxy doctor`, **Then** its first section is the same attention list and count. Its diagnostics follow under the heading "Diagnostics" and are never called "issues that need attention" (X1).
 
 ---
@@ -291,7 +291,7 @@ A first-time user connects a client and imports servers in the wizard. Import ro
 **F. Navigation and header (M7, N7, N8, H1–H4, X6)**
 
 - **FR-050**: The personal-edition sidebar MUST follow [contracts/navigation-map.md](contracts/navigation-map.md): Home; Connect (Clients, Profiles*, Servers, Tools); Protect (Review queue, Secrets); Monitor (Activity, Usage); footer (Settings, Docs, Feedback, Theme, version). Badges: Home = attention count, Clients = live clients, Servers = total, Tools = total, Review queue = review count (one per server awaiting review, Definitions). (*Profiles appears when Spec 108's route exists.)
-- **FR-051**: `/` MUST render Home: the attention list (FR-003), the topology from today's Overview panel with its actions, and a usage summary strip that moves above the topology when the list is empty. `/usage` is the full Usage page in Monitor. `/overview` redirects to `/`. 109-a ships the interim step: `/` defaults to the Overview panel.
+- **FR-051**: `/` MUST render Home: the attention list (FR-003), the topology from today's Overview panel with its actions, and a usage summary strip that moves above the topology when the list is empty. Where no server is configured, Home shows a "Get started" card (Add a server, Connect a client, Run setup wizard) in place of "All clear" and hides the top usage strip; any attention item still wins, and `mcpproxy attention` still prints `All clear`. `/usage` is the full Usage page in Monitor. `/overview` redirects to `/`. 109-a ships the interim step: `/` defaults to the Overview panel.
 - **FR-052**: The header MUST contain, in order: ⌘K search (one field, no separate button), the Viewing-chip slot (empty until Spec 108), a status pill (online/total servers, tools, read-only routing-mode chip; click → `/servers`), the attention pill (hidden at 0; click → popover with the first 5 items + "See all" → Home), and "+ Add ▾" (Server → `/add-server`, Client → connect dialog, Token → `/clients?tab=tokens&create=1`, which opens the create dialog and strips `create`; Profile → `/profiles?create=1` once a `/profiles` route exists). ModeSwitcher and the endpoint dropdown leave the header (FR-031).
 - **FR-053**: Below 1100 px the header MUST collapse search to an icon button, both pills (status and attention) to icon + count, and "+ Add ▾" to `+`; at 390 px the header is one row holding exactly these collapsed controls plus the drawer toggle ([contracts/navigation-map.md](contracts/navigation-map.md)). At 900 px and 390 px nothing may be clipped and the page may not scroll horizontally (checked by `visual-a11y-sweep`).
 - **FR-054**: The ⌘K palette MUST search pages, servers, tools, profiles, clients, agent tokens, settings fields and actions, keyboard-first (arrows, Enter, Esc), and Enter on free text opens `/tools?q=` (the default row "Search tools for …"; tool rows are debounced 150 ms with `limit=8`). Tools are queried only for a non-empty (trimmed) input — `GET /api/v1/index/search` answers an empty `q` with `400` — so the empty palette shows pages, actions and servers only (research D16). Profiles, clients and agent tokens are needle-only like settings: one `GET /profiles`, `GET /clients` and `GET /tokens` run on the first non-empty input after opening, never on open, and a failed one hides only its own group (research D35 A10; a tenant and the server edition get none of the three).
@@ -313,10 +313,10 @@ A first-time user connects a client and imports servers in the wizard. Import ro
 
 **H. Activity and usage (A1, A2, N5)**
 
-- **FR-070**: Activity MUST offer views Tool calls (`tool_call`, `internal_tool_call`) · Sessions · System events (every other type) · All, in the URL as `?view=calls|sessions|system|all`, defaulting to `calls` on Web and macOS. `/sessions` redirects to `/activity?view=sessions`, keeping the query.
+- **FR-070**: Activity MUST offer views Tool calls (`tool_call`, `internal_tool_call`) · Sessions · System events (every other type) · All, in the URL as `?view=calls|sessions|system|all`, defaulting to `calls` on Web and macOS. `/sessions` redirects to `/activity?view=sessions`, keeping the query. In Tool calls, `status=blocked` also selects `policy_decision` (refused attempts). The view's blocked count opens that filter, and an empty Tool calls table with blocked attempts in the window offers "Show N blocked attempts".
 - **FR-071**: In System events, consecutive records of the same type and server within 60 s MUST fold into one summary row ("filesystem: 14 tools approved") that expands in place. Folding is presentation only; export and CLI output are unfolded.
 - **FR-072**: Activity MUST hide columns that are empty for every visible row, show the block reason on blocked rows (from record metadata today, from Spec 108's `block_reason` once present), and not clip Duration.
-- **FR-073**: `ServerTokenMetrics` MUST add `estimated` (bool) and fill `average_query_result_size` from a catalog-based estimate (mean per-tool token size × the default `retrieve_tools` limit) until real calls exist. Web Usage/Home strip, macOS token savings and `mcpproxy status` show the estimate labelled "estimate".
+- **FR-073**: `ServerTokenMetrics` MUST add `estimated` (bool) and fill `average_query_result_size` from a catalog-based estimate (mean per-tool token size × the default `retrieve_tools` limit) until real calls exist. Web Usage tile and Home hub chip + Token Savings details, macOS Home hub badge + Token Savings card, and `mcpproxy status` show the estimate labelled "estimate".
 - **FR-074**: Count charts MUST use integer ticks. The usage "unresolved" group MUST be labelled "Calls to unknown tools" on Web. macOS has no usage charts or "unresolved" group today; the same ticks and label apply to the native macOS Usage view when it ships (a follow-up, parity row 22a).
 - **FR-075**: CLI `activity list|watch` MUST accept `--view calls|system|all` (default `all`, research D11), and `activity list|watch|summary|export` MUST accept `--from/--to` accepting RFC 3339 or relative `-24h`/`-7d`: on `list` and `export` they are aliases of `--start-time/--end-time`; on `watch`, which streams `/events`, they filter the streamed records by timestamp client-side (like its `--server`) and `watch` exits once `--to` has passed; on `summary`, whose endpoint takes only `period`, `--from` accepts exactly the `--period` presets (`-1h`, `-24h`, `-7d`, `-30d`, no `--to`) and any other range exits 1 with `summary supports --from -1h|-24h|-7d|-30d only` — never a silently widened window (the same rule as the Usage `window` mapping).
 
diff --git a/specs/109-ux-navigation-consistency/tasks.md b/specs/109-ux-navigation-consistency/tasks.md
index 6adefae5f..daa5c7714 100644
--- a/specs/109-ux-navigation-consistency/tasks.md
+++ b/specs/109-ux-navigation-consistency/tasks.md
@@ -373,6 +373,17 @@ Not new requirements: nine findings from a live demo of `main` at `b3191a059`, f
 - [x] T164 [P] #6 useful browse order (FR-060; amends Spec 110 FR-005): Official is curated-first, then round-robin across sources, never popularity-ordered (`internal/registries/catalog_browse_order_test.go`); Popular renders before Official when non-empty on the Web UI (`frontend/tests/unit/catalog-browse-order.spec.ts`), macOS (`CatalogTests.swift`) and the CLI table (`cmd/mcpproxy/catalog_cmd_test.go`)
 - [x] T165 [P] Docs and bookkeeping for T160–T164: `docs/api/rest-api.md`, `docs/cli/catalog-commands.md`, `specs/109-ux-navigation-consistency/parity-matrix.json`, `quickstart.md` recipe `demo-ux-fixes`, research D35
 
+## Phase 16: PR fix-ux-residuals — final done-check residuals (2026-10-02)
+
+Not new requirements: the last open items of the done check, fixed test-first inside Spec 109's own surfaces (Home, Activity, health vocabulary). No backend change, no new dependency, no golden change. Decisions: research D36.
+
+- [x] T166 [P] FR-073 / #1394 item 1: the Home hub chip, the Token Savings Details stat and its title badge say "estimate" while `ServerTokenMetrics.estimated` (`frontend/tests/unit/home-token-savings-estimate.spec.ts`); the macOS hub badge shows the same capsule through the shared `HomeTokenSavingsBadge`, which the Token Savings card reuses (`HomeTokenSavingsBadgeTests.swift`)
+- [x] T167 [P] #1394 item 2 / rule 8: Activity "Clear filters" on the server/tool conflict banner, and removing either conflicting chip, issue exactly one request for what remains (`scopeConflict` joins the refetch watch; `frontend/tests/unit/activity-scope-conflict-clear.spec.ts`)
+- [x] T168 FR-070: the Tool calls "N blocked" chip names refused attempts and opens `status=blocked`; an empty Tool calls table with blocked attempts offers "Show N blocked attempts"; the Events tile reads "1 call" (`frontend/tests/unit/activity-blocked-in-calls-view.spec.ts`)
+- [x] T169 [P] health-vocabulary "Colors": Server Detail's header badge, Health tile and Configuration → Health badge colour by `health.status`, and the tile takes its word from the status label when `status` is present (`frontend/tests/unit/server-detail-health-status-colour.spec.ts`)
+- [x] T170 [P] FR-051 / US1-4: a fresh instance (no server configured) shows a "Get started" card instead of "All clear" and hides the top usage strip; any attention item wins; `mcpproxy attention` is unchanged (`frontend/tests/unit/home-getting-started.spec.ts`)
+- [x] T171 Docs and bookkeeping for T166–T170: `spec.md` (US1-4, FR-051, FR-070, FR-073), `contracts/url-filter-contract.md`, `contracts/health-vocabulary.md`, `parity-matrix.json` row 22, `acceptance-index.json`, `quickstart.md` recipe `fix-ux-residuals`, research D36, `docs/web-ui/dashboard.md`
+
 ---
 
 ## Dependencies & Execution Order
@@ -421,4 +432,4 @@ Spec 108-f, 108-i, 108-j, 108-k + 109-i ──> 109-l
 
 ## Task Count
 
-201 tasks (the mechanical count of `- [ ] T…` lines under the phase headings; 195 before the demo-ux-fixes PR, 186 before 109-m; demo-ux-fixes added T160–T165); see the checklist above for phase totals and completion state (109-l added T152a, T154a, T157, T158, T159; 109-m added T144a, T145a, T145b, T147a, T148c, T149a–T149d; codex round 4 added T078c, T124a; codex round 3 added T011a, T076a, T101a, T125a, T148a, T148b; codex round 1 added T069a, T077b, T078b, and the threshold-timer test inside T053; Spec 108's duplicated scope-filter and Clients-shell tasks were merged into T111/T116/T117/T122/T131).
+207 tasks (the mechanical count of `- [ ] T…` lines under the phase headings; 201 before fix-ux-residuals, which added T166–T171; 195 before the demo-ux-fixes PR, 186 before 109-m; demo-ux-fixes added T160–T165); see the checklist above for phase totals and completion state (109-l added T152a, T154a, T157, T158, T159; 109-m added T144a, T145a, T145b, T147a, T148c, T149a–T149d; codex round 4 added T078c, T124a; codex round 3 added T011a, T076a, T101a, T125a, T148a, T148b; codex round 1 added T069a, T077b, T078b, and the threshold-timer test inside T053; Spec 108's duplicated scope-filter and Clients-shell tasks were merged into T111/T116/T117/T122/T131).

From 4ec9ce7d05e1719834e76bb074191aa4c51335ae Mon Sep 17 00:00:00 2001
From: Algis Dumbris <a.dumbris@gmail.com>
Date: Fri, 2 Oct 2026 16:19:25 +0300
Subject: [PATCH 6/6] fix: address review round 1

F1.1 (confirmed): removing a conflicting server/tool chip, or Clear filters,
with a profile/client/token scope in the URL sent two requests, the first
without the scope. The conflicting URL made toRest() return null, so the scope
dropped out of the request until the router.replace settled and the scope key
changed. profile/client/token do not depend on the server/tool pair, so
Activity now reads them with toRest({ ignoreConflict: true }); the scope key
no longer flips on conflict resolution and the single refetch carries it.
loadActivities() still issues nothing while scopeConflict is set.
---
 frontend/src/composables/useScopeQuery.ts     | 11 ++-
 frontend/src/views/Activity.vue               |  7 +-
 ...tivity-scope-conflict-clear-scoped.spec.ts | 92 +++++++++++++++++++
 3 files changed, 105 insertions(+), 5 deletions(-)
 create mode 100644 frontend/tests/unit/activity-scope-conflict-clear-scoped.spec.ts

diff --git a/frontend/src/composables/useScopeQuery.ts b/frontend/src/composables/useScopeQuery.ts
index 916817d34..d92558094 100644
--- a/frontend/src/composables/useScopeQuery.ts
+++ b/frontend/src/composables/useScopeQuery.ts
@@ -381,8 +381,11 @@ export interface UseScopeQueryResult {
   /** Rule 8: null when the active parameters are contradictory (today, an
    * explicit `server` that disagrees with `tool`'s server prefix) — the
    * caller must issue no request and render the conflict empty state instead
-   * (chips carry `conflicting: true` for the pair). */
-  toRest: () => Record<string, string> | null
+   * (chips carry `conflicting: true` for the pair). `ignoreConflict` returns
+   * the map the non-conflicting parameters produce anyway, for a caller that
+   * reads only parameters independent of the conflicting pair (a page whose own
+   * state already resolved it while the URL write-back is still in flight). */
+  toRest: (opts?: { ignoreConflict?: boolean }) => Record<string, string> | null
   linkTo: (page: PageId, patch?: Record<string, string>) => RouteLocationRaw
   chips: ComputedRef<ScopeChip[]>
 }
@@ -436,7 +439,7 @@ export function useScopeQuery(page: PageId): UseScopeQueryResult {
     set(patch)
   }
 
-  function toRest(): Record<string, string> | null {
+  function toRest(opts?: { ignoreConflict?: boolean }): Record<string, string> | null {
     const out: Record<string, string> = {}
     const snapshot: Record<string, string | undefined> = {}
     for (const def of defsForPage(page)) snapshot[def.name] = state[def.name]
@@ -470,7 +473,7 @@ export function useScopeQuery(page: PageId): UseScopeQueryResult {
     // Rule 8 ("Contradictory parameters"): no REST query could express both
     // active values, so no request is issued at all — never a partial one
     // built from whichever fields didn't conflict.
-    if (conflicted) return null
+    if (conflicted && !opts?.ignoreConflict) return null
 
     // Usage `window` (url-filter-contract.md `from`/`to` row): computed from
     // BOTH values together, including when neither is present (window=all) —
diff --git a/frontend/src/views/Activity.vue b/frontend/src/views/Activity.vue
index cd75d070b..f8047f9c0 100644
--- a/frontend/src/views/Activity.vue
+++ b/frontend/src/views/Activity.vue
@@ -2417,7 +2417,12 @@ const displayRows = computed((): ActivityDisplayRow[] => {
 
 /** The three REST names the page applies right now (rule 7: none while the build
  * does not advertise them; a server/tool conflict is null, so none either). */
-const activityScopeParams = computed(() => pickScopeParams(scopeQuery.toRest()))
+// profile/client/token do not depend on the server/tool pair, so read them past
+// a conflict: while the URL still carries one (a chip just removed, the
+// router.replace not settled) the scope must not drop out and back in, which
+// would send a second request (review F1.1). loadActivities() itself still
+// issues nothing while `scopeConflict` is set.
+const activityScopeParams = computed(() => pickScopeParams(scopeQuery.toRest({ ignoreConflict: true })))
 const scopeApplied = computed(() => Object.keys(activityScopeParams.value).length > 0)
 const scopeKey = computed(() => scopeParamsKey(activityScopeParams.value))
 
diff --git a/frontend/tests/unit/activity-scope-conflict-clear-scoped.spec.ts b/frontend/tests/unit/activity-scope-conflict-clear-scoped.spec.ts
new file mode 100644
index 000000000..54d5bf442
--- /dev/null
+++ b/frontend/tests/unit/activity-scope-conflict-clear-scoped.spec.ts
@@ -0,0 +1,92 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { flushPromises, mount } from '@vue/test-utils'
+import { createPinia, setActivePinia } from 'pinia'
+import { createMemoryHistory, createRouter } from 'vue-router'
+import { setAvailableFeatures } from '@/composables/useScopeQuery'
+
+// Spec 109 url-filter-contract rule 8 / T167 with a profile/client/token scope in
+// the URL (review F1.1): resolving a server/tool conflict - by removing either
+// conflicting chip or "Clear filters" - issues exactly ONE request, and that
+// request already carries the scope. The scope param is independent of the
+// conflict, so the conflicting URL must not hide it for the first request.
+
+const getActivitiesMock = vi.hoisted(() => vi.fn())
+const getStatusMock = vi.hoisted(() => vi.fn())
+
+vi.mock('@/services/api', () => ({
+  default: {
+    getActivities: getActivitiesMock,
+    getActivitySummary: vi.fn(() =>
+      Promise.resolve({ success: true, data: { period: '24h', total_count: 0, success_count: 0, error_count: 0, blocked_count: 0, rejected_count: 0 } })
+    ),
+    getSessions: vi.fn(() => Promise.resolve({ success: true, data: { sessions: [] } })),
+    getActivityExportUrl: vi.fn(() => 'http://localhost/api/v1/activity/export?format=json'),
+    getStatus: getStatusMock,
+    listAgentTokens: vi.fn(() => Promise.resolve({ success: true, data: { tokens: [] } })),
+    getProfiles: vi.fn(() => Promise.resolve({ profiles: [] })),
+    getClients: vi.fn(() => Promise.resolve({ success: true, data: { clients: [] } })),
+  },
+}))
+
+const CONFLICT = '/activity?view=all&server=fixture&tool=other:x&profile=work'
+
+async function mountActivityAt(path: string) {
+  const Activity = (await import('@/views/Activity.vue')).default
+  const router = createRouter({
+    history: createMemoryHistory(),
+    routes: [
+      { path: '/activity', component: Activity },
+      { path: '/servers/:serverName', component: { template: '<div/>' } },
+    ],
+  })
+  await router.push(path)
+  await router.isReady()
+  const wrapper = mount(Activity, { global: { plugins: [createPinia(), router] } })
+  await flushPromises()
+  await flushPromises()
+  return { wrapper, router }
+}
+
+describe('Activity - clearing a conflict with a scope filter requests once (F1.1)', () => {
+  beforeEach(() => {
+    setActivePinia(createPinia())
+    vi.clearAllMocks()
+    setAvailableFeatures(['profile', 'client', 'token'])
+    getActivitiesMock.mockImplementation(() =>
+      Promise.resolve({ success: true, data: { activities: [], total: 0, limit: 200, offset: 0 } })
+    )
+    getStatusMock.mockResolvedValue({ success: true, data: { features: { scope_filters: ['profile', 'client', 'token'] } } })
+  })
+  afterEach(() => setAvailableFeatures([]))
+
+  it('removing the tool chip: one request, server + profile', async () => {
+    const { wrapper } = await mountActivityAt(CONFLICT)
+    expect(getActivitiesMock).not.toHaveBeenCalled()
+    await wrapper.find('[data-test="activity-filter-chip-tool"]').trigger('click')
+    await flushPromises()
+    await flushPromises()
+    expect(getActivitiesMock).toHaveBeenCalledTimes(1)
+    expect(getActivitiesMock.mock.calls[0][0]).toEqual(expect.objectContaining({ server: 'fixture', profile: 'work' }))
+  })
+
+  it('removing the server chip: one request, server:tool split + profile', async () => {
+    const { wrapper } = await mountActivityAt(CONFLICT)
+    await wrapper.find('[data-test="activity-filter-chip-server"]').trigger('click')
+    await flushPromises()
+    await flushPromises()
+    expect(getActivitiesMock).toHaveBeenCalledTimes(1)
+    expect(getActivitiesMock.mock.calls[0][0]).toEqual(expect.objectContaining({ server: 'other', tool: 'x', profile: 'work' }))
+  })
+
+  it('"Clear filters": one request that keeps the scope', async () => {
+    const { wrapper } = await mountActivityAt(CONFLICT)
+    await wrapper.find('[data-test="activity-scope-conflict-clear"]').trigger('click')
+    await flushPromises()
+    await flushPromises()
+    expect(getActivitiesMock).toHaveBeenCalledTimes(1)
+    const params = getActivitiesMock.mock.calls[0][0] as Record<string, unknown>
+    expect(params.profile).toBe('work')
+    expect(params.server).toBeUndefined()
+    expect(params.tool).toBeUndefined()
+  })
+})