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.

fix(desktop/terminal): ⌥⏎ sent the turn instead of breaking the line

reinSPQR248af22924aa
diff --git a/desktop/CLAUDE.md b/desktop/CLAUDE.md
index 73e2d56d1..e36334364 100644
--- a/desktop/CLAUDE.md
+++ b/desktop/CLAUDE.md
@@ -448,8 +448,11 @@ from `node_status` pushes — distinct from our own socket status, pending offli
▸ Keyboard shortcuts, group cards reflowed across the pane, plus the recessed "the terminal keeps"
card built from `kTerminalOwnedKeys`). Same rows behind both, so they cannot disagree; keycaps come
from `shortcuts/key_cap.dart`. Every shortcut is ⌘-based — Ctrl belongs to the shell/tmux, ⌥ is a
- Meta prefix for the pty, and ⌘C/⌘V/⌘A are owned by xterm — with one pinned exception, `⌃⇥`/`⌃⇧⇥`
- for the panes, which the terminal is made to let past.
+ Meta prefix for the pty (⌥⏎ only — `MetaEnterInputHandler` in
+ `lib/terminal/terminal_input.dart` turns it into `ESC` + Return so the engine's prompt breaks the
+ line instead of submitting; ⌥ stays the compose key everywhere else, and the composer answers the
+ same chord by writing the newline itself), and ⌘C/⌘V/⌘A are owned by xterm — with one pinned
+ exception, `⌃⇥`/`⌃⇧⇥` for the panes, which the terminal is made to let past.
- `lib/flash/` flashes the ESP32-S3 dial through the CLI runner; `SerialPortLease` pauses daemon
supervision while the port is held so `harness start` cannot steal it mid-write.
- `lib/update/desktop_updater.dart` self-updates from the GCS manifest (sha256-verified, strictly
diff --git a/desktop/lib/terminal/terminal_input.dart b/desktop/lib/terminal/terminal_input.dart
new file mode 100644
index 000000000..088fa9c99
--- /dev/null
+++ b/desktop/lib/terminal/terminal_input.dart
@@ -0,0 +1,41 @@
+import 'package:xterm/xterm.dart';
+
+/// Makes ⌥⏎ a newline inside the engine's prompt instead of a submit.
+///
+/// Claude Code, Codex and every other Ink/readline prompt read Meta+Enter — `ESC` followed by the
+/// ordinary Return bytes — as "add a line, do not send this turn yet". A real terminal produces
+/// that only when it is configured to treat ⌥ as Meta (iTerm's "Esc+", Terminal.app's "Use Option
+/// as Meta Key"); xterm.dart has no such setting, and its [AltInputHandler] deliberately does
+/// nothing on macOS so ⌥ stays the compose key for `å`/`ø`/`¬`. So ⌥⏎ fell through to the keytab,
+/// which matches on `Return` alone and answers `\r` — the submit. The key the shortcuts sheet
+/// promises (`kTerminalOwnedKeys`) sent the turn instead of breaking the line.
+///
+/// ⌥ is Meta for THIS ONE KEY, not for the keyboard: Enter carries no character to compose, so
+/// prefixing it costs nothing that ⌥-as-compose needs, and the rest of the alphabet is untouched.
+///
+/// The base bytes are asked of [_inner] rather than written out here, because Return is not always
+/// `\r`: under LNM (`lineFeedMode`) the keytab answers `\r\n`, and a caller may pass a keytab of
+/// its own. Alt and Shift are cleared for that question — Alt so the keytab does not see the very
+/// modifier being translated, Shift so ⌥⇧⏎ yields a prefixed Return rather than a prefixed `\EOM`,
+/// which no prompt would recognise.
+class MetaEnterInputHandler implements TerminalInputHandler {
+ const MetaEnterInputHandler(this._inner);
+
+ final TerminalInputHandler _inner;
+
+ @override
+ String? call(TerminalKeyboardEvent event) {
+ final isEnter =
+ event.key == TerminalKey.enter || event.key == TerminalKey.numpadEnter;
+ // Ctrl+Alt+Enter is left alone: that chord belongs to whatever is running, not to this.
+ if (!isEnter || !event.alt || event.ctrl) return _inner(event);
+ final base = _inner(event.copyWith(alt: false, shift: false));
+ if (base == null) return null;
+ return '\x1b$base';
+ }
+}
+
+/// The handler every pane's [Terminal] is built with — xterm's default behaviour, plus ⌥⏎.
+const TerminalInputHandler harnessInputHandler = MetaEnterInputHandler(
+ defaultInputHandler,
+);
diff --git a/desktop/lib/terminal/terminal_session.dart b/desktop/lib/terminal/terminal_session.dart
index 713cc8f39..9258188c0 100644
--- a/desktop/lib/terminal/terminal_session.dart
+++ b/desktop/lib/terminal/terminal_session.dart
@@ -8,6 +8,7 @@ import 'package:xterm/xterm.dart';
import '../core/crash_log.dart';
import 'terminal_binary.dart';
+import 'terminal_input.dart';
import 'terminal_viewport.dart';
typedef TerminalFrameSender = Future<bool> Function(
@@ -777,6 +778,9 @@ class TerminalSession extends ChangeNotifier {
final result = Terminal(
maxLines: 10000,
platform: TerminalTargetPlatform.macos,
+ // ⌥⏎ has to become a Meta-prefixed Return before it reaches the pty, or the engine's prompt
+ // reads it as the submit it is byte-identical to. See [MetaEnterInputHandler].
+ inputHandler: harnessInputHandler,
// The remote pane owns its grid and redraws after resize. Reflowing TUI
// rows locally both changes their geometry and exercises an xterm.dart
// circular-buffer bug when a remote/local switch changes viewport size.
diff --git a/desktop/lib/widgets/terminal_composer.dart b/desktop/lib/widgets/terminal_composer.dart
index 68cc8322d..ff075eefe 100644
--- a/desktop/lib/widgets/terminal_composer.dart
+++ b/desktop/lib/widgets/terminal_composer.dart
@@ -106,7 +106,37 @@ class _TerminalComposerState extends State<TerminalComposer> {
}
}
- /// Enter sends; Shift+Enter is left to the field so it inserts a newline.
+ /// Breaks the line at the caret, for ⌥⏎.
+ ///
+ /// Written into the controller rather than left to the field, which is what Shift+Enter does:
+ /// AppKit turns ⌥⏎ into `insertNewlineIgnoringFieldEditor:`, a selector Flutter's text input
+ /// client does not answer, so passing the key through would drop it on the floor. Doing it here
+ /// also makes the behaviour the same on every platform the app builds for.
+ void _insertNewline() {
+ final value = _controller.value;
+ final selection = value.selection;
+ if (!selection.isValid) {
+ // No caret to speak of (the field has never been placed in). Append.
+ _controller.value = TextEditingValue(
+ text: '${value.text}\n',
+ selection: TextSelection.collapsed(offset: value.text.length + 1),
+ );
+ return;
+ }
+ _controller.value = TextEditingValue(
+ text:
+ '${selection.textBefore(value.text)}\n'
+ '${selection.textAfter(value.text)}',
+ selection: TextSelection.collapsed(offset: selection.start + 1),
+ );
+ }
+
+ /// Enter sends; ⌥⏎ and Shift+Enter compose another line.
+ ///
+ /// ⌥⏎ is the one the muscle memory comes with — it is how Claude Code and Codex take a second
+ /// line at their own prompts, and it is what the shortcuts sheet promises for a pane
+ /// (`kTerminalOwnedKeys`). The composer is the same prompt wearing a Flutter field, so it has to
+ /// answer the same key. Shift+Enter is left to the field, which inserts for it natively.
///
/// `TextField.onSubmitted` cannot do this — it never fires for a multi-line field.
KeyEventResult _onKeyEvent(FocusNode node, KeyEvent event) {
@@ -117,6 +147,10 @@ class _TerminalComposerState extends State<TerminalComposer> {
event.logicalKey == LogicalKeyboardKey.enter ||
event.logicalKey == LogicalKeyboardKey.numpadEnter;
if (!isEnter) return KeyEventResult.ignored;
+ if (HardwareKeyboard.instance.isAltPressed) {
+ _insertNewline();
+ return KeyEventResult.handled;
+ }
if (HardwareKeyboard.instance.isShiftPressed) return KeyEventResult.ignored;
unawaited(_submit());
return KeyEventResult.handled;
diff --git a/desktop/test/terminal_composer_test.dart b/desktop/test/terminal_composer_test.dart
index 1e278a1b7..73b58b1fb 100644
--- a/desktop/test/terminal_composer_test.dart
+++ b/desktop/test/terminal_composer_test.dart
@@ -355,6 +355,40 @@ void main() {
app.dispose();
});
+ testWidgets('Option+Enter adds a line instead of sending', (tester) async {
+ final outbound = <String>[];
+ final app = _notifier(local: false);
+ final session = await _liveSession(outbound);
+ await tester.pumpWidget(_host(app, session));
+ await tester.pump();
+
+ await tester.tap(find.byType(TextField));
+ await tester.pump();
+ await tester.enterText(find.byType(TextField), 'first');
+ await tester.pump();
+
+ await tester.sendKeyDownEvent(LogicalKeyboardKey.altLeft);
+ await tester.sendKeyEvent(LogicalKeyboardKey.enter);
+ await tester.sendKeyUpEvent(LogicalKeyboardKey.altLeft);
+ await tester.pump(const Duration(milliseconds: 12));
+
+ expect(outbound, isEmpty, reason: '⌥⏎ composes, it does not send');
+ // Unlike Shift+Enter, this newline IS observable: the composer writes it into the controller
+ // itself rather than handing the key to a text-input channel a widget test never runs.
+ expect(
+ tester.widget<TextField>(find.byType(TextField)).controller?.text,
+ 'first\n',
+ );
+
+ await tester.enterText(find.byType(TextField), 'first\nsecond');
+ await tester.pump();
+ await tester.sendKeyEvent(LogicalKeyboardKey.enter);
+ await tester.pump(const Duration(milliseconds: 12));
+ expect(outbound, ['first\nsecond']);
+ session.dispose();
+ app.dispose();
+ });
+
testWidgets('Ctrl+W deletes the last word', (tester) async {
final app = _notifier(local: false);
final session = await _liveSession([]);
diff --git a/desktop/test/terminal_input_test.dart b/desktop/test/terminal_input_test.dart
new file mode 100644
index 000000000..72011cd3f
--- /dev/null
+++ b/desktop/test/terminal_input_test.dart
@@ -0,0 +1,266 @@
+import 'dart:convert';
+
+import 'package:flutter/material.dart';
+import 'package:flutter/services.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:harness/auth/auth_session.dart';
+import 'package:harness/core/config.dart';
+import 'package:harness/core/models.dart';
+import 'package:harness/state/app_state.dart';
+import 'package:harness/terminal/terminal_binary.dart';
+import 'package:harness/terminal/terminal_input.dart';
+import 'package:harness/terminal/terminal_session.dart';
+import 'package:harness/widgets/terminal_panel.dart';
+import 'package:xterm/xterm.dart';
+
+Terminal _pane() => Terminal(
+ maxLines: 20,
+ platform: TerminalTargetPlatform.macos,
+ reflowEnabled: false,
+ inputHandler: harnessInputHandler,
+)..resize(80, 4);
+
+/// A pane on THIS computer, which is the case with no composer in front of it: the keystroke goes
+/// straight into the terminal, which is the path ⌥⏎ has to survive.
+AppNotifier _localNotifier() {
+ final app = AppNotifier(
+ config: AppConfig.dev,
+ authSession: AuthSession(),
+ configStore: null,
+ );
+ final machine = Machine(
+ machineId: 'm1',
+ apiKey: '',
+ authMode: MachineAuthMode.remote,
+ name: 'm1',
+ status: 'online',
+ );
+ app.machines = [machine];
+ app.machineStates['m1'] = MachineState(machine)..localOnly = true;
+ return app;
+}
+
+const _streamId = '00112233-4455-6677-8899-aabbccddeeff';
+
+/// A session past `terminal_ready` and its first keyframe, so it accepts input and the pane is
+/// live rather than frozen behind the ATTACHING overlay.
+Future<TerminalSession> _liveSession(List<TerminalBinaryFrame> wire) async {
+ Object? openRequestId;
+ final session = TerminalSession(
+ machineId: 'm1',
+ agentId: 'a1',
+ agentName: 'a1',
+ engineId: 'claude',
+ send: (type, payload) async {
+ if (type == 'terminal_open') openRequestId = payload['requestId'];
+ return true;
+ },
+ sendBinary: (frame) async {
+ wire.add(frame);
+ return true;
+ },
+ );
+ await session.open(initialCols: 80, initialRows: 24);
+ await session.handleFrame('terminal_ready', {
+ 'requestId': openRequestId,
+ 'protocolVersion': 3,
+ 'streamId': _streamId,
+ 'agentId': 'a1',
+ });
+ await session.handleBinary(
+ TerminalBinaryFrame(
+ kind: TerminalBinaryKind.keyframe,
+ streamId: _streamId,
+ seq: 0,
+ bytes: Uint8List.fromList(utf8.encode(r'$ ')),
+ compressed: false,
+ cols: 80,
+ rows: 24,
+ ),
+ );
+ return session;
+}
+
+Widget _host(AppNotifier app, TerminalSession session) => MaterialApp(
+ home: Scaffold(
+ body: SizedBox(
+ width: 900,
+ height: 400,
+ child: TerminalPanel(
+ notifier: app,
+ session: session,
+ focused: true,
+ composerVisible: false,
+ onToggleComposer: () {},
+ ),
+ ),
+ ),
+);
+
+/// What the input batcher actually put on the wire, joined — typing is coalesced behind a trailing
+/// timer, so the bytes are asserted after it fires rather than per frame.
+String _typed(List<TerminalBinaryFrame> wire) => utf8.decode([
+ for (final frame in wire)
+ if (frame.kind == TerminalBinaryKind.input) ...frame.bytes,
+]);
+
+void main() {
+ test('⌥⏎ reaches the engine as a Meta-prefixed Return, not a submit', () {
+ final out = <String>[];
+ final terminal = _pane()..onOutput = out.add;
+
+ terminal.keyInput(TerminalKey.enter, alt: true);
+
+ expect(out, ['\x1b\r']);
+ });
+
+ test('plain Enter still submits', () {
+ final out = <String>[];
+ final terminal = _pane()..onOutput = out.add;
+
+ terminal.keyInput(TerminalKey.enter);
+
+ expect(out, ['\r']);
+ });
+
+ test('⌥⏎ prefixes the numpad Return too', () {
+ final out = <String>[];
+ final terminal = _pane()..onOutput = out.add;
+
+ terminal.keyInput(TerminalKey.numpadEnter, alt: true);
+
+ expect(out, ['\x1b\r']);
+ });
+
+ test('⌥⇧⏎ breaks the line rather than sending SS3 M', () {
+ final out = <String>[];
+ final terminal = _pane()..onOutput = out.add;
+
+ terminal.keyInput(TerminalKey.enter, alt: true, shift: true);
+
+ expect(out, ['\x1b\r']);
+ });
+
+ test('the prefix follows the keytab under LNM, not a hardcoded \\r', () {
+ final out = <String>[];
+ final terminal = _pane()..onOutput = out.add;
+ terminal.write('\x1b[20h'); // LNM on: Return is \r\n from here.
+
+ terminal.keyInput(TerminalKey.enter, alt: true);
+
+ expect(out, ['\x1b\r\n']);
+ });
+
+ test('⌃⌥⏎ is left to whatever is running', () {
+ final out = <String>[];
+ final terminal = _pane()..onOutput = out.add;
+
+ terminal.keyInput(TerminalKey.enter, alt: true, ctrl: true);
+
+ expect(out, ['\r'], reason: 'the plain Return the keytab would have sent');
+ });
+
+ test('⌥ stays the compose key for every other letter', () {
+ final out = <String>[];
+ final terminal = _pane()..onOutput = out.add;
+
+ terminal.keyInput(TerminalKey.keyA, alt: true);
+
+ expect(out, isEmpty, reason: 'macOS composes å here; it is not Meta+a');
+ });
+
+ // The tests above call `keyInput` directly, which is the one step of this journey that was never
+ // in doubt. These drive a REAL key event through a REAL pane instead — xterm's shortcut map, the
+ // `_isPrintableText` deferral to the macOS IME, the ⌘ and ⌃⇥ escapes, `TerminalPanel._onTerminalKey`,
+ // then the session's input batcher — and assert the bytes that would leave for the daemon. That is
+ // the whole distance between the key and the engine's prompt.
+
+ testWidgets('⌥⏎ leaves a live pane as ESC + Return', (tester) async {
+ final wire = <TerminalBinaryFrame>[];
+ final app = _localNotifier();
+ final session = await _liveSession(wire);
+ await tester.pumpWidget(_host(app, session));
+ await tester.pump();
+
+ await tester.sendKeyDownEvent(
+ LogicalKeyboardKey.altLeft,
+ platform: 'macos',
+ );
+ await tester.sendKeyEvent(LogicalKeyboardKey.enter, platform: 'macos');
+ await tester.sendKeyUpEvent(LogicalKeyboardKey.altLeft, platform: 'macos');
+ await tester.pump(const Duration(milliseconds: 30));
+
+ expect(_typed(wire), '\x1b\r');
+ session.dispose();
+ app.dispose();
+ });
+
+ testWidgets('⌥⏎ survives the character macOS attaches to Return', (
+ tester,
+ ) async {
+ final wire = <TerminalBinaryFrame>[];
+ final app = _localNotifier();
+ final session = await _liveSession(wire);
+ await tester.pumpWidget(_host(app, session));
+ await tester.pump();
+
+ // Return can arrive carrying `\r` as its character. `_isPrintableText` must not mistake that
+ // for IME text and hand it to the platform, which would drop the key on the floor.
+ await tester.sendKeyDownEvent(
+ LogicalKeyboardKey.altLeft,
+ platform: 'macos',
+ );
+ await tester.sendKeyEvent(
+ LogicalKeyboardKey.enter,
+ character: '\r',
+ platform: 'macos',
+ );
+ await tester.sendKeyUpEvent(LogicalKeyboardKey.altLeft, platform: 'macos');
+ await tester.pump(const Duration(milliseconds: 30));
+
+ expect(_typed(wire), '\x1b\r');
+ session.dispose();
+ app.dispose();
+ });
+
+ testWidgets('a plain Return off the same pane still submits', (tester) async {
+ final wire = <TerminalBinaryFrame>[];
+ final app = _localNotifier();
+ final session = await _liveSession(wire);
+ await tester.pumpWidget(_host(app, session));
+ await tester.pump();
+
+ await tester.sendKeyEvent(LogicalKeyboardKey.enter, platform: 'macos');
+ await tester.pump(const Duration(milliseconds: 30));
+
+ expect(_typed(wire), '\r');
+ session.dispose();
+ app.dispose();
+ });
+
+ testWidgets('⌥ + a letter is still composed, not sent as Meta', (
+ tester,
+ ) async {
+ final wire = <TerminalBinaryFrame>[];
+ final app = _localNotifier();
+ final session = await _liveSession(wire);
+ await tester.pumpWidget(_host(app, session));
+ await tester.pump();
+
+ await tester.sendKeyDownEvent(
+ LogicalKeyboardKey.altLeft,
+ platform: 'macos',
+ );
+ await tester.sendKeyEvent(
+ LogicalKeyboardKey.keyA,
+ character: 'a',
+ platform: 'macos',
+ );
+ await tester.sendKeyUpEvent(LogicalKeyboardKey.altLeft, platform: 'macos');
+ await tester.pump(const Duration(milliseconds: 30));
+
+ expect(_typed(wire), isEmpty, reason: 'the IME owns ⌥a, and it makes å');
+ session.dispose();
+ app.dispose();
+ });
+}