fix(desktop): run an agent command on tmux that cannot tag its pane, untracked

Agent `run` inside tmux tagged its pane with a pane option (`set-option -p`,
tmux 3.0+) and refused the command when that failed, so on older tmux every
agent run failed, with the background executor off too.

A run whose pane cannot be tagged now goes ahead untracked: Stop, sign-out and
switching Terminal off leave it alone, since nothing could tell its pane from
one of the user's. Tagged runs are unchanged. The gate still holds every
command until the tagging call has finished.

Author: waleedlatif1

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

@@ -521,7 +521,8 @@ export class TerminalService {
     const pending = this.pendingRuns.get(terminalId)
     if (!pending) return
     for (const handle of pending) {
-      if (env && !isRunComplete(handle)) this.orphanedRuns.set(handle, env)
+      // An untracked run is never stopped, so there is nothing to keep it for.
+      if (env && handle.runId !== null && !isRunComplete(handle)) this.orphanedRuns.set(handle, env)
       this.releaseRun(handle)
     }
     this.pendingRuns.delete(terminalId)

apps/desktop/src/main/terminal/tmux.test.ts

@@ -107,6 +107,9 @@ interface FakeTmuxState {
   fail?: Record<string, string>
   /** Attached clients, as `list-clients` reports them. */
   clients?: Array<{ pid: string; tty: string; session: string }>
+
+  /** Commands the fake answers only after this many milliseconds, like a busy tmux server. */
+  delay?: Record<string, number>
 }
 
 const FAKE_TMUX = `
@@ -123,6 +126,10 @@ const escaped = (text) =>
   text
     .replace(/\\\\/g, '\\\\\\\\')
     .replace(/[\\x00-\\x1f]/g, (c) => '\\\\' + c.charCodeAt(0).toString(8).padStart(3, '0'))
+
+if (state.delay && state.delay[args[0]]) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, state.delay[args[0]])
+}
 if (state.fail && state.fail[args[0]]) fail(state.fail[args[0]])
 switch (args[0]) {
   case 'new-window': {
@@ -287,16 +294,22 @@ describe('stopping a tmux run touches only its own pane', () => {
     expect(tmux.read().log).toEqual([])
   })
 
-  it('never lets a run it could not tag start, and closes no pane by id to stop it', async () => {
+  it('starts a run it could not tag, untracked, and never stops it by a pane id', async () => {
     const tmux = fakeTmux()
     dirs.push(tmux.dir)
+    // tmux before 3.0 has no pane options.
     tmux.write({ ...tmux.read(), fail: { 'set-option': 'invalid option: @sim-run-id' } })
 
-    const result = await startRun('agent', 'sleep 600', null, tmux.env)
+    const run = await startRun('agent', 'sleep 600', null, tmux.env)
+    if ('error' in run) throw new Error(run.error)
 
-    expect(result).toMatchObject({ error: expect.stringContaining('was not run') })
-    // No pane is closed by an id that a restarted server might have handed to the user.
+    expect(run.runId).toBeNull()
+    expect(existsSync(join(run.statusPath, '..', 'go'))).toBe(true)
+    expect(await runPaneState(run, tmux.env)).toBe('unknown')
+    await stopRun(run, tmux.env, 0)
+    // No pane is touched by an id that a restarted server might have handed to the user.
     expect(tmux.read().log).toEqual([])
+    expect(Object.keys(tmux.read().panes)).toEqual([run.pane])
   })
 
   it('lets a tagged run start only once its pane is tagged', async () => {
@@ -318,7 +331,7 @@ describe('stopping a tmux run touches only its own pane', () => {
     expect(tmux.read().log).toEqual([])
   })
 
-  it('runs a tagged command for real, and never runs one it could not tag', async () => {
+  it('runs a command for real whether or not tmux could tag its pane', async () => {
     const tagged = fakeTmux({ exec: true })
     dirs.push(tagged.dir)
     const run = await startRun('agent', 'echo ran', null, tagged.env)
@@ -333,10 +346,27 @@ describe('stopping a tmux run touches only its own pane', () => {
     const untagged = fakeTmux({ exec: true })
     dirs.push(untagged.dir)
     untagged.write({ ...untagged.read(), fail: { 'set-option': 'invalid option' } })
-    const marker = join(untagged.dir, 'ran')
-    await startRun('agent', `touch ${JSON.stringify(marker)}`, null, untagged.env)
-    await sleep(6_000)
+    const untracked = await startRun('agent', 'echo ran', null, untagged.env)
+    if ('error' in untracked) throw new Error(untracked.error)
+    await expect
+      .poll(() => pollRun(untracked), { timeout: 10_000 })
+      .toMatchObject({ done: true, exitCode: 0, output: 'ran\n' })
+  }, 20_000)
 
+  it('holds a command until tmux has finished tagging its pane', async () => {
+    const tmux = fakeTmux({ exec: true })
+    dirs.push(tmux.dir)
+    tmux.write({ ...tmux.read(), delay: { 'set-option': 2_000 } })
+    const marker = join(tmux.dir, 'ran')
+
+    const starting = startRun('agent', `touch ${JSON.stringify(marker)}`, null, tmux.env)
+    await sleep(1_200)
+    // The pane exists and its script is running, but the tag is not on it yet.
+    expect(Object.keys(tmux.read().panes)).toHaveLength(1)
     expect(existsSync(marker)).toBe(false)
+
+    const run = await starting
+    if ('error' in run) throw new Error(run.error)
+    await expect.poll(() => existsSync(marker), { timeout: 10_000 }).toBe(true)
   }, 20_000)
 })

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

@@ -311,9 +311,11 @@ export interface TmuxRunHandle {
   pane: string
   /**
    * Tagged on the pane as the `@sim-run-id` user option. Window and pane ids restart from zero
-   * with the tmux server, so only the tag proves a pane is still this run's.
+   * with the tmux server, so only the tag proves a pane is still this run's. Null when tmux could
+   * not tag the pane (tmux before 3.0 has no pane options): the run goes ahead untracked, and
+   * nothing ever stops it, since nothing could tell its pane from one of the user's.
    */
-  runId: string
+  runId: string | null
   outPath: string
   statusPath: string
   dispose(): void
@@ -368,10 +370,10 @@ export async function startRun(
   // into the pipeline and print `No such file or directory` into the user's own
   // tmux window, minutes after they closed the tab.
   //
-  // The command waits for its pane to be tagged as this run's (the go file), so nothing runs that
-  // a later stop could not recognize. Untagged, the script gives up once the tagging call has
-  // surely failed, and its pane closes on its own; no one has to close a pane whose id might no
-  // longer be its own.
+  // The command waits for the tagging call to finish (the go file), so a tagged run's command
+  // never runs before a later stop could recognize its pane. If Sim never releases it (it quit
+  // mid-start), the script gives up once the tagging call has surely ended and its pane closes on
+  // its own; no one has to close a pane whose id might no longer be its own.
   //
   // The script is a file rather than a `bash -c` string: tmux hands its command to `sh -c`, which
   // would expand `$` references meant for bash (the gate's counter, PIPESTATUS) before bash ran.
@@ -410,18 +412,16 @@ export async function startRun(
     return { error: created.stderr.trim() || 'tmux could not open a window for the command.' }
   }
   const [window = '', pane = ''] = created.stdout.trim().split(' ')
-  const runId = generateId()
+  const tag = generateId()
   // An untagged pane is never treated as the run's: without the tag a stop could not tell it from
-  // a pane the user opened later under the same id, so it sends nothing at all.
-  const tagged = await runTmux(['set-option', '-p', '-t', pane, RUN_ID_OPTION, runId], env)
+  // a pane the user opened later under the same id, so the run is left untracked.
+  const tagged = await runTmux(['set-option', '-p', '-t', pane, RUN_ID_OPTION, tag], env)
   if (!tagged.ok) {
-    // Untagged, nothing could stop it safely later, so it never starts: without the go file the
-    // wrapper exits by itself.
-    dispose()
-    return {
-      error: `tmux could not mark the command's pane (${tagged.stderr.trim() || 'no detail'}), so the command was not run.`,
-    }
+    logger.warn('tmux could not tag a run pane; the run goes ahead untracked', {
+      error: tagged.stderr.trim(),
+    })
   }
+  const runId = tagged.ok ? tag : null
   try {
     writeFileSync(goPath, '')
   } catch (error) {
@@ -435,14 +435,15 @@ export async function startRun(
 /**
  * Whether the run's pane is still the run's: `ours`, or `gone` when tmux has no such pane or the
  * pane under that id is not tagged as this run's (the user closed it, or a restarted tmux server
- * handed the id to one of the user's own panes). `unknown` when tmux could not be asked: such a
- * pane is neither touched nor given up on.
+ * handed the id to one of the user's own panes). `unknown` when tmux could not be asked, or the
+ * run is untracked: such a pane is neither touched nor given up on.
  */
 export async function runPaneState(
   handle: TmuxRunHandle,
   env: NodeJS.ProcessEnv
 ): Promise<'ours' | 'gone' | 'unknown'> {
   if (!handle.pane) return 'gone'
+  if (handle.runId === null) return 'unknown'
   const shown = await runTmux(
     ['display-message', '-p', '-t', handle.pane, `#{${RUN_ID_OPTION}}`],
     env

packages/terminal-protocol/src/index.ts

@@ -177,8 +177,8 @@ export interface TerminalToolArgs {
    */
   terminalId?: string
   /**
-   * Which tmux pane to act on, as a tmux target (`session:window.pane`), for
-   * a terminal that has tmux attached. Omitting it uses that session's active
+   * Which tmux pane to act on, as a tmux target (`session:window.pane`, or a
+   * run's pane id `%N`), for a terminal that has tmux attached. Omitting it uses that session's active
    * pane. Ignored when the terminal is a plain shell.
    */
   pane?: string
@@ -214,7 +214,10 @@ export interface TerminalRunResult {
   durationMs: number
   cwd: string | null
   terminalId: string
-  /** Set when the command ran in tmux: the target it ran under. */
+  /**
+   * Set when the command ran in tmux: its own pane's id (`%N`), a tmux target that `read`,
+   * `input`, `kill` and `close` accept as `pane`.
+   */
   pane?: string
   /** True when output was elided to fit {@link MAX_TOOL_OUTPUT_CHARS}. */
   truncated: boolean