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(pty): pace scrollback snapshots and skip unchanged ones
enes8df485d9953e
diff --git a/CLAUDE.md b/CLAUDE.mdindex 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 "sessionrestored" 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`, therenderer re-launches the agent CLI: `resumeCommand(agentId, sessionId)` (from the session idpersisted in `agentStatus` localStorage — `claude --resume`, `codex resume`, `geminidiff --git a/src/core/pty-manager.snapshot-cadence.test.ts b/src/core/pty-manager.snapshot-cadence.test.tsnew file mode 100644index 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.tsindex 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-treimport { 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) continueanyPersisted = 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) continuesession.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 falsetry {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.tsnew file mode 100644index 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.tsnew file mode 100644index 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+}