From c267456068203e9f5fcc1781f91fdcd8d47c51f1 Mon Sep 17 00:00:00 2001
From: Noley Holland <hollandnoley@gmail.com>
Date: Fri, 7 Aug 2026 11:11:30 -0700
Subject: [PATCH] Create instances df store, connect instances list, add specs

---
 frontend/src/pages/team/Instances.vue         | 135 +++++-----
 frontend/src/stores/account-auth.js           |   2 +
 frontend/src/stores/account.js                |   2 +
 .../src/stores/data-farm-hosted-instances.ts  | 157 ++++++++++++
 .../stores/data-farm-hosted-instances.spec.js | 234 ++++++++++++++++++
 5 files changed, 465 insertions(+), 65 deletions(-)
 create mode 100644 frontend/src/stores/data-farm-hosted-instances.ts
 create mode 100644 test/unit/frontend/stores/data-farm-hosted-instances.spec.js

diff --git a/frontend/src/pages/team/Instances.vue b/frontend/src/pages/team/Instances.vue
index 37f45b0fe0..c6e2956e5f 100644
--- a/frontend/src/pages/team/Instances.vue
+++ b/frontend/src/pages/team/Instances.vue
@@ -176,7 +176,7 @@
             </template>
         </div>
         <template v-if="!statusChannelLive">
-            <InstanceStatusPolling v-for="instance in instances" :key="instance.id" :instance="instance" @instance-updated="instanceUpdated" />
+            <InstanceStatusPolling v-for="instance in currentPageInstanceRefs" :key="instance.id" :instance="instance" @instance-updated="instanceUpdated" />
         </template>
         <ConfirmInstanceDeleteDialog ref="confirmInstanceDeleteDialog" @confirm="onInstanceDeleted" />
     </ff-page>
@@ -184,20 +184,17 @@
 
 <script>
 import { PlusSmallIcon } from '@heroicons/vue/24/outline'
-import { mapState } from 'pinia'
+import { mapActions, mapState } from 'pinia'
 import { markRaw } from 'vue'
 
-import teamApi from '../../api/team.js'
 import EmptyState from '../../components/EmptyState.vue'
 import InstanceStatusPolling from '../../components/InstanceStatusPolling.vue'
 import FeatureUnavailableToTeam from '../../components/banners/FeatureUnavailableToTeam.vue'
 import { useInstanceStates } from '../../composables/InstanceStates.js'
 import { useNavigationHelper } from '../../composables/NavigationHelper.js'
 import usePermissions from '../../composables/Permissions.js'
-import instanceActionsMixin from '../../mixins/InstanceActions.js'
 import Alerts from '../../services/alerts.js'
-import { InstanceStateMutator } from '../../utils/InstanceStateMutator.js'
-import { applyLiveState } from '../../utils/applyLiveState.js'
+import Dialog from '../../services/dialog.js'
 import { debounce } from '../../utils/eventHandling.js'
 import ApplicationLink from '../application/components/cells/ApplicationLink.vue'
 import DeploymentName from '../application/components/cells/DeploymentName.vue'
@@ -209,6 +206,7 @@ import InstanceStatusBadge from '../instance/components/InstanceStatusBadge.vue'
 
 import { useAccountSettingsStore } from '@/stores/account-settings.js'
 import { useContextStore } from '@/stores/context.js'
+import { useDataFarmHostedInstancesStore } from '@/stores/data-farm-hosted-instances'
 import { useLiveStatusStore } from '@/stores/live-status'
 import PopoverItem from '@/ui-components/components/PopoverItem.vue'
 
@@ -224,22 +222,19 @@ export default {
         FeatureUnavailableToTeam,
         PopoverItem
     },
-    mixins: [instanceActionsMixin],
     setup () {
-        const { isRunningState, statesMap } = useInstanceStates()
+        const { statesMap } = useInstanceStates()
         const { navigateTo } = useNavigationHelper()
         const { hasPermission } = usePermissions()
 
-        return { hasPermission, isRunningState, navigateTo, statesMap }
+        return { hasPermission, navigateTo, statesMap }
     },
     data () {
         return {
             loading: true,
             abortController: null,
-            instancesMap: new Map(),
             page: 1,
             pageSize: 25,
-            totalRows: 0,
             searchTerm: null,
             selectedStatusGroups: [],
             statusFilters: [
@@ -299,8 +294,13 @@ export default {
         ...mapState(useContextStore, ['team']),
         ...mapState(useAccountSettingsStore, ['featuresCheck']),
         ...mapState(useLiveStatusStore, { liveInstanceMetadata: 'instanceMetadata', statusChannelLive: 'live' }),
+        ...mapState(useDataFarmHostedInstancesStore, { currentPageInstances: 'currentPageInstances', currentPageInstanceRefs: 'currentPageInstanceRefs', totalRows: 'total' }),
         instances () {
-            return Array.from(this.instancesMap.values())
+            return this.currentPageInstances.map(instance => {
+                const canDelete = this.hasPermission('project:delete', { application: instance.application })
+                const canChangeStatus = this.hasPermission('project:change-status', { application: instance.application })
+                return { ...instance, canDelete, canChangeStatus, hideContextMenu: !(canDelete || canChangeStatus) }
+            })
         },
         instancesAvailable () {
             return this.featuresCheck?.isHostedInstancesEnabledForTeam
@@ -339,6 +339,16 @@ export default {
         this.abortController?.abort()
     },
     methods: {
+        ...mapActions(useDataFarmHostedInstancesStore, [
+            'fetchTeamInstancesPage',
+            'applyLiveStatus',
+            'applyPolledStatus',
+            'startInstance',
+            'restartInstance',
+            'suspendInstance',
+            'removeInstance',
+            'reset'
+        ]),
         fullReload () {
             this.page = 1
             this.fetchData()
@@ -356,36 +366,20 @@ export default {
             this.abortController = controller
             this.loading = true
             try {
-                let response
                 if (this.hasPermission('team:projects:list')) {
-                    response = await teamApi.getInstances(this.team.id, {
-                        pagination: {
-                            page: this.page,
-                            limit: this.pageSize,
-                            query: this.searchTerm || null,
-                            sort: this.sort.key || null,
-                            dir: this.sort.order || null
-                        },
-                        includeMeta: true,
+                    await this.fetchTeamInstancesPage(this.team.id, {
+                        page: this.page,
+                        limit: this.pageSize,
+                        query: this.searchTerm || null,
+                        sort: this.sort.key || null,
+                        dir: this.sort.order || null,
                         states: this.statusFilter,
                         signal: controller.signal
                     })
+                    this.applyLiveStatus()
+                } else {
+                    this.reset()
                 }
-                const projects = response?.projects || []
-                this.totalRows = response?.meta?.total ?? response?.count ?? projects.length
-                const nextMap = new Map()
-                projects.forEach(instance => {
-                    instance.running = this.isRunningState(instance.meta?.state || instance.status)
-                    instance.notSuspended = (instance.meta?.state || instance.status) !== 'suspended'
-                    instance.pendingStateChange = false
-                    instance.optimisticStateChange = false
-                    instance.canDelete = this.hasPermission('project:delete', { application: instance.application })
-                    instance.canChangeStatus = this.hasPermission('project:change-status', { application: instance.application })
-                    instance.hideContextMenu = !(instance.canDelete || instance.canChangeStatus)
-                    nextMap.set(instance.id, instance)
-                })
-                this.instancesMap = nextMap
-                this.applyLiveStatus()
             } catch (error) {
                 if (error.name !== 'AbortError' && error.name !== 'CanceledError') {
                     Alerts.emit('Failed to load instances.', 'warning')
@@ -397,21 +391,6 @@ export default {
                 }
             }
         },
-        applyLiveStatus () {
-            const metadata = this.liveInstanceMetadata
-            for (const id of this.instancesMap.keys()) {
-                const meta = metadata[id]
-                if (!meta?.status) continue
-                const state = meta.status
-                const row = this.instancesMap.get(id)
-                if (row.status === state && row.meta?.state === state) continue
-                this.instancesMap.set(id, {
-                    ...applyLiveState(row, state, { versions: meta.versions, clearFlags: true }),
-                    running: this.isRunningState(state),
-                    notSuspended: state !== 'suspended'
-                })
-            }
-        },
         toggleStatusGroup (key) {
             const index = this.selectedStatusGroups.indexOf(key)
             if (index === -1) {
@@ -456,22 +435,48 @@ export default {
                 }
             }, event)
         },
-        instanceUpdated: function (newData) {
-            const mutator = new InstanceStateMutator(newData)
-            mutator.clearState()
-            newData.running = this.isRunningState(newData.meta.state)
-            newData.notSuspended = newData.meta.state !== 'suspended'
-            this.instancesMap.set(newData.id, {
-                ...this.instancesMap.get(newData.id),
-                ...newData
+        async instanceStart (instance) {
+            try {
+                await this.startInstance(instance.id)
+            } catch (err) {
+                console.warn('Instance start failed.', err)
+                Alerts.emit('Instance start failed.', 'warning')
+            }
+        },
+        async instanceRestart (instance) {
+            try {
+                await this.restartInstance(instance.id)
+            } catch (err) {
+                console.warn('Instance restart failed.', err)
+                Alerts.emit('Instance restart failed.', 'warning')
+            }
+        },
+        instanceShowConfirmSuspend (instance) {
+            Dialog.show({
+                header: 'Suspend Instance',
+                text: `Are you sure you want to suspend ${instance.name}`,
+                confirmLabel: 'Suspend',
+                kind: 'danger'
+            }, async () => {
+                try {
+                    await this.suspendInstance(instance.id)
+                    Alerts.emit('Instance suspend request succeeded.', 'confirmation')
+                } catch (err) {
+                    console.warn(err)
+                    Alerts.emit('Instance failed to suspend.', 'warning')
+                }
             })
         },
+        instanceShowConfirmDelete (instance) {
+            this.$refs.confirmInstanceDeleteDialog.show(instance)
+        },
+        instanceUpdated (newData) {
+            this.applyPolledStatus(newData)
+        },
         onInstanceDeleted (instance) {
-            if (this.instancesMap.has(instance.id)) {
-                this.instancesMap.delete(instance.id)
-                // Refetch to refresh totals and pull in any backfill row from the next page.
-                this.fetchData()
-            }
+            this.removeInstance(instance.id)
+            // Refetch to refresh totals and pull in any backfill row from the next page.
+            this.fetchData()
         }
     }
 }
diff --git a/frontend/src/stores/account-auth.js b/frontend/src/stores/account-auth.js
index 0c3a06505f..9da8251a9d 100644
--- a/frontend/src/stores/account-auth.js
+++ b/frontend/src/stores/account-auth.js
@@ -12,6 +12,7 @@ import { useAccountStore } from '@/stores/account.js'
 import { useContextStore } from '@/stores/context.js'
 import { useCookieConsentStore } from '@/stores/cookie-consent'
 import { useDataFarmApplicationsStore } from '@/stores/data-farm-applications'
+import { useDataFarmHostedInstancesStore } from '@/stores/data-farm-hosted-instances'
 import { useDataFarmTeamsStore } from '@/stores/data-farm-teams'
 import { useProductAssistantStore } from '@/stores/product-assistant.js'
 import { useProductBrokersStore } from '@/stores/product-brokers.js'
@@ -236,6 +237,7 @@ export const useAccountAuthStore = defineStore('account-auth', {
             useContextStore().$reset()
             useCookieConsentStore().reset()
             useDataFarmApplicationsStore().reset()
+            useDataFarmHostedInstancesStore().reset()
             useDataFarmTeamsStore().reset()
             useProductTablesStore().$reset()
             useProductBrokersStore().$reset()
diff --git a/frontend/src/stores/account.js b/frontend/src/stores/account.js
index 2735426a00..32df29e715 100644
--- a/frontend/src/stores/account.js
+++ b/frontend/src/stores/account.js
@@ -7,6 +7,7 @@ import getAppOrchestrator from '@/services/app.orchestrator'
 import product from '@/services/product.js'
 import { useContextStore } from '@/stores/context.js'
 import { useDataFarmApplicationsStore } from '@/stores/data-farm-applications'
+import { useDataFarmHostedInstancesStore } from '@/stores/data-farm-hosted-instances'
 import { useProductTablesStore } from '@/stores/product-tables.js'
 
 function ensureTeamChannelConnected (team) {
@@ -120,6 +121,7 @@ export const useAccountStore = defineStore('account', {
         clearOtherStores () {
             useProductTablesStore().clearState()
             useDataFarmApplicationsStore().reset()
+            useDataFarmHostedInstancesStore().reset()
         }
     }
 })
diff --git a/frontend/src/stores/data-farm-hosted-instances.ts b/frontend/src/stores/data-farm-hosted-instances.ts
new file mode 100644
index 0000000000..376d7fc87c
--- /dev/null
+++ b/frontend/src/stores/data-farm-hosted-instances.ts
@@ -0,0 +1,157 @@
+import { defineStore } from 'pinia'
+import { computed, ref } from 'vue'
+
+import instanceApi from '@/api/instances.js'
+import teamApi from '@/api/team.js'
+import { useInstanceStates } from '@/composables/InstanceStates.js'
+import { useLiveStatusStore } from '@/stores/live-status'
+import type { InstanceStatus, InstanceSummary, PaginationParams } from '@/types'
+import { InstanceStateMutator } from '@/utils/InstanceStateMutator'
+import { applyLiveState } from '@/utils/applyLiveState.js'
+
+type StoreInstance = InstanceSummary & Pick<InstanceStatus, 'meta' | 'flowLastUpdatedAt'> & {
+    status?: string
+    optimisticStateChange?: boolean
+    pendingStateChange?: boolean
+    running?: boolean
+    notSuspended?: boolean
+    flowLastUpdatedSince?: string
+}
+
+type MutatorInstance = ConstructorParameters<typeof InstanceStateMutator>[0]
+
+type PageQuery = PaginationParams & {
+    states?: string[] | null
+    signal?: AbortSignal | null
+}
+
+export const useDataFarmHostedInstancesStore = defineStore('data-farm-hosted-instances', () => {
+    const instancesById = ref<Record<string, StoreInstance>>({})
+    const currentPageIds = ref<string[]>([])
+    const total = ref(0)
+
+    const { isRunningState } = useInstanceStates()
+
+    const currentPageInstanceRefs = computed(() =>
+        currentPageIds.value.map(id => instancesById.value[id]).filter(Boolean)
+    )
+
+    const currentPageInstances = computed(() =>
+        currentPageInstanceRefs.value.map(instance => {
+            const state = instance.meta?.state || instance.status
+            return { ...instance, running: isRunningState(state), notSuspended: state !== 'suspended' }
+        })
+    )
+
+    function removeInstance (id: string): void {
+        delete instancesById.value[id]
+        currentPageIds.value = currentPageIds.value.filter(instanceId => instanceId !== id)
+    }
+
+    async function fetchTeamInstancesPage (teamId: string, query: PageQuery = {}): Promise<void> {
+        if (!teamId) return
+        const response = await teamApi.getInstances(teamId, {
+            pagination: {
+                page: query.page ?? 1,
+                limit: query.limit ?? 25,
+                query: query.query ?? null,
+                sort: query.sort ?? null,
+                dir: query.dir ?? null
+            },
+            includeMeta: true,
+            states: query.states ?? null,
+            signal: query.signal ?? null
+        })
+        const projects: StoreInstance[] = response?.projects || []
+        const byId: Record<string, StoreInstance> = {}
+        const ids: string[] = []
+        projects.forEach(instance => {
+            instance.pendingStateChange = false
+            instance.optimisticStateChange = false
+            byId[instance.id] = instance
+            ids.push(instance.id)
+        })
+        instancesById.value = byId
+        currentPageIds.value = ids
+        total.value = response?.meta?.total ?? response?.count ?? projects.length
+    }
+
+    function applyLiveStatus (): void {
+        const metadata = useLiveStatusStore().instanceMetadata
+        for (const id of currentPageIds.value) {
+            const meta = metadata[id]
+            if (!meta?.status) continue
+            const state = meta.status
+            const row = instancesById.value[id]
+            if (!row) continue
+            if (row.status === state && row.meta?.state === state) continue
+            instancesById.value[id] = {
+                ...applyLiveState(row, state, { versions: meta.versions, clearFlags: true }),
+                running: isRunningState(state),
+                notSuspended: state !== 'suspended'
+            }
+        }
+    }
+
+    function applyPolledStatus (newData: StoreInstance): void {
+        if (!newData?.id) return
+        const existing = instancesById.value[newData.id]
+        if (!existing) return
+        const state = newData.meta?.state as string | undefined
+        instancesById.value[newData.id] = {
+            ...existing,
+            ...newData,
+            ...(state ? { status: state } : {}),
+            optimisticStateChange: false,
+            pendingStateChange: false
+        }
+    }
+
+    async function transition (id: string, optimisticState: string, apiCall: (instance: StoreInstance) => Promise<unknown>): Promise<void> {
+        const instance = instancesById.value[id]
+        if (!instance) return
+        const mutator = new InstanceStateMutator(instance as unknown as MutatorInstance)
+        mutator.setStateOptimistically(optimisticState)
+        try {
+            await apiCall(instance)
+            mutator.setStateAsPendingFromServer()
+        } catch (err) {
+            mutator.restoreState()
+            throw err
+        }
+    }
+
+    function startInstance (id: string): Promise<void> {
+        return transition(id, 'starting', instance => instanceApi.startInstance(instance))
+    }
+
+    function restartInstance (id: string): Promise<void> {
+        return transition(id, 'restarting', instance => instanceApi.restartInstance(instance))
+    }
+
+    function suspendInstance (id: string): Promise<void> {
+        return transition(id, 'suspending', instance => instanceApi.suspendInstance(instance))
+    }
+
+    function reset (): void {
+        instancesById.value = {}
+        currentPageIds.value = []
+        total.value = 0
+    }
+
+    return {
+        instancesById,
+        currentPageIds,
+        total,
+        currentPageInstanceRefs,
+        currentPageInstances,
+        fetchTeamInstancesPage,
+        removeInstance,
+        applyLiveStatus,
+        applyPolledStatus,
+        startInstance,
+        restartInstance,
+        suspendInstance,
+        reset
+    }
+})
diff --git a/test/unit/frontend/stores/data-farm-hosted-instances.spec.js b/test/unit/frontend/stores/data-farm-hosted-instances.spec.js
new file mode 100644
index 0000000000..4ad6eb72bb
--- /dev/null
+++ b/test/unit/frontend/stores/data-farm-hosted-instances.spec.js
@@ -0,0 +1,234 @@
+import { createPinia, setActivePinia } from 'pinia'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import instanceApi from '@/api/instances.js'
+import teamApi from '@/api/team.js'
+import { useDataFarmHostedInstancesStore } from '@/stores/data-farm-hosted-instances'
+import { useLiveStatusStore } from '@/stores/live-status'
+
+vi.mock('@/composables/InstanceStates.js', () => ({
+    useInstanceStates: () => ({
+        isRunningState: state => state === 'running',
+        isTransitionState: state => ['starting', 'restarting', 'suspending', 'stopping'].includes(state),
+        statesMap: {}
+    })
+}))
+
+const instance = (id, state = 'stopped', extra = {}) => ({ id, name: id, meta: { state }, status: state, ...extra })
+
+describe('data-farm-hosted-instances store', () => {
+    beforeEach(() => {
+        setActivePinia(createPinia())
+    })
+
+    afterEach(() => {
+        vi.restoreAllMocks()
+    })
+
+    it('starts empty', () => {
+        const store = useDataFarmHostedInstancesStore()
+        expect(store.currentPageInstances).toEqual([])
+        expect(store.total).toBe(0)
+    })
+
+    describe('fetchTeamInstancesPage', () => {
+        it('loads a page into byId + currentPageIds and resets transition flags', async () => {
+            vi.spyOn(teamApi, 'getInstances').mockResolvedValue({
+                projects: [instance('i1'), instance('i2', 'running')],
+                meta: { total: 7 }
+            })
+            const store = useDataFarmHostedInstancesStore()
+
+            await store.fetchTeamInstancesPage('team-1', { page: 1 })
+
+            expect(store.currentPageIds).toEqual(['i1', 'i2'])
+            expect(store.total).toBe(7)
+            expect(store.instancesById.i1.optimisticStateChange).toBe(false)
+            expect(store.instancesById.i1.pendingStateChange).toBe(false)
+        })
+
+        it('falls back to count then length for total', async () => {
+            vi.spyOn(teamApi, 'getInstances').mockResolvedValueOnce({ projects: [instance('i1')], count: 3 })
+            const store = useDataFarmHostedInstancesStore()
+            await store.fetchTeamInstancesPage('team-1')
+            expect(store.total).toBe(3)
+
+            teamApi.getInstances.mockResolvedValueOnce({ projects: [instance('i1'), instance('i2')] })
+            await store.fetchTeamInstancesPage('team-1')
+            expect(store.total).toBe(2)
+        })
+
+        it('does nothing without a teamId', async () => {
+            const spy = vi.spyOn(teamApi, 'getInstances')
+            const store = useDataFarmHostedInstancesStore()
+            await store.fetchTeamInstancesPage('')
+            expect(spy).not.toHaveBeenCalled()
+        })
+    })
+
+    describe('currentPageInstances', () => {
+        it('maps ids in order and derives running/notSuspended', async () => {
+            vi.spyOn(teamApi, 'getInstances').mockResolvedValue({
+                projects: [instance('i1', 'running'), instance('i2', 'suspended')],
+                meta: { total: 2 }
+            })
+            const store = useDataFarmHostedInstancesStore()
+            await store.fetchTeamInstancesPage('team-1')
+
+            const rows = store.currentPageInstances
+            expect(rows.map(r => r.id)).toEqual(['i1', 'i2'])
+            expect(rows[0].running).toBe(true)
+            expect(rows[0].notSuspended).toBe(true)
+            expect(rows[1].running).toBe(false)
+            expect(rows[1].notSuspended).toBe(false)
+        })
+    })
+
+    describe('currentPageInstanceRefs', () => {
+        it('returns raw entities and keeps stable identity for rows that did not change', async () => {
+            vi.spyOn(teamApi, 'getInstances').mockResolvedValue({ projects: [instance('i1'), instance('i2')], meta: { total: 2 } })
+            const store = useDataFarmHostedInstancesStore()
+            await store.fetchTeamInstancesPage('team-1')
+
+            const i1Before = store.currentPageInstanceRefs.find(i => i.id === 'i1')
+            const i2Before = store.currentPageInstanceRefs.find(i => i.id === 'i2')
+            expect(i1Before).not.toHaveProperty('running') // raw, not the decorated shape
+
+            store.applyPolledStatus({ id: 'i1', meta: { state: 'running' } })
+
+            expect(store.currentPageInstanceRefs.find(i => i.id === 'i2')).toBe(i2Before) // unchanged row keeps identity
+            expect(store.currentPageInstanceRefs.find(i => i.id === 'i1')).not.toBe(i1Before) // changed row is replaced
+        })
+    })
+
+    describe('removeInstance', () => {
+        it('removeInstance drops from byId and currentPageIds', async () => {
+            vi.spyOn(teamApi, 'getInstances').mockResolvedValue({ projects: [instance('i1'), instance('i2')], meta: { total: 2 } })
+            const store = useDataFarmHostedInstancesStore()
+            await store.fetchTeamInstancesPage('team-1')
+
+            store.removeInstance('i1')
+
+            expect(store.instancesById.i1).toBeUndefined()
+            expect(store.currentPageIds).toEqual(['i2'])
+        })
+    })
+
+    describe('applyLiveStatus', () => {
+        it('applies live state to current-page instances and clears flags', async () => {
+            vi.spyOn(teamApi, 'getInstances').mockResolvedValue({ projects: [instance('i1', 'stopped', { optimisticStateChange: true })], meta: { total: 1 } })
+            const store = useDataFarmHostedInstancesStore()
+            await store.fetchTeamInstancesPage('team-1')
+            useLiveStatusStore().setInstanceStatus('i1', 'running')
+
+            store.applyLiveStatus()
+
+            expect(store.instancesById.i1.status).toBe('running')
+            expect(store.instancesById.i1.meta.state).toBe('running')
+            expect(store.instancesById.i1.optimisticStateChange).toBe(false)
+            expect(store.currentPageInstances[0].running).toBe(true)
+        })
+
+        it('skips instances already at the live state', async () => {
+            vi.spyOn(teamApi, 'getInstances').mockResolvedValue({ projects: [instance('i1', 'running')], meta: { total: 1 } })
+            const store = useDataFarmHostedInstancesStore()
+            await store.fetchTeamInstancesPage('team-1')
+            const before = store.instancesById.i1
+            useLiveStatusStore().setInstanceStatus('i1', 'running')
+
+            store.applyLiveStatus()
+
+            expect(store.instancesById.i1).toBe(before)
+        })
+    })
+
+    describe('applyPolledStatus', () => {
+        it('merges polled data and clears flags for a known instance', () => {
+            const store = useDataFarmHostedInstancesStore()
+            store.instancesById.i1 = instance('i1', 'stopped', { optimisticStateChange: true })
+
+            // getInstance returns meta.state but not a top-level status
+            store.applyPolledStatus({ id: 'i1', meta: { state: 'running' } })
+
+            expect(store.instancesById.i1.meta.state).toBe('running')
+            expect(store.instancesById.i1.status).toBe('running')
+            expect(store.instancesById.i1.optimisticStateChange).toBe(false)
+        })
+
+        it('ignores an unknown instance', () => {
+            const store = useDataFarmHostedInstancesStore()
+            store.applyPolledStatus({ id: 'nope', status: 'running' })
+            expect(store.instancesById.nope).toBeUndefined()
+        })
+    })
+
+    describe('lifecycle actions', () => {
+        it('startInstance sets optimistic then pending-from-server on success', async () => {
+            vi.spyOn(instanceApi, 'startInstance').mockResolvedValue({})
+            const store = useDataFarmHostedInstancesStore()
+            store.instancesById.i1 = instance('i1', 'stopped')
+
+            await store.startInstance('i1')
+
+            expect(instanceApi.startInstance).toHaveBeenCalled()
+            expect(store.instancesById.i1.meta.state).toBe('starting')
+            expect(store.instancesById.i1.optimisticStateChange).toBe(false)
+            expect(store.instancesById.i1.pendingStateChange).toBe(true)
+        })
+
+        it('restores state and rethrows when the action fails', async () => {
+            vi.spyOn(instanceApi, 'suspendInstance').mockRejectedValue(new Error('boom'))
+            const store = useDataFarmHostedInstancesStore()
+            store.instancesById.i1 = instance('i1', 'running')
+
+            await expect(store.suspendInstance('i1')).rejects.toThrow('boom')
+
+            expect(store.instancesById.i1.meta.state).toBe('running')
+            expect(store.instancesById.i1.optimisticStateChange).toBe(false)
+            expect(store.instancesById.i1.pendingStateChange).toBe(false)
+        })
+
+        it('does nothing for an unknown instance', async () => {
+            const spy = vi.spyOn(instanceApi, 'restartInstance')
+            const store = useDataFarmHostedInstancesStore()
+            await store.restartInstance('nope')
+            expect(spy).not.toHaveBeenCalled()
+        })
+
+        it('a live update mid-transition wins and is not reverted when the request resolves', async () => {
+            let resolveStart
+            vi.spyOn(instanceApi, 'startInstance').mockReturnValue(new Promise(resolve => { resolveStart = resolve }))
+            vi.spyOn(teamApi, 'getInstances').mockResolvedValue({ projects: [instance('i1', 'stopped')], meta: { total: 1 } })
+            const store = useDataFarmHostedInstancesStore()
+            await store.fetchTeamInstancesPage('team-1')
+
+            const pending = store.startInstance('i1')
+            expect(store.instancesById.i1.optimisticStateChange).toBe(true)
+            expect(store.instancesById.i1.meta.state).toBe('starting')
+
+            // live status lands while the start request is still in flight
+            useLiveStatusStore().setInstanceStatus('i1', 'running')
+            store.applyLiveStatus()
+
+            resolveStart({})
+            await pending
+
+            expect(store.instancesById.i1.meta.state).toBe('running')
+            expect(store.instancesById.i1.optimisticStateChange).toBe(false)
+        })
+    })
+
+    describe('reset', () => {
+        it('clears all state', async () => {
+            vi.spyOn(teamApi, 'getInstances').mockResolvedValue({ projects: [instance('i1')], meta: { total: 1 } })
+            const store = useDataFarmHostedInstancesStore()
+            await store.fetchTeamInstancesPage('team-1')
+
+            store.reset()
+
+            expect(store.instancesById).toEqual({})
+            expect(store.currentPageIds).toEqual([])
+            expect(store.total).toBe(0)
+        })
+    })
+})