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.

fix(pty): a failed scrollback write re-marks the session dirty

enes48e86eb8ab80
diff --git a/CLAUDE.md b/CLAUDE.md
index 96ad1dc24..7eb0adbf9 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -922,7 +922,8 @@ session (you can't keep a live OS process across a reboot):
`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)
+ (`snapshotQueued`), and a failed capture OR a failed disk write re-marks it dirty
+ (`writeScrollbackIfChanged` reports the write; a skipped unchanged capture counts as done). 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
diff --git a/src/core/pty-manager.snapshot-cadence.test.ts b/src/core/pty-manager.snapshot-cadence.test.ts
index 04aab3fae..468638feb 100644
--- a/src/core/pty-manager.snapshot-cadence.test.ts
+++ b/src/core/pty-manager.snapshot-cadence.test.ts
@@ -3,7 +3,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.
+// failed capture OR a failed disk write 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'
@@ -200,6 +201,29 @@ describe('snapshotTick serialization', () => {
expect(session.outputSinceSnapshot).toBe(true)
expect(session.snapshotQueued).toBe(false)
})
+
+ it('a failed disk WRITE puts the dirty bit back too (the capture succeeding is not enough)', async () => {
+ const mgr = await manager(['a'])
+ const session = mgr.sessions.get('sess-a')!
+ store.failNext = true
+ mgr.snapshotTick()
+ await settle(mgr)
+ expect(store.writes).toHaveLength(1) // the capture ran and the write was attempted…
+ expect(session.outputSinceSnapshot).toBe(true) // …and failed, so the next tick retries
+ expect(session.snapshotQueued).toBe(false)
+ })
+
+ it('an unchanged capture (skipped write) counts as done and stays clean', async () => {
+ const mgr = await manager(['a'])
+ const session = mgr.sessions.get('sess-a')!
+ mgr.snapshotTick()
+ await settle(mgr)
+ session.outputSinceSnapshot = true // a cursor-only redraw: same captured text
+ mgr.snapshotTick()
+ await settle(mgr)
+ expect(store.writes).toHaveLength(1)
+ expect(session.outputSinceSnapshot).toBe(false)
+ })
})
describe('snapshot digest skip', () => {
diff --git a/src/core/pty-manager.ts b/src/core/pty-manager.ts
index 456915823..46922b011 100644
--- a/src/core/pty-manager.ts
+++ b/src/core/pty-manager.ts
@@ -4251,21 +4251,28 @@ 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> {
+ /**
+ * Skip rewriting an identical snapshot (a quiet-but-dirty pane, a cursor-only change). Returns
+ * whether the disk now holds this text: true when written OR skipped as unchanged, false when the
+ * write failed — so the tick can re-mark the session dirty and retry.
+ */
+ private async writeScrollbackIfChanged(persistKey: string, text: string): Promise<boolean> {
const digest = createHash('sha1').update(text).digest('hex')
- if (this.lastSnapshotDigest.get(persistKey) === digest) return
+ if (this.lastSnapshotDigest.get(persistKey) === digest) return true
// Only a write that LANDED may be remembered: recording the digest of a failed one (ENOSPC, a
// rename that exhausted its retries on Windows) would skip every later identical capture —
// detach/quit's final ones included — for the rest of the run.
- if (await writeScrollback(persistKey, text)) this.lastSnapshotDigest.set(persistKey, digest)
+ const written = await writeScrollback(persistKey, text)
+ if (written) this.lastSnapshotDigest.set(persistKey, digest)
+ return written
}
/**
* 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.
- * Returns false when the capture failed, so the periodic tick can re-mark the session dirty
- * and retry (the dirty bit is cleared optimistically before the capture starts).
+ * Returns false when the capture OR its disk write failed, so the periodic tick can re-mark the
+ * session dirty and retry (the dirty bit is cleared optimistically before the capture starts).
+ * An empty capture writes nothing and counts as done.
*/
private async snapshotScrollback(
persistKey: string,
@@ -4282,8 +4289,7 @@ export class PtyManager {
remoteCapturePaneArgs(sshRemote.conn, sshRemote.controlPath, sessionName(persistKey), false),
{ encoding: 'utf-8', maxBuffer: 50 * 1024 * 1024 }
)
- if (stdout) await this.writeScrollbackIfChanged(persistKey, stdout)
- return true
+ return stdout ? await this.writeScrollbackIfChanged(persistKey, stdout) : true
} catch {
// remote session gone / master down — keep the last good snapshot
return false
@@ -4298,8 +4304,7 @@ export class PtyManager {
if (!this.getSettings().tmuxEnabled || !sessionHostSupported()) return false
try {
const text = await sessionHostCapture(sessionName(persistKey), true)
- if (text) await this.writeScrollbackIfChanged(persistKey, text)
- return true
+ return text ? await this.writeScrollbackIfChanged(persistKey, text) : true
} catch {
return false
}
@@ -4310,8 +4315,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 this.writeScrollbackIfChanged(persistKey, stdout)
- return true
+ return stdout ? await this.writeScrollbackIfChanged(persistKey, stdout) : true
} catch {
// session gone / tmux unavailable — keep the last good snapshot
return false