diff --git a/src/renderer/src/lib/pane-manager/reveal-repaint-synchronized-output.test.ts b/src/renderer/src/lib/pane-manager/reveal-repaint-synchronized-output.test.ts
index 28a726f470b..4d3519726b7 100644
--- a/src/renderer/src/lib/pane-manager/reveal-repaint-synchronized-output.test.ts
+++ b/src/renderer/src/lib/pane-manager/reveal-repaint-synchronized-output.test.ts
@@ -16,8 +16,10 @@ import type { ManagedPaneInternal } from './pane-manager-types'
 
 type GateState = { synchronizedOutput: boolean; rendered: number }
 
-// Mirrors RenderService.refreshRows (RenderService.ts:155-181): paused first,
-// then the synchronized-output buffer gate, then the actual render.
+// Mirrors RenderService.refreshRows: paused first, then the synchronized-output
+// buffer gate, then the actual render. This double can drift from xterm on an
+// upgrade, so the gate order it encodes is independently pinned against the real
+// renderer in tests/e2e/terminal-reveal-draw-command-probe.spec.ts.
 function createGatedPane(options: { synchronizedOutput: boolean }): {
   pane: ManagedPaneInternal
   gate: GateState