Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

Stop hidden terminal cursors from waking the renderer (#628)

Deeafea68e8f2f8
diff --git a/desktop/integration_test/terminal_cursor_native_test.dart b/desktop/integration_test/terminal_cursor_native_test.dart
new file mode 100644
index 000000000..8fbaa5656
--- /dev/null
+++ b/desktop/integration_test/terminal_cursor_native_test.dart
@@ -0,0 +1,14 @@
+import 'package:harness/core/test_run.dart';
+import 'package:integration_test/integration_test.dart';
+
+import '../test/terminal_cursor_idle_test.dart' as cursor;
+import 'native_terminal_e2e_test.dart' as terminal;
+
+void main() {
+ if (!kUnderTest) {
+ throw StateError('Native cursor fixtures require FLUTTER_TEST=1');
+ }
+ IntegrationTestWidgetsFlutterBinding.ensureInitialized();
+ cursor.main();
+ terminal.main();
+}
diff --git a/desktop/lib/terminal/terminal_session.dart b/desktop/lib/terminal/terminal_session.dart
index f0f5da67a..ffbdc66de 100644
--- a/desktop/lib/terminal/terminal_session.dart
+++ b/desktop/lib/terminal/terminal_session.dart
@@ -271,7 +271,14 @@ class TerminalSession extends ChangeNotifier {
bool _openStallRecovered = false;
bool _disposed = false;
int _generation = 0;
- bool _remoteCursorVisible = true;
+ final _remoteCursorVisible = ValueNotifier(true);
+
+ /// The program's cursor visibility, independent of the local blink phase.
+ /// Views can stop their cursor clock while the program draws its own caret.
+ /// This is separate from session notifications: an escape sequence must not
+ /// rebuild the workspace or change input ownership.
+ ValueListenable<bool> get remoteCursorVisibility => _remoteCursorVisible;
+
bool _cursorBlinkPhaseVisible = true;
List<int> _utf8Tail = const [];
final List<int> _inputBytes = [];
@@ -393,7 +400,6 @@ class TerminalSession extends ChangeNotifier {
_lastRealignedTo = null;
_resizeSeq = 0;
_utf8Tail = const [];
- _remoteCursorVisible = true;
_cursorBlinkPhaseVisible = true;
_resyncRequested = false;
_resyncAttempts = 0;
@@ -405,6 +411,7 @@ class TerminalSession extends ChangeNotifier {
rows = _clampRows(initialRows);
if (!preserveTerminal) terminal = _newTerminal()..resize(cols, rows);
status = TerminalSessionStatus.opening;
+ _remoteCursorVisible.value = true;
_openRequestId =
'term_${DateTime.now().microsecondsSinceEpoch}_${Random.secure().nextInt(1 << 31)}';
notifyListeners();
@@ -774,8 +781,8 @@ class TerminalSession extends ChangeNotifier {
cols = _clampCols(nextCols);
rows = _clampRows(nextRows);
_utf8Tail = decoded.tail;
- _remoteCursorVisible = terminal.cursorVisibleMode;
_cursorBlinkPhaseVisible = true;
+ _remoteCursorVisible.value = terminal.cursorVisibleMode;
_expectedSeq = frame.seq + 1;
_lastRenderedSeq = frame.seq;
_resyncRequested = false;
@@ -893,22 +900,26 @@ class TerminalSession extends ChangeNotifier {
/// is always parsed against [_remoteCursorVisible], so blinking cannot turn
/// a remote DECTCEM hide/show command into terminal input or corrupt its
/// authoritative cursor state.
- void setCursorBlinkPhase(bool visible) {
- if (_cursorBlinkPhaseVisible == visible) return;
+ /// Returns whether the effective cursor visibility changed and needs paint.
+ bool setCursorBlinkPhase(bool visible) {
+ if (_cursorBlinkPhaseVisible == visible) return false;
+ final wasVisible = terminal.cursorVisibleMode;
_cursorBlinkPhaseVisible = visible;
_applyCursorVisibility();
+ return wasVisible != terminal.cursorVisibleMode;
}
void _writeTerminalText(String text) {
- terminal.setCursorVisibleMode(_remoteCursorVisible);
+ terminal.setCursorVisibleMode(_remoteCursorVisible.value);
terminal.write(text);
- _remoteCursorVisible = terminal.cursorVisibleMode;
- _applyCursorVisibility();
+ final remoteVisible = terminal.cursorVisibleMode;
+ terminal.setCursorVisibleMode(remoteVisible && _cursorBlinkPhaseVisible);
+ _remoteCursorVisible.value = remoteVisible;
}
void _applyCursorVisibility() {
terminal.setCursorVisibleMode(
- _remoteCursorVisible && _cursorBlinkPhaseVisible,
+ _remoteCursorVisible.value && _cursorBlinkPhaseVisible,
);
}
@@ -1696,6 +1707,7 @@ class TerminalSession extends ChangeNotifier {
_disposed = true;
_generation++;
_cancelTimers();
+ _remoteCursorVisible.dispose();
super.dispose();
}
}
diff --git a/desktop/lib/widgets/terminal_panel.dart b/desktop/lib/widgets/terminal_panel.dart
index 9ec137277..ce42bae50 100644
--- a/desktop/lib/widgets/terminal_panel.dart
+++ b/desktop/lib/widgets/terminal_panel.dart
@@ -320,6 +320,7 @@ class _TerminalPanelState extends State<TerminalPanel>
WidgetsBinding.instance.addObserver(this);
widget.session.attachViewport(this);
widget.session.addListener(_onSessionChanged);
+ widget.session.remoteCursorVisibility.addListener(_syncCursorBlink);
terminalFontStore.addListener(_onFontChanged);
// Colours repaint the view in place — no relayout, no resize frame — but
// they still need a rebuild to reach it, and this widget reads the store
@@ -411,9 +412,11 @@ class _TerminalPanelState extends State<TerminalPanel>
_previewProgress = null;
oldWidget.session.setCursorBlinkPhase(true);
oldWidget.session.removeListener(_onSessionChanged);
+ oldWidget.session.remoteCursorVisibility.removeListener(_syncCursorBlink);
oldWidget.session.detachViewport(this);
widget.session.attachViewport(this);
widget.session.addListener(_onSessionChanged);
+ widget.session.remoteCursorVisibility.addListener(_syncCursorBlink);
_composerFocusPending = false;
_cancelDialInertia();
_controller.clearSelection();
@@ -500,6 +503,7 @@ class _TerminalPanelState extends State<TerminalPanel>
_observeLinkModifiers(false);
widget.session.setCursorBlinkPhase(true);
widget.session.removeListener(_onSessionChanged);
+ widget.session.remoteCursorVisibility.removeListener(_syncCursorBlink);
widget.session.detachViewport(this);
terminalFontStore.removeListener(_onFontChanged);
terminalThemeStore.removeListener(_onFontChanged);
@@ -947,6 +951,7 @@ class _TerminalPanelState extends State<TerminalPanel>
!widget.readOnly &&
_focusNode.hasFocus &&
widget.session.acceptsInput &&
+ widget.session.remoteCursorVisibility.value &&
(_tickerMode?.value.enabled ?? false) &&
(lifecycle == null || lifecycle == AppLifecycleState.resumed);
if (!enabled) {
@@ -968,8 +973,9 @@ class _TerminalPanelState extends State<TerminalPanel>
void _setCursorBlinkVisible(bool visible) {
if (visible == _cursorBlinkVisible) return;
_cursorBlinkVisible = visible;
- widget.session.setCursorBlinkPhase(visible);
- _repaintTerminalCursor();
+ if (widget.session.setCursorBlinkPhase(visible)) {
+ _repaintTerminalCursor();
+ }
}
void _repaintTerminalCursor() {
diff --git a/desktop/test/terminal_cursor_idle_test.dart b/desktop/test/terminal_cursor_idle_test.dart
new file mode 100644
index 000000000..217db52a3
--- /dev/null
+++ b/desktop/test/terminal_cursor_idle_test.dart
@@ -0,0 +1,313 @@
+import 'dart:convert';
+import 'dart:ui' as ui;
+
+import 'package:flutter/material.dart';
+import 'package:flutter/rendering.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:harness/state/app_state.dart';
+import 'package:harness/terminal/terminal_binary.dart';
+import 'package:harness/terminal/terminal_session.dart';
+import 'package:harness/widgets/pane_grid.dart';
+import 'package:harness/widgets/terminal_panel.dart';
+import 'package:xterm/xterm.dart';
+
+import 'support/periodic_timer_probe.dart';
+import 'swarm_screen_test.dart' show terminal;
+import 'swarm_state_test.dart' show createApp;
+
+Future<void> output(
+ TerminalSession session,
+ int sequence,
+ String text, {
+ bool keyframe = false,
+}) => session.handleBinary(
+ TerminalBinaryFrame(
+ kind: keyframe ? TerminalBinaryKind.keyframe : TerminalBinaryKind.output,
+ streamId: session.streamId!,
+ seq: sequence,
+ bytes: utf8.encode(text),
+ compressed: false,
+ cols: keyframe ? 80 : null,
+ rows: keyframe ? 24 : null,
+ ),
+);
+
+class _CursorFixture {
+ final AppNotifier app = createApp();
+ final session = ValueNotifier(terminal('a0', []));
+ final visible = ValueNotifier(true);
+ final readOnly = ValueNotifier(false);
+ final tickers = ValueNotifier(true);
+ final probe = PeriodicTimerProbe();
+ final sessions = <TerminalSession>[];
+ final pixels = GlobalKey();
+
+ TerminalSession get current => session.value;
+
+ TerminalViewState view(WidgetTester tester) =>
+ tester.state<TerminalViewState>(find.byType(TerminalView));
+
+ Future<void> mount(WidgetTester tester) async {
+ sessions.add(current);
+ await output(current, 0, 'Prompt\x1b[?25l', keyframe: true);
+ await tester.pumpWidget(
+ MaterialApp(
+ home: RepaintBoundary(
+ key: pixels,
+ child: ListenableBuilder(
+ listenable: Listenable.merge([session, visible, readOnly, tickers]),
+ builder: (_, _) => TickerMode(
+ enabled: tickers.value,
+ child: AnimatedBuilder(
+ animation: current,
+ builder: (_, _) => TerminalPanel(
+ notifier: app,
+ session: current,
+ focused: true,
+ showHeader: false,
+ visible: visible.value,
+ readOnly: readOnly.value,
+ ),
+ ),
+ ),
+ ),
+ ),
+ ),
+ );
+ await focus(tester);
+ }
+
+ Future<void> focus(WidgetTester tester) async {
+ await tester.pump(const Duration(milliseconds: 100));
+ view(tester).widget.focusNode!.requestFocus();
+ await tester.pump();
+ expect(view(tester).widget.focusNode!.hasFocus, isTrue);
+ }
+
+ Future<Color> cursorPixel(WidgetTester tester) async {
+ final boundary =
+ pixels.currentContext!.findRenderObject()! as RenderRepaintBoundary;
+ final render = view(tester).renderTerminal;
+ final point = boundary.globalToLocal(
+ render.localToGlobal(
+ render.cursorOffset + render.cellSize.center(Offset.zero),
+ ),
+ );
+ return (await tester.runAsync(() async {
+ final image = await boundary.toImage(pixelRatio: 1);
+ try {
+ final bytes = (await image.toByteData(
+ format: ui.ImageByteFormat.rawRgba,
+ ))!;
+ final offset = (point.dy.floor() * image.width + point.dx.floor()) * 4;
+ return Color.fromARGB(
+ bytes.getUint8(offset + 3),
+ bytes.getUint8(offset),
+ bytes.getUint8(offset + 1),
+ bytes.getUint8(offset + 2),
+ );
+ } finally {
+ image.dispose();
+ }
+ }))!;
+ }
+
+ Future<void> dispose(WidgetTester tester) async {
+ await tester.pumpWidget(const SizedBox());
+ for (final item in sessions) {
+ item.dispose();
+ }
+ app.dispose();
+ session.dispose();
+ visible.dispose();
+ readOnly.dispose();
+ tickers.dispose();
+ expect(probe.active, 0);
+ }
+}
+
+Future<void> _withCursor(
+ WidgetTester tester,
+ Future<void> Function(_CursorFixture fixture) body,
+) async {
+ final fixture = _CursorFixture();
+ await fixture.probe.run(() async {
+ try {
+ await fixture.mount(tester);
+ await body(fixture);
+ } finally {
+ await fixture.dispose(tester);
+ }
+ });
+}
+
+void main() {
+ testWidgets('a remotely hidden cursor has no local blink timer', (
+ tester,
+ ) async {
+ final probe = PeriodicTimerProbe();
+ await probe.run(() async {
+ final app = createApp();
+ app.machineStates['m']!.nodeOnline = true;
+ final session = terminal('a0', []);
+ await output(session, 0, 'Idle prompt\x1b[?25l', keyframe: true);
+ app.adoptSessionForTest(session);
+ await tester.pumpWidget(
+ MaterialApp(
+ home: PaneGrid(
+ notifier: app,
+ swarmMode: true,
+ empty: const SizedBox(),
+ ),
+ ),
+ );
+ await tester.pump(const Duration(milliseconds: 100));
+ final view = tester.state<TerminalViewState>(find.byType(TerminalView));
+ view.widget.focusNode!.requestFocus();
+ await tester.pump();
+ expect(view.widget.focusNode!.hasFocus, isTrue);
+ expect(session.acceptsInput, isTrue);
+ expect(session.terminal.cursorVisibleMode, isFalse);
+ final timers = probe.active;
+ final before = probe.callbacks;
+ for (var tick = 0; tick < 10; tick++) {
+ await tester.pump(const Duration(milliseconds: 500));
+ }
+ final callbacks = probe.callbacks - before;
+ await tester.pumpWidget(const SizedBox());
+ app.dispose();
+ debugPrint('HIDDEN_CURSOR_IDLE timers=$timers callbacks=$callbacks/5s');
+ expect(timers, 0);
+ expect(callbacks, 0);
+ expect(probe.active, 0);
+ });
+ });
+
+ testWidgets(
+ 'remote hide/show controls the clock and painted cursor',
+ (tester) => _withCursor(tester, (fixture) async {
+ final session = fixture.current;
+ final background = await fixture.cursorPixel(tester);
+ expect(fixture.probe.active, 0);
+ await output(session, 1, '\x1b[?25h');
+ await tester.pump();
+ expect(fixture.probe.active, 1);
+ expect(session.terminal.cursorVisibleMode, isTrue);
+ final cursor = await fixture.cursorPixel(tester);
+ expect(cursor, isNot(background));
+ await tester.pump(const Duration(milliseconds: 500));
+ expect(session.terminal.cursorVisibleMode, isFalse);
+ expect(await fixture.cursorPixel(tester), background);
+
+ // Hiding while the local blink is dark must still stop its timer.
+ await output(session, 2, '\x1b[?25l');
+ await tester.pump();
+ expect(fixture.probe.active, 0);
+ final callbacks = fixture.probe.callbacks;
+ await tester.pump(const Duration(milliseconds: 1100));
+ expect(fixture.probe.callbacks, callbacks);
+ expect(await fixture.cursorPixel(tester), background);
+
+ // A split escape sequence takes effect only when it is complete.
+ await output(session, 3, '\x1b[?2');
+ expect(fixture.probe.active, 0);
+ await output(session, 4, '5h');
+ await tester.pump();
+ expect(fixture.probe.active, 1);
+ expect(await fixture.cursorPixel(tester), cursor);
+ }),
+ );
+
+ for (final gate in ['window', 'ticker', 'pane', 'read only', 'focus']) {
+ testWidgets(
+ 'remote show respects $gate eligibility',
+ (tester) => _withCursor(tester, (fixture) async {
+ switch (gate) {
+ case 'window':
+ tester.binding.handleAppLifecycleStateChanged(
+ AppLifecycleState.inactive,
+ );
+ case 'ticker':
+ fixture.tickers.value = false;
+ case 'pane':
+ fixture.visible.value = false;
+ case 'read only':
+ fixture.readOnly.value = true;
+ case 'focus':
+ fixture.view(tester).widget.focusNode!.unfocus();
+ }
+ try {
+ await tester.pump();
+ await output(fixture.current, 1, '\x1b[?25h');
+ await tester.pump(const Duration(milliseconds: 1100));
+ expect(fixture.probe.active, 0);
+ expect(fixture.current.terminal.cursorVisibleMode, isTrue);
+ } finally {
+ tester.binding.handleAppLifecycleStateChanged(
+ AppLifecycleState.resumed,
+ );
+ fixture.tickers.value = true;
+ fixture.visible.value = true;
+ fixture.readOnly.value = false;
+ }
+ await fixture.focus(tester);
+ // Native rebuilds run in the engine's callback zone, outside the
+ // timer probe's zone. Check the actual resumed blink, not whether that
+ // particular clock was created inside the probe.
+ expect(fixture.current.terminal.cursorVisibleMode, isTrue);
+ await tester.pump(const Duration(milliseconds: 550));
+ expect(fixture.current.terminal.cursorVisibleMode, isFalse);
+ await output(fixture.current, 2, '\x1b[?25l');
+ await tester.pump();
+ expect(fixture.probe.active, 0);
+ }),
+ );
+ }
+
+ testWidgets(
+ 'replacing a session moves the cursor visibility listener',
+ (tester) => _withCursor(tester, (fixture) async {
+ final previous = fixture.current;
+ await output(previous, 1, '\x1b[?25h');
+ expect(fixture.probe.active, 1);
+ final replacement = terminal('a1', []);
+ fixture.sessions.add(replacement);
+ await output(replacement, 0, 'Replacement\x1b[?25l', keyframe: true);
+ fixture.session.value = replacement;
+ await fixture.focus(tester);
+ expect(fixture.probe.active, 0);
+
+ await output(previous, 2, '\x1b[?25l');
+ await output(previous, 3, '\x1b[?25h');
+ expect(fixture.probe.active, 0);
+ await output(replacement, 1, '\x1b[?25h');
+ expect(fixture.probe.active, 1);
+
+ await tester.pumpWidget(const SizedBox());
+ expect(fixture.probe.active, 0);
+ await output(replacement, 2, '\x1b[?25l');
+ await output(replacement, 3, '\x1b[?25h');
+ expect(fixture.probe.active, 0);
+ expect(tester.takeException(), isNull);
+ }),
+ );
+
+ testWidgets(
+ 'replacement keyframes reconcile visibility without extra clocks',
+ (tester) => _withCursor(tester, (fixture) async {
+ final session = fixture.current;
+ await output(session, 1, 'Reconnected\x1b[?25h', keyframe: true);
+ await tester.pump();
+ await fixture.focus(tester);
+ expect(fixture.view(tester).widget.terminal, same(session.terminal));
+ expect(fixture.probe.active, 1);
+ await tester.pump(const Duration(milliseconds: 500));
+ expect(session.terminal.cursorVisibleMode, isFalse);
+ await output(session, 2, 'New screen\x1b[?25l', keyframe: true);
+ await tester.pump();
+ expect(fixture.probe.active, 0);
+ expect(session.terminal.cursorVisibleMode, isFalse);
+ expect(session.terminal.buffer.getText(), contains('New screen'));
+ }),
+ );
+}
diff --git a/desktop/test/terminal_session_test.dart b/desktop/test/terminal_session_test.dart
index f0f64dd66..9b16ab5e5 100644
--- a/desktop/test/terminal_session_test.dart
+++ b/desktop/test/terminal_session_test.dart
@@ -400,6 +400,51 @@ void main() {
},
);
+ test(
+ 'cursor visibility notifications ignore local blinks and ordinary output',
+ () async {
+ await ready();
+ await session.handleBinary(
+ output(
+ 0,
+ utf8.encode('prompt\x1b[?25h'),
+ keyframe: true,
+ cols: 100,
+ rows: 30,
+ ),
+ );
+ final visibility = <bool>[];
+ var sessionChanges = 0;
+ session.remoteCursorVisibility.addListener(() {
+ visibility.add(session.remoteCursorVisibility.value);
+ });
+ session.addListener(() => sessionChanges++);
+
+ expect(session.setCursorBlinkPhase(false), isTrue);
+ expect(session.setCursorBlinkPhase(false), isFalse);
+ expect(session.remoteCursorVisibility.value, isTrue);
+ await session.handleBinary(output(1, utf8.encode('output')));
+ expect(session.terminal.cursorVisibleMode, isFalse);
+ expect(visibility, isEmpty);
+ expect(session.setCursorBlinkPhase(true), isTrue);
+
+ await session.handleBinary(output(2, utf8.encode('\x1b[?25l')));
+ expect(visibility, [false]);
+ expect(session.setCursorBlinkPhase(false), isFalse);
+ expect(session.setCursorBlinkPhase(true), isFalse);
+ // Transient hide/show within one packet does not change the final state.
+ await session.handleBinary(output(3, utf8.encode('\x1b[?25h\x1b[?25l')));
+ expect(visibility, [false]);
+ await session.handleBinary(output(4, utf8.encode('\x1b[?25h')));
+ expect(visibility, [false, true]);
+ expect(
+ sessionChanges,
+ 0,
+ reason: 'cursor changes must not rebuild the workspace',
+ );
+ },
+ );
+
test('remote history keyframe survives viewport resize without circular-buffer reflow', () async {
await ready();
final oldStyleHistory = List.generate(
diff --git a/docs/performance/2026-10-02-hidden-terminal-cursor.json b/docs/performance/2026-10-02-hidden-terminal-cursor.json
new file mode 100644
index 000000000..16561a18c
--- /dev/null
+++ b/docs/performance/2026-10-02-hidden-terminal-cursor.json
@@ -0,0 +1,434 @@
+{
+ "schema": 1,
+ "date": "2026-10-02",
+ "scope": "Stop local terminal cursor timer while remote DECTCEM visibility is hidden",
+ "source": {
+ "baseline": "56d71adf501b6d85c19334abf20a909a8baa3979",
+ "validated_commit": "14b2e497a7c58c5c4fcd6d08fb7bc57ad1d651db",
+ "validated_tree": "5e4d84a8dabb7ae17fe0adf1b874fac8b046a5e7",
+ "files_sha256": {
+ "desktop/lib/terminal/terminal_session.dart": "ed640c1bdc875338718447bc4baf2ad051196d469b9c53a7adfe15a6dc8e8199",
+ "desktop/lib/widgets/terminal_panel.dart": "94d5f580a997175b8765730cc887ef6a7e12dc9e0e623af01a0a20abc28a3777",
+ "desktop/test/terminal_cursor_idle_test.dart": "4b87d69322b611ed1a0cb80bb59a2966bec08078b5bd2e4c8495905c4e1020c8",
+ "desktop/test/terminal_session_test.dart": "ee5b9e2a363692f828205b7d0e87fc6891084dcd25913fc817bdaa495e272132",
+ "desktop/integration_test/terminal_cursor_native_test.dart": "3a47bca513aa4fea2422c926f15561c27587314808bba91fce3d06fdf6c9795d",
+ "desktop/integration_test/native_terminal_e2e_test.dart": "00a1a273eb81e3c4f2d8c951f8062ec1064c5c99b45f701754363fbea16502ba",
+ "desktop/test/support/periodic_timer_probe.dart": "854fd76377403a18f60c4960baafecf8cda4c02a405d418ade9e1215aa4625ed",
+ "desktop/test/swarm_screen_test.dart": "503eb6f5a3b24dde0779d626ccd85a07002f16538c7478765d150e4ea761b348",
+ "desktop/test/swarm_state_test.dart": "80ff899fb511f710f38a98d7af5a25c07c274afe83f54a180adbb297e64fc7dd",
+ "desktop/pubspec.lock": "0987d3b363535b314a292bab02ff8ec5bc51691398f8ede9406b9885925c00b7"
+ }
+ },
+ "environment": {
+ "flutter": "3.47.2",
+ "dart": "3.13.2",
+ "platform": "macOS arm64",
+ "native_renderer": "Impeller",
+ "native_traffic": "In-memory TerminalSession, FLUTTER_TEST=1"
+ },
+ "measurement": {
+ "clock": "headless widget fake clock",
+ "simulated_seconds": 5,
+ "interval_ms": 500,
+ "before": {
+ "active_blink_timers": 1,
+ "callbacks": 10
+ },
+ "after": {
+ "active_blink_timers": 0,
+ "callbacks": 0
+ },
+ "baseline_log_sha256": "0ec77574672faeba00bd469f51b362c0cedee2fca8e84f6be1db0cc3724a5d10",
+ "baseline_log_result": "Intentional failing regression: HIDDEN_CURSOR_IDLE timers=1 callbacks=10/5s",
+ "whole_app_energy_improvement": null
+ },
+ "validation_summary": {
+ "headless_tests_passed": 137,
+ "changed_dart_analysis": "passed",
+ "native_distinct_cases_with_passing_evidence": 11,
+ "native_initial": {
+ "passed": 8,
+ "failed": 3,
+ "failure": "Resumed timer creation occurs outside probe zone on native engine callbacks"
+ },
+ "native_retry": {
+ "eligibility_cases_passed": 5,
+ "change": "Assert observable cursor phase after resume instead of zone-scoped timer count"
+ },
+ "normal_review_build_restored": true,
+ "physical_keyboard_ime_tested": false,
+ "linux_native_tested": false,
+ "browser_rendering_tested": false
+ },
+ "evidence_reuse": {
+ "rebase_from": "85816751c",
+ "rebase_to": "14b2e497a7c58c5c4fcd6d08fb7bc57ad1d651db",
+ "native_inputs_unchanged": [
+ "desktop/lib/terminal",
+ "desktop/lib/widgets/terminal_panel.dart",
+ "desktop/integration_test/native_terminal_e2e_test.dart",
+ "desktop/integration_test/terminal_cursor_native_test.dart",
+ "desktop/test/terminal_cursor_idle_test.dart",
+ "desktop/test/swarm_screen_test.dart",
+ "desktop/test/swarm_state_test.dart",
+ "desktop/pubspec.lock",
+ "desktop/macos/Runner"
+ ],
+ "upstream_changes": "Added headless test binding configuration; affected headless suite and analysis rerun. Native entry point and inputs unchanged; settings helper comments only."
+ },
+ "receipts": [
+ {
+ "role": "headless_before_rebase",
+ "local_receipt": ".harness/validation/20261002T155504.725139Z-65833/receipt.json",
+ "receipt_sha256": "ea5202f929dd356519970ec3fb0dfe7044f1e3751962ce6fbf7ff0d5baa6971f",
+ "result": {
+ "schema": 2,
+ "started_at": "2026-10-02T15:55:04.725444+00:00",
+ "reason": "Stop local cursor clocks for remotely hidden cursors without altering terminal content, focus or protocol.",
+ "source": {
+ "commit": "56d71adf501b6d85c19334abf20a909a8baa3979",
+ "tree": "ab18d942d2127f4de1b200ca0d07ad7a8d4db11e",
+ "working_changes_sha256": "4a3e4cc1f669a793bb2b1edab59a985af3dabb2514a3050c1b3bf9aaeb98dcf2",
+ "dirty": true
+ },
+ "checks": [
+ {
+ "name": "cursor-analysis",
+ "cwd": "desktop",
+ "argv": [
+ "<FLUTTER_SDK>/bin/cache/dart-sdk/bin/dart",
+ "analyze",
+ "lib/terminal/terminal_session.dart",
+ "lib/widgets/terminal_panel.dart",
+ "test/terminal_cursor_idle_test.dart",
+ "test/terminal_session_test.dart",
+ "integration_test/terminal_cursor_native_test.dart"
+ ],
+ "timeout_seconds": 120,
+ "started_at": "2026-10-02T15:55:04.966140+00:00",
+ "status": "passed",
+ "log": ".harness/validation/20261002T155504.725139Z-65833/cursor-analysis.log",
+ "exit_code": 0,
+ "duration_seconds": 2.339,
+ "finished_at": "2026-10-02T15:55:07.326450+00:00",
+ "log_sha256": "ab77e677f7b06503b76ec5c5a31152306631e2eef9f5b6707a95a9585d3efe9a"
+ },
+ {
+ "name": "cursor-regressions",
+ "cwd": "desktop",
+ "argv": [
+ "<FLUTTER_SDK>/bin/flutter",
+ "test",
+ "--no-pub",
+ "--concurrency=2",
+ "--timeout=60s",
+ "test/terminal_cursor_idle_test.dart",
+ "test/terminal_session_test.dart",
+ "test/terminal_render_suspension_test.dart",
+ "test/terminal_initial_output_test.dart",
+ "test/terminal_panel_focus_test.dart",
+ "test/terminal_view_interaction_test.dart",
+ "test/pane_focus_test.dart",
+ "test/terminal_find_test.dart"
+ ],
+ "timeout_seconds": 240,
+ "started_at": "2026-10-02T15:55:04.964319+00:00",
+ "status": "passed",
+ "log": ".harness/validation/20261002T155504.725139Z-65833/cursor-regressions.log",
+ "exit_code": 0,
+ "duration_seconds": 13.867,
+ "finished_at": "2026-10-02T15:55:18.851773+00:00",
+ "log_sha256": "d36dfe738ace46fd08293e04f670cd67ecbd47a22c1494dbfd4a4be7808f8e2e"
+ }
+ ],
+ "free_gib_before": 10.865,
+ "source_after": {
+ "commit": "56d71adf501b6d85c19334abf20a909a8baa3979",
+ "tree": "ab18d942d2127f4de1b200ca0d07ad7a8d4db11e",
+ "working_changes_sha256": "4a3e4cc1f669a793bb2b1edab59a985af3dabb2514a3050c1b3bf9aaeb98dcf2",
+ "dirty": true
+ },
+ "status": "passed",
+ "finished_at": "2026-10-02T15:55:19.069593+00:00",
+ "duration_seconds": 14.105
+ }
+ },
+ {
+ "role": "native_initial",
+ "local_receipt": ".harness/validation/20261002T155609.502505Z-81502/receipt.json",
+ "receipt_sha256": "86e43b38588e9565e01af94ca595525837a955d55d209b4d5c9be8d9d5976828",
+ "result": {
+ "schema": 2,
+ "started_at": "2026-10-02T15:56:09.502831+00:00",
+ "reason": "Native macOS cursor visibility/pixel/lifecycle checks and existing terminal/input/keyframe journeys; isolated fake sessions only.",
+ "source": {
+ "commit": "56d71adf501b6d85c19334abf20a909a8baa3979",
+ "tree": "ab18d942d2127f4de1b200ca0d07ad7a8d4db11e",
+ "working_changes_sha256": "4a3e4cc1f669a793bb2b1edab59a985af3dabb2514a3050c1b3bf9aaeb98dcf2",
+ "dirty": true
+ },
+ "checks": [
+ {
+ "name": "cursor-native",
+ "cwd": "desktop",
+ "argv": [
+ "env",
+ "FLUTTER_TEST=1",
+ "<FLUTTER_SDK>/bin/flutter",
+ "test",
+ "-d",
+ "macos",
+ "--no-pub",
+ "--timeout=90s",
+ "integration_test/terminal_cursor_native_test.dart"
+ ],
+ "timeout_seconds": 300,
+ "started_at": "2026-10-02T15:56:09.733415+00:00",
+ "status": "failed",
+ "log": ".harness/validation/20261002T155609.502505Z-81502/cursor-native.log",
+ "exit_code": 1,
+ "duration_seconds": 56.376,
+ "finished_at": "2026-10-02T15:57:06.160001+00:00",
+ "log_sha256": "83760f5ca1a872404b9444edcdb187ddf8f05885e279af48430c5bfe114476ab"
+ }
+ ],
+ "free_gib_before": 10.999,
+ "source_after": {
+ "commit": "56d71adf501b6d85c19334abf20a909a8baa3979",
+ "tree": "ab18d942d2127f4de1b200ca0d07ad7a8d4db11e",
+ "working_changes_sha256": "4a3e4cc1f669a793bb2b1edab59a985af3dabb2514a3050c1b3bf9aaeb98dcf2",
+ "dirty": true
+ },
+ "status": "failed",
+ "finished_at": "2026-10-02T15:57:06.720932+00:00",
+ "duration_seconds": 56.987
+ }
+ },
+ {
+ "role": "native_eligibility_retry",
+ "local_receipt": ".harness/validation/20261002T155843.730694Z-13909/receipt.json",
+ "receipt_sha256": "fd6c743f741f960d527d43aa7dde97064b1656f6bb1e4e500975415e34e6ab18",
+ "result": {
+ "schema": 2,
+ "started_at": "2026-10-02T15:58:43.731062+00:00",
+ "reason": "Recheck native visibility eligibility using observable cursor phases; the timer probe cannot count clocks created in the native engine callback zone.",
+ "source": {
+ "commit": "56d71adf501b6d85c19334abf20a909a8baa3979",
+ "tree": "ab18d942d2127f4de1b200ca0d07ad7a8d4db11e",
+ "working_changes_sha256": "56c530c2a28c05fecffb6e6c943d490b8af626493527236e2ed78938681c1153",
+ "dirty": true
+ },
+ "checks": [
+ {
+ "name": "cursor-native-eligibility",
+ "cwd": "desktop",
+ "argv": [
+ "env",
+ "FLUTTER_TEST=1",
+ "<FLUTTER_SDK>/bin/flutter",
+ "test",
+ "-d",
+ "macos",
+ "--no-pub",
+ "--timeout=90s",
+ "integration_test/terminal_cursor_native_test.dart",
+ "--plain-name",
+ "remote show respects"
+ ],
+ "timeout_seconds": 300,
+ "started_at": "2026-10-02T15:58:43.951022+00:00",
+ "status": "passed",
+ "log": ".harness/validation/20261002T155843.730694Z-13909/cursor-native-eligibility.log",
+ "exit_code": 0,
+ "duration_seconds": 46.646,
+ "finished_at": "2026-10-02T15:59:30.620327+00:00",
+ "log_sha256": "9cea7379ca12a0314b94b3f893859a09ee9a87da098689279eac6fd86f37f9e9"
+ }
+ ],
+ "free_gib_before": 10.96,
+ "source_after": {
+ "commit": "56d71adf501b6d85c19334abf20a909a8baa3979",
+ "tree": "ab18d942d2127f4de1b200ca0d07ad7a8d4db11e",
+ "working_changes_sha256": "56c530c2a28c05fecffb6e6c943d490b8af626493527236e2ed78938681c1153",
+ "dirty": true
+ },
+ "status": "passed",
+ "finished_at": "2026-10-02T15:59:30.848522+00:00",
+ "duration_seconds": 46.897
+ }
+ },
+ {
+ "role": "final_fixture_and_normal_build",
+ "local_receipt": ".harness/validation/20261002T160048.907155Z-33416/receipt.json",
+ "receipt_sha256": "8d55aa5d5aaead75442215f9b235f0b33728e833ee013c3a576f85f3f7927bed",
+ "result": {
+ "schema": 2,
+ "started_at": "2026-10-02T16:00:48.907461+00:00",
+ "reason": "Final changed fixture recheck after native timer instrumentation correction; prior 128 unaffected checks retain their evidence. Restore normal Debug review artifact after native tests.",
+ "source": {
+ "commit": "56d71adf501b6d85c19334abf20a909a8baa3979",
+ "tree": "ab18d942d2127f4de1b200ca0d07ad7a8d4db11e",
+ "working_changes_sha256": "56c530c2a28c05fecffb6e6c943d490b8af626493527236e2ed78938681c1153",
+ "dirty": true
+ },
+ "checks": [
+ {
+ "name": "cursor-final-analysis",
+ "cwd": "desktop",
+ "argv": [
+ "<FLUTTER_SDK>/bin/cache/dart-sdk/bin/dart",
+ "analyze",
+ "lib/terminal/terminal_session.dart",
+ "lib/widgets/terminal_panel.dart",
+ "test/terminal_cursor_idle_test.dart",
+ "test/terminal_session_test.dart",
+ "integration_test/terminal_cursor_native_test.dart"
+ ],
+ "timeout_seconds": 120,
+ "started_at": "2026-10-02T16:00:49.126920+00:00",
+ "status": "passed",
+ "log": ".harness/validation/20261002T160048.907155Z-33416/cursor-final-analysis.log",
+ "exit_code": 0,
+ "duration_seconds": 2.666,
+ "finished_at": "2026-10-02T16:00:51.813805+00:00",
+ "log_sha256": "ab77e677f7b06503b76ec5c5a31152306631e2eef9f5b6707a95a9585d3efe9a"
+ },
+ {
+ "name": "cursor-final-fixture",
+ "cwd": "desktop",
+ "argv": [
+ "<FLUTTER_SDK>/bin/flutter",
+ "test",
+ "--no-pub",
+ "--concurrency=2",
+ "--timeout=60s",
+ "test/terminal_cursor_idle_test.dart"
+ ],
+ "timeout_seconds": 120,
+ "started_at": "2026-10-02T16:00:49.125373+00:00",
+ "status": "passed",
+ "log": ".harness/validation/20261002T160048.907155Z-33416/cursor-final-fixture.log",
+ "exit_code": 0,
+ "duration_seconds": 4.387,
+ "finished_at": "2026-10-02T16:00:53.532835+00:00",
+ "log_sha256": "82942c93bc1ea052089dde90f7b3364ee2b2fc1e1b102e08ddf2441da0b11565"
+ },
+ {
+ "name": "normal-review-build",
+ "cwd": "desktop",
+ "argv": [
+ "env",
+ "PATH=<FLUTTER_SDK>/bin/:/usr/bin:/bin:/usr/sbin:/sbin:/opt/homebrew/bin",
+ "bash",
+ "scripts/build-macos-debug.sh",
+ "--no-pub",
+ "--target",
+ "lib/main.dart"
+ ],
+ "timeout_seconds": 300,
+ "started_at": "2026-10-02T16:00:51.866299+00:00",
+ "status": "passed",
+ "log": ".harness/validation/20261002T160048.907155Z-33416/normal-review-build.log",
+ "exit_code": 0,
+ "duration_seconds": 31.974,
+ "finished_at": "2026-10-02T16:01:23.861713+00:00",
+ "log_sha256": "d1f5f7774c63879f71e0cfb153de90df7a3a9c2a538e9cdc09a97b38e64483f7"
+ }
+ ],
+ "free_gib_before": 10.827,
+ "source_after": {
+ "commit": "56d71adf501b6d85c19334abf20a909a8baa3979",
+ "tree": "ab18d942d2127f4de1b200ca0d07ad7a8d4db11e",
+ "working_changes_sha256": "56c530c2a28c05fecffb6e6c943d490b8af626493527236e2ed78938681c1153",
+ "dirty": true
+ },
+ "status": "passed",
+ "finished_at": "2026-10-02T16:01:24.091993+00:00",
+ "duration_seconds": 34.966
+ }
+ },
+ {
+ "role": "rebased_headless_and_analysis",
+ "local_receipt": ".harness/validation/20261002T160403.227680Z-77699/receipt.json",
+ "receipt_sha256": "b236fe659ae8e02bb04f8717d3a9043fdfbb9b219ae7f0a3ca17bc3679f5f65a",
+ "result": {
+ "schema": 2,
+ "started_at": "2026-10-02T16:04:03.227986+00:00",
+ "reason": "Stop local cursor clocks for remotely hidden cursors without altering terminal content, focus or protocol.",
+ "source": {
+ "commit": "14b2e497a7c58c5c4fcd6d08fb7bc57ad1d651db",
+ "tree": "5e4d84a8dabb7ae17fe0adf1b874fac8b046a5e7",
+ "working_changes_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+ "dirty": false
+ },
+ "checks": [
+ {
+ "name": "cursor-analysis",
+ "cwd": "desktop",
+ "argv": [
+ "<FLUTTER_SDK>/bin/cache/dart-sdk/bin/dart",
+ "analyze",
+ "lib/terminal/terminal_session.dart",
+ "lib/widgets/terminal_panel.dart",
+ "test/terminal_cursor_idle_test.dart",
+ "test/terminal_session_test.dart",
+ "integration_test/terminal_cursor_native_test.dart"
+ ],
+ "timeout_seconds": 120,
+ "started_at": "2026-10-02T16:04:03.445325+00:00",
+ "status": "passed",
+ "log": ".harness/validation/20261002T160403.227680Z-77699/cursor-analysis.log",
+ "exit_code": 0,
+ "duration_seconds": 1.711,
+ "finished_at": "2026-10-02T16:04:05.177940+00:00",
+ "log_sha256": "ab77e677f7b06503b76ec5c5a31152306631e2eef9f5b6707a95a9585d3efe9a"
+ },
+ {
+ "name": "cursor-regressions",
+ "cwd": "desktop",
+ "argv": [
+ "<FLUTTER_SDK>/bin/flutter",
+ "test",
+ "--no-pub",
+ "--concurrency=2",
+ "--timeout=60s",
+ "test/terminal_cursor_idle_test.dart",
+ "test/terminal_session_test.dart",
+ "test/terminal_render_suspension_test.dart",
+ "test/terminal_initial_output_test.dart",
+ "test/terminal_panel_focus_test.dart",
+ "test/terminal_view_interaction_test.dart",
+ "test/pane_focus_test.dart",
+ "test/terminal_find_test.dart"
+ ],
+ "timeout_seconds": 240,
+ "started_at": "2026-10-02T16:04:03.443936+00:00",
+ "status": "passed",
+ "log": ".harness/validation/20261002T160403.227680Z-77699/cursor-regressions.log",
+ "exit_code": 0,
+ "duration_seconds": 14.255,
+ "finished_at": "2026-10-02T16:04:17.719299+00:00",
+ "log_sha256": "8c6f7aa67d8dc5d160d0de3c318dc30d8b449496a84c56317bdb7c424954c993"
+ }
+ ],
+ "free_gib_before": 10.647,
+ "source_after": {
+ "commit": "14b2e497a7c58c5c4fcd6d08fb7bc57ad1d651db",
+ "tree": "5e4d84a8dabb7ae17fe0adf1b874fac8b046a5e7",
+ "working_changes_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+ "dirty": false
+ },
+ "status": "passed",
+ "finished_at": "2026-10-02T16:04:17.929868+00:00",
+ "duration_seconds": 14.486
+ }
+ }
+ ],
+ "release_policy": "PR and merge only. No release or app update without renewed user authorization.",
+ "limitations": [
+ "No measured whole-app CPU, GPU, battery improvement or 100x result.",
+ "Native probe does not count timers created outside its Dart zone; resumed cursor behavior verified directly.",
+ "Native launcher could not foreground app; attachment, pixel checks and framework input passed.",
+ "Saved-session, daemon, real engine and shared-server behavior unchanged."
+ ]
+}
diff --git a/docs/performance/2026-10-02-hidden-terminal-cursor.md b/docs/performance/2026-10-02-hidden-terminal-cursor.md
new file mode 100644
index 000000000..85a1b16b1
--- /dev/null
+++ b/docs/performance/2026-10-02-hidden-terminal-cursor.md
@@ -0,0 +1,79 @@
+# Stop clocks for remotely hidden terminal cursors
+
+A focused, interactive terminal kept a 500 ms blink timer after its program sent
+DECTCEM hide (`ESC[?25l`). Each callback also requested a terminal repaint even
+though the effective cursor stayed hidden. This is common for programs that draw
+their own caret.
+
+`TerminalSession` now exposes the program's cursor visibility through a separate
+`ValueListenable`. `TerminalPanel` stops its blink clock while that cursor is
+hidden, then resumes on DECTCEM show when focus, pane visibility, window lifecycle,
+input permission and ticker eligibility allow it. Cursor changes do not emit
+session-wide notifications. Local blink changes request paint only when effective
+cursor visibility changes. Replacing a session moves the listener; disposal
+removes it.
+
+## Measured scope
+
+The same focused-pane fixture ran before and after the change. Ten 500 ms fake-clock
+advances cover five simulated seconds after terminal output stops:
+
+| Remotely hidden cursor | Before | After |
+| --- | ---: | ---: |
+| Active local blink timers | 1 | 0 |
+| Timer callbacks in five simulated seconds | 10 | 0 |
+
+This removes all callbacks from that clock while the program hides its cursor.
+It does not measure whole-app CPU, GPU, battery life or macOS's significant-energy
+classification. Visible cursors retain their normal blink behavior. The
+[machine-readable record](2026-10-02-hidden-terminal-cursor.json) includes source
+hashes, receipt identifiers, log hashes and the failed baseline reproduction.
+
+## Validation
+
+- **137 affected unit/widget tests passed** on the rebased implementation, covering
+ cursor state, terminal sessions, hidden rendering, initial output, focus, input,
+ selection and find. Analysis of all five changed Dart files passed.
+- **11 distinct native macOS cases have passing evidence:** nine cursor scenarios
+ plus the existing keyframe/input and agent-switch journeys. Pixel checks confirm
+ hidden, shown, blink-dark and restored cursor output. The scenarios cover split
+ escape sequences, visibility changes during the dark phase, inactive windows,
+ disabled tickers, hidden/read-only/unfocused panes, session replacement,
+ keyframe replacement and unmounting.
+- Native validation used in-memory sessions with `FLUTTER_TEST=1`. The normal
+ Debug review app was rebuilt afterward; strict signature validation passed.
+ No installed app, daemon or real agent was restarted by these checks.
+
+The initial native invocation had eight passes and three instrumentation failures.
+The timer probe could not observe timers created from native engine callback
+zones after a widget rebuild. Those resume assertions now check the actual cursor
+phase before and after 550 ms. All five eligibility cases passed in the targeted
+native retry; the other six cases retain their passing results. This is not a
+claim that the first native invocation passed. All nine final cursor fixtures
+also passed headlessly, then passed again in the rebased 137-test scope.
+
+An earlier unit fixture used an 80×24 keyframe against a 100×30 startup size,
+introducing an unrelated resize notification. Matching the startup grid fixed
+that fixture before the passing 137-test run. The native launcher reported that
+it could not foreground the app, then attached and executed the rendering checks.
+These results cover native rendering and framework input, not physical AppKit
+keyboard/IME input, foreground latency, Linux or browser rendering.
+
+## Source and timing
+
+Baseline: `56d71adf501b6d85c19334abf20a909a8baa3979` (1.2.54 source).
+Validated implementation: `14b2e497a7c58c5c4fcd6d08fb7bc57ad1d651db`, rebased on
+`a94c7aa83`. Toolchain: Flutter 3.47.2 / Dart 3.13.2, macOS arm64.
+
+The rebase preserved all changed production code, native fixtures and their
+dependencies. Upstream added a headless test binding configuration, so the entire
+affected headless scope and analysis were rerun. Native evidence remains applicable:
+that configuration is under `test/`, outside the `integration_test/` entry point,
+and the native inputs were unchanged. No new runtime/dependency change was made
+after validation; this report is documentation only.
+
+Native validation ran from 15:56:09 to 15:59:30 UTC on October 2, including the
+targeted retry. The normal review build was restored at 16:01:24. Rebased
+validation completed at 16:04:17. Original request time is unavailable in this
+continuation; merge time is recorded in the PR. This work is PR/merge only under
+the user's release hold. No release is requested by this report.