refactor(mothership): one claim primitive, one desktop-tool classifier, sealed Stop results

The desktop claim is now an option of the run-locked tool execution claim
(claimSimToolExecution becomes claimToolExecution) instead of a second copy
of the admission check. Stop picks the open desktop calls with the shared TS
classifier, which moves to lib/mothership/tools/desktop-tools.ts, instead of
a SQL restatement of it, and seals each result the way the confirm route
does, so a waiter restores what Stop did rather than failing to unseal it.

Author: waleedlatif1

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

@@ -8,7 +8,6 @@ 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,
@@ -40,11 +39,9 @@ import {
   createUnauthorizedResponse,
 } from '@/lib/mothership/request/http'
 import { withIncomingGoSpan } from '@/lib/mothership/request/otel'
-import {
-  retainSealedClientToolContext,
-  sealClientToolCompletion,
-} from '@/lib/mothership/request/tools/client-completion-seal.server'
+import { sealClientToolSettlement } from '@/lib/mothership/request/tools/client-completion-seal.server'
 import { isWorkflowToolName } from '@/lib/mothership/tools/client-executed-tools'
+import { getDesktopToolClaimOwner } from '@/lib/mothership/tools/desktop-tools'
 import {
   createStructuralWorkflowToolCompletionData,
   getWorkflowToolCompletionExecutionId,
@@ -417,27 +414,24 @@ export const POST = withRouteHandler((req: NextRequest) => {
             }
           : {
               message: getClientToolCompletionMessage(status),
-              data: {
-                ...retainSealedClientToolContext(existing.result),
-                ...(await sealClientToolCompletion({
-                  toolCallId,
-                  runId: existing.runId,
-                  userId: authenticatedUserId,
-                  ...(isIndeterminateNativeExit
-                    ? {
-                        message: NATIVE_HANDOFF_INTERRUPTED_MESSAGE,
-                        data: {
-                          error: NATIVE_HANDOFF_INTERRUPTED_MESSAGE,
-                          outcomeUnknown: true,
-                          doNotRetry: true,
-                        },
-                      }
-                    : {
-                        ...(message !== undefined ? { message } : {}),
-                        ...(data !== undefined ? { data } : {}),
-                      }),
-                })),
-              },
+              data: await sealClientToolSettlement(existing.result, {
+                toolCallId,
+                runId: existing.runId,
+                userId: authenticatedUserId,
+                ...(isIndeterminateNativeExit
+                  ? {
+                      message: NATIVE_HANDOFF_INTERRUPTED_MESSAGE,
+                      data: {
+                        error: NATIVE_HANDOFF_INTERRUPTED_MESSAGE,
+                        outcomeUnknown: true,
+                        doNotRetry: true,
+                      },
+                    }
+                  : {
+                      ...(message !== undefined ? { message } : {}),
+                      ...(data !== undefined ? { data } : {}),
+                    }),
+              }),
             }
 
         const updateOutcome = await updateToolCallStatus(

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

@@ -17,7 +17,7 @@ vi.mock('@/lib/mothership/async-runs/repository', () => mothershipAsyncRunsMock)
 
 import { POST } from './route'
 
-const claimPendingAsyncToolCall = mothershipAsyncRunsMockFns.mockClaimPendingAsyncToolCall
+const claimToolExecution = mothershipAsyncRunsMockFns.mockClaimToolExecution
 const getAsyncToolCall = mothershipAsyncRunsMockFns.mockGetAsyncToolCall
 const getRunSegment = mothershipAsyncRunsMockFns.mockGetRunSegment
 const resolveInvocationWorkspace = mothershipWorkspaceTargetMockFns.mockResolveInvocationWorkspace
@@ -50,7 +50,7 @@ describe('desktop tool authorization', () => {
       userId: 'user-1',
       status: 'active',
     })
-    claimPendingAsyncToolCall.mockResolvedValue('claimed')
+    claimToolExecution.mockResolvedValue({ outcome: 'claimed' })
   })
 
   it('never returns presentation activity as an executable browser argument', async () => {
@@ -84,7 +84,7 @@ describe('desktop tool authorization', () => {
     const response = await POST(request('retired-browser-tool'))
 
     expect(response.status).toBe(403)
-    expect(claimPendingAsyncToolCall).not.toHaveBeenCalled()
+    expect(claimToolExecution).not.toHaveBeenCalled()
   })
 
   it('rejects a replayed browser action after its pending row was claimed', async () => {
@@ -98,7 +98,7 @@ describe('desktop tool authorization', () => {
 
     const response = await POST(request('browser-tool'))
     expect(response.status).toBe(404)
-    expect(claimPendingAsyncToolCall).not.toHaveBeenCalled()
+    expect(claimToolExecution).not.toHaveBeenCalled()
   })
 
   it('rejects workspace VFS calls and mutating legacy local tools', async () => {
@@ -176,13 +176,18 @@ describe('desktop tool authorization', () => {
       { userId: 'user-1', chatId: 'chat-1', organizationId: 'org-1', workspaceId: undefined },
       'target'
     )
-    expect(claimPendingAsyncToolCall).toHaveBeenCalledExactlyOnceWith('import-1', 'desktop-files')
+    expect(claimToolExecution).toHaveBeenCalledExactlyOnceWith({
+      toolCallId: 'import-1',
+      runId: 'run-1',
+      userId: 'user-1',
+      claimedBy: 'desktop-files',
+    })
     getAsyncToolCall.mockResolvedValue({ ...tool, status: 'running', claimedBy: 'desktop-files' })
     expect((await POST(request('import-1', true))).status).toBe(409)
     expect((await POST(request('import-1'))).status).toBe(200)
     getAsyncToolCall.mockResolvedValue({ ...tool, status: 'running', claimedBy: 'sim-stream' })
     expect((await POST(request('import-1'))).status).toBe(404)
-    expect(claimPendingAsyncToolCall).toHaveBeenCalledOnce()
+    expect(claimToolExecution).toHaveBeenCalledOnce()
   })
 
   it('rejects inaccessible destinations and lost import claims before exposing files', async () => {
@@ -197,8 +202,8 @@ describe('desktop tool authorization', () => {
       new OrchestrationError('not_found', 'Workspace not found')
     )
     expect((await POST(request('import-1', true))).status).toBe(404)
-    expect(claimPendingAsyncToolCall).not.toHaveBeenCalled()
-    claimPendingAsyncToolCall.mockResolvedValueOnce('not_pending')
+    expect(claimToolExecution).not.toHaveBeenCalled()
+    claimToolExecution.mockResolvedValueOnce({ outcome: 'existing' })
     expect((await POST(request('import-1', true))).status).toBe(409)
   })
 

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

@@ -9,10 +9,10 @@ import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
 import { resolveInvocationWorkspace } from '@/lib/mothership/application/workspace-target'
 import { DESKTOP_TOOL_CLAIM_OWNER } from '@/lib/mothership/async-runs/lifecycle'
 import {
-  claimPendingAsyncToolCall,
+  claimToolExecution,
   getAsyncToolCall,
   getRunSegment,
-  type PendingToolCallClaim,
+  type ToolExecutionClaim,
 } from '@/lib/mothership/async-runs/repository'
 import {
   authenticateCopilotRequestSessionOnly,
@@ -23,16 +23,16 @@ 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' },
+    { error: 'This chat turn ended or 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'>,
+  claim: Exclude<ToolExecutionClaim['outcome'], 'claimed'>,
   notPending: () => NextResponse
 ): NextResponse {
-  if (claim === 'admission_closed') return admissionClosedResponse()
+  if (claim === 'closed') return admissionClosedResponse()
   if (claim === 'awaiting_permission')
     return NextResponse.json({ error: 'The user has not approved this tool call' }, { status: 403 })
   return notPending()
@@ -115,11 +115,13 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
           { 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)
+      const { outcome } = await claimToolExecution({
+        toolCallId: toolCall.toolCallId,
+        runId: toolCall.runId,
+        userId,
+        claimedBy: DESKTOP_TOOL_CLAIM_OWNER.files,
+      })
+      if (outcome !== 'claimed') return refusedClaimResponse(outcome, alreadyStarted)
     } else if (
       toolCall.status !== 'running' ||
       toolCall.claimedBy !== DESKTOP_TOOL_CLAIM_OWNER.files
@@ -134,11 +136,15 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
   if (isBrowserTool || isTerminalTool) {
     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 (claim !== 'claimed') return refusedClaimResponse(claim, notPending)
+    const { outcome } = await claimToolExecution({
+      toolCallId: toolCall.toolCallId,
+      runId: toolCall.runId,
+      userId,
+      claimedBy: isBrowserTool
+        ? DESKTOP_TOOL_CLAIM_OWNER.browser
+        : DESKTOP_TOOL_CLAIM_OWNER.terminal,
+    })
+    if (outcome !== 'claimed') return refusedClaimResponse(outcome, notPending)
   }
 
   return NextResponse.json({

apps/sim/lib/mothership/agent-cli/saved-run-read.live.test.ts

@@ -95,7 +95,7 @@ import { runCli } from '@/lib/mothership/agent-cli/run-cli'
 import { resolveCopilotWorkspaceFileReference } from '@/lib/mothership/application/execute-file-use-case'
 import {
   areStreamToolExecutionsSettled,
-  claimSimToolExecution,
+  claimToolExecution,
   claimWorkflowToolExecution,
   closeStreamToolAdmission,
   completeAsyncToolCall,
@@ -1750,7 +1750,7 @@ describe.skipIf(!process.env.MSHIP_TEST_DATABASE_URL)(
         status: 'running',
       })
       const owner = { runId, toolCallId, ownerToken, userId: 'run-reader' }
-      expect(await claimSimToolExecution(owner)).toEqual({ outcome: 'claimed' })
+      expect(await claimToolExecution(owner)).toEqual({ outcome: 'claimed' })
       return { owner, chatId, streamId }
     }
 
@@ -1811,7 +1811,7 @@ describe.skipIf(!process.env.MSHIP_TEST_DATABASE_URL)(
       ).rejects.toThrow('outcome is unknown')
       expect(await revokeExpiredSimToolExecutions(owner)).toHaveLength(1)
       expect(await revokeExpiredSimToolExecutions(owner)).toEqual([])
-      expect(await claimSimToolExecution({ ...owner, ownerToken: generateId() })).toEqual({
+      expect(await claimToolExecution({ ...owner, ownerToken: generateId() })).toEqual({
         outcome: 'existing',
       })
       const saved = await readTool(owner.toolCallId)
@@ -2058,7 +2058,7 @@ describe.skipIf(!process.env.MSHIP_TEST_DATABASE_URL)(
         })
         expect(await claimWorkflowToolExecution(toolCallId, executionId, 'client')).not.toBeNull()
         expect(
-          await claimSimToolExecution({
+          await claimToolExecution({
             runId,
             toolCallId,
             userId: 'run-reader',
@@ -2132,7 +2132,7 @@ describe.skipIf(!process.env.MSHIP_TEST_DATABASE_URL)(
       ])
       const priorExecutionId = generateId()
       await claimWorkflowToolExecution(priorToolId, priorExecutionId, 'client')
-      await claimSimToolExecution({
+      await claimToolExecution({
         runId,
         toolCallId,
         userId: 'run-reader',
@@ -2175,7 +2175,7 @@ describe.skipIf(!process.env.MSHIP_TEST_DATABASE_URL)(
       })
       expect(await claimWorkflowToolExecution(toolCallId, generateId(), 'sim')).not.toBeNull()
       expect(
-        await claimSimToolExecution({
+        await claimToolExecution({
           runId,
           toolCallId,
           userId: 'run-reader',

apps/sim/lib/mothership/async-runs/orphaned-runs.integration.ts

@@ -52,7 +52,7 @@ import {
   sweepOrphanedRuns,
 } from '@/lib/mothership/async-runs/orphaned-runs'
 import {
-  claimSimToolExecution,
+  claimToolExecution,
   requestRunStop,
   updateRunStatus,
 } from '@/lib/mothership/async-runs/repository'
@@ -279,7 +279,7 @@ describe.runIf(Boolean(redisUrl))('Chat runs no controller owns', () => {
     /** A long tool call writes nothing to the run; only its execution heartbeat shows it is alive. */
     const orphan = await admittedRun({ idleMinutes: 90, status: 'paused_waiting_for_tool' })
     const tool = await dispatchedTool(orphan.runId)
-    expect(await claimSimToolExecution(tool)).toEqual({ outcome: 'claimed' })
+    expect(await claimToolExecution(tool)).toEqual({ outcome: 'claimed' })
 
     expect((await sweepOrphanedRuns()).settledRunIds).not.toContain(orphan.runId)
     const live = await stored(orphan.runId)
@@ -309,7 +309,7 @@ describe.runIf(Boolean(redisUrl))('Chat runs no controller owns', () => {
           .where(eq(copilotRuns.id, orphan.runId))
           .for('update'),
       async (holder) => {
-        const claim = claimSimToolExecution(tool)
+        const claim = claimToolExecution(tool)
         const claimant = await lockWaiterBehind(holder)
         const sweep = sweepOrphanedRuns()
         await lockWaiterBehind(holder, claimant)
@@ -327,7 +327,7 @@ describe.runIf(Boolean(redisUrl))('Chat runs no controller owns', () => {
   it('never settles a run whose Sim tool lease a heartbeat renewed as the sweep settled it', async () => {
     const orphan = await admittedRun({ idleMinutes: 90, status: 'paused_waiting_for_tool' })
     const tool = await dispatchedTool(orphan.runId)
-    expect(await claimSimToolExecution(tool)).toEqual({ outcome: 'claimed' })
+    expect(await claimToolExecution(tool)).toEqual({ outcome: 'claimed' })
     await db
       .update(copilotAsyncToolCalls)
       .set({ executionLeaseExpiresAt: sql`clock_timestamp() - interval '1 second'` })

apps/sim/lib/mothership/async-runs/repository.test.ts

@@ -9,7 +9,7 @@ import { dbChainMockFns, hasMockCondition, queueTableRows, resetDbChainMock } fr
 import { beforeEach, describe, expect, it } from 'vitest'
 import {
   areStreamToolExecutionsSettled,
-  claimSimToolExecution,
+  claimToolExecution,
   claimWorkflowToolExecution,
   closeStreamToolAdmission,
   createRunSegment,
@@ -211,7 +211,7 @@ describe('durable Sim tool ownership', () => {
       dbChainMockFns.for.mockResolvedValueOnce([
         { toolExecutionVersion: 2, toolAdmissionClosedAt: null, status },
       ])
-      expect(await claimSimToolExecution(input)).toEqual({ outcome: 'closed' })
+      expect(await claimToolExecution(input)).toEqual({ outcome: 'closed' })
       dbChainMockFns.for.mockResolvedValueOnce([{ version: 2, closedAt: null, status }])
       await expect(
         recordSimSandboxProcess({
@@ -232,7 +232,7 @@ describe('durable Sim tool ownership', () => {
       { id: input.runId, toolExecutionVersion: 2, toolAdmissionClosedAt: null },
     ])
     dbChainMockFns.returning.mockResolvedValueOnce([{ id: 'row-1' }])
-    expect(await claimSimToolExecution(input)).toEqual({ outcome: 'claimed' })
+    expect(await claimToolExecution(input)).toEqual({ outcome: 'claimed' })
     expect(dbChainMockFns.for).toHaveBeenCalledWith('update')
     expect(
       hasMockCondition(
@@ -257,13 +257,13 @@ describe('durable Sim tool ownership', () => {
     dbChainMockFns.for.mockResolvedValueOnce([
       { toolExecutionVersion: 2, toolAdmissionClosedAt: new Date() },
     ])
-    expect(await claimSimToolExecution(input)).toEqual({ outcome: 'closed' })
+    expect(await claimToolExecution(input)).toEqual({ outcome: 'closed' })
     expect(dbChainMockFns.update).not.toHaveBeenCalled()
   })
 
   it.each([0, 1])('does not certify or execute through tracking version %s', async (version) => {
     dbChainMockFns.for.mockResolvedValueOnce([{ toolExecutionVersion: version }])
-    await expect(claimSimToolExecution(input)).rejects.toThrow('ownership is unavailable')
+    await expect(claimToolExecution(input)).rejects.toThrow('ownership is unavailable')
     dbChainMockFns.returning.mockResolvedValueOnce([{ version }])
     expect(await closeStreamToolAdmission('stream-1', input.userId)).toBe(false)
   })
@@ -278,7 +278,7 @@ describe('durable Sim tool ownership', () => {
       executionSettledAt: null,
     }
     queueTableRows(copilotAsyncToolCalls, [record])
-    expect(await claimSimToolExecution(input)).toEqual({ outcome: 'existing' })
+    expect(await claimToolExecution(input)).toEqual({ outcome: 'existing' })
   })
 
   it('keeps a terminal result distinct from actual execution settlement', async () => {