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(pty): pace scrollback snapshots and skip unchanged ones

enes8df485d9953e
diff --git a/CLAUDE.md b/CLAUDE.md
index 793b54d8c..b8dd6a1d6 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -912,6 +912,19 @@ session (you can't keep a live OS process across a reboot):
renderer reads it via `pty.readScrollback` and writes it back into xterm (with a "session
restored" separator). Warm reattach skips it (tmux already redraws). Deleted with the node in
`destroySession`.
+ **The periodic capture is paced, serialized and deduplicated** (`snapshotTick`,
+ `core/scrollback-cadence.ts`). A working agent's spinner keeps its session dirty forever, so the
+ old tick spawned a `capture-pane -S -1500` (an ssh exec for a remote node) and rewrote up to
+ 256 KB for EVERY busy session, all in the same instant, every 15 s. Now: a dirty session is
+ captured on its first `BUSY_AFTER_TICKS` (4) consecutive dirty ticks, then every
+ `BUSY_EVERY_TICKS`-th (60 s); an off-cadence tick KEEPS the dirty bit, which is what lets
+ detach/quit still take their final capture; an idle tick resets the count. Captures run one at a
+ time on `snapshotChain`, a session whose capture is still queued is never queued twice
+ (`snapshotQueued`), and a failed capture re-marks it dirty. Every write (periodic, detach, quit)
+ goes through `writeScrollbackIfChanged`, which skips a capture whose sha1 matches the last one
+ written; the digest is dropped with the file in `endSession`, so a recreated node always writes.
+ The cost is bounded and deliberate: a continuously busy session's post-reboot replay can be up to
+ ~60 s stale, since the snapshot only serves a machine reboot.
- **Agent resume** — on a cold start of a node whose `agentId` is in `RESUMABLE_AGENTS`, the
renderer re-launches the agent CLI: `resumeCommand(agentId, sessionId)` (from the session id
persisted in `agentStatus` localStorage — `claude --resume`, `codex resume`, `gemini
diff --git a/src/core/pty-manager.snapshot-cadence.test.ts b/src/core/pty-manager.snapshot-cadence.test.ts
new file mode 100644
index 000000000..3bf7fd4ce
--- /dev/null
+++ b/src/core/pty-manager.snapshot-cadence.test.ts
@@ -0,0 +1,218 @@
+// `PtyManager.snapshotTick` — the periodic cold-restore scrollback snapshot (Task 8).
+//
+// The cadence rule itself is the pure `scrollback-cadence.ts`; this file pins the WIRING: a
+// continuously dirty session is captured on the cadence, not on every tick; captures run one at a
+// time instead of all in the same instant; a capture still in flight is never queued twice; a
+// failed capture re-marks the session dirty; and an identical capture is not rewritten to disk.
+// Sessions are registered directly (no spawn harness) — the tick reads only the fields set below.
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+import { initPlatform, resetPlatformForTests } from './platform'
+import { fakePlatform } from './platform-fake'
+import { BUSY_AFTER_TICKS, BUSY_EVERY_TICKS } from './scrollback-cadence'
+
+type Cb = (err: Error | null, res?: { stdout: string; stderr: string }) => void
+
+/** Every `capture-pane` lands here; `hold` parks its callback until the test releases it. */
+const tmux = vi.hoisted(() => ({
+ captures: [] as string[],
+ held: [] as Array<{ target: string; cb: Cb }>,
+ hold: false,
+ fail: false,
+ text: 'PANE SNAPSHOT'
+}))
+
+vi.mock('child_process', () => {
+ const execFile = (file: string, args: string[], a?: unknown, b?: unknown): unknown => {
+ const cb = (typeof a === 'function' ? a : b) as Cb | undefined
+ if (args.includes('capture-pane')) {
+ const target = args[args.indexOf('-t') + 1]
+ tmux.captures.push(target)
+ if (tmux.hold) tmux.held.push({ target, cb: cb! })
+ else if (tmux.fail) cb?.(new Error('tmux busy'))
+ else cb?.(null, { stdout: tmux.text, stderr: '' })
+ } else cb?.(null, { stdout: '', stderr: '' })
+ return {}
+ }
+ return { execFile, execFileSync: (): string => '' }
+})
+
+const store = vi.hoisted(() => ({ writes: [] as Array<{ key: string; text: string }> }))
+vi.mock('./scrollback-store', () => ({
+ writeScrollback: async (key: string, text: string) => {
+ store.writes.push({ key, text })
+ },
+ readScrollback: async () => '',
+ deleteScrollback: async () => {}
+}))
+
+vi.mock('./session-host-backend', async () =>
+ (await import('./__fixtures__/no-session-host')).noSessionHost()
+)
+
+vi.mock('node-pty', () => ({ spawn: () => ({}) }))
+
+interface Internals {
+ tmuxPath: string | null
+ sessions: Map<string, Record<string, unknown>>
+ snapshotChain: Promise<unknown>
+ snapshotTick(): void
+ snapshotScrollback(k: string): Promise<boolean>
+ destroySession(clientId: null, persistKey: string): Promise<void>
+}
+
+async function manager(keys: string[]): Promise<Internals> {
+ const { PtyManager } = await import('./pty-manager')
+ const mgr = new PtyManager() as unknown as Internals
+ mgr.tmuxPath = '/usr/bin/tmux'
+ for (const key of keys)
+ mgr.sessions.set(`sess-${key}`, {
+ persistKey: key,
+ outputSinceSnapshot: true,
+ snapshotDirtyTicks: 0,
+ snapshotQueued: false
+ })
+ return mgr
+}
+
+/** Let the serialized chain drain (each link is a few microtask hops). */
+async function settle(mgr: Internals): Promise<void> {
+ await mgr.snapshotChain
+ await new Promise((r) => setImmediate(r))
+}
+
+beforeEach(() => {
+ initPlatform(fakePlatform())
+ tmux.captures.length = 0
+ tmux.held.length = 0
+ tmux.hold = false
+ tmux.fail = false
+ tmux.text = 'PANE SNAPSHOT'
+ store.writes.length = 0
+})
+afterEach(() => resetPlatformForTests())
+
+describe('snapshotTick cadence', () => {
+ it('captures a continuously dirty session on ticks 1-4, then every 4th tick', async () => {
+ const mgr = await manager(['n1'])
+ const session = mgr.sessions.get('sess-n1')!
+ const capturedOn: number[] = []
+ for (let tick = 1; tick <= 16; tick++) {
+ session.outputSinceSnapshot = true // the spinner redrew since the last tick
+ const before = tmux.captures.length
+ mgr.snapshotTick()
+ await settle(mgr)
+ if (tmux.captures.length > before) capturedOn.push(tick)
+ }
+ expect(BUSY_AFTER_TICKS).toBe(4)
+ expect(BUSY_EVERY_TICKS).toBe(4)
+ expect(capturedOn).toEqual([1, 2, 3, 4, 8, 12, 16])
+ })
+
+ it('an idle tick resets the busy count, so the next output is captured at once', async () => {
+ const mgr = await manager(['n1'])
+ const session = mgr.sessions.get('sess-n1')!
+ for (let tick = 1; tick <= 5; tick++) {
+ session.outputSinceSnapshot = true
+ mgr.snapshotTick()
+ await settle(mgr)
+ }
+ expect(tmux.captures).toHaveLength(4) // tick 5 is off-cadence
+ // Tick 5 kept the dirty bit, so clear it by hand to model a genuinely quiet interval.
+ session.outputSinceSnapshot = false
+ mgr.snapshotTick()
+ await settle(mgr)
+ expect(session.snapshotDirtyTicks).toBe(0)
+ session.outputSinceSnapshot = true
+ mgr.snapshotTick()
+ await settle(mgr)
+ expect(tmux.captures).toHaveLength(5)
+ })
+
+ it('an off-cadence tick keeps the dirty bit, so detach/quit still take a final capture', async () => {
+ const mgr = await manager(['n1'])
+ const session = mgr.sessions.get('sess-n1')!
+ for (let tick = 1; tick <= 5; tick++) {
+ session.outputSinceSnapshot = true
+ mgr.snapshotTick()
+ await settle(mgr)
+ }
+ expect(session.outputSinceSnapshot).toBe(true)
+ })
+})
+
+describe('snapshotTick serialization', () => {
+ it('runs captures one at a time, never all in the same instant', async () => {
+ const mgr = await manager(['a', 'b', 'c'])
+ tmux.hold = true
+ mgr.snapshotTick()
+ await new Promise((r) => setImmediate(r))
+ expect(tmux.captures).toEqual(['nt-a'])
+ tmux.held.shift()!.cb(null, { stdout: 'A', stderr: '' })
+ await new Promise((r) => setImmediate(r))
+ expect(tmux.captures).toEqual(['nt-a', 'nt-b'])
+ tmux.held.shift()!.cb(null, { stdout: 'B', stderr: '' })
+ await new Promise((r) => setImmediate(r))
+ expect(tmux.captures).toEqual(['nt-a', 'nt-b', 'nt-c'])
+ tmux.held.shift()!.cb(null, { stdout: 'C', stderr: '' })
+ await settle(mgr)
+ })
+
+ it('never queues a session whose capture is still pending', async () => {
+ const mgr = await manager(['a'])
+ const session = mgr.sessions.get('sess-a')!
+ tmux.hold = true
+ mgr.snapshotTick()
+ await new Promise((r) => setImmediate(r))
+ session.outputSinceSnapshot = true
+ mgr.snapshotTick() // tick 2 is on-cadence, but the first capture has not returned
+ await new Promise((r) => setImmediate(r))
+ expect(tmux.captures).toEqual(['nt-a'])
+ expect(tmux.held).toHaveLength(1)
+ tmux.held.shift()!.cb(null, { stdout: 'A', stderr: '' })
+ await settle(mgr)
+ expect(tmux.captures).toEqual(['nt-a'])
+ expect(session.snapshotQueued).toBe(false)
+ // The skipped tick left the dirty bit set, so the next tick captures it.
+ tmux.hold = false
+ mgr.snapshotTick()
+ await settle(mgr)
+ expect(tmux.captures).toEqual(['nt-a', 'nt-a'])
+ })
+
+ it('a failed capture puts the dirty bit back for the next tick', async () => {
+ const mgr = await manager(['a'])
+ const session = mgr.sessions.get('sess-a')!
+ tmux.fail = true
+ mgr.snapshotTick()
+ await settle(mgr)
+ expect(session.outputSinceSnapshot).toBe(true)
+ expect(session.snapshotQueued).toBe(false)
+ })
+})
+
+describe('snapshot digest skip', () => {
+ it('does not rewrite an identical capture, but writes a changed one', async () => {
+ const mgr = await manager(['a'])
+ await mgr.snapshotScrollback('a')
+ await mgr.snapshotScrollback('a')
+ expect(store.writes).toHaveLength(1)
+ tmux.text = 'NEW OUTPUT'
+ await mgr.snapshotScrollback('a')
+ expect(store.writes.map((w) => w.text)).toEqual(['PANE SNAPSHOT', 'NEW OUTPUT'])
+ })
+
+ it('keys the digest per node', async () => {
+ const mgr = await manager(['a', 'b'])
+ await mgr.snapshotScrollback('a')
+ await mgr.snapshotScrollback('b')
+ expect(store.writes.map((w) => w.key)).toEqual(['a', 'b'])
+ })
+
+ it('forgets the digest when the node is destroyed, so a recreated node writes again', async () => {
+ const mgr = await manager([])
+ await mgr.snapshotScrollback('gone')
+ await mgr.destroySession(null, 'gone')
+ await mgr.snapshotScrollback('gone')
+ expect(store.writes.map((w) => w.key)).toEqual(['gone', 'gone'])
+ })
+})
diff --git a/src/core/pty-manager.ts b/src/core/pty-manager.ts
index 8a90c81b4..783837d42 100644
--- a/src/core/pty-manager.ts
+++ b/src/core/pty-manager.ts
@@ -82,6 +82,8 @@ import { terminateWindowsProcessTree } from '../session-host/windows-process-tre
import { effectiveSize, type PtySize } from './pty-size'
import { machOArch, archMismatch } from './macho-arch'
import { writeScrollback, readScrollback, deleteScrollback } from './scrollback-store'
+import { snapshotDue } from './scrollback-cadence'
+import { createHash } from 'node:crypto'
import { claudeConfigDirFor } from './claude-config-dir'
import { envPathKey, findExecutableSync, findInPathString, resolveShellPath, shellPathNow } from './exec-path'
import {
@@ -677,6 +679,12 @@ interface Session {
sshRemote?: NonNullable<PtyCreateOptions['sshRemote']>
/** Output arrived since the last scrollback snapshot — idle sessions skip the capture. */
outputSinceSnapshot: boolean
+ /** Consecutive snapshot ticks this session was dirty — drives the busy cadence
+ * (scrollback-cadence.ts). Reset by an idle tick. */
+ snapshotDirtyTicks: number
+ /** A periodic capture for this session is queued or running on `snapshotChain`; a tick that
+ * lands meanwhile must not queue a second one. */
+ snapshotQueued: boolean
/** A tmux session (local `nt-<id>`, or the remote one an SSH project attaches to) is holding this
* session's work, so the pty client here is expendable: detaching it loses nothing and the next
* create re-attaches with `new-session -A`. It is the precondition for the idle reap — see
@@ -970,6 +978,10 @@ export class PtyManager {
/** ONE shared snapshot interval for all persisted sessions — a per-session interval spawned
* one tmux/ssh capture subprocess per session per tick, forever, even for idle terminals. */
private snapshotTimer: ReturnType<typeof setInterval> | null = null
+ /** The periodic captures, serialized: one tmux/ssh spawn + scrollback write at a time. */
+ private snapshotChain: Promise<unknown> = Promise.resolve()
+ /** persistKey → sha1 of the last snapshot WRITTEN, so an identical capture is not rewritten. */
+ private lastSnapshotDigest = new Map<string, string>()
/** ONE shared sweep for the idle reap (see `reapTick` / pty-reap.ts), armed by the first
* tmux-backed session and cleared once no session is left. */
private reapTimer: ReturnType<typeof setInterval> | null = null
@@ -1056,13 +1068,31 @@ export class PtyManager {
for (const session of this.sessions.values()) {
if (!session.persistKey) continue
anyPersisted = true
- if (!session.outputSinceSnapshot) continue // idle since the last capture — skip the spawn
+ if (!session.outputSinceSnapshot) {
+ session.snapshotDirtyTicks = 0 // idle since the last capture — skip the spawn
+ continue
+ }
+ session.snapshotDirtyTicks++
+ // Continuously busy: keep the dirty bit, capture on the cadence (scrollback-cadence.ts).
+ if (!snapshotDue(session.snapshotDirtyTicks) || session.snapshotQueued) continue
session.outputSinceSnapshot = false
- void this.snapshotScrollback(session.persistKey, session.sshRemote, !!session.sessionHost).then((ok) => {
- // Transient capture failure (ssh blip, tmux busy): put the dirty bit back so the next
- // tick retries — otherwise a quiet session would never be snapshotted again.
- if (!ok) session.outputSinceSnapshot = true
- })
+ session.snapshotQueued = true
+ const persistKey = session.persistKey
+ // ONE capture at a time: the old loop fired every busy session's tmux/ssh spawn and 256 KB
+ // write in the same instant.
+ this.snapshotChain = this.snapshotChain
+ .then(() => this.snapshotScrollback(persistKey, session.sshRemote, !!session.sessionHost))
+ .then((ok) => {
+ // Transient capture failure (ssh blip, tmux busy): put the dirty bit back so the next
+ // tick retries — otherwise a quiet session would never be snapshotted again.
+ if (!ok) session.outputSinceSnapshot = true
+ })
+ .catch(() => {
+ session.outputSinceSnapshot = true
+ })
+ .finally(() => {
+ session.snapshotQueued = false
+ })
}
if (!anyPersisted && this.snapshotTimer) {
clearInterval(this.snapshotTimer)
@@ -3442,6 +3472,8 @@ export class PtyManager {
persistKey: persisted ? options.persistKey : undefined,
sshRemote: remote,
outputSinceSnapshot: true, // capture the initial screen on the first tick
+ snapshotDirtyTicks: 0,
+ snapshotQueued: false,
// `persisted` IS "a tmux session (local or remote) is holding this work" — the same condition
// that gates the scrollback snapshots. Recorded under its own name because the reap decision
// asks a different question of it: not "is it worth snapshotting" but "would releasing this
@@ -4212,6 +4244,14 @@ export class PtyManager {
}
}
+ /** Skip rewriting an identical snapshot (a quiet-but-dirty pane, a cursor-only change). */
+ private async writeScrollbackIfChanged(persistKey: string, text: string): Promise<void> {
+ const digest = createHash('sha1').update(text).digest('hex')
+ if (this.lastSnapshotDigest.get(persistKey) === digest) return
+ await writeScrollback(persistKey, text)
+ this.lastSnapshotDigest.set(persistKey, digest)
+ }
+
/**
* Snapshot a node's recent scrollback (with colors, `-e`) to disk for cold-restart replay.
* Best-effort: a missing session / unavailable tmux just leaves the prior snapshot in place.
@@ -4233,7 +4273,7 @@ export class PtyManager {
remoteCapturePaneArgs(sshRemote.conn, sshRemote.controlPath, sessionName(persistKey), false),
{ encoding: 'utf-8', maxBuffer: 50 * 1024 * 1024 }
)
- if (stdout) await writeScrollback(persistKey, stdout)
+ if (stdout) await this.writeScrollbackIfChanged(persistKey, stdout)
return true
} catch {
// remote session gone / master down — keep the last good snapshot
@@ -4249,7 +4289,7 @@ export class PtyManager {
if (!this.getSettings().tmuxEnabled || !sessionHostSupported()) return false
try {
const text = await sessionHostCapture(sessionName(persistKey), true)
- if (text) await writeScrollback(persistKey, text)
+ if (text) await this.writeScrollbackIfChanged(persistKey, text)
return true
} catch {
return false
@@ -4261,7 +4301,7 @@ export class PtyManager {
['-L', TMUX_SOCKET, 'capture-pane', '-p', '-e', '-t', sessionName(persistKey), '-S', '-1500'],
{ encoding: 'utf-8', maxBuffer: 50 * 1024 * 1024 }
)
- if (stdout) await writeScrollback(persistKey, stdout)
+ if (stdout) await this.writeScrollbackIfChanged(persistKey, stdout)
return true
} catch {
// session gone / tmux unavailable — keep the last good snapshot
@@ -5285,6 +5325,9 @@ export class PtyManager {
// OLD cwd's session, and the respawn is a cold start (`fresh`), so replaying it would paint the
// pre-move terminal into the new one.
await deleteScrollback(persistKey)
+ // The file is gone, so the digest no longer describes anything on disk: a recreated node must
+ // write its first snapshot even if the pane text happens to match.
+ this.lastSnapshotDigest.delete(persistKey)
// Same hook, same reason as the snapshot above: this node's Codex thread records go with the
// session. Left behind they accumulate one file per thread forever, and the hook prelude keeps
// re-exporting a DELETED node's id into any tool shell that still carries that thread id.
diff --git a/src/core/scrollback-cadence.test.ts b/src/core/scrollback-cadence.test.ts
new file mode 100644
index 000000000..aef3eb8e3
--- /dev/null
+++ b/src/core/scrollback-cadence.test.ts
@@ -0,0 +1,13 @@
+import { describe, it, expect } from 'vitest'
+import { snapshotDue, BUSY_AFTER_TICKS, BUSY_EVERY_TICKS } from './scrollback-cadence'
+
+describe('snapshotDue', () => {
+ it('captures on each of the first BUSY_AFTER_TICKS consecutive dirty ticks', () => {
+ for (let t = 1; t <= BUSY_AFTER_TICKS; t++) expect(snapshotDue(t)).toBe(true)
+ })
+ it('then only every BUSY_EVERY_TICKS-th tick (60 s at the 15 s tick)', () => {
+ const due = Array.from({ length: 12 }, (_, i) => i + BUSY_AFTER_TICKS + 1).filter(snapshotDue)
+ expect(due).toEqual([8, 12, 16])
+ expect(BUSY_EVERY_TICKS).toBe(4)
+ })
+})
diff --git a/src/core/scrollback-cadence.ts b/src/core/scrollback-cadence.ts
new file mode 100644
index 000000000..ba6a71e45
--- /dev/null
+++ b/src/core/scrollback-cadence.ts
@@ -0,0 +1,14 @@
+/**
+ * Cadence of the periodic cold-restore scrollback snapshot (pty-manager `snapshotTick`, 15 s).
+ * `dirtyTicks` = consecutive ticks on which the session had output. A session that just produced
+ * output is captured at once; one that has been continuously busy (an agent's spinner redraws
+ * forever) is captured every BUSY_EVERY_TICKS-th tick instead. The snapshot only serves a restore
+ * after a machine reboot, and detach/quit capture anyway, so a busy session loses at most ~60 s of
+ * restore scrollback in exchange for a quarter of the capture spawns and 256 KB rewrites.
+ */
+export const BUSY_AFTER_TICKS = 4
+export const BUSY_EVERY_TICKS = 4
+
+export function snapshotDue(dirtyTicks: number): boolean {
+ return dirtyTicks <= BUSY_AFTER_TICKS || dirtyTicks % BUSY_EVERY_TICKS === 0
+}