fix(mothership): hold a turn's Stop only while its desktop tools run

Replace the bounded LRU of turn controllers with leases: each running
browser action or local file tool holds its turn's Stop until it settles,
so a live turn can never be evicted and settled turns leave nothing behind.

Author: waleedlatif1

apps/sim/app/workspace/[workspaceId]/home/hooks/desktop-tool-lifetimes.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it } from 'vitest'
+import { leaseDesktopTool, stopDesktopTools } from './desktop-tool-lifetimes'
+
+describe('desktop tool leases', () => {
+  it('cancels every running tool of the stopped turn and no other turn', () => {
+    const first = leaseDesktopTool('turn-a')
+    const second = leaseDesktopTool('turn-a')
+    const other = leaseDesktopTool('turn-b')
+
+    stopDesktopTools('turn-a', 'user_stop')
+
+    expect(first.signal.aborted).toBe(true)
+    expect(second.signal.aborted).toBe(true)
+    expect(first.signal.reason).toBe('user_stop')
+    expect(other.signal.aborted).toBe(false)
+    other.release()
+  })
+
+  it('keeps a turn reachable by Stop while any of its tools still runs', () => {
+    const settled = leaseDesktopTool('turn-c')
+    const running = leaseDesktopTool('turn-c')
+    for (let turn = 0; turn < 500; turn++) leaseDesktopTool(`busy-${turn}`).release()
+
+    settled.release()
+    settled.release()
+    stopDesktopTools('turn-c', 'user_stop')
+
+    expect(running.signal.aborted).toBe(true)
+  })
+
+  it('gives a turn whose tools all settled a fresh lifetime for its next tool', () => {
+    const settled = leaseDesktopTool('turn-d')
+    settled.release()
+    stopDesktopTools('turn-d', 'user_stop')
+
+    const next = leaseDesktopTool('turn-d')
+
+    expect(settled.signal.aborted).toBe(false)
+    expect(next.signal).not.toBe(settled.signal)
+    expect(next.signal.aborted).toBe(false)
+    next.release()
+  })
+
+  it('does not let a tool that settles after Stop release a newer lease on the turn', () => {
+    const stopped = leaseDesktopTool('turn-e')
+    stopDesktopTools('turn-e', 'user_stop')
+    const next = leaseDesktopTool('turn-e')
+
+    stopped.release()
+    stopDesktopTools('turn-e', 'user_stop')
+
+    expect(next.signal.aborted).toBe(true)
+  })
+})

apps/sim/app/workspace/[workspaceId]/home/hooks/desktop-tool-lifetimes.ts

@@ -1,28 +1,51 @@
-import { LRUCache } from 'lru-cache'
+/** The desktop tools of one turn that are still running in this tab, and the Stop that ends them. */
+interface RunningTurnTools {
+  stop: AbortController
+  running: number
+}
 
 /**
- * Turns whose desktop tools may still be running in this tab. A tool outlives the chat view that
- * started it (and any stream reader), so the turn, not the view, owns its Stop. Bounded: a tool
- * runs for minutes, far fewer turns than this.
+ * Turns with a desktop tool still running in this tab, keyed by the turn's stream id. A tool
+ * outlives the chat view that started it (and any stream reader), so the turn, not the view, owns
+ * its Stop. A turn is held only while one of its tools runs: each tool releases it as it settles.
  */
-const turnStops = new LRUCache<string, AbortController>({ max: 64 })
+const runningTurns = new Map<string, RunningTurnTools>()
+
+/** A running desktop tool's hold on its turn. */
+interface DesktopToolLease {
+  /** Aborted only by the user's Stop of the turn. */
+  signal: AbortSignal
+  /** Called once when the tool settles. */
+  release(): void
+}
 
 /**
- * The lifetime of a desktop tool (a browser action, a local file read or import) started for a
- * turn: only the user's Stop of that turn ends it. Replacing the stream reader, leaving the chat
- * view, or stopping another chat's turn leaves it running to finish and report its own result.
+ * Starts a desktop tool (a browser action, a local file read or import) for a turn. Only the
+ * user's Stop of that turn cancels it: replacing the stream reader, leaving the chat view, or
+ * stopping another chat's turn leaves it running to finish and report its own result.
  */
-export function desktopToolLifetime(streamId: string): AbortSignal {
-  let stop = turnStops.get(streamId)
-  if (!stop) {
-    stop = new AbortController()
-    turnStops.set(streamId, stop)
+export function leaseDesktopTool(streamId: string): DesktopToolLease {
+  let turn = runningTurns.get(streamId)
+  if (!turn) {
+    turn = { stop: new AbortController(), running: 0 }
+    runningTurns.set(streamId, turn)
+  }
+  turn.running += 1
+  const held = turn
+  let released = false
+  return {
+    signal: held.stop.signal,
+    release() {
+      if (released) return
+      released = true
+      held.running -= 1
+      if (held.running === 0 && runningTurns.get(streamId) === held) runningTurns.delete(streamId)
+    },
   }
-  return stop.signal
 }
 
-/** Cancels the desktop tools of a turn the user stopped, from whichever view started them. */
+/** Cancels the running desktop tools of a turn the user stopped, from whichever view started them. */
 export function stopDesktopTools(streamId: string, reason: string): void {
-  turnStops.get(streamId)?.abort(reason)
-  turnStops.delete(streamId)
+  runningTurns.get(streamId)?.stop.abort(reason)
+  runningTurns.delete(streamId)
 }

apps/sim/app/workspace/[workspaceId]/home/hooks/use-chat.dom.test.tsx

@@ -2217,6 +2217,9 @@ describe('useChat remount send recovery', () => {
 
     beforeEach(() => {
       libDesktopMockFns.mockIsDesktopApp.mockReturnValue(true)
+      const stillRunning = () => new Promise<void>(() => {})
+      mockExecuteBrowserToolOnClient.mockImplementation(stillRunning)
+      mockExecuteLocalFilesystemTool.mockImplementation(stillRunning)
     })
 
     afterEach(() => {

apps/sim/app/workspace/[workspaceId]/home/hooks/use-chat.ts

@@ -92,7 +92,7 @@ import { initTerminalTransport } from '@/lib/terminal/transport'
 import { getQueryClient } from '@/app/_shell/providers/get-query-client'
 import { chatUrl } from '@/app/workspace/[workspaceId]/home/hooks/chat-url'
 import {
-  desktopToolLifetime,
+  leaseDesktopTool,
   stopDesktopTools,
 } from '@/app/workspace/[workspaceId]/home/hooks/desktop-tool-lifetimes'
 import { useFilePreviewController } from '@/app/workspace/[workspaceId]/home/hooks/preview'
@@ -472,10 +472,18 @@ function startClientBrowserTool(
   toolArgs: Record<string, unknown>,
   scopeId: string,
   eventTs?: string,
-  signal?: AbortSignal
+  turnStreamId?: string
 ): void {
   if (!isCurrentBrowserToolName(toolName)) return
-  executeBrowserToolOnClient(toolCallId, toolName, toolArgs, scopeId, eventTs, signal)
+  const lease = turnStreamId ? leaseDesktopTool(turnStreamId) : undefined
+  void executeBrowserToolOnClient(
+    toolCallId,
+    toolName,
+    toolArgs,
+    scopeId,
+    eventTs,
+    lease?.signal
+  ).finally(() => lease?.release())
 }
 
 /**
@@ -1580,10 +1588,11 @@ export function useChat(
         return
       }
       handledClientLocalFilesystemToolIds.add(toolCallId)
+      const lease = streamIdRef.current ? leaseDesktopTool(streamIdRef.current) : undefined
       const options = {
         workspaceId,
         chatId: chatIdRef.current ?? selectedChatIdRef.current,
-        signal: streamIdRef.current ? desktopToolLifetime(streamIdRef.current) : undefined,
+        signal: lease?.signal,
       }
       /**
        * Dynamic on purpose: the local-filesystem executor only runs for desktop-local
@@ -1594,35 +1603,40 @@ export function useChat(
        * report an error completion rather than leaving it hanging with the dedupe ref
        * already marked handled.
        */
-      import('@/lib/mothership/tools/client/local-filesystem').then(
-        (m) => m.executeLocalFilesystemTool(toolCallId, toolName, toolArgs, options),
-        async (error) => {
-          logger.error('Failed to load local filesystem tool executor', { error })
-          /**
-           * The recovery itself can reject (the helper chunks or the completion POST can
-           * fail for the same reason the executor chunk did). Contain it: an unhandled
-           * rejection here would settle nothing and surface as a console error, exactly
-           * like the executor's own report-failure path, which also degrades to a log.
-           */
-          try {
-            const [{ reportClientToolCompletion }, { ASYNC_TOOL_CONFIRMATION_STATUS }] =
-              await Promise.all([
-                import('@/lib/mothership/tools/client/completion'),
-                import('@/lib/mothership/async-runs/lifecycle'),
-              ])
-            await reportClientToolCompletion(
-              toolCallId,
-              ASYNC_TOOL_CONFIRMATION_STATUS.error,
-              'Local filesystem tool failed to load'
-            )
-          } catch (reportError) {
-            logger.error('Failed to report local filesystem tool load failure', {
-              toolCallId,
-              error: reportError,
-            })
+      import('@/lib/mothership/tools/client/local-filesystem')
+        .then(
+          (m) => m.executeLocalFilesystemTool(toolCallId, toolName, toolArgs, options),
+          async (error) => {
+            logger.error('Failed to load local filesystem tool executor', { error })
+            /**
+             * The recovery itself can reject (the helper chunks or the completion POST can
+             * fail for the same reason the executor chunk did). Contain it: an unhandled
+             * rejection here would settle nothing and surface as a console error, exactly
+             * like the executor's own report-failure path, which also degrades to a log.
+             */
+            try {
+              const [{ reportClientToolCompletion }, { ASYNC_TOOL_CONFIRMATION_STATUS }] =
+                await Promise.all([
+                  import('@/lib/mothership/tools/client/completion'),
+                  import('@/lib/mothership/async-runs/lifecycle'),
+                ])
+              await reportClientToolCompletion(
+                toolCallId,
+                ASYNC_TOOL_CONFIRMATION_STATUS.error,
+                'Local filesystem tool failed to load'
+              )
+            } catch (reportError) {
+              logger.error('Failed to report local filesystem tool load failure', {
+                toolCallId,
+                error: reportError,
+              })
+            }
           }
-        }
-      )
+        )
+        .catch((error) => {
+          logger.error('Local filesystem tool execution failed unexpectedly', { toolCallId, error })
+        })
+        .finally(() => lease?.release())
     },
     [workspaceId, organizationId, scopeKey]
   )
@@ -2159,9 +2173,7 @@ export function useChat(
         shouldContinue?: () => boolean
       }
     ) => {
-      const browserToolSignal = streamIdRef.current
-        ? desktopToolLifetime(streamIdRef.current)
-        : undefined
+      const turnStreamId = streamIdRef.current
       const activityTracker = getResourceActivityTracker(
         expectedGen ?? streamGenRef.current,
         options?.targetChatId
@@ -2182,7 +2194,7 @@ export function useChat(
         eventTs?: string
       ) => {
         const scopeId = activityScopeId()
-        startClientBrowserTool(toolCallId, toolName, toolArgs, scopeId, eventTs, browserToolSignal)
+        startClientBrowserTool(toolCallId, toolName, toolArgs, scopeId, eventTs, turnStreamId)
       }
       const startClientTerminalToolForStream = (
         toolCallId: string,

apps/sim/lib/mothership/tools/client/browser-tool-execution.ts

@@ -551,20 +551,21 @@ function timeoutForTool(toolName: BrowserToolName, params: Record<string, unknow
 }
 
 /**
- * Fire-and-forget entry point invoked by the stream tool-event handler when a
- * `browser_*` client tool call arrives.
+ * Entry point invoked by the stream tool-event handler when a `browser_*`
+ * client tool call arrives. It reports its own outcome; the returned promise
+ * only tells the caller when the action has settled.
  *
  * @param eventTs - the stream envelope's emission timestamp; stale events
  * (replays after reconnect/reload) are dropped rather than re-executed.
  */
-export function executeBrowserToolOnClient(
+export async function executeBrowserToolOnClient(
   toolCallId: string,
   toolName: BrowserToolName,
   params: Record<string, unknown>,
   scopeId = useBrowserSessionStore.getState().activeScopeId,
   eventTs?: string,
   abortSignal?: AbortSignal
-): void {
+): Promise<void> {
   if (retryRetainedTerminalCompletion(toolCallId)) {
     logger.info('Suppressing browser tool while recovering its terminal completion', {
       toolCallId,
@@ -703,7 +704,7 @@ export function executeBrowserToolOnClient(
     }
   }
   runningBrowserToolCalls.add(toolCallId)
-  void doExecuteBrowserTool(
+  await doExecuteBrowserTool(
     toolCallId,
     toolName,
     params,

apps/sim/lib/mothership/tools/client/local-filesystem.ts

@@ -337,17 +337,17 @@ async function execute(
   return executeUserLocalRead(toolCallId, args, context.signal)
 }
 
-export function executeLocalFilesystemTool(
+export async function executeLocalFilesystemTool(
   toolCallId: string,
   toolName: string,
   args: Record<string, unknown>,
   context: LocalFilesystemExecutionContext
-): void {
+): Promise<void> {
   if (isNativeFileTool(toolName)) {
-    void executeNativeFileTool(toolCallId, toolName, context.signal)
+    await executeNativeFileTool(toolCallId, toolName, context.signal)
     return
   }
-  void execute(toolCallId, toolName, args, context).then(
+  await execute(toolCallId, toolName, args, context).then(
     async (data) => {
       if (context.signal?.aborted) return
       try {