fix(copilot): disambiguate VFS upload paths to prevent stale-row reads

Same-name chat attachments (e.g. multiple "image.png" screenshots) collided
on the VFS path uploads/<originalName>, causing read("uploads/image.png") to
return whichever row Postgres ordered first — leading to the agent reading
stale uploads instead of the latest one.

Adds displayName column + partial unique index on (chat_id, display_name)
WHERE context='mothership'. trackChatUpload allocates "image.png", then
"image (2).png", "image (3).png", ... with retry on 23505. The read-hint
string returned to the model uses displayName so subsequent read/materialize
calls resolve unambiguously. Resolver now matches on displayName with the
existing normalizeVfsSegment fallback for macOS U+202F screenshot names.

Author: TheodoreSpeaks

apps/sim/lib/copilot/chat/payload.ts

@@ -238,7 +238,7 @@ export async function buildCopilotRequestPayload(
       const filename = (f.filename ?? f.name ?? 'file') as string
       const mediaType = (f.media_type ?? f.mimeType ?? 'application/octet-stream') as string
       try {
-        await trackChatUpload(
+        const { displayName } = await trackChatUpload(
           params.workspaceId,
           userId,
           chatId,
@@ -248,13 +248,13 @@ export async function buildCopilotRequestPayload(
           f.size
         )
         const lines = [
-          `File "${filename}" (${mediaType}, ${f.size} bytes) uploaded.`,
-          `Read with: read("uploads/${filename}")`,
-          `To save permanently: materialize_file(fileName: "${filename}")`,
+          `File "${displayName}" (${mediaType}, ${f.size} bytes) uploaded.`,
+          `Read with: read("uploads/${displayName}")`,
+          `To save permanently: materialize_file(fileName: "${displayName}")`,
         ]
-        if (filename.endsWith('.json')) {
+        if (displayName.endsWith('.json')) {
           lines.push(
-            `To import as a workflow: materialize_file(fileName: "${filename}", operation: "import")`
+            `To import as a workflow: materialize_file(fileName: "${displayName}", operation: "import")`
           )
         }
         uploadContexts.push({

apps/sim/lib/copilot/tools/handlers/materialize-file.ts

@@ -21,7 +21,7 @@ function toFileRecord(row: typeof workspaceFiles.$inferSelect) {
   return {
     id: row.id,
     workspaceId: row.workspaceId || '',
-    name: row.originalName,
+    name: row.displayName,
     key: row.key,
     path: `${pathPrefix}${encodeURIComponent(row.key)}?context=mothership`,
     size: row.size,
@@ -45,7 +45,7 @@ async function executeSave(fileName: string, chatId: string): Promise<ToolCallRe
 
   const [updated] = await db
     .update(workspaceFiles)
-    .set({ context: 'workspace', chatId: null })
+    .set({ context: 'workspace', chatId: null, originalName: row.displayName })
     .where(and(eq(workspaceFiles.id, row.id), isNull(workspaceFiles.deletedAt)))
     .returning({ id: workspaceFiles.id, originalName: workspaceFiles.originalName })
 

apps/sim/lib/copilot/tools/handlers/upload-file-reader.test.ts

@@ -0,0 +1,157 @@
+/**
+ * @vitest-environment node
+ */
+
+import { dbChainMock, dbChainMockFns, resetDbChainMock } from '@sim/testing'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+vi.mock('@sim/db', () => dbChainMock)
+
+const { mockReadFileRecord } = vi.hoisted(() => ({
+  mockReadFileRecord: vi.fn(),
+}))
+
+vi.mock('@/lib/copilot/vfs/file-reader', () => ({
+  readFileRecord: mockReadFileRecord,
+}))
+
+import {
+  findMothershipUploadRowByChatAndName,
+  listChatUploads,
+  readChatUpload,
+} from './upload-file-reader'
+
+const CHAT_ID = '11111111-1111-1111-1111-111111111111'
+const NOW = new Date('2026-05-05T00:00:00.000Z')
+
+function makeRow(overrides: Partial<Record<string, unknown>> = {}) {
+  return {
+    id: 'wf_1',
+    key: 'mothership/abc/123-image.png',
+    userId: 'user_1',
+    workspaceId: 'ws_1',
+    context: 'mothership',
+    chatId: CHAT_ID,
+    originalName: 'image.png',
+    displayName: 'image.png',
+    contentType: 'image/png',
+    size: 1024,
+    deletedAt: null,
+    uploadedAt: NOW,
+    updatedAt: NOW,
+    ...overrides,
+  }
+}
+
+describe('findMothershipUploadRowByChatAndName', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    resetDbChainMock()
+  })
+
+  it('matches by displayName for the first occurrence', async () => {
+    const row = makeRow({ id: 'wf_1', displayName: 'image.png' })
+    dbChainMockFns.limit.mockResolvedValueOnce([row])
+
+    const result = await findMothershipUploadRowByChatAndName(CHAT_ID, 'image.png')
+
+    expect(result).toEqual(row)
+  })
+
+  it('matches by suffixed displayName for collision-disambiguated rows', async () => {
+    const row = makeRow({ id: 'wf_2', displayName: 'image (2).png' })
+    dbChainMockFns.limit.mockResolvedValueOnce([row])
+
+    const result = await findMothershipUploadRowByChatAndName(CHAT_ID, 'image (2).png')
+
+    expect(result?.id).toBe('wf_2')
+    expect(result?.displayName).toBe('image (2).png')
+  })
+
+  it('returns null when no row matches and the fallback scan is empty', async () => {
+    // First query: .where().limit(1) — empty.
+    dbChainMockFns.limit.mockResolvedValueOnce([])
+    // Second query awaits .where(...) directly. Default `where` returns the chainable
+    // (consumed by call #1); call #2 must return a thenable so `await` resolves to [].
+    dbChainMockFns.where.mockImplementationOnce(() => ({ limit: dbChainMockFns.limit }) as never)
+    dbChainMockFns.where.mockImplementationOnce(() => Promise.resolve([]) as never)
+
+    const result = await findMothershipUploadRowByChatAndName(CHAT_ID, 'missing.png')
+
+    expect(result).toBeNull()
+  })
+
+  it('falls back to normalized segment match when exact lookup misses (macOS U+202F)', async () => {
+    // Model passes ASCII space; DB row was saved with U+202F (narrow no-break space).
+    const macosName = 'Screenshot 2026-05-05 at 9.41.00 AM.png'
+    const asciiName = 'Screenshot 2026-05-05 at 9.41.00 AM.png'
+    const row = makeRow({ id: 'wf_3', displayName: macosName })
+
+    dbChainMockFns.limit.mockResolvedValueOnce([])
+    dbChainMockFns.where.mockImplementationOnce(() => ({ limit: dbChainMockFns.limit }) as never)
+    dbChainMockFns.where.mockImplementationOnce(() => Promise.resolve([row]) as never)
+
+    const result = await findMothershipUploadRowByChatAndName(CHAT_ID, asciiName)
+
+    expect(result?.id).toBe('wf_3')
+  })
+})
+
+describe('listChatUploads', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    resetDbChainMock()
+  })
+
+  it('returns rows in upload order with name set to displayName', async () => {
+    const rows = [
+      makeRow({ id: 'a', displayName: 'image.png' }),
+      makeRow({ id: 'b', displayName: 'image (2).png' }),
+      makeRow({ id: 'c', displayName: 'image (3).png' }),
+    ]
+    dbChainMockFns.orderBy.mockResolvedValueOnce(rows)
+
+    const result = await listChatUploads(CHAT_ID)
+
+    expect(result.map((r) => r.id)).toEqual(['a', 'b', 'c'])
+    expect(result.map((r) => r.name)).toEqual(['image.png', 'image (2).png', 'image (3).png'])
+    expect(result.every((r) => r.storageContext === 'mothership')).toBe(true)
+  })
+
+  it('returns [] and does not throw when the DB query fails', async () => {
+    dbChainMockFns.orderBy.mockRejectedValueOnce(new Error('boom'))
+    const result = await listChatUploads(CHAT_ID)
+    expect(result).toEqual([])
+  })
+})
+
+describe('readChatUpload', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    resetDbChainMock()
+    mockReadFileRecord.mockReset()
+  })
+
+  it('reads the row resolved by the suffixed displayName', async () => {
+    const row = makeRow({ id: 'wf_2', displayName: 'image (2).png' })
+    dbChainMockFns.limit.mockResolvedValueOnce([row])
+    mockReadFileRecord.mockResolvedValueOnce({ content: 'PNGDATA', totalLines: 1 })
+
+    const result = await readChatUpload('image (2).png', CHAT_ID)
+
+    expect(result).toEqual({ content: 'PNGDATA', totalLines: 1 })
+    expect(mockReadFileRecord).toHaveBeenCalledWith(
+      expect.objectContaining({ id: 'wf_2', name: 'image (2).png', storageContext: 'mothership' })
+    )
+  })
+
+  it('returns null when no row matches', async () => {
+    dbChainMockFns.limit.mockResolvedValueOnce([])
+    dbChainMockFns.where.mockResolvedValueOnce([])
+
+    const result = await readChatUpload('nope.png', CHAT_ID)
+
+    expect(result).toBeNull()
+    expect(mockReadFileRecord).not.toHaveBeenCalled()
+  })
+})

apps/sim/lib/copilot/tools/handlers/upload-file-reader.ts

@@ -2,7 +2,7 @@ import { db } from '@sim/db'
 import { workspaceFiles } from '@sim/db/schema'
 import { createLogger } from '@sim/logger'
 import { toError } from '@sim/utils/errors'
-import { and, eq, isNull } from 'drizzle-orm'
+import { and, asc, eq, isNull } from 'drizzle-orm'
 import { type FileReadResult, readFileRecord } from '@/lib/copilot/vfs/file-reader'
 import { normalizeVfsSegment } from '@/lib/copilot/vfs/normalize-segment'
 import { getServePathPrefix } from '@/lib/uploads'
@@ -15,7 +15,7 @@ function toWorkspaceFileRecord(row: typeof workspaceFiles.$inferSelect): Workspa
   return {
     id: row.id,
     workspaceId: row.workspaceId || '',
-    name: row.originalName,
+    name: row.displayName,
     key: row.key,
     path: `${pathPrefix}${encodeURIComponent(row.key)}?context=mothership`,
     size: row.size,
@@ -29,8 +29,10 @@ function toWorkspaceFileRecord(row: typeof workspaceFiles.$inferSelect): Workspa
 }
 
 /**
- * Resolve a mothership upload row by `originalName`, preferring an exact DB match (limit 1) and
- * only scanning all chat uploads when that misses (e.g. macOS U+202F vs ASCII space in the name).
+ * Resolve a mothership upload row by `displayName` (the collision-disambiguated name
+ * exposed via `uploads/<displayName>` in the VFS). Prefers an exact DB match; falls back
+ * to a normalized scan when the model passes a visually-equivalent name (e.g. macOS U+202F
+ * narrow no-break space vs ASCII space in screenshot filenames).
  */
 export async function findMothershipUploadRowByChatAndName(
   chatId: string,
@@ -43,7 +45,7 @@ export async function findMothershipUploadRowByChatAndName(
       and(
         eq(workspaceFiles.chatId, chatId),
         eq(workspaceFiles.context, 'mothership'),
-        eq(workspaceFiles.originalName, fileName),
+        eq(workspaceFiles.displayName, fileName),
         isNull(workspaceFiles.deletedAt)
       )
     )
@@ -65,11 +67,11 @@ export async function findMothershipUploadRowByChatAndName(
     )
 
   const segmentKey = normalizeVfsSegment(fileName)
-  return allRows.find((r) => normalizeVfsSegment(r.originalName) === segmentKey) ?? null
+  return allRows.find((r) => normalizeVfsSegment(r.displayName) === segmentKey) ?? null
 }
 
 /**
- * List all chat-scoped uploads for a given chat.
+ * List all chat-scoped uploads for a given chat in upload order.
  */
 export async function listChatUploads(chatId: string): Promise<WorkspaceFileRecord[]> {
   try {
@@ -83,6 +85,7 @@ export async function listChatUploads(chatId: string): Promise<WorkspaceFileReco
           isNull(workspaceFiles.deletedAt)
         )
       )
+      .orderBy(asc(workspaceFiles.uploadedAt), asc(workspaceFiles.id))
 
     return rows.map(toWorkspaceFileRecord)
   } catch (err) {