feat(desktop): bind turns to a desktop and enforce its deadlines from the row

A turn sent from a desktop whose background executor is registered to the
same session (and with mothership-desktop-background-executor on) is bound
to that device at admission: copilot_runs.desktop_device_id. Its desktop
calls are persisted pending, offered to the device and claimed through the
executor's own fenced routes; the chat view's authorize and confirm answer
409 for them.

There is no supervisor. The single desktop wait (waitForDesktopToolCall)
branches on the binding: a bound call is offered (pickup_deadline_at, a new
nullable column) and the device's doorbell rung, then the existing durable
wait enforces every deadline from the row on each 5 s check, beside the
lease revocation that already lives there:
- an unclaimed call whose device is offline fails at once as not started
  (reason offline); one still unclaimed past its pickup window fails the same
  way (reason not_responding), as the inverse CAS of the claim;
- a claimed call whose lease lapsed fails as outcome unknown, revoking the
  device's token so its late result is superseded, and rings it to cancel.
Every settlement is sealed like the device's own result. The stale-execution
cron settles, the same way, bound calls whose waiter died with its process.

One not-started builder carries a reason (chat_not_open, offline,
not_responding), and the server-owned failure helper now settles through the
shared client settlement. The device is rung when a bound call needs
approval, when the user answers, and on Stop.

Author: waleedlatif1

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

@@ -131,6 +131,28 @@ describe('Copilot Confirm API Route', () => {
     expect(JSON.stringify(publishToolConfirmation.mock.calls)).not.toContain('resolved-secret')
   })
 
+  it("refuses a chat view's report for a call a desktop's background executor owns", async () => {
+    getAsyncToolCall.mockResolvedValue({
+      ...existingRow,
+      toolName: 'browser_click',
+      status: 'pending',
+      claimedBy: null,
+    })
+    getRunSegment.mockResolvedValue({ id: 'run-1', userId: 'user-1', desktopDeviceId: 'device-1' })
+
+    const response = await POST(
+      createMockPostRequest({
+        toolCallId: 'tool-call-123',
+        status: 'error',
+        message: 'The desktop refused this claim',
+      })
+    )
+
+    expect(response.status).toBe(409)
+    expect(completePendingAsyncToolCall).not.toHaveBeenCalled()
+    expect(completeAsyncToolCall).not.toHaveBeenCalled()
+  })
+
   it('atomically detaches a live background confirmation', async () => {
     const response = await POST(
       createMockPostRequest({

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

@@ -1,7 +1,7 @@
 import type { Span } from '@opentelemetry/api'
 import { createLogger } from '@sim/logger'
 import { getErrorMessage, toError } from '@sim/utils/errors'
-import { isPlainRecord } from '@sim/utils/object'
+import { isPlainRecord, toRecord } from '@sim/utils/object'
 import { type NextRequest, NextResponse } from 'next/server'
 import { copilotConfirmContract } from '@/lib/api/contracts/copilot'
 import { parseRequest, validationErrorResponse } from '@/lib/api/server'
@@ -40,7 +40,11 @@ import {
   settleClientToolCall,
 } from '@/lib/mothership/request/tools/client-settlement.server'
 import { isWorkflowToolName } from '@/lib/mothership/tools/client-executed-tools'
-import { getDesktopToolClaimOwner, isNativeDesktopTool } from '@/lib/mothership/tools/desktop-tools'
+import {
+  getDesktopToolClaimOwner,
+  isDesktopToolCall,
+  isNativeDesktopTool,
+} from '@/lib/mothership/tools/desktop-tools'
 import {
   createStructuralWorkflowToolCompletionData,
   getWorkflowToolCompletionExecutionId,
@@ -194,6 +198,17 @@ export const POST = withRouteHandler((req: NextRequest) => {
           return NextResponse.json({ error: 'Forbidden' }, { status: 403 })
         }
 
+        if (run.desktopDeviceId && isDesktopToolCall(existing.toolName, toRecord(existing.args))) {
+          span.setAttribute(TraceAttr.CopilotConfirmOutcome, CopilotConfirmOutcome.Forbidden)
+          return NextResponse.json(
+            {
+              error:
+                "This chat's desktop actions report through the desktop app's background executor",
+            },
+            { status: 409 }
+          )
+        }
+
         const isWorkflowTool = isWorkflowToolName(existing.toolName || '')
         const workflowId = isWorkflowTool
           ? resolveWorkflowToolTargetId(existing.args, run.workflowId)

apps/sim/app/api/copilot/tool-permission/route.ts

@@ -5,6 +5,7 @@ import { copilotToolPermissionContract } from '@/lib/api/contracts/copilot'
 import { parseRequest, validationErrorResponse } from '@/lib/api/server'
 import { isCopilotToolPermissionsEnabled } from '@/lib/core/config/env-flags'
 import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
+import { ringDesktopInbox } from '@/lib/desktop/executor/doorbell'
 import {
   getAsyncToolCall,
   getRunSegment,
@@ -136,6 +137,8 @@ async function applyDecision(
     toolName: claimed.toolName,
     decidedAt: claimed.permissionDecidedAt?.toISOString(),
   })
+  // A bound device lists the call for approval; the answer turns it into a call or drops it.
+  if (run.desktopDeviceId) ringDesktopInbox(run.desktopDeviceId, 'approval')
 
   return { toolCallId, decision, applied: true }
 }

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

@@ -72,6 +72,27 @@ describe('desktop tool authorization', () => {
     })
   })
 
+  it("refuses a chat view's claim on a run bound to a desktop's background executor", async () => {
+    getAsyncToolCall.mockResolvedValueOnce({
+      toolCallId: 'bound-click',
+      runId: 'run-1',
+      status: 'pending',
+      toolName: 'browser_click',
+      args: { ref: 'e1' },
+    })
+    getRunSegment.mockResolvedValueOnce({
+      id: 'run-1',
+      chatId: 'chat-1',
+      userId: 'user-1',
+      status: 'active',
+      desktopDeviceId: 'device-1',
+    })
+
+    const response = await POST(request('bound-click'))
+    expect(response.status).toBe(409)
+    expect(claimDesktopToolCall).not.toHaveBeenCalled()
+  })
+
   it('rejects retired browser tools retained only for history', async () => {
     getAsyncToolCall.mockResolvedValueOnce({
       toolCallId: 'retired-browser-tool',

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

@@ -74,6 +74,12 @@ 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')
   }
+  // The device's background executor claims a bound run's calls through its own fenced route.
+  if (run.desktopDeviceId)
+    return NextResponse.json(
+      { error: "This chat's desktop actions run in the desktop app's background executor" },
+      { status: 409 }
+    )
 
   const args = isRecordLike(toolCall.args) ? (toolCall.args as Record<string, unknown>) : {}
   if (!isDesktopToolCall(toolCall.toolName, args)) {

apps/sim/background/cleanup-stale-executions.ts

@@ -31,6 +31,7 @@ import {
   type StaleSweepableExecutionStatus,
 } from '@/lib/logs/types'
 import { sweepOrphanedRuns } from '@/lib/mothership/async-runs/orphaned-runs'
+import { settleAbandonedDesktopToolCalls } from '@/lib/mothership/request/tools/desktop-wait'
 import { cancelStaleDispatches } from '@/lib/table/dispatcher'
 import { deleteFile } from '@/lib/uploads/core/storage-service'
 import {
@@ -743,6 +744,19 @@ export async function runCleanupStaleExecutions() {
     })
   }
 
+  /**
+   * Settle desktop calls on device-bound runs whose waiter died with its process: an offered call
+   * nobody claimed, or a claimed one whose device stopped renewing its lease.
+   */
+  let abandonedDesktopCallsSettled = 0
+  try {
+    abandonedDesktopCallsSettled = await settleAbandonedDesktopToolCalls()
+  } catch (error) {
+    logger.error('Failed to settle abandoned desktop tool calls:', {
+      error: toError(error).message,
+    })
+  }
+
   return {
     executions: {
       found: staleExecutionsFound,
@@ -774,6 +788,7 @@ export async function runCleanupStaleExecutions() {
     },
     chatRuns: {
       orphanedSettled: orphanedRunsSettled,
+      abandonedDesktopCallsSettled,
     },
   }
 }

apps/sim/lib/desktop/application/executor.ts

@@ -26,6 +26,7 @@ import { classifyDesktopInbox, type DesktopInboxEntry } from '@/lib/desktop/exec
 import { markDesktopPresent } from '@/lib/desktop/executor/presence'
 import {
   acknowledgeDesktopCallResult,
+  getBindableDesktopDevice,
   getBoundDesktopCall,
   getBoundDesktopDevice,
   listDesktopInboxRows,
@@ -68,6 +69,31 @@ async function requireBoundDevice(principal: SessionPrincipal, deviceId: string)
   return device
 }
 
+/**
+ * The device a new turn binds to: the composer's own, but only while the executor is on for this
+ * user and the device is registered to this very session as an executor. Anything else leaves
+ * the turn to the chat view, as before the executor existed.
+ */
+export async function resolveTurnDesktopDevice(
+  principal: SessionPrincipal,
+  deviceId: string
+): Promise<string | null> {
+  if (!(await isDesktopBackgroundExecutorEnabled(principal.userId))) return null
+  const device = await getBindableDesktopDevice({
+    deviceId,
+    userId: principal.userId,
+    sessionId: principal.sessionId,
+  })
+  if (!device) {
+    logger.warn('Turn not bound: its desktop is not registered to this session', {
+      userId: principal.userId,
+      deviceId,
+    })
+    return null
+  }
+  return device.id
+}
+
 interface RegisterDesktopDeviceInput extends DeviceInput {
   name: string
   appVersion: string