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.

perf(ssh): on-screen terminals attach first on a project switch

enesd32d93ba4aa2
diff --git a/src/core/pty-manager.ts b/src/core/pty-manager.ts
index b86a67759..8e8876451 100644
--- a/src/core/pty-manager.ts
+++ b/src/core/pty-manager.ts
@@ -987,6 +987,9 @@ export class PtyManager {
* exactly as it did before it existed.
*/
private readProjectSpawnOverrides: ProjectSpawnOverridesReader | null = null
+ /** In-flight project-settings reads, per project, joined by concurrent spawns. See
+ * `projectSpawnOverrides`. Entries are removed when the read settles — this is not a cache. */
+ private overridesInFlight = new Map<string, Promise<ProjectSpawnOverrides | null>>()
/** "Which SSH host owns this node?", from the persisted index — see `setRemoteNodeOwner`. */
private remoteNodeOwner: RemoteNodeOwnerResolver | null = null
/** ONE shared snapshot interval for all persisted sessions — a per-session interval spawned
@@ -1629,10 +1632,29 @@ export class PtyManager {
): Promise<ProjectSpawnOverrides | null> {
const read = this.readProjectSpawnOverrides
if (!read || !options.ownerProjectId) return null
+ const projectId = options.ownerProjectId
+ // COALESCE concurrent reads for one project. A project switch mounts every node in one tick,
+ // and for an SSH project each read is an ssh round trip for the host's settings.json, paced by
+ // the per-master child gate — MEASURED (41-terminal SSH project): those reads spread the
+ // terminals' arrival at the spawn gate over ~1.3 s, in node order, so the on-screen ones came
+ // last. Joining an IN-FLIGHT read only (nothing is cached past its settle) keeps every
+ // freshness property the per-spawn read had: a create that starts after it settles reads anew.
+ let shared = this.overridesInFlight.get(projectId)
+ if (!shared) {
+ const p = Promise.resolve()
+ .then(() => read(projectId))
+ .finally(() => {
+ if (this.overridesInFlight.get(projectId) === p) this.overridesInFlight.delete(projectId)
+ })
+ this.overridesInFlight.set(projectId, p)
+ shared = p
+ }
+ // Each spawn gets its own copy: the answer is shared, the object must not be.
+ const mine = shared.then((o) => (o ? { ...o, ...(o.env ? { env: { ...o.env } } : {}) } : o))
let timer: ReturnType<typeof setTimeout> | undefined
try {
return await Promise.race([
- read(options.ownerProjectId),
+ mine,
new Promise<null>((resolve) => {
timer = setTimeout(() => resolve(null), PROJECT_OVERRIDES_TIMEOUT_MS)
// Never hold the process open for a settings read nobody is waiting on any more.
@@ -2431,7 +2453,9 @@ export class PtyManager {
// trip. Local spawns are not gated: there is no connection to overrun.
const spawnSlot =
options.sshRemote && options.persistKey
- ? await remotePtySpawnGate.acquire(options.sshRemote.controlPath)
+ ? await remotePtySpawnGate.acquire(options.sshRemote.controlPath, {
+ background: options.onScreen === false
+ })
: null
let sessionId: string
try {
diff --git a/src/core/pty-project-settings.test.ts b/src/core/pty-project-settings.test.ts
index 349477c26..dce2a62f2 100644
--- a/src/core/pty-project-settings.test.ts
+++ b/src/core/pty-project-settings.test.ts
@@ -149,6 +149,34 @@ describe('project settings at the spawn — LOCAL leg', () => {
expect(seen).toEqual([PROJECT])
})
+ it('a burst of spawns for one project shares ONE in-flight read, and each gets its own copy', async () => {
+ // A project switch mounts every node at once; on an SSH project each read is an ssh round trip,
+ // and 41 of them spread the terminals over ~1.3 s (measured). Joining the in-flight read fixes it.
+ let calls = 0
+ let release!: (v: ProjectSpawnOverrides | null) => void
+ await manager(() => {
+ calls++
+ return new Promise((r) => (release = r))
+ })
+ const burst = ['n-a', 'n-b', 'n-c'].map((k) => create({ persistKey: k, ownerProjectId: PROJECT }))
+ await new Promise((r) => setTimeout(r, 0))
+ release({ env: { PROJECT_TOKEN: 'abc' } })
+ await Promise.all(burst)
+ expect(calls).toBe(1)
+ expect(spawns.map((s) => s.env.PROJECT_TOKEN)).toEqual(['abc', 'abc', 'abc'])
+ })
+
+ it('is not a cache: a spawn after the read settled reads again', async () => {
+ let calls = 0
+ await manager(async () => {
+ calls++
+ return null
+ })
+ await create({ persistKey: 'n-a', ownerProjectId: PROJECT })
+ await create({ persistKey: 'n-b', ownerProjectId: PROJECT })
+ expect(calls).toBe(2)
+ })
+
it('never asks — and changes nothing — when the pane has no proven owner', async () => {
const read = vi.fn(async () => ({ env: { PROJECT_TOKEN: 'abc' } }))
await manager(read)
diff --git a/src/core/remote-ssh/pty-spawn-gate.test.ts b/src/core/remote-ssh/pty-spawn-gate.test.ts
index 452b26ecc..7eb394919 100644
--- a/src/core/remote-ssh/pty-spawn-gate.test.ts
+++ b/src/core/remote-ssh/pty-spawn-gate.test.ts
@@ -54,6 +54,42 @@ describe('PtySpawnGate', () => {
expect(gate.inFlight('/cm/p1')).toBe(2)
})
+ it('hands a freed permit to an on-screen waiter before older background ones, FIFO within a class', async () => {
+ const clock = fakeClock()
+ const gate = new PtySpawnGate(1, 5000, clock.schedule)
+ let release = await gate.acquire('/cm/p1')
+ const order: string[] = []
+ const wait = (name: string, background: boolean) =>
+ gate.acquire('/cm/p1', { background }).then((r) => {
+ order.push(name)
+ return r
+ })
+ const bg1 = wait('bg1', true)
+ const bg2 = wait('bg2', true)
+ const vis1 = wait('vis1', false)
+ const vis2 = wait('vis2', false)
+ await tick()
+ for (const p of [vis1, vis2, bg1, bg2]) {
+ release()
+ release = await p
+ }
+ expect(order).toEqual(['vis1', 'vis2', 'bg1', 'bg2'])
+ })
+
+ it('with no class given, stays the plain FIFO it was', async () => {
+ const clock = fakeClock()
+ const gate = new PtySpawnGate(1, 5000, clock.schedule)
+ let release = await gate.acquire('/cm/p1')
+ const order: string[] = []
+ const ps = ['a', 'b', 'c'].map((n) => gate.acquire('/cm/p1').then((r) => (order.push(n), r)))
+ await tick()
+ for (const p of ps) {
+ release()
+ release = await p
+ }
+ expect(order).toEqual(['a', 'b', 'c'])
+ })
+
it('keeps hosts separate — one budget per ControlMaster, like MaxSessions itself', async () => {
const clock = fakeClock()
const gate = new PtySpawnGate(1, 5000, clock.schedule)
diff --git a/src/core/remote-ssh/pty-spawn-gate.ts b/src/core/remote-ssh/pty-spawn-gate.ts
index 60b2c99c6..20d2da27c 100644
--- a/src/core/remote-ssh/pty-spawn-gate.ts
+++ b/src/core/remote-ssh/pty-spawn-gate.ts
@@ -26,6 +26,12 @@
//
// LOCAL terminals are not gated at all: there is no connection to overrun, and node-pty spawns
// cost nothing a queue would save.
+//
+// ON-SCREEN FIRST. The queue has two classes: a spawn the renderer reports as on screen goes ahead
+// of every queued background one, FIFO within each class. MEASURED (41-terminal SSH project, 12 on
+// screen, cold attach, dev build): with a plain FIFO the 12 visible terminals were the LAST to paint
+// (first at 2.6 s, last at 3.2 s — 26 offscreen ones ahead of them in node order). The permits
+// already granted are not revoked, so at most `limit` background spawns can precede a visible one.
/** Remote pty spawns allowed in flight per ControlMaster. Deliberately small: each one is an ssh
* channel that will be held for the terminal's whole life, so the burst is the only thing worth
@@ -43,7 +49,7 @@ export type SpawnSlot = () => void
export class PtySpawnGate {
private active = new Map<string, number>()
- private waiting = new Map<string, (() => void)[]>()
+ private waiting = new Map<string, { resolve: () => void; background: boolean }[]>()
constructor(
private limit: number = REMOTE_PTY_SPAWN_CONCURRENCY,
@@ -59,8 +65,8 @@ export class PtySpawnGate {
/** Wait for a slot on this control path. The returned release is idempotent and is ALSO armed
* on the settle deadline, so a caller that forgets (or a pty that never starts) cannot wedge
* the queue. */
- async acquire(controlPath: string): Promise<SpawnSlot> {
- await this.take(controlPath)
+ async acquire(controlPath: string, opts?: { background?: boolean }): Promise<SpawnSlot> {
+ await this.take(controlPath, opts?.background === true)
let released = false
const deadline = this.schedule(() => release(), this.settleMs)
const release: SpawnSlot = () => {
@@ -82,7 +88,7 @@ export class PtySpawnGate {
return this.waiting.get(controlPath)?.length ?? 0
}
- private take(key: string): Promise<void> {
+ private take(key: string, background: boolean): Promise<void> {
const n = this.active.get(key) ?? 0
if (n < this.limit) {
this.active.set(key, n + 1)
@@ -90,19 +96,22 @@ export class PtySpawnGate {
}
return new Promise<void>((resolve) => {
const q = this.waiting.get(key)
- if (q) q.push(resolve)
- else this.waiting.set(key, [resolve])
+ const entry = { resolve, background }
+ if (q) q.push(entry)
+ else this.waiting.set(key, [entry])
})
}
private give(key: string): void {
const q = this.waiting.get(key)
- const next = q?.shift()
- if (next) {
- if (q && q.length === 0) this.waiting.delete(key)
+ if (q && q.length > 0) {
+ // On-screen first, FIFO within each class.
+ const i = q.findIndex((w) => !w.background)
+ const [next] = q.splice(i === -1 ? 0 : i, 1)
+ if (q.length === 0) this.waiting.delete(key)
// Hand the permit straight to the waiter — `active` never dips, so a burst cannot slip past
// the limit in the gap between one spawn finishing and the next starting.
- next()
+ next.resolve()
return
}
const n = (this.active.get(key) ?? 1) - 1
diff --git a/src/renderer/nodes/TerminalNode.tsx b/src/renderer/nodes/TerminalNode.tsx
index 4d5e0739f..93b63a57f 100644
--- a/src/renderer/nodes/TerminalNode.tsx
+++ b/src/renderer/nodes/TerminalNode.tsx
@@ -1,3 +1,4 @@
+import { elementOnScreen } from '../terminal/on-screen'
import { useContextEnsure } from '../terminal/useContextEnsure'
import { canPlainApprove, sendHeaderAnswer } from '../lib/approveGate'
import { FIND_DECORATIONS } from '../lib/palette'
@@ -3496,6 +3497,9 @@ export function TerminalNode({
// on a genuine fresh spawn, so a second project opening another's live node id cannot
// claim it. Machine-local id, never the git-shared project.json id.
ownerProjectId: sshProjectId ?? useProjects.getState().activeProjectId,
+ // Only orders the remote spawn queue: on-screen terminals attach before offscreen ones
+ // on a project switch (terminal/on-screen.ts, core/remote-ssh/pty-spawn-gate.ts).
+ onScreen: elementOnScreen(container),
agentId: data.agentId,
agentModel: data.agentModel,
// "Restart on subscription": ride the spawn's env-strip path. Cleared below once the
diff --git a/src/renderer/terminal/on-screen.test.ts b/src/renderer/terminal/on-screen.test.ts
new file mode 100644
index 000000000..7aa21278b
--- /dev/null
+++ b/src/renderer/terminal/on-screen.test.ts
@@ -0,0 +1,23 @@
+import { describe, it, expect } from 'vitest'
+import { rectOnScreen } from './on-screen'
+
+const pane = { left: 0, top: 0, right: 1000, bottom: 800 }
+const r = (left: number, top: number, w = 100, h = 100) => ({ left, top, right: left + w, bottom: top + h })
+
+describe('rectOnScreen', () => {
+ it('is true for a node inside or overlapping the pane', () => {
+ expect(rectOnScreen(r(10, 10), pane)).toBe(true)
+ expect(rectOnScreen(r(-50, -50), pane)).toBe(true)
+ expect(rectOnScreen(r(950, 750), pane)).toBe(true)
+ })
+ it('is false only for a measured node entirely outside', () => {
+ expect(rectOnScreen(r(1000, 10), pane)).toBe(false)
+ expect(rectOnScreen(r(10, -100), pane)).toBe(false)
+ expect(rectOnScreen(r(-5000, 3000), pane)).toBe(false)
+ })
+ it('fails toward on-screen (the old FIFO position) when it cannot tell', () => {
+ expect(rectOnScreen(null, pane)).toBe(true)
+ expect(rectOnScreen(r(5000, 5000), null)).toBe(true)
+ expect(rectOnScreen({ left: 0, top: 0, right: 0, bottom: 0 }, pane)).toBe(true)
+ })
+})
diff --git a/src/renderer/terminal/on-screen.ts b/src/renderer/terminal/on-screen.ts
new file mode 100644
index 000000000..cc3cf99ac
--- /dev/null
+++ b/src/renderer/terminal/on-screen.ts
@@ -0,0 +1,28 @@
+// Whether a terminal node is on screen right now, for ordering remote spawns
+// (PtyCreateOptions.onScreen → core/remote-ssh/pty-spawn-gate.ts: on-screen spawns go first).
+//
+// A hint, never a gate: it only decides who queues behind whom on a project switch. So every
+// uncertain case answers TRUE (= the old plain-FIFO position), and only a measured miss answers
+// false.
+
+export interface Rect {
+ left: number
+ top: number
+ right: number
+ bottom: number
+}
+
+/** True unless `node` is measured and lies entirely outside `pane`. */
+export function rectOnScreen(node: Rect | null, pane: Rect | null): boolean {
+ if (!node || !pane) return true
+ // An unmeasured element (display:none, not laid out yet) reports an all-zero rect.
+ if (node.right - node.left <= 0 && node.bottom - node.top <= 0) return true
+ return node.right > pane.left && node.left < pane.right && node.bottom > pane.top && node.top < pane.bottom
+}
+
+/** DOM glue: the element against the React Flow pane it sits in (the whole canvas viewport). */
+export function elementOnScreen(el: Element | null): boolean {
+ if (!el) return true
+ const pane = el.closest('.react-flow')
+ return rectOnScreen(el.getBoundingClientRect(), pane ? pane.getBoundingClientRect() : null)
+}
diff --git a/src/shared/types.ts b/src/shared/types.ts
index 815987870..72f44e77b 100644
--- a/src/shared/types.ts
+++ b/src/shared/types.ts
@@ -131,6 +131,14 @@ export interface PtyCreateOptions {
* pane is left unproven and messaging to it fails closed (never derived from the file id).
*/
ownerProjectId?: string
+ /**
+ * Whether the node was on screen when the renderer asked for this session. Used ONLY to order
+ * the per-ControlMaster remote spawn queue (`remote-ssh/pty-spawn-gate.ts`): a project switch
+ * mounts every node in one tick, and without it the terminals the user is looking at queued
+ * behind the ones they are not. `false` = queue behind on-screen spawns; absent (older clients,
+ * relay, headless) = on-screen, i.e. the previous plain FIFO.
+ */
+ onScreen?: boolean
/**
* Which agent runs in this session (claude/codex/gemini/custom). Drives the hook env
* injected at spawn. Defaults to 'claude' for backward compat; the renderer passes a