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.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
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.dartnew file mode 100644index 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.dartindex 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.dartindex 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.dartnew file mode 100644index 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.dartindex 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.jsonnew file mode 100644index 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.mdnew file mode 100644index 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.