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): back off the remote context tail while the transcript is idle

enesa2bc433d674d
diff --git a/CLAUDE.md b/CLAUDE.md
index 83f6657dd..c1507d84f 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1834,7 +1834,11 @@ else, and its context links must keep classifying across restarts).
with base64, transferring less than 1.6 MiB including alignment/framing; idle replies contain
only the size/range header. The encoded dd exit status must survive the shell pipeline:
pipeline success alone can hide a failed read. Short/malformed replies and SSH failures throw,
- retain the cursor, and back off from 2s to 60s with payload-free diagnostics. Bootstrap and
+ retain the cursor, and back off from 2s to 60s with payload-free diagnostics. A SEPARATE idle
+ backoff (`idleDelayMs`) stretches the 1 s poll after three consecutive empty successful reads
+ (2/4/8 s, capped at 10 s) and is reset by any data-bearing read and by every same-ref `track()`
+ — i.e. every hook POST for the session, which is what keeps a `<task-notification>` (it rides
+ a UserPromptSubmit hook) at ~1 s latency; never merge it with the failure backoff. Bootstrap and
detected truncation restore usage without replaying historical task notifications/tool results,
including a historical partial line completed later. A changed remote reference replaces its
tracking generation so stale in-flight replies cannot publish. Server Edition uses the local
diff --git a/src/main/remote-context-tail.test.ts b/src/main/remote-context-tail.test.ts
index 3e85ec9cc..069fa904d 100644
--- a/src/main/remote-context-tail.test.ts
+++ b/src/main/remote-context-tail.test.ts
@@ -3,7 +3,7 @@ import { execFileSync } from 'node:child_process'
import { mkdtempSync, writeFileSync, appendFileSync, rmSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
-import { createRemoteContextTail } from './remote-context-tail'
+import { createRemoteContextTail, idleDelayMs } from './remote-context-tail'
import { RemoteFile, type RemoteFileRef } from './remote-ssh/remote-file'
const cap = 1024 * 1024
@@ -218,3 +218,96 @@ it('passes only live SSH result IDs to the correlated answer consumer', async ()
expect(h.onToolResult.mock.calls).toEqual([['session', 'other'], ['session', 'ask']])
} finally { h.tail.untrack('session') }
})
+
+describe('idle backoff', () => {
+ const idleRemote = () => vi.fn()
+ .mockResolvedValue({ data: Buffer.alloc(0), newOffset: 4096, initial: false })
+ .mockResolvedValueOnce({ data: Buffer.from(usage(100)), newOffset: 4096, initial: true })
+
+ it('idleDelayMs keeps 1 s polling for the first three empty reads, then backs off to 10 s', () => {
+ expect([1, 2, 3].map(idleDelayMs)).toEqual([0, 0, 0])
+ expect(idleDelayMs(4)).toBe(2000)
+ expect(idleDelayMs(5)).toBe(4000)
+ expect(idleDelayMs(6)).toBe(8000)
+ expect(idleDelayMs(7)).toBe(10_000)
+ expect(idleDelayMs(50)).toBe(10_000)
+ })
+
+ it('stops reading every second once the transcript has been idle', async () => {
+ const readContextWindow = idleRemote()
+ const { tail } = harness({ readContextWindow })
+ try {
+ tail.track('s1', ref)
+ await flush()
+ for (let i = 0; i < 30; i++) await vi.advanceTimersByTimeAsync(1000)
+ // Unbacked-off polling would read 31 times (the immediate read plus one per tick).
+ expect(readContextWindow.mock.calls.length).toBeLessThan(15)
+ } finally { tail.untrack('s1') }
+ })
+
+ it('a read that returns data resets the streak', async () => {
+ const readContextWindow = idleRemote()
+ const { tail } = harness({ readContextWindow })
+ try {
+ tail.track('s1', ref)
+ await flush()
+ for (let i = 0; i < 20; i++) await vi.advanceTimersByTimeAsync(1000)
+ // Backed off: the next read lands only once idleUntil passes. Make it carry data.
+ readContextWindow.mockResolvedValueOnce({ data: Buffer.from(usage(200)), newOffset: 8192, initial: false })
+ const backedOff = readContextWindow.mock.calls.length
+ while (readContextWindow.mock.calls.length === backedOff) await vi.advanceTimersByTimeAsync(1000)
+ expect(tail.offsetFor('s1')).toBe(8192)
+ const before = readContextWindow.mock.calls.length
+ await vi.advanceTimersByTimeAsync(3000)
+ // Streak reset: back to one read per tick for the next three empty reads.
+ expect(readContextWindow.mock.calls.length - before).toBe(3)
+ } finally { tail.untrack('s1') }
+ })
+
+ it('track() of the same ref resets the backoff (a hook arrived)', async () => {
+ const readContextWindow = idleRemote()
+ const { tail } = harness({ readContextWindow })
+ try {
+ tail.track('s1', ref)
+ await flush()
+ for (let i = 0; i < 20; i++) await vi.advanceTimersByTimeAsync(1000)
+ // Land just after a backed-off read so the next one is ~10 s away.
+ let before = readContextWindow.mock.calls.length
+ while (readContextWindow.mock.calls.length === before) await vi.advanceTimersByTimeAsync(1000)
+ before = readContextWindow.mock.calls.length
+ tail.track('s1', { ...ref, conn: { ...ref.conn } })
+ await vi.advanceTimersByTimeAsync(1100)
+ expect(readContextWindow.mock.calls.length - before).toBe(1)
+ } finally { tail.untrack('s1') }
+ })
+
+ it('a failed read keeps the failure backoff, not the idle one', async () => {
+ vi.spyOn(console, 'warn').mockImplementation(() => {})
+ const readContextWindow = idleRemote()
+ const { tail } = harness({ readContextWindow })
+ try {
+ tail.track('s1', ref)
+ await flush()
+ readContextWindow.mockRejectedValueOnce(new Error('down'))
+ await vi.advanceTimersByTimeAsync(1000)
+ const before = readContextWindow.mock.calls.length
+ await vi.advanceTimersByTimeAsync(1000)
+ expect(readContextWindow.mock.calls.length).toBe(before)
+ await vi.advanceTimersByTimeAsync(1000)
+ expect(readContextWindow.mock.calls.length).toBe(before + 1)
+ } finally { tail.untrack('s1') }
+ })
+
+ it('offsetFor reports the last read offset', async () => {
+ const readContextWindow = idleRemote()
+ const { tail } = harness({ readContextWindow })
+ try {
+ expect(tail.offsetFor('s1')).toBeNull()
+ tail.track('s1', ref)
+ await flush()
+ expect(tail.offsetFor('s1')).toBe(4096)
+ expect(tail.offsetFor('unknown')).toBeNull()
+ expect(tail.offsetFor(undefined)).toBeNull()
+ } finally { tail.untrack('s1') }
+ })
+})
diff --git a/src/main/remote-context-tail.ts b/src/main/remote-context-tail.ts
index 9b467f7f4..52544ebbb 100644
--- a/src/main/remote-context-tail.ts
+++ b/src/main/remote-context-tail.ts
@@ -23,11 +23,23 @@ const POLL_MS = 1000
// context-tail.ts stays untouched; value mirrors its INITIAL_READ_CAP.
const INITIAL_READ_CAP = 1024 * 1024 // 1 MB
+/** Extra wait before the next read after `streak` consecutive EMPTY reads. The first three stay at
+ * the 1 s tick (a turn's output usually arrives within seconds); then 2/4/8 s, capped at 10 s.
+ * Any hook event for the session resets it (track()), so a waking agent is picked up at once. */
+export function idleDelayMs(streak: number): number {
+ if (streak <= 3) return 0
+ return Math.min(10_000, 1000 * 2 ** (streak - 3))
+}
+
interface Tracked {
ref: RemoteFileRef
offset: number | null
failures: number
retryAt: number
+ // Idle backoff, separate from the failure backoff above: consecutive successful EMPTY reads,
+ // and the time before which the tick skips this session (see idleDelayMs).
+ idleStreak: number
+ idleUntil: number
suppressCarry: boolean
used: number
window: number
@@ -51,6 +63,8 @@ export interface RemoteContextTail {
untrack(sessionId: string | undefined): void
/** The transcript path currently tracked for a session, if any. */
pathFor(sessionId: string | undefined): string | undefined
+ /** Byte offset of the last successful read (the remote file's size then), or null. */
+ offsetFor(sessionId: string | undefined): number | null
}
export function createRemoteContextTail(
@@ -110,7 +124,7 @@ export function createRemoteContextTail(
// One bounded read per tick; retain the last good meter through transport failures.
const read = async (sessionId: string, t: Tracked): Promise<void> => {
- if (t.reading || Date.now() < t.retryAt) return
+ if (t.reading || Date.now() < t.retryAt || Date.now() < t.idleUntil) return
t.reading = true
try {
const result = await remoteFile.readContextWindow(t.ref, t.offset, INITIAL_READ_CAP)
@@ -121,6 +135,13 @@ export function createRemoteContextTail(
}
t.offset = result.newOffset
if (result.data.length) scan(sessionId, t, result.data, result.initial)
+ if (!result.initial && result.data.length === 0) {
+ t.idleStreak++
+ t.idleUntil = Date.now() + idleDelayMs(t.idleStreak)
+ } else {
+ t.idleStreak = 0
+ t.idleUntil = 0
+ }
t.failures = 0
t.retryAt = 0
} catch {
@@ -162,6 +183,10 @@ export function createRemoteContextTail(
if (existing && existing.ref.path === ref.path &&
existing.ref.controlPath === ref.controlPath &&
JSON.stringify(existing.ref.conn) === JSON.stringify(ref.conn)) {
+ // A hook just arrived for this session — the transcript is about to grow, so drop the
+ // idle backoff and let the next tick read it.
+ existing.idleStreak = 0
+ existing.idleUntil = 0
if (sessionWindow !== undefined && sessionWindow !== existing.sessionWindow) {
existing.sessionWindow = sessionWindow
existing.lastWindow = 0 // publish even if only provenance changed
@@ -174,6 +199,8 @@ export function createRemoteContextTail(
offset: null,
failures: 0,
retryAt: 0,
+ idleStreak: 0,
+ idleUntil: 0,
suppressCarry: false,
used: 0,
window: 0,
@@ -205,6 +232,10 @@ export function createRemoteContextTail(
pathFor(sessionId) {
if (!sessionId) return undefined
return sessions.get(sessionId)?.ref.path
+ },
+ offsetFor(sessionId) {
+ if (!sessionId) return null
+ return sessions.get(sessionId)?.offset ?? null
}
}
}