Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
fix(pty): stop re-probing a timed-out update-environment on every spawn
review1397adf620a5
diff --git a/CLAUDE.md b/CLAUDE.mdindex 6f5c81c5e..c890e8301 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -629,7 +629,10 @@ the repro, i.e. forever against a server that never recovers). The bound kills oclient (SIGKILL, so one that ignores SIGTERM cannot keep `execFileSync` waiting), never the server.A timeout is `console.warn`ed and fails open (tmux stays resolved; the spawn goes ahead); "no serveryet" stays silent, as it always was. A timeout also ends the rest of that call's tmux work — the-next `set-option` would only wait out the same wedge. Proven against a real client in+next `set-option` would only wait out the same wedge — and a `show-options` / `set-option` timeout+starts `TMUX_UPDATE_ENV_COOLDOWN_MS` (60 s) in which `ensureUpdateEnvKeys` makes no tmux call at+all: every spawn passes the account-scope names, so without it each later spawn on a slow server+would stall main again (20 terminals ≈ 40 s). After it, the next spawn probes again. Proven against a real client in`pty-tmux-wedged.realtmux.test.ts`. A new sync tmux call goes through `runTmuxSync`, not a bare`execFileSync`.diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 30b265bde..9ce07b533 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -973,6 +973,8 @@ real-tmux test (`account-env.realtmux.test.ts` is the pattern).`TMUX_BOOT_CMD_TIMEOUT_MS`), never a bare `execFileSync` on the tmux socket: one runs before thefirst window exists, and a wedged server held an unbounded call for as long as it stayed wedged(4.05 s in the audit repro, main-5). Warn on a timeout and fail open; keep "no server yet" silent.+A call that runs on every spawn also needs a cooldown after a timeout+(`TMUX_UPDATE_ENV_COOLDOWN_MS`), or each spawn waits out the same wedge again.**The same goes for the CWD: a tmux client never runs in the node's directory.** The server keepsthe cwd of the client that started it, and from tmux 3.7 a new pane's `-c` is silently dropped oncediff --git a/src/core/pty-manager.ts b/src/core/pty-manager.tsindex be5c66902..6085b8677 100644--- a/src/core/pty-manager.ts+++ b/src/core/pty-manager.ts@@ -313,6 +313,15 @@ const PROBE_TIMEOUT_MS = 6_000*/export const TMUX_BOOT_CMD_TIMEOUT_MS = 2_000+/**+ * After a `show-options` / `set-option` in `ensureUpdateEnvKeys` times out, how long it runs no+ * synchronous tmux call at all. Every spawn passes the account-scope names, so without it each+ * later spawn on a slow-but-alive server would block main for up to TMUX_BOOT_CMD_TIMEOUT_MS+ * again (a 20-terminal restore: about 40 s of stalls). Once it ends the next spawn probes again,+ * so a server that recovered is still learned.+ */+export const TMUX_UPDATE_ENV_COOLDOWN_MS = 60_000+/** Outcome of one bounded synchronous tmux call. `timeout` is a wedged server and is LOGGED;* `failed` is the ordinary "no server running yet" exit and stays silent, as it always was.* Callers fail open on both — neither is `ok: true` with empty output. */@@ -2090,6 +2099,8 @@ export class PtyManager {/** `update-environment` names already pushed to the running server this app-run (plus the* conf-baked set), so a custom agent's spawn costs at most one `set-option` per NEW key. */private updateEnvKeys: Set<string> | null = null+ /** Epoch ms until which `ensureUpdateEnvKeys` makes no tmux call (a recent timeout). */+ private updateEnvCooldownUntil = 0/** Make the shared tmux server copy these client-env names into new sessions. The conf bakes* the fixed gateway list; a CUSTOM agent's env keys are user-defined and can only be appended@@ -2104,12 +2115,16 @@ export class PtyManager {(n) => /^[A-Za-z_][A-Za-z0-9_]*$/.test(n) && n !== 'PATH' && n !== 'LANG')if (!wanted.length) return+ if (Date.now() < this.updateEnvCooldownUntil) returnif (!this.updateEnvKeys) {const shown = this.runTmuxSync(['show-options', '-g', 'update-environment'], true)// A wedged server: stop here. Every `set-option` below would wait out the same bound — one- // stall per new name on the spawn path (audit main-5) — and leaving the cache unset lets a- // later spawn probe a recovered server properly. The spawn itself goes ahead.- if (!shown.ok && shown.reason === 'timeout') return+ // stall per new name on the spawn path — and leaving the cache unset lets a spawn after the+ // cooldown probe a recovered server properly. The spawn itself goes ahead.+ if (!shown.ok && shown.reason === 'timeout') {+ this.updateEnvCooldownUntil = Date.now() + TMUX_UPDATE_ENV_COOLDOWN_MS+ return+ }this.updateEnvKeys = new Set(MODEL_GATEWAY_ENV_KEYS)// `failed` is "no server yet" — the conf list is what a fresh server will have.if (shown.ok) {@@ -2123,7 +2138,10 @@ export class PtyManager {const set = this.runTmuxSync(['set-option', '-ga', 'update-environment', name], false)if (set.ok) this.updateEnvKeys.add(name)// One timeout per call, not per name: the rest would only wait out the same wedge.- else if (set.reason === 'timeout') break+ else if (set.reason === 'timeout') {+ this.updateEnvCooldownUntil = Date.now() + TMUX_UPDATE_ENV_COOLDOWN_MS+ break+ }/* `failed`: no server yet — fresh-server sessions inherit the client env directly */}}diff --git a/src/core/pty-tmux-boot-timeout.test.ts b/src/core/pty-tmux-boot-timeout.test.tsindex ef1974e55..f5e36ff6d 100644--- a/src/core/pty-tmux-boot-timeout.test.ts+++ b/src/core/pty-tmux-boot-timeout.test.ts@@ -11,8 +11,9 @@ import { fakePlatform } from './platform-fake'* `execFileSync` with no timeout, so a tmux server that accepts the connection and never answers* held main for as long as it stayed wedged (4.05 s in the audit's repro — the listener's whole* lifetime). These pin the contract with an injected `execFileSync`: every call carries the bound,- * a timeout is WARNED and fails open, and the ordinary "no server yet" failure stays as silent as- * it always was. The real-tmux proof is `pty-tmux-wedged.realtmux.test.ts`.+ * a timeout is WARNED and fails open and starts a cooldown with no further spawn-path probe, and+ * the ordinary "no server yet" failure stays as silent as it always was. The real-tmux proof is+ * `pty-tmux-wedged.realtmux.test.ts`.*/type ExecCall = { args: string[]; opts: { timeout?: number; killSignal?: string } }@@ -108,8 +109,9 @@ describe('boot-path tmux calls under a wedged server', () => {expect(warn).not.toHaveBeenCalled()})- it('a show-options timeout skips every set-option and re-probes on the next spawn', async () => {- const { ensureUpdateEnvKeys } = await boot()+ it('a show-options timeout skips every set-option, then no spawn probes until the cooldown ends', async () => {+ vi.useFakeTimers({ toFake: ['Date'] })+ const { ensureUpdateEnvKeys, TMUX_UPDATE_ENV_COOLDOWN_MS } = await bootWithCooldown()execState.reply.set('show-options', TIMED_OUT)ensureUpdateEnvKeys(['KEY_A', 'KEY_B', 'KEY_C'])// One stall, not 1 + 3: the set-options would only wait out the same wedge.@@ -117,15 +119,28 @@ describe('boot-path tmux calls under a wedged server', () => {expect(callsFor('set-option')).toHaveLength(0)expect(warn).toHaveBeenCalledTimes(1)- // The server recovers: the cache was left unset, so the next spawn probes it properly.+ // Every spawn passes the account-scope names, so a re-probe per spawn would stall main up to+ // 2 s per terminal on a slow server. Inside the cooldown no sync tmux call runs at all.+ for (let i = 0; i < 20; i++) {+ vi.advanceTimersByTime(TMUX_UPDATE_ENV_COOLDOWN_MS / 25)+ ensureUpdateEnvKeys(['KEY_A', 'KEY_B'])+ }+ expect(callsFor('show-options')).toHaveLength(1)+ expect(callsFor('set-option')).toHaveLength(0)++ // The server recovers and the cooldown ends: the cache was left unset, so the next spawn+ // probes it properly.+ vi.advanceTimersByTime(TMUX_UPDATE_ENV_COOLDOWN_MS)execState.reply.set('show-options', 'update-environment[0] KEY_A\n')ensureUpdateEnvKeys(['KEY_A', 'KEY_B'])expect(callsFor('show-options')).toHaveLength(2)expect(callsFor('set-option').map((c) => c.args[5])).toEqual(['KEY_B'])+ vi.useRealTimers()})- it('a set-option timeout stops the loop after the first name', async () => {- const { ensureUpdateEnvKeys } = await boot()+ it('a set-option timeout stops the loop after the first name and starts the same cooldown', async () => {+ vi.useFakeTimers({ toFake: ['Date'] })+ const { ensureUpdateEnvKeys, TMUX_UPDATE_ENV_COOLDOWN_MS } = await bootWithCooldown()execState.reply.set('set-option', TIMED_OUT)ensureUpdateEnvKeys(['KEY_A', 'KEY_B', 'KEY_C'])expect(callsFor('set-option')).toHaveLength(1)@@ -134,5 +149,21 @@ describe('boot-path tmux calls under a wedged server', () => {expect(c.opts.killSignal).toBe('SIGKILL')}expect(warn).toHaveBeenCalledTimes(1)++ vi.advanceTimersByTime(TMUX_UPDATE_ENV_COOLDOWN_MS - 1)+ ensureUpdateEnvKeys(['KEY_A', 'KEY_B', 'KEY_C'])+ expect(callsFor('set-option')).toHaveLength(1)++ vi.advanceTimersByTime(1)+ execState.reply.delete('set-option')+ ensureUpdateEnvKeys(['KEY_A', 'KEY_B', 'KEY_C'])+ expect(callsFor('set-option').map((c) => c.args[5])).toEqual(['KEY_A', 'KEY_A', 'KEY_B', 'KEY_C'])+ vi.useRealTimers()})})++async function bootWithCooldown() {+ const booted = await boot()+ const { TMUX_UPDATE_ENV_COOLDOWN_MS } = await import('./pty-manager')+ return { ...booted, TMUX_UPDATE_ENV_COOLDOWN_MS }+}