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
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.tsindex 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.readProjectSpawnOverridesif (!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> | undefinedtry {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+ }): nulllet sessionId: stringtry {diff --git a/src/core/pty-project-settings.test.ts b/src/core/pty-project-settings.test.tsindex 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.tsindex 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.tsindex 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 = () => voidexport 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 = falseconst 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) ?? 0if (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) - 1diff --git a/src/renderer/nodes/TerminalNode.tsx b/src/renderer/nodes/TerminalNode.tsxindex 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 thediff --git a/src/renderer/terminal/on-screen.test.ts b/src/renderer/terminal/on-screen.test.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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