Skip to content

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.

fix(pty): stop re-probing a timed-out update-environment on every spawn

review1397adf620a5
diff --git a/CLAUDE.md b/CLAUDE.md
index 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 o
client (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 server
yet" 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.md
index 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 the
first 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 keeps
the cwd of the client that started it, and from tmux 3.7 a new pane's `-c` is silently dropped once
diff --git a/src/core/pty-manager.ts b/src/core/pty-manager.ts
index 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) return
if (!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.ts
index 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 }
+}