fix(desktop): stop the agent's tmux runs a previous process left going

A tmux run outlives the app, but only the process that started it knew about
it: after a crash, a quit, or a crash mid-sign-out, the next launch had nothing
to stop, and a chat put away took its runs out of reach of sign-out too.

- Each tagged run is recorded in userData (outside account data): its tag, its
  pane and its tmux server's socket, nothing else. The record goes once the run
  has ended, its pane is gone, or Sim has stopped it.
- Sign-out, switching Terminal off and the launch-time account recovery stop
  every recorded run; every launch stops the runs a previous process left
  going. A pane is only acted on, on the run's own server, while it still
  carries the run's tag.
- Restart semantics follow the executor's journal: a call claimed before the
  crash is settled as outcome unknown and nothing reattaches to its command, so
  a run still going belongs to a call no one can collect; a run that finished
  is only cleaned up.

Author: waleedlatif1

apps/desktop/src/main/index.ts

@@ -101,6 +101,7 @@ import {
 import { setShellTheme } from '@/main/shell-theme'
 import { attachTelemetryPolicy } from '@/main/telemetry-policy'
 import { TerminalRegistry } from '@/main/terminal/registry'
+import { createRunLedger } from '@/main/terminal/run-ledger'
 import { installTray, type TrayHandle } from '@/main/tray'
 import { checkForUpdatesInteractive, initUpdater, type UpdaterHandle } from '@/main/updater'
 import { installBrowserUserAgent } from '@/main/user-agent'
@@ -167,15 +168,20 @@ function main(): void {
     ),
   })
   const scopeEvents = new ScopedEventRouter()
-  const terminal = new TerminalRegistry({
-    load: (scopeId) => desktopChatSessions.getTerminal(processOrigin, scopeId) ?? undefined,
-    save: (scopeId, snapshot) => desktopChatSessions.setTerminal(processOrigin, scopeId, snapshot),
-    migrate: (fromScopeId, toScopeId) =>
-      desktopChatSessions.migrateTerminal(processOrigin, fromScopeId, toScopeId),
-    disposeScope: (scopeId) => {
-      desktopChatSessions.deleteScope(processOrigin, scopeId)
+  const terminal = new TerminalRegistry(
+    {
+      load: (scopeId) => desktopChatSessions.getTerminal(processOrigin, scopeId) ?? undefined,
+      save: (scopeId, snapshot) =>
+        desktopChatSessions.setTerminal(processOrigin, scopeId, snapshot),
+      migrate: (fromScopeId, toScopeId) =>
+        desktopChatSessions.migrateTerminal(processOrigin, fromScopeId, toScopeId),
+      disposeScope: (scopeId) => {
+        desktopChatSessions.deleteScope(processOrigin, scopeId)
+      },
     },
-  })
+    undefined,
+    createRunLedger(join(userDataPath, 'terminal-runs'))
+  )
   const preloadPath = join(__dirname, 'preload.cjs')
 
   const windows = new Set<BrowserWindow>()
@@ -804,6 +810,11 @@ function main(): void {
       }
     }
 
+    // A tmux run the previous process left going belongs to a call it can no longer report (its
+    // journal settles it as outcome unknown) or to a chat view that is gone: nothing will collect
+    // what it does, so it is stopped, while its pane still carries its tag.
+    void terminal.stopRecordedRuns({ excludeLive: true })
+
     if (!accountDataAvailable()) {
       logger.warn(
         'Account-bearing browser, terminal, and local filesystem APIs are unavailable until local recovery succeeds'

apps/desktop/src/main/terminal/index.ts

@@ -38,6 +38,7 @@ import {
   resourceTabTargetIndex,
 } from '@/main/resource-shortcuts'
 import { readForegroundProcessGroup, signalProcessGroup } from '@/main/terminal/process-group'
+import type { RunLedger } from '@/main/terminal/run-ledger'
 import { elide, TerminalSession } from '@/main/terminal/session'
 import {
   activePane,
@@ -156,6 +157,8 @@ export interface TerminalServiceOptions {
   canSpawn?(): boolean
   /** Reads and signals a terminal's foreground process group; the OS's by default. */
   processGroups?: TerminalProcessGroups
+  /** Where tagged tmux runs are recorded, so a later process can still stop them. */
+  runLedger?: RunLedger
 }
 
 interface TerminalProcessGroups {
@@ -490,7 +493,10 @@ export class TerminalService {
   private async reapFinishedRuns(terminalId: string, env: NodeJS.ProcessEnv): Promise<void> {
     // A closed tab's run whose pane has since gone (its command ended) needs no stopping.
     for (const [handle, orphanEnv] of this.orphanedRuns) {
-      if ((await runPaneState(handle, orphanEnv)) === 'gone') this.orphanedRuns.delete(handle)
+      if ((await runPaneState(handle, orphanEnv)) === 'gone') {
+        this.orphanedRuns.delete(handle)
+        this.forgetRun(handle)
+      }
     }
     for (const handle of this.pendingRuns.get(terminalId) ?? []) {
       if (this.awaitedRuns.has(handle)) continue
@@ -499,11 +505,17 @@ export class TerminalService {
         // A pane kept open after its command ended (`remain-on-exit`) closes with its run.
         if (complete) await closeRunPane(handle, env)
         this.untrackRun(terminalId, handle)
+        this.forgetRun(handle)
         handle.dispose()
       }
     }
   }
 
+  /** Drops a run's record once nothing of it is left for any process to stop. */
+  private forgetRun(handle: TmuxRunHandle): void {
+    if (handle.runId) this.options.runLedger?.forget(handle.runId)
+  }
+
   /** Removes a run's files now, or once the call still reading them is done with them. */
   private releaseRun(handle: TmuxRunHandle): void {
     if (this.awaitedRuns.has(handle)) this.releasedAwaitedRuns.add(handle)
@@ -1282,6 +1294,13 @@ export class TerminalService {
     await this.reapFinishedRuns(terminal.terminalId, terminal.env)
     const handle = await startRun(session, command, terminal.currentCwd, terminal.env)
     if ('error' in handle) throw new TerminalError('SPAWN_FAILED', handle.error)
+    if (handle.runId && handle.socket) {
+      this.options.runLedger?.record({
+        runId: handle.runId,
+        pane: handle.pane,
+        socket: handle.socket,
+      })
+    }
     // Tracked from the moment its window exists, so sign-out can stop it even mid-wait.
     const pending = this.pendingRuns.get(terminal.terminalId)
     if (pending) pending.push(handle)
@@ -1316,6 +1335,7 @@ export class TerminalService {
     if (outcome.done) {
       await closeRunPane(handle, terminal.env)
       this.untrackRun(terminal.terminalId, handle)
+      this.forgetRun(handle)
       handle.dispose()
     }
     // Still going, it stays tracked, and nothing polls the status file again: `read` captures

apps/desktop/src/main/terminal/registry-run-ledger.test.ts

@@ -0,0 +1,66 @@
+import { mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+vi.mock('electron', () => import('@/test/electron-mock'))
+
+/** How each recorded run's pane answers when stopped: still tracked by tmux or not. */
+const { panes } = vi.hoisted(() => ({
+  panes: new Map<string, 'gone' | 'unknown'>(),
+}))
+
+vi.mock('@/main/terminal/tmux', async () => {
+  const actual =
+    await vi.importActual<typeof import('@/main/terminal/tmux')>('@/main/terminal/tmux')
+  return {
+    ...actual,
+    stopRecordedRun: async (run: { runId: string }) => panes.get(run.runId) ?? 'gone',
+  }
+})
+
+import { TerminalRegistry } from '@/main/terminal/registry'
+import { createRunLedger } from '@/main/terminal/run-ledger'
+
+const dirs: string[] = []
+
+function ledgerDir(): string {
+  const dir = mkdtempSync(join(tmpdir(), 'sim-registry-ledger-'))
+  dirs.push(dir)
+  return join(dir, 'terminal-runs')
+}
+
+function run(runId: string, pane: string) {
+  return { runId, pane, socket: '/tmp/tmux-501/default' }
+}
+
+afterEach(() => {
+  panes.clear()
+  for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true })
+})
+
+describe('stopping recorded tmux runs', () => {
+  it('forgets each run once nothing of it is left, and keeps one tmux could not answer for', async () => {
+    const dir = ledgerDir()
+    const previous = createRunLedger(dir)
+    previous.record(run('stopped', '%1'))
+    previous.record(run('unanswered', '%2'))
+    panes.set('unanswered', 'unknown')
+    const ledger = createRunLedger(dir)
+
+    await new TerminalRegistry(undefined, undefined, ledger).stopAgentCommands()
+
+    expect(ledger.list().map((record) => record.runId)).toEqual(['unanswered'])
+  })
+
+  it("at launch, stops the previous process's runs and none this one has started", async () => {
+    const dir = ledgerDir()
+    createRunLedger(dir).record(run('previous', '%1'))
+    const ledger = createRunLedger(dir)
+    ledger.record(run('current', '%2'))
+
+    await new TerminalRegistry(undefined, undefined, ledger).stopRecordedRuns({ excludeLive: true })
+
+    expect(ledger.list().map((record) => record.runId)).toEqual(['current'])
+  })
+})

apps/desktop/src/main/terminal/registry.ts

@@ -19,6 +19,11 @@ import {
   type TerminalServiceOptions,
   type TerminalSink,
 } from '@/main/terminal'
+import type { RunLedger } from '@/main/terminal/run-ledger'
+import { stopRecordedRun } from '@/main/terminal/tmux'
+
+/** How long a recorded run gets to end on Ctrl-C before its pane is closed. */
+const RECORDED_RUN_GRACE_MS = 2_000
 
 /** Native PTYs and their headless xterm buffers are process-wide resources. */
 export const MAX_TERMINALS_PER_PROCESS = 48
@@ -106,7 +111,8 @@ export class TerminalRegistry {
 
   constructor(
     private readonly persistence?: TerminalScopePersistence,
-    private readonly serviceFactory: TerminalServiceFactory = createTerminalService
+    private readonly serviceFactory: TerminalServiceFactory = createTerminalService,
+    private readonly runLedger?: RunLedger
   ) {}
 
   setSink(sink: ScopedTerminalSink | null): void {
@@ -369,11 +375,33 @@ export class TerminalRegistry {
     return true
   }
 
-  /** Stops every command the agent started in any chat's terminals; the user's own are untouched. */
+  /**
+   * Stops every command the agent started in any chat's terminals; the user's own are untouched.
+   * That includes tmux runs no live terminal holds any more: a chat put away, or a previous
+   * process that quit or crashed while they ran.
+   */
   async stopAgentCommands(): Promise<void> {
     await Promise.allSettled(
       [...this.entries.values()].map((entry) => entry.service.stopAgentCommands())
     )
+    await this.stopRecordedRuns()
+  }
+
+  /**
+   * Stops the recorded tmux runs, each only while its pane still carries its tag, and drops the
+   * records with nothing left to stop. At launch it skips the runs this process has started since:
+   * every other run belongs to a call the previous process can no longer report, which its
+   * journal settles as outcome unknown, so nothing is left to collect what it does.
+   */
+  async stopRecordedRuns(options: { excludeLive?: boolean } = {}): Promise<void> {
+    const ledger = this.runLedger
+    if (!ledger) return
+    await Promise.allSettled(
+      ledger.list(options).map(async (run) => {
+        const state = await stopRecordedRun(run, process.env, RECORDED_RUN_GRACE_MS)
+        if (state === 'gone') ledger.forget(run.runId)
+      })
+    )
   }
 
   /** Tears down every shell owned by every chat scope. */
@@ -405,6 +433,7 @@ export class TerminalRegistry {
       service: this.serviceFactory(scope, {
         loadCwd: () => this.entries.get(scope)?.persisted?.tabs[0]?.cwd,
         canSpawn: () => this.liveTerminalCount() < MAX_TERMINALS_PER_PROCESS,
+        runLedger: this.runLedger,
       }),
       persisted,
       restoreApplied: false,

apps/desktop/src/main/terminal/run-ledger.test.ts

@@ -0,0 +1,63 @@
+import { mkdtempSync, readdirSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import { createRunLedger } from '@/main/terminal/run-ledger'
+
+const dirs: string[] = []
+
+function scratch(): string {
+  const dir = mkdtempSync(join(tmpdir(), 'sim-run-ledger-'))
+  dirs.push(dir)
+  return join(dir, 'terminal-runs')
+}
+
+const RUN = { runId: 'run-1', pane: '%3', socket: '/tmp/tmux-501/default' }
+
+afterEach(() => {
+  for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true })
+})
+
+describe('the tmux run ledger', () => {
+  it('keeps a run recorded until it is forgotten, for the next process too', () => {
+    const dir = scratch()
+    createRunLedger(dir).record(RUN)
+
+    const nextProcess = createRunLedger(dir)
+    expect(nextProcess.list()).toEqual([RUN])
+
+    nextProcess.forget(RUN.runId)
+    expect(createRunLedger(dir).list()).toEqual([])
+  })
+
+  it("leaves out this process's own runs when asked", () => {
+    const dir = scratch()
+    createRunLedger(dir).record(RUN)
+    const ledger = createRunLedger(dir)
+    ledger.record({ ...RUN, runId: 'run-2', pane: '%4' })
+
+    expect(ledger.list({ excludeLive: true })).toEqual([RUN])
+    expect(ledger.list()).toHaveLength(2)
+  })
+
+  it('drops files nothing could act on safely', () => {
+    const dir = scratch()
+    const ledger = createRunLedger(dir)
+    ledger.record(RUN)
+    writeFileSync(join(dir, 'garbled.json'), '{not json')
+    writeFileSync(join(dir, 'run-9.json'), JSON.stringify({ ...RUN, socket: 'relative.sock' }))
+    // A record under another run's name could stop the wrong run.
+    writeFileSync(join(dir, 'run-8.json'), JSON.stringify({ ...RUN, runId: 'run-7' }))
+
+    expect(ledger.list()).toEqual([RUN])
+    expect(readdirSync(dir)).toEqual(['run-1.json'])
+  })
+
+  it('records nothing for a run tag that is not a plain id', () => {
+    const dir = scratch()
+    const ledger = createRunLedger(dir)
+    ledger.record({ ...RUN, runId: '../escape' })
+
+    expect(ledger.list()).toEqual([])
+  })
+})