fix: close the gaps an adversarial review of this branch found

A conflict handler added earlier in this branch was dead code. It read the
Postgres error code off the thrown object, but the driver error arrives
wrapped with the real one on `cause`, so the check returned false on its
first line and the 409 never fired. Its test passed only because it threw a
flat shape production never produces. It now reads through the cause chain
with the shared helpers, compares the constraint name exactly instead of
matching a substring of the SQL, and its test throws the real wrapped error.

Resuming a conversation checked its workflow and its workspace but not its
type, so a conversation created by the web surface could be continued as a
CLI turn. It now refuses through the same uniform 404 as every other
mismatch, which closes the same omission on the web posting path. Minting
one no longer leaves a blank untitled row at the top of the Chat list.

The pre-write check on a minted API key refused fewer characters than the
writer does, so a key the check accepted could still fail at the write —
after the endpoint beside it was already stored, pairing a new endpoint with
the previous key. The two had drifted because the set was spelled three
times; there is now one.

A description claimed a processed count reported only the chunks that
changed. The update returns every row it matched, so re-enabling chunks that
were already enabled counts them all. Two OpenAPI sentences promised no
conflict detection and no persistence warnings in a dry run, both of which
the same branch had just made false. A described window was wrong whenever a
start was supplied without an end.

Listing the editors of a built-in skill answered a read with a modification
refusal on the internal surface. Archived table listings could reach the
strict folder projector again through a third scope value the input type
still allowed. A metadata-only secret write skipped the guard its
personal-scope twin has. The internal document boundary still took the two
processing fields as unbounded strings. Truncation was reported only from
the response envelope, so a clipped file body, row search and workflow-stats
list said nothing.

A staged download stopped watching for signals before it finished removing
its directory, and cleared every listener for the signal rather than its own.
Three tests asserted a contract constant against itself; they now drive
rendered help, real argv, or real render output.

Author: waleedlatif1

apps/docs/content/docs/en/cli/scripting.mdx

@@ -31,6 +31,20 @@ printf 'wf_3Qm8ZtLpR2yVnKd7BsXwC\nwf_5Hn1JvTqW9xUcMb4RzPgL\n' | sim files mv --f
 
 Arrays of objects stay JSON.
 
+## Passing a literal leading `@`
+
+Because `@` introduces a file reference, a value that genuinely starts with one
+is written `@@`. Only the leading `@` is dropped, and every `@`-aware flag
+accepts the escape:
+
+```bash
+sim files share set wf_3Qm8ZtLpR2yVnKd7BsXwC --allowed-emails @@example.org
+sim secrets set API_HOST --value @@internal
+```
+
+Without it, `--allowed-emails @example.org` can only be read as a request to
+open a file named `example.org`.
+
 ## Filtering table rows
 
 `--filter` takes the same predicate tree the API uses: `all` (AND) or `any` (OR)
@@ -117,11 +131,23 @@ esac
 
 ## Selecting workflow output
 
-`--select-output` takes `blockName.field` selectors. Fields that a run did not
-produce are simply omitted:
+`--select-output` shapes a streamed result, so it requires `--follow`. It takes
+`blockName.field` selectors; fields that a run did not produce are simply
+omitted:
+
+```bash
+sim workflows run 3a9e21d8-5f47-4c0b-b2ea-91d7c6034ef8 --follow --select-output agent_1.content --output json
+```
+
+Without `--follow` the CLI refuses the pair rather than spending a request on a
+response that carries no outputs, and `--async` cannot be combined with it
+either — there is no stream to shape. To narrow a run that has already finished,
+read it back with `workflows runs get`, which matches block **ids** rather than
+the block names `workflows run` takes:
 
 ```bash
-sim workflows run 3a9e21d8-5f47-4c0b-b2ea-91d7c6034ef8 --select-output agent_1.content --output json
+sim workflows runs get "$run_id" --workflow 3a9e21d8-5f47-4c0b-b2ea-91d7c6034ef8 \
+  --select-output 1d4c8f02-7b63-4a19-8e52-63f0a7c5d9b1.content --output json
 ```
 
 ## Polling a long run

apps/sim/app/api/mothership/chats/route.ts

@@ -9,6 +9,7 @@ import {
 import { parseRequest } from '@/lib/api/server'
 import { listMothershipChats } from '@/lib/copilot/chat/list-mothership-chats'
 import { chatPubSub } from '@/lib/copilot/chat-status'
+import { MOTHERSHIP_CHAT_DEFAULT_MODEL } from '@/lib/copilot/constants'
 import {
   authenticateCopilotRequestSessionOnly,
   createForbiddenResponse,
@@ -78,7 +79,7 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
         workspaceId,
         type: 'mothership',
         title: null,
-        model: 'claude-opus-4-8',
+        model: MOTHERSHIP_CHAT_DEFAULT_MODEL,
         updatedAt: now,
         lastSeenAt: now,
       })

apps/sim/app/api/v2/chat/route.test.ts

@@ -325,6 +325,42 @@ describe('POST /api/v2/chat', () => {
     expect(mockRunHeadlessCopilotLifecycle).not.toHaveBeenCalled()
   })
 
+  it('asks the resolver for a mothership conversation, so another type resolves to nothing', async () => {
+    await callChat({
+      workspaceId: 'workspace-1',
+      message: 'and then?',
+      conversationId: OWNED_CONVERSATION_ID,
+    })
+
+    expect(mockResolveOrCreateChat).toHaveBeenCalledWith(
+      expect.objectContaining({ chatId: OWNED_CONVERSATION_ID, type: 'mothership' })
+    )
+  })
+
+  it('titles a new conversation by its first message so the web Chat list has no blank row', async () => {
+    await callChat({ workspaceId: 'workspace-1', message: '  Summarize\n  last week   ' })
+
+    expect(mockResolveOrCreateChat).toHaveBeenCalledWith(
+      expect.objectContaining({ title: 'Summarize last week' })
+    )
+  })
+
+  it('truncates a long first message into a title instead of storing the whole message', async () => {
+    const message = 'a'.repeat(500)
+
+    await callChat({ workspaceId: 'workspace-1', message })
+
+    const title = (mockResolveOrCreateChat.mock.calls[0][0] as { title?: string }).title
+    expect(title).toBe(`${'a'.repeat(80)}...`)
+  })
+
+  it('leaves the title unset for a whitespace-only message rather than stamping an empty one', async () => {
+    await callChat({ workspaceId: 'workspace-1', message: '   \n  ' })
+
+    const resolverInput = mockResolveOrCreateChat.mock.calls[0][0] as Record<string, unknown>
+    expect(Object.hasOwn(resolverInput, 'title')).toBe(false)
+  })
+
   it('rejects a malformed conversation id before resolving anything', async () => {
     const response = await callChat({
       workspaceId: 'workspace-1',

apps/sim/app/api/v2/chat/route.ts

@@ -1,6 +1,7 @@
 import { createLogger } from '@sim/logger'
 import { getErrorMessage, toError } from '@sim/utils/errors'
 import { generateId } from '@sim/utils/id'
+import { truncate } from '@sim/utils/string'
 import type { NextRequest } from 'next/server'
 import { v2ChatContract } from '@/lib/api/contracts/v2/chat'
 import { parseRequest } from '@/lib/api/server'
@@ -16,6 +17,7 @@ import { chatOperations } from '@/lib/copilot/application/operations'
 import { resolveOrCreateChat } from '@/lib/copilot/chat/lifecycle'
 import { buildIntegrationToolSchemas } from '@/lib/copilot/chat/payload'
 import { generateWorkspaceContext } from '@/lib/copilot/chat/workspace-context'
+import { MOTHERSHIP_CHAT_DEFAULT_MODEL } from '@/lib/copilot/constants'
 import { computeWorkspaceEntitlements } from '@/lib/copilot/entitlements'
 import {
   type CopilotEnvironmentContext,
@@ -50,10 +52,23 @@ const CHAT_HEARTBEAT_INTERVAL_MS = 15_000
 const ndjsonEncoder = new TextEncoder()
 
 /**
- * Model recorded on conversations this route creates, matching the model the
- * web Chat surface stamps on a new mothership conversation.
+ * Longest title derived from a first message. Well under the 200-character
+ * ceiling the rename contract enforces, and short enough to read as one line
+ * in the web Chat list.
  */
-const V2_CHAT_MODEL = 'claude-opus-4-8'
+const CHAT_TITLE_MAX_LENGTH = 80
+
+/**
+ * Title a conversation this route creates by its first message, so a `sim chat`
+ * turn does not leave a blank row at the top of the user's web Chat list.
+ * Returns undefined for a message that is only whitespace, leaving the title
+ * unset rather than stamping an empty one.
+ */
+function deriveConversationTitle(message: string): string | undefined {
+  const normalized = message.replace(/\s+/g, ' ').trim()
+  if (!normalized) return undefined
+  return truncate(normalized, CHAT_TITLE_MAX_LENGTH)
+}
 
 function isAbortError(error: unknown): boolean {
   return error instanceof Error && error.name === 'AbortError'
@@ -145,6 +160,8 @@ export const POST = withRouteHandler(
       const workspaceAccess = await assertActiveWorkspaceAccess(workspaceId, userId)
       const userPermission = workspaceAccess.permission
 
+      const conversationTitle = deriveConversationTitle(message)
+
       // A caller-supplied conversation id is a claim, not an identity: resolve
       // it through the same owner- and workspace-scoped loader the web Chat
       // surface uses, and refuse every id that does not resolve with the same
@@ -154,8 +171,9 @@ export const POST = withRouteHandler(
         ...(conversationId ? { chatId: conversationId } : {}),
         userId,
         workspaceId,
-        model: V2_CHAT_MODEL,
+        model: MOTHERSHIP_CHAT_DEFAULT_MODEL,
         type: 'mothership',
+        ...(conversationTitle ? { title: conversationTitle } : {}),
       })
       if (conversationId && !resolvedChat.chat) {
         return v2Error('NOT_FOUND', 'Conversation not found')

apps/sim/app/api/v2/workspaces/[workspaceId]/route.test.ts

@@ -121,6 +121,8 @@ describe.each(routes)('v2 $name workspace concealment', ({ spy, call }) => {
     const response = await call()
 
     expect(response.status).toBe(403)
-    expect(await response.json()).toMatchObject({ error: { code: 'FORBIDDEN' } })
+    expect(await response.json()).toMatchObject({
+      error: { code: 'FORBIDDEN', details: { code: 'INSUFFICIENT_WORKSPACE_ROLE' } },
+    })
   })
 })

apps/sim/lib/api/contracts/knowledge/documents.test.ts

@@ -3,8 +3,10 @@
  */
 import { describe, expect, it } from 'vitest'
 import {
+  bulkCreateDocumentsBodySchema,
   listKnowledgeDocumentsQuerySchema,
   parseDocumentTagFiltersParam,
+  upsertDocumentBodySchema,
 } from '@/lib/api/contracts/knowledge/documents'
 
 describe('listKnowledgeDocumentsQuerySchema.tagFilters', () => {
@@ -143,3 +145,53 @@ describe('parseDocumentTagFiltersParam', () => {
     expect(parseDocumentTagFiltersParam(JSON.stringify(filters))).toEqual(filters)
   })
 })
+
+/**
+ * `recipe` and `lang` reach analytics and nothing else, so an unrecognised value
+ * was accepted with a 200 and silently discarded. Both internal write bodies
+ * reuse the upload boundary's validated shape, which is what every first-party
+ * caller already sends.
+ */
+describe('internal document processingOptions', () => {
+  const DOCUMENT = {
+    filename: 'notes.txt',
+    fileUrl: 'https://example.com/notes.txt',
+    fileSize: 12,
+    mimeType: 'text/plain',
+  }
+
+  const boundaries = [
+    {
+      name: 'bulk create',
+      parse: (processingOptions: unknown) =>
+        bulkCreateDocumentsBodySchema.safeParse({
+          documents: [DOCUMENT],
+          bulk: true,
+          processingOptions,
+        }),
+    },
+    {
+      name: 'upsert',
+      parse: (processingOptions: unknown) =>
+        upsertDocumentBodySchema.safeParse({ ...DOCUMENT, processingOptions }),
+    },
+  ] as const
+
+  describe.each(boundaries)('$name', ({ parse }) => {
+    it('accepts what the shipped first-party callers send', () => {
+      expect(parse({ recipe: 'default', lang: 'en' }).success).toBe(true)
+    })
+
+    it('rejects an unrecognised recipe instead of discarding it', () => {
+      const result = parse({ recipe: 'super-chunker-9000', lang: 'en' })
+      expect(result.success).toBe(false)
+      expect(result.error?.issues[0]?.path).toEqual(['processingOptions', 'recipe'])
+    })
+
+    it('rejects a lang that is not a BCP-47 tag', () => {
+      const result = parse({ recipe: 'default', lang: 'en_US' })
+      expect(result.success).toBe(false)
+      expect(result.error?.issues[0]?.path).toEqual(['processingOptions', 'lang'])
+    })
+  })
+})

apps/sim/lib/api/contracts/knowledge/documents.ts

@@ -17,6 +17,7 @@ import { defineRouteContract } from '@/lib/api/contracts/types'
 import { PRIVATE_SECRET_PROVENANCE_FIELD } from '@/lib/execution/private-tool-metadata'
 import { getFieldTypeForSlot, MAX_KNOWLEDGE_DOCUMENTS_PER_CREATE } from '@/lib/knowledge/constants'
 import { getOperatorsForFieldType, isValidFilterValue } from '@/lib/knowledge/filters/types'
+import { knowledgeDocumentUploadMetadataSchema } from '@/lib/knowledge/upload-metadata'
 
 export const documentTagFilterSchema = z
   .object({
@@ -136,12 +137,7 @@ export const bulkCreateDocumentsBodySchema = z.object({
       MAX_KNOWLEDGE_DOCUMENTS_PER_CREATE,
       `At most ${MAX_KNOWLEDGE_DOCUMENTS_PER_CREATE} documents may be created at once`
     ),
-  processingOptions: z
-    .object({
-      recipe: z.string().optional(),
-      lang: z.string().optional(),
-    })
-    .optional(),
+  processingOptions: knowledgeDocumentUploadMetadataSchema.shape.processingOptions,
   bulk: z.literal(true),
   workflowId: z.string().optional(),
   [PRIVATE_SECRET_PROVENANCE_FIELD]: privateSecretProvenanceBundleSchema.optional(),
@@ -173,12 +169,7 @@ export const upsertDocumentBodySchema = z.object({
   fileSize: z.number().min(1, 'File size must be greater than 0'),
   mimeType: z.string().min(1, 'MIME type is required'),
   documentTagsData: z.string().optional(),
-  processingOptions: z
-    .object({
-      recipe: z.string().optional(),
-      lang: z.string().optional(),
-    })
-    .optional(),
+  processingOptions: knowledgeDocumentUploadMetadataSchema.shape.processingOptions,
   workflowId: z.string().optional(),
   [PRIVATE_SECRET_PROVENANCE_FIELD]: privateSecretProvenanceBundleSchema.optional(),
 })