fix(mothership): refuse desktop claims for unapproved or stopped calls

The desktop authorize route claimed any pending call, so a gated terminal
run that was still awaiting approval, or a call on a run the user had
stopped, could be claimed and executed. The claim now locks the run row and
refuses once tool admission has closed (Stop, a newer turn, or the run's
end), and refuses a call held for the user's decision until they allow it.
Whether a call is gated depends on the turn, so pre-persist records it on
the row (permission_requested_at).

Stop now settles the stopped runs' open desktop calls in the transaction
that closes admission: unclaimed calls as never started, claimed calls as
outcome unknown. A result for an already-settled call (a retry, or one that
lost to Stop) is acknowledged with the stored outcome instead of 404/500.

Author: waleedlatif1

apps/sim/app/api/copilot/confirm/route.test.ts

@@ -624,6 +624,26 @@ describe('Copilot Confirm API Route', () => {
     )
   })
 
+  it.each([
+    ['client_tool', 'running', 'success', completeAsyncToolCall],
+    ['browser_snapshot', 'pending', 'error', completePendingAsyncToolCall],
+  ] as const)(
+    'acknowledges a %s result whose write lost to a settlement that landed first',
+    async (toolName, storedStatus, status, completion) => {
+      const row = { ...existingRow, toolName, claimedBy: null }
+      getAsyncToolCall
+        .mockResolvedValueOnce({ ...row, status: storedStatus })
+        .mockResolvedValueOnce({ ...row, status: 'failed' })
+      completion.mockResolvedValueOnce(null)
+
+      const response = await POST(createMockPostRequest({ toolCallId: 'tool-call-123', status }))
+
+      expect(response.status).toBe(200)
+      expect(await response.json()).toMatchObject({ toolCallId: 'tool-call-123', status: 'error' })
+      expect(publishToolConfirmation).not.toHaveBeenCalled()
+    }
+  )
+
   it('does not publish when another terminal confirmation already won', async () => {
     completeAsyncToolCall.mockResolvedValueOnce(null)
 

apps/sim/app/api/copilot/confirm/route.ts

@@ -1,4 +1,5 @@
-import { isBrowserToolName, isCurrentBrowserToolName } from '@sim/browser-protocol'
+import type { Span } from '@opentelemetry/api'
+import { isBrowserToolName } from '@sim/browser-protocol'
 import { createLogger } from '@sim/logger'
 import { isTerminalToolName } from '@sim/terminal-protocol'
 import { getErrorMessage, toError } from '@sim/utils/errors'
@@ -7,12 +8,13 @@ import { type NextRequest, NextResponse } from 'next/server'
 import { copilotConfirmContract } from '@/lib/api/contracts/copilot'
 import { parseRequest, validationErrorResponse } from '@/lib/api/server'
 import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
+import { getDesktopToolClaimOwner } from '@/lib/mothership/async-runs/desktop-tools'
 import {
   ASYNC_TOOL_CONFIRMATION_STATUS,
   ASYNC_TOOL_STATUS,
   type AsyncCompletionData,
   type AsyncConfirmationStatus,
-  DESKTOP_TOOL_CLAIM_OWNER,
+  type AsyncTerminalStatus,
   isDeliveredAsyncStatus,
   isTerminalAsyncStatus,
   isWorkflowToolExecutionClaimable,
@@ -83,6 +85,24 @@ function createConfirmationResponse(
   return NextResponse.json({ success: true, message, toolCallId, status })
 }
 
+/**
+ * A result for a call that is already settled — a retried delivery, or one that lost to the server
+ * settling the call first (Stop, a fast "not started" failure) — answers with the stored outcome.
+ * Nothing is written or published again, and the reporter stops retrying.
+ */
+function acknowledgeSettledToolCall(
+  span: Span,
+  toolCallId: string,
+  storedStatus: AsyncTerminalStatus
+): NextResponse {
+  const settledStatus = getWorkflowToolConfirmationStatus(storedStatus)
+  span.setAttributes({
+    [TraceAttr.ToolConfirmationStatus]: settledStatus,
+    [TraceAttr.CopilotConfirmOutcome]: CopilotConfirmOutcome.Delivered,
+  })
+  return createConfirmationResponse(toolCallId, settledStatus, 'Tool call was already settled')
+}
+
 /** Atomically finalize or detach a client tool before publishing its wakeup event. */
 async function updateToolCallStatus(
   existing: NonNullable<Awaited<ReturnType<typeof getAsyncToolCall>>>,
@@ -284,26 +304,22 @@ export const POST = withRouteHandler((req: NextRequest) => {
           )
         }
 
+        if (!isWorkflowTool && isTerminalAsyncStatus(existing.status)) {
+          return acknowledgeSettledToolCall(span, toolCallId, existing.status)
+        }
+
         const isErrorOrCancelledOutcome =
           status === ASYNC_TOOL_CONFIRMATION_STATUS.error ||
           status === ASYNC_TOOL_CONFIRMATION_STATUS.cancelled
         const isNativeClientTool =
           isBrowserToolName(existing.toolName) ||
           isTerminalToolName(existing.toolName) ||
           existing.toolName === 'import_local_files'
+        const nativeClaimOwner = getDesktopToolClaimOwner(existing.toolName)
         const isPreclaimNativeTerminalOutcome =
-          (isCurrentBrowserToolName(existing.toolName) ||
-            isTerminalToolName(existing.toolName) ||
-            existing.toolName === 'import_local_files') &&
+          nativeClaimOwner !== undefined &&
           existing.status === ASYNC_TOOL_STATUS.pending &&
           isErrorOrCancelledOutcome
-        const nativeClaimOwner = isCurrentBrowserToolName(existing.toolName)
-          ? DESKTOP_TOOL_CLAIM_OWNER.browser
-          : isTerminalToolName(existing.toolName)
-            ? DESKTOP_TOOL_CLAIM_OWNER.terminal
-            : existing.toolName === 'import_local_files'
-              ? DESKTOP_TOOL_CLAIM_OWNER.files
-              : undefined
         const isIndeterminateNativeExit =
           isPreclaimNativeTerminalOutcome &&
           status === ASYNC_TOOL_CONFIRMATION_STATUS.error &&
@@ -453,6 +469,13 @@ export const POST = withRouteHandler((req: NextRequest) => {
               )
             : updateOutcome
 
+        if (reconciledOutcome === 'conflict' && !isWorkflowTool) {
+          const settled = await getAsyncToolCall(toolCallId).catch(() => null)
+          if (settled && isTerminalAsyncStatus(settled.status)) {
+            return acknowledgeSettledToolCall(span, toolCallId, settled.status)
+          }
+        }
+
         if (reconciledOutcome === 'conflict' && isPreclaimNativeTerminalOutcome) {
           span.setAttribute(TraceAttr.CopilotConfirmOutcome, CopilotConfirmOutcome.ToolCallNotFound)
           return createNotFoundResponse('Pending client tool call not found')

apps/sim/app/api/desktop/tool/authorize/route.test.ts

@@ -50,7 +50,7 @@ describe('desktop tool authorization', () => {
       userId: 'user-1',
       status: 'active',
     })
-    claimPendingAsyncToolCall.mockResolvedValue({ toolCallId: 'browser-tool', status: 'running' })
+    claimPendingAsyncToolCall.mockResolvedValue('claimed')
   })
 
   it('never returns presentation activity as an executable browser argument', async () => {
@@ -198,7 +198,7 @@ describe('desktop tool authorization', () => {
     )
     expect((await POST(request('import-1', true))).status).toBe(404)
     expect(claimPendingAsyncToolCall).not.toHaveBeenCalled()
-    claimPendingAsyncToolCall.mockResolvedValueOnce(null)
+    claimPendingAsyncToolCall.mockResolvedValueOnce('not_pending')
     expect((await POST(request('import-1', true))).status).toBe(409)
   })
 

apps/sim/app/api/desktop/tool/authorize/route.ts

@@ -12,6 +12,7 @@ import {
   claimPendingAsyncToolCall,
   getAsyncToolCall,
   getRunSegment,
+  type PendingToolCallClaim,
 } from '@/lib/mothership/async-runs/repository'
 import {
   authenticateCopilotRequestSessionOnly,
@@ -20,12 +21,33 @@ import {
 } from '@/lib/mothership/request/http'
 import { isUserLocalVfsToolCall } from '@/lib/mothership/tools/local-filesystem'
 
+const admissionClosedResponse = () =>
+  NextResponse.json(
+    { error: 'This chat was stopped, so the tool call can no longer run' },
+    { status: 410 }
+  )
+
+/** A refused claim answers the same way for every tool, except how each reports a lost race. */
+function refusedClaimResponse(
+  claim: Exclude<PendingToolCallClaim, 'claimed'>,
+  notPending: () => NextResponse
+): NextResponse {
+  if (claim === 'admission_closed') return admissionClosedResponse()
+  if (claim === 'awaiting_permission')
+    return NextResponse.json({ error: 'The user has not approved this tool call' }, { status: 403 })
+  return notPending()
+}
+
 /**
  * Electron calls this endpoint from the main process before every privileged
  * native model action. It returns only server-persisted canonical tool args;
  * Electron validates local-file requests against them and uses them directly
  * for browser and terminal tools. The presentation-only `activity` field is
  * dropped: desktop actions reject arguments they do not declare.
+ *
+ * Nothing is handed over once the run's tool admission has closed (Stop, a
+ * newer turn, or the run's end), nor for a call held for the user's decision
+ * that they have not allowed.
  */
 export const POST = withRouteHandler(async (request: NextRequest) => {
   const { userId, isAuthenticated } = await authenticateCopilotRequestSessionOnly()
@@ -47,6 +69,7 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
   if (run.status === 'complete' || run.status === 'error' || run.status === 'cancelled') {
     return createNotFoundResponse('Pending client tool call not found')
   }
+  if (run.toolAdmissionClosedAt) return admissionClosedResponse()
 
   const args = isRecordLike(toolCall.args) ? (toolCall.args as Record<string, unknown>) : {}
   const isBrowserTool = isCurrentBrowserToolName(toolCall.toolName)
@@ -84,14 +107,17 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
       return NextResponse.json(projected.body, { status: projected.status })
     }
     if (parsed.data.body.claim) {
-      if (
-        toolCall.status !== 'pending' ||
-        !(await claimPendingAsyncToolCall(toolCall.toolCallId, DESKTOP_TOOL_CLAIM_OWNER.files))
-      )
-        return NextResponse.json(
+      const alreadyStarted = () =>
+        NextResponse.json(
           { error: 'This import was already started; inspect its result before retrying' },
           { status: 409 }
         )
+      if (toolCall.status !== 'pending') return alreadyStarted()
+      const claim = await claimPendingAsyncToolCall(
+        toolCall.toolCallId,
+        DESKTOP_TOOL_CLAIM_OWNER.files
+      )
+      if (claim !== 'claimed') return refusedClaimResponse(claim, alreadyStarted)
     } else if (
       toolCall.status !== 'running' ||
       toolCall.claimedBy !== DESKTOP_TOOL_CLAIM_OWNER.files
@@ -104,16 +130,13 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
   // the Electron boundary — a replayed renderer event must not run a command
   // or click a button twice.
   if (isBrowserTool || isTerminalTool) {
-    if (toolCall.status !== 'pending') {
-      return createNotFoundResponse('Pending client tool call not found')
-    }
-    const claimed = await claimPendingAsyncToolCall(
+    const notPending = () => createNotFoundResponse('Pending client tool call not found')
+    if (toolCall.status !== 'pending') return notPending()
+    const claim = await claimPendingAsyncToolCall(
       toolCall.toolCallId,
       isBrowserTool ? DESKTOP_TOOL_CLAIM_OWNER.browser : DESKTOP_TOOL_CLAIM_OWNER.terminal
     )
-    if (!claimed) {
-      return createNotFoundResponse('Pending client tool call not found')
-    }
+    if (claim !== 'claimed') return refusedClaimResponse(claim, notPending)
   }
 
   return NextResponse.json({

apps/sim/lib/mothership/async-runs/desktop-tools.ts

@@ -0,0 +1,33 @@
+import { CURRENT_BROWSER_TOOL_NAMES, isCurrentBrowserToolName } from '@sim/browser-protocol'
+import { isTerminalToolName, TERMINAL_TOOL_NAME } from '@sim/terminal-protocol'
+import { DESKTOP_TOOL_CLAIM_OWNER } from '@/lib/mothership/async-runs/lifecycle'
+
+type DesktopToolClaimOwner =
+  (typeof DESKTOP_TOOL_CLAIM_OWNER)[keyof typeof DESKTOP_TOOL_CLAIM_OWNER]
+
+/**
+ * The owner Electron claims a call as before acting on it, for the desktop tools whose pending
+ * call is claimed atomically through `/api/desktop/tool/authorize`. Undefined for every other tool.
+ */
+export function getDesktopToolClaimOwner(toolName: string): DesktopToolClaimOwner | undefined {
+  if (isCurrentBrowserToolName(toolName)) return DESKTOP_TOOL_CLAIM_OWNER.browser
+  if (isTerminalToolName(toolName)) return DESKTOP_TOOL_CLAIM_OWNER.terminal
+  if (toolName === 'import_local_files') return DESKTOP_TOOL_CLAIM_OWNER.files
+  return undefined
+}
+
+/** Every tool that acts on the user's machine through the desktop app. */
+export const DESKTOP_TOOL_NAMES = [
+  ...CURRENT_BROWSER_TOOL_NAMES,
+  TERMINAL_TOOL_NAME,
+  'import_local_files',
+  'read_local_file',
+] as const
+
+/** What the model learns about a desktop call that Stop cancelled before the desktop picked it up. */
+export const STOPPED_BEFORE_START_MESSAGE =
+  'Not run: the user stopped the chat before the Sim desktop app started this action. Nothing happened on their computer.'
+
+/** What the model learns about a desktop call that Stop cancelled after the desktop picked it up. */
+export const STOPPED_WHILE_RUNNING_MESSAGE =
+  'Stopped by the user while the Sim desktop app was running this action. It may already have taken effect; inspect the current state before repeating it.'

apps/sim/lib/mothership/async-runs/lifecycle.ts

@@ -102,6 +102,17 @@ export function isExecutableToolPermissionDecision(
   return decision !== null && decision !== undefined && decision !== 'skip'
 }
 
+/** A call held for the user's decision may run only once they allowed it. */
+export function isAwaitingToolPermission(call: {
+  permissionRequestedAt: Date | null
+  permissionDecision: CopilotToolPermissionDecision | null
+}): boolean {
+  return (
+    Boolean(call.permissionRequestedAt) &&
+    !isExecutableToolPermissionDecision(call.permissionDecision)
+  )
+}
+
 export function isWorkflowToolExecutionClaimable(
   status: CopilotAsyncToolStatus,
   permissionDecision: CopilotToolPermissionDecision | null | undefined