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.

Open the companion terminal from memory learning notices (#665)

Dee3979e5c8aa34
diff --git a/desktop/design/desktop-ui-migration.md b/desktop/design/desktop-ui-migration.md
index 0cd4624d4..217cbd7fc 100644
--- a/desktop/design/desktop-ui-migration.md
+++ b/desktop/design/desktop-ui-migration.md
@@ -665,3 +665,16 @@ unmerged.
and [Companions at 200% text](../../docs/research/2026-10-02-experimental-store/companions-light-large-text.png)
in a narrow light window. These widget renders do not establish native VoiceOver or physical
IME behavior. The installed desktop app was not replaced.
+
+### Companion memory recovery, 2026-10-03
+
+- A learning notice can open the existing companion terminal from Memories.
+ The action waits while opening, supports explicit retry, preserves the DSH
+ split and ignores stale owner/companion callbacks. Learn and Recall stay as set.
+- [Native fixture renders](../../docs/research/2026-10-03-memory-recovery.md)
+ cover waiting, failed resume and recovery; light/dark narrow VM renders use
+ 200% text. The complete native recovery journey and synthetic key delivery
+ passed. The final native run also observed foreground focus; both cases passed.
+ Earlier foreground failures remain documented, with no established cause or
+ production focus fix. Physical AppKit input and VoiceOver remain unverified;
+ no installed app or real companion was changed.
diff --git a/desktop/integration_test/native_memory_companion_recovery_test.dart b/desktop/integration_test/native_memory_companion_recovery_test.dart
new file mode 100644
index 000000000..8b91115b2
--- /dev/null
+++ b/desktop/integration_test/native_memory_companion_recovery_test.dart
@@ -0,0 +1,56 @@
+import 'dart:io';
+
+import 'package:flutter/material.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:harness/core/test_run.dart';
+import 'package:integration_test/integration_test.dart';
+import 'package:window_manager/window_manager.dart';
+
+import '../test/memory_companion_recovery_test.dart' as recovery;
+
+/// The same complete workspace journey uses in-memory stores and fake transports.
+/// It cannot run with production pollers enabled or launch a real companion.
+void main() {
+ if (!kUnderTest) {
+ throw StateError('Native memory recovery requires FLUTTER_TEST=1');
+ }
+ IntegrationTestWidgetsFlutterBinding.ensureInitialized();
+ setUpAll(() async {
+ await windowManager.ensureInitialized();
+ await windowManager.setSize(const Size(1280, 1000));
+ });
+ testWidgets('native recovery test window has foreground focus', (tester) async {
+ // Check a rendered window: AppKit activation is asynchronous, and this
+ // fixture otherwise reaches the assertion before mounting its first frame.
+ await tester.pumpWidget(
+ const MaterialApp(
+ home: Scaffold(body: Text('Synthetic memory recovery fixture')),
+ ),
+ );
+ await windowManager.show();
+ await windowManager.focus();
+ // A native reviewer can activate this exact synthetic window when the
+ // platform launcher cannot foreground it. The assertion remains required.
+ final manualReview =
+ Platform.environment['HARNESS_NATIVE_FOCUS_REVIEW'] == '1';
+ if (manualReview) {
+ debugPrint('Synthetic memory fixture is ready for foreground review.');
+ }
+ final focusTimeout = Duration(seconds: manualReview ? 60 : 3);
+ final deadline = Stopwatch()..start();
+ var focused = await windowManager.isFocused();
+ while (!focused && deadline.elapsed < focusTimeout) {
+ await tester.pump(const Duration(milliseconds: 100));
+ focused = await windowManager.isFocused();
+ }
+ expect(
+ focused,
+ isTrue,
+ reason:
+ 'Native focus after a rendered frame and bounded activation wait '
+ '(visible=${await windowManager.isVisible()}, '
+ 'minimized=${await windowManager.isMinimized()}).',
+ );
+ });
+ recovery.memoryCompanionRecoveryTests(native: true);
+}
diff --git a/desktop/lib/companions/coding_memory_view.dart b/desktop/lib/companions/coding_memory_view.dart
index 67c5e76c5..b31011e3d 100644
--- a/desktop/lib/companions/coding_memory_view.dart
+++ b/desktop/lib/companions/coding_memory_view.dart
@@ -22,8 +22,15 @@ part 'coding_memory_activity_view.dart';
/// The collection's owner library; it does not send chat or terminal input.
class CodingMemoryView extends StatefulWidget {
- const CodingMemoryView({super.key, required this.library});
+ const CodingMemoryView({
+ super.key,
+ required this.library,
+ this.onOpenCompanion,
+ this.openingCompanion = false,
+ });
final CodingMemoryLibrary library;
+ final VoidCallback? onOpenCompanion;
+ final bool openingCompanion;
@override
State<CodingMemoryView> createState() => _CodingMemoryViewState();
}
@@ -32,6 +39,28 @@ class _CodingMemoryViewState extends State<CodingMemoryView> {
String section = 'How you work';
CodingMemoryLibrary get library => widget.library;
+ bool get _showConversationAction {
+ final runtime = memoryMap(library.status?['runtime']);
+ return library.valid &&
+ library.learn &&
+ runtime['state'] == 'ready' &&
+ memoryMap(runtime['learning'])['state'] == 'waiting_for_model' &&
+ (widget.onOpenCompanion != null || widget.openingCompanion);
+ }
+
+ Widget _conversationAction() => TextButton(
+ key: const ValueKey('memory-open-companion'),
+ onPressed: library.busy || widget.openingCompanion
+ ? null
+ : () {
+ // A stale rendered control cannot act after learning or ownership changes.
+ if (_showConversationAction) widget.onOpenCompanion?.call();
+ },
+ child: Text(
+ widget.openingCompanion ? 'Opening terminal…' : 'Open companion terminal',
+ ),
+ );
+
@override
void didUpdateWidget(CodingMemoryView oldWidget) {
super.didUpdateWidget(oldWidget);
@@ -118,11 +147,18 @@ class _CodingMemoryViewState extends State<CodingMemoryView> {
const SizedBox(height: 8),
_text(learning.captureIssue!),
],
- TextButton(
- onPressed: library.busy
- ? null
- : () => _selectSection('Learning'),
- child: const Text('Review learning'),
+ Wrap(
+ spacing: 8,
+ runSpacing: 8,
+ children: [
+ if (_showConversationAction) _conversationAction(),
+ TextButton(
+ onPressed: library.busy
+ ? null
+ : () => _selectSection('Learning'),
+ child: const Text('Review learning'),
+ ),
+ ],
),
const SizedBox(height: 16),
],
@@ -195,6 +231,7 @@ class _CodingMemoryViewState extends State<CodingMemoryView> {
crossAxisAlignment: CrossAxisAlignment.start,
children: [
_text(learning.message),
+ if (_showConversationAction) _conversationAction(),
if (learning.captureIssue != null) ...[
const SizedBox(height: 8),
_text(learning.captureIssue!),
diff --git a/desktop/lib/companions/companion_home.dart b/desktop/lib/companions/companion_home.dart
index 174e25a24..0e523efa2 100644
--- a/desktop/lib/companions/companion_home.dart
+++ b/desktop/lib/companions/companion_home.dart
@@ -36,6 +36,7 @@ class CompanionHome extends StatefulWidget {
required this.onHatch,
required this.onOpenControls,
this.onOpenConversation,
+ this.openingConversation = false,
this.terminalStatus,
this.dial,
this.onDeviceSettings,
@@ -46,6 +47,7 @@ class CompanionHome extends StatefulWidget {
final ValueChanged<ZooEgg> onHatch;
final ValueChanged<String> onOpenControls;
final VoidCallback? onOpenConversation;
+ final bool openingConversation;
final String? terminalStatus;
final DialState? dial;
final void Function(String, Map<String, Object?>)? onDeviceSettings;
@@ -283,9 +285,10 @@ class _CompanionHomeState extends State<CompanionHome> {
child: switch (_section) {
'Collection' => _collection(),
'Memories' => _memories(),
- _ => zoo.zoo.daemons.isEmpty && _previewSpecies == null
- ? _nest()
- : _story(),
+ _ =>
+ zoo.zoo.daemons.isEmpty && _previewSpecies == null
+ ? _nest()
+ : _story(),
},
),
),
@@ -812,7 +815,12 @@ class _CompanionHomeState extends State<CompanionHome> {
style: ink(15, AppColors.textSoft),
),
const SizedBox(height: 28),
- if (_codingMemory != null) CodingMemoryView(library: _codingMemory!),
+ if (_codingMemory != null)
+ CodingMemoryView(
+ library: _codingMemory!,
+ onOpenCompanion: widget.onOpenConversation,
+ openingCompanion: widget.openingConversation,
+ ),
if (widget.brain.active && _codingMemory?.available != true) ...[
_memoryCard(
AppIcons.history,
diff --git a/desktop/lib/screens/swarm_screen.dart b/desktop/lib/screens/swarm_screen.dart
index 9adf8bffb..67c062a30 100644
--- a/desktop/lib/screens/swarm_screen.dart
+++ b/desktop/lib/screens/swarm_screen.dart
@@ -4210,6 +4210,31 @@ class _SwarmScreenState extends State<SwarmScreen> {
return result;
}
+ bool get _canOpenCompanionTerminal =>
+ mounted &&
+ _creatureEnabled &&
+ _zoo.loaded &&
+ !_zoo.isPreview &&
+ _zoo.paired != null &&
+ _brain.active &&
+ _companionOpeningKey == null;
+
+ VoidCallback? _companionConversationAction() {
+ if (!_canOpenCompanionTerminal) return null;
+ final key = '${_zoo.scope}:${_zoo.paired!.uid}';
+ final machineId = app.localMachineState?.machine.machineId;
+ return () {
+ if (!_canOpenCompanionTerminal ||
+ key != '${_zoo.scope}:${_zoo.paired?.uid}' ||
+ machineId != app.localMachineState?.machine.machineId) {
+ return;
+ }
+ _companionAttemptedKey = null;
+ _focusCompanionTerminal = true;
+ _scheduleCompanionWorkspace();
+ };
+ }
+
Widget _companionViewer(BuildContext context) => !_zoo.loaded
? const Center(child: Text('Opening your collection…'))
: CompanionHome(
@@ -4226,13 +4251,8 @@ class _SwarmScreenState extends State<SwarmScreen> {
(_companionOpeningKey != null
? 'Opening your companion’s terminal…'
: null),
- onOpenConversation: _companionTerminalError == null
- ? null
- : () {
- _companionAttemptedKey = null;
- _focusCompanionTerminal = true;
- _scheduleCompanionWorkspace();
- },
+ onOpenConversation: _companionConversationAction(),
+ openingConversation: _companionOpeningKey != null,
dial: app.dial,
onDeviceSettings: app.setDeviceSettings,
);
diff --git a/desktop/test/coding_memory_view_test.dart b/desktop/test/coding_memory_view_test.dart
index 77a3e82d0..3ec917789 100644
--- a/desktop/test/coding_memory_view_test.dart
+++ b/desktop/test/coding_memory_view_test.dart
@@ -46,6 +46,8 @@ void main() {
Brightness brightness = Brightness.dark,
double scale = 1,
Size size = const Size(850, 850),
+ VoidCallback? onOpenCompanion,
+ bool openingCompanion = false,
}) async {
tester.view.physicalSize = size;
tester.view.devicePixelRatio = 1;
@@ -75,7 +77,11 @@ void main() {
home: Scaffold(
body: SingleChildScrollView(
padding: const EdgeInsets.all(24),
- child: CodingMemoryView(library: library),
+ child: CodingMemoryView(
+ library: library,
+ onOpenCompanion: onOpenCompanion,
+ openingCompanion: openingCompanion,
+ ),
),
),
),
@@ -1189,6 +1195,99 @@ void main() {
});
}
+ for (final reason in [
+ 'companion_unopened',
+ 'companion_stopped',
+ 'inference_provider_restricted',
+ ]) {
+ testWidgets('memory recovery explicitly opens the companion for $reason', (
+ tester,
+ ) async {
+ var opened = 0;
+ transport.runtime = {
+ 'state': 'ready',
+ 'learning': {'state': 'waiting_for_model', 'reason': reason},
+ };
+ await mount(tester, onOpenCompanion: () => opened++);
+ expect(opened, 0, reason: 'Reading memories cannot launch an agent.');
+ await tap(tester, 'Open companion terminal');
+ expect(opened, 1);
+ await tap(tester, 'Review learning');
+ await tap(tester, 'Open companion terminal');
+ expect(opened, 2);
+ expect(transport.learn, isTrue);
+ expect(transport.recall, isTrue);
+ expect(
+ transport.calls.where(
+ (p) => ['preview', 'apply'].contains(p['action']),
+ ),
+ isEmpty,
+ );
+ transport.runtime = {
+ 'state': 'ready',
+ 'learning': {'state': 'learned', 'learned': 1},
+ };
+ await library.refresh();
+ await tester.pumpAndSettle();
+ expect(find.text('Open companion terminal'), findsNothing);
+ });
+ }
+
+ testWidgets(
+ 'pending recovery is disabled, while a paused or stale owner cannot open it',
+ (tester) async {
+ var opened = 0;
+ transport.runtime = {
+ 'state': 'ready',
+ 'learning': {
+ 'state': 'waiting_for_model',
+ 'reason': 'companion_stopped',
+ },
+ };
+ await mount(
+ tester,
+ onOpenCompanion: () => opened++,
+ openingCompanion: true,
+ );
+ expect(
+ tester
+ .widget<TextButton>(
+ find.byKey(const ValueKey('memory-open-companion')),
+ )
+ .onPressed,
+ isNull,
+ );
+ expect(find.text('Opening terminal…'), findsOneWidget);
+ expect(opened, 0);
+
+ await mount(tester, onOpenCompanion: () => opened++);
+ final stale = tester
+ .widget<TextButton>(
+ find.byKey(const ValueKey('memory-open-companion')),
+ )
+ .onPressed!;
+ transport.learn = false;
+ await library.refresh();
+ stale();
+ await tester.pumpAndSettle();
+ expect(opened, 0);
+ expect(find.text('Open companion terminal'), findsNothing);
+ transport.learn = true;
+ await library.refresh();
+ await tester.pumpAndSettle();
+ final oldOwner = tester
+ .widget<TextButton>(
+ find.byKey(const ValueKey('memory-open-companion')),
+ )
+ .onPressed!;
+ transport.invalidate();
+ oldOwner();
+ expect(opened, 0);
+ await tester.pumpAndSettle();
+ expect(find.text('Open companion terminal'), findsNothing);
+ },
+ );
+
for (final reason in [
('companion_unopened', 'Start your companion'),
('companion_stopped', 'Reopen its conversation'),
@@ -1257,6 +1356,7 @@ void main() {
brightness: brightness,
scale: 2,
size: const Size(440, 1100),
+ onOpenCompanion: () {},
);
expect(find.textContaining('Reopen its conversation'), findsOneWidget);
expect(find.textContaining('queue is full'), findsOneWidget);
diff --git a/desktop/test/memory_companion_recovery_test.dart b/desktop/test/memory_companion_recovery_test.dart
new file mode 100644
index 000000000..b7dc65e40
--- /dev/null
+++ b/desktop/test/memory_companion_recovery_test.dart
@@ -0,0 +1,350 @@
+import 'dart:io';
+import 'dart:ui' as ui;
+
+import 'package:flutter/material.dart';
+import 'package:flutter/rendering.dart';
+import 'package:flutter/services.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:harness/auth/auth_session.dart';
+import 'package:harness/companions/coding_memory_connection.dart';
+import 'package:harness/companions/coding_memory_view.dart';
+import 'package:harness/companions/companion_home.dart';
+import 'package:harness/core/config.dart';
+import 'package:harness/core/models.dart';
+import 'package:harness/daemons/zoo.dart';
+import 'package:harness/daemons/zoo_controller.dart';
+import 'package:harness/screens/swarm_screen.dart';
+import 'package:harness/settings/experimental_features.dart';
+import 'package:harness/shared/theme/app_theme.dart' as grid;
+import 'package:harness/state/app_state.dart';
+import 'package:harness/state/pane_arrangement.dart';
+import 'package:harness/state/pane_layout_store.dart';
+import 'package:harness/state/swarm_catalog.dart';
+import 'package:harness/terminal/terminal_binary.dart';
+import 'package:harness/ws/local_cli_discovery.dart';
+import 'package:xterm/xterm.dart';
+
+import 'daemons/zoo_test.dart' show FakeZooTransport;
+import 'support/coding_memory_fixture.dart';
+import 'support/experimental_settings.dart';
+import 'support/real_fonts.dart';
+import 'swarm_screen_test.dart' show terminal;
+import 'swarm_state_test.dart' show MemoryStore;
+
+class _MemoryWorkspace extends AppNotifier {
+ _MemoryWorkspace(this.memory)
+ : super(
+ config: AppConfig.dev,
+ authSession: AuthSession(),
+ configStore: null,
+ paneLayoutStore: PaneLayoutStore(storage: MemoryStore()),
+ );
+
+ final MemoryFixture memory;
+
+ @override
+ CodingMemoryConnection? openCodingMemoryConnection() => memory;
+}
+
+void main() => memoryCompanionRecoveryTests();
+
+void memoryCompanionRecoveryTests({bool native = false}) {
+ TestWidgetsFlutterBinding.ensureInitialized();
+ setUpAll(loadRealFonts);
+
+ testWidgets(
+ 'Memories reopens the same companion after failure without duplicate requests or changing its DSH',
+ (tester) async {
+ final memory = MemoryFixture()
+ ..runtime = {
+ 'state': 'ready',
+ 'learning': {
+ 'state': 'waiting_for_model',
+ 'reason': 'companion_stopped',
+ },
+ 'capture': {'state': 'unavailable', 'reason': 'memory_backlog_full'},
+ };
+ final app = _MemoryWorkspace(memory)
+ ..hasNavigationRail = false
+ ..currentUser = const CurrentUserProfile(
+ id: 'owner',
+ email: '[email protected]',
+ );
+ addTearDown(app.dispose);
+ const machine = Machine(
+ machineId: 'm',
+ authMode: MachineAuthMode.remote,
+ name: 'Fixture',
+ );
+ app.machines = [machine];
+ app.machineStates['m'] = MachineState(machine)
+ ..nodeOnline = true
+ ..connectionStatus = ConnectionStatus.connected
+ ..agentLoadStatus = AgentLoadStatus.loaded
+ ..localEndpoint = LocalCliEndpoint(
+ computerId: 'fixture',
+ wsUri: Uri.parse('ws://fixture.invalid'),
+ protocolVersion: 1,
+ terminalProtocolVersion: 3,
+ )
+ ..agents = [
+ const Agent(
+ id: 'pair-one',
+ name: 'Companions',
+ engine: 'codex',
+ dsh: 'autonomous/pair',
+ terminalAvailable: true,
+ ),
+ ];
+ final frames = <(String, Map<String, dynamic>)>[];
+ app.daemonFrameSenderForTest = (type, payload) {
+ frames.add((type, payload));
+ return true;
+ };
+ final input = <TerminalBinaryFrame>[];
+ final conversation = terminal('pair-one', input);
+ conversation.terminal.write(
+ 'Companion terminal (synthetic fixture)\r\n\r\n> ',
+ );
+ app.adoptSessionForTest(conversation);
+ final experiments = MemoryExperimentalFeaturesStore(
+ storage: MemoryStore(),
+ );
+ await experiments.set(ExperimentalFeature.focusBarCreature, true);
+ final zoo = ZooController();
+ final preview = ValueNotifier(true);
+ addTearDown(experiments.dispose);
+ addTearDown(zoo.dispose);
+ addTearDown(preview.dispose);
+ final remote = FakeZooTransport()
+ ..revision = 1
+ ..zoo = Zoo(
+ daemons: [
+ ZooDaemon(uid: 'tim-one', id: 'tim', hatched: '', egg: 'first'),
+ ],
+ pair: 'tim-one',
+ firstEgg: true,
+ consent: const ZooConsent(watching: true, at: '2026-10-03T00:00:00Z'),
+ );
+ if (!native) {
+ tester.view.devicePixelRatio = 1;
+ tester.view.physicalSize = const Size(1280, 1000);
+ addTearDown(tester.view.reset);
+ }
+ final boundary = GlobalKey();
+ Future<void> capture(String name) async {
+ final directory =
+ Platform.environment['HARNESS_MEMORY_WORKSPACE_CAPTURE_DIR'];
+ if (directory == null) return;
+ await tester.runAsync(() async {
+ final image =
+ await (boundary.currentContext!.findRenderObject()!
+ as RenderRepaintBoundary)
+ .toImage(pixelRatio: 1);
+ final bytes = await image.toByteData(format: ui.ImageByteFormat.png);
+ await Directory(directory).create(recursive: true);
+ await File('$directory/$name.png')
+ .writeAsBytes(bytes!.buffer.asUint8List());
+ image.dispose();
+ });
+ }
+
+ Future<void> frame(String type, Map<String, dynamic> payload) async {
+ await app.handleMachineEventForTest('m', {
+ 'type': type,
+ 'payload': payload,
+ });
+ await tester.pump();
+ }
+
+ Iterable<(String, Map<String, dynamic>)> opens() =>
+ frames.where((f) => f.$1 == 'daemon_open');
+ Future<void> answerOpen(bool ok) => frame('daemon_open_result', {
+ 'requestId': opens().last.$2['requestId'],
+ 'ok': ok,
+ if (ok) 'agentId': 'pair-one',
+ if (ok) 'engine': 'codex',
+ if (!ok) 'error': 'RESUME_FAILED',
+ });
+
+ await tester.pumpWidget(
+ RepaintBoundary(
+ key: boundary,
+ child: MaterialApp(
+ theme: grid.buildAppTheme(brightness: Brightness.dark),
+ home: SwarmScreen(
+ notifier: app,
+ experimentalFeatures: experiments,
+ projectStore: SwarmProjectStore(),
+ zoo: zoo,
+ zooTransport: remote,
+ daemonClock: () => tester.binding.clock.now(),
+ daemonsPreview: preview,
+ ),
+ ),
+ ),
+ );
+ await tester.pump(const Duration(milliseconds: 100));
+ await frame('daemon_state', {
+ 'pair': 'tim',
+ 'companionHarness': {'agentId': 'pair-one', 'engine': 'codex'},
+ 'needs': [],
+ 'working': 0,
+ 'failing': [],
+ 'machines': [],
+ 'done': {'count': 0, 'last': []},
+ 'asks': [],
+ 'acted': [],
+ });
+ await tester.tap(find.byKey(const ValueKey('daemon-slot')));
+ await tester.pump();
+ await tester.pump();
+ expect(opens(), hasLength(1));
+ await answerOpen(true);
+ await tester.pump();
+ final tab = app.activeSwarm;
+ final paneIds = app.panes.map((p) => p.id).toList();
+ final tabIds = app.swarms.map((s) => s.id).toList();
+ expect(tab.isCompanions, isTrue);
+ expect(
+ tab.manualLayout!.tiles,
+ PaneArrangement.viewerBesideTerminal.tiles,
+ );
+
+ void expectSplit(double fraction) {
+ final left = tester.getRect(
+ find.byKey(ValueKey('pane-frame:${paneIds.first}')),
+ );
+ final right = tester.getRect(
+ find.byKey(ValueKey('pane-frame:${paneIds.last}')),
+ );
+ expect(left.right, lessThanOrEqualTo(right.left));
+ expect(left.width / (left.width + right.width), closeTo(fraction, .02));
+ }
+
+ expectSplit(.7);
+ final resized = PaneArrangement(const [
+ Rect.fromLTRB(0, 0, .62, 1),
+ Rect.fromLTRB(.62, 0, 1, 1),
+ ]);
+ tab.savePaneSizes('2:manual', resized);
+ app.stateOf('m')!.agents[0] = app
+ .stateOf('m')!
+ .agents[0]
+ .copyWith(status: 'stopped');
+ app.notifyListeners();
+ await tester.pump();
+ await tester.tap(find.byKey(const ValueKey('companion-nav-Memories')));
+ await tester.pump();
+ for (final request in frames.where((f) => f.$1 == 'pair').toList()) {
+ await frame('pair_result', {
+ 'requestId': request.$2['requestId'],
+ 'ok': true,
+ 'lessons': [],
+ });
+ }
+ await tester.pump();
+ final action = find.byKey(const ValueKey('memory-open-companion'));
+ expect(action, findsOneWidget);
+ expect(
+ opens(),
+ hasLength(1),
+ reason: 'Reading the blocked state does not resume the agent.',
+ );
+ final retained = tester
+ .widget<CompanionHome>(find.byType(CompanionHome))
+ .onOpenConversation!;
+ await tester.ensureVisible(action);
+ await capture('memory-recovery-waiting');
+ await tester.tap(action);
+ await tester.pump();
+ await tester.pump();
+ expect(opens(), hasLength(2));
+ expect(tester.widget<TextButton>(action).onPressed, isNull);
+ retained();
+ await tester.pump();
+ expect(
+ opens(),
+ hasLength(2),
+ reason: 'An already-rendered callback cannot duplicate pending work.',
+ );
+ expectSplit(.62);
+
+ await answerOpen(false);
+ await tester.pump();
+ expect(action, findsOneWidget);
+ expect(tester.widget<TextButton>(action).onPressed, isNotNull);
+ expectSplit(.62);
+ await tester.ensureVisible(action);
+ await capture('memory-recovery-retry');
+ await tester.tap(action);
+ await tester.pump();
+ await tester.pump();
+ expect(opens(), hasLength(3));
+ app.stateOf('m')!.agents[0] = app
+ .stateOf('m')!
+ .agents[0]
+ .copyWith(status: 'active');
+ await answerOpen(true);
+ await tester.pump();
+ expect(app.activeSwarm, same(tab));
+ expect(app.swarms.map((s) => s.id), tabIds);
+ expect(app.panes.map((p) => p.id), paneIds);
+ expect(app.panes.last.agentId, 'pair-one');
+ expect(app.panes.last.session, same(conversation));
+ expect(app.focusedPane!.id, paneIds.last);
+ expect(tab.manualLayout, same(resized));
+ expectSplit(.62);
+ final view = tester.widget<TerminalView>(find.byType(TerminalView));
+ expect(view.focusNode!.hasFocus, isTrue);
+ expect(input, isEmpty, reason: 'Recovery sends no terminal input.');
+ await tester.sendKeyEvent(LogicalKeyboardKey.arrowRight);
+ await tester.pump(const Duration(milliseconds: 30));
+ expect(input.single.bytes, [27, 91, 67]);
+ await capture('memory-recovery-resumed');
+ expect(
+ opens().every(
+ (f) =>
+ f.$2['companionUid'] == 'tim-one' &&
+ !f.$2.containsKey('engine') &&
+ !f.$2.containsKey('text'),
+ ),
+ isTrue,
+ );
+ expect(frames.where((f) => f.$1 == 'daemon_talk'), isEmpty);
+ expect(
+ memory.calls.where((p) => ['preview', 'apply'].contains(p['action'])),
+ isEmpty,
+ );
+ expect(memory.learn, isTrue);
+ expect(memory.recall, isTrue);
+
+ memory.runtime = {
+ 'state': 'ready',
+ 'learning': {'state': 'learned', 'learned': 1},
+ };
+ await tester
+ .widget<CodingMemoryView>(find.byType(CodingMemoryView))
+ .library
+ .refresh();
+ await tester.pump();
+ expect(action, findsNothing);
+ final oldOwner = tester
+ .widget<CompanionHome>(find.byType(CompanionHome))
+ .onOpenConversation!;
+ app.currentUser = const CurrentUserProfile(
+ id: 'another-owner',
+ email: '[email protected]',
+ );
+ app.notifyListeners();
+ await tester.pump();
+ final count = opens().length;
+ oldOwner();
+ await tester.pump();
+ expect(opens(), hasLength(count));
+ expect(tester.takeException(), isNull);
+ await tester.pumpWidget(const SizedBox());
+ await tester.pump(const Duration(seconds: 11));
+ },
+ );
+}
diff --git a/docs/plans/2026-09-30-coding-memory-review-log.md b/docs/plans/2026-09-30-coding-memory-review-log.md
index 741fe4ff1..48c375757 100644
--- a/docs/plans/2026-09-30-coding-memory-review-log.md
+++ b/docs/plans/2026-09-30-coding-memory-review-log.md
@@ -1106,3 +1106,22 @@ The candidate was rejected and archived with its exact patch and evidence.
Production remains v6. No further private model call, native setting change,
release or installation followed. This closes the compact-defaults experiment,
not the live-learning blockage or the broader memory quality gates.
+
+### Reach the existing companion from a learning notice — October 3
+
+Memories now offers **Open companion terminal** when learning is waiting for its
+model. The action uses the same conversation in the existing DSH, is disabled
+while opening, and supports retry after failure. Rendering the notice does not
+trigger it. Stale owner/companion actions and paused learning are guarded; model
+selection, setup and trust remain in the real terminal.
+
+The [recovery review](../research/2026-10-03-memory-recovery.md) records layout,
+identity, retry, ownership and synthetic key-delivery checks. The native recovery
+journey passed across native attempts. Earlier foreground checks failed even
+after mounting a first frame and waiting three seconds. The final native command
+passed both cases, observing focus within its first second without a manual
+click; it allowed a bounded native review but needed no app-control action.
+The intermittent startup-focus cause remains unestablished. Physical input and
+the actual live model still need verification. This supplies a missing user
+action without claiming that the installed stopped conversation or its provider
+refusal was resolved.
diff --git a/docs/research/2026-10-03-memory-recovery.md b/docs/research/2026-10-03-memory-recovery.md
new file mode 100644
index 000000000..c48d5f9b3
--- /dev/null
+++ b/docs/research/2026-10-03-memory-recovery.md
@@ -0,0 +1,52 @@
+# Recover the companion from Memories
+
+When learning is waiting for the companion's model, **Open companion terminal**
+now appears beside the explanation and on the Learning page. It uses the existing
+DSH conversation path, keeps the selected agent, and focuses its real terminal.
+Reading Memories does not invoke this action. Pending opens disable it; a failure
+allows another explicit attempt. Paused learning, unavailable ownership and stale
+companion/account callbacks cannot activate it.
+
+The workspace fixture checks initial 70/30 placement, a preserved 62/38 resize,
+failure/retry, duplicate pending activation, retained tab/pane/conversation IDs,
+focus and synthetic keyboard delivery. Recovery sends no chat text and changes
+neither Learn nor Recall. Agent setup and provider/model choices stay in the
+existing terminal. Opening that terminal does not by itself resolve a provider
+refusal or certify successful learning.
+
+The native renderer captured the synthetic
+[waiting workspace](2026-10-03-memory-recovery/native-waiting.png),
+[failed attempt with retry](2026-10-03-memory-recovery/native-retry.png), and
+[resumed terminal](2026-10-03-memory-recovery/native-resumed.png).
+The last image precedes the simulated learning-status refresh; the recovery
+action disappears after that refresh. The VM renders cover
+[dark](2026-10-03-memory-recovery/dark-large-text.png) and
+[light](2026-10-03-memory-recovery/light-large-text.png) appearance at 440×1100
+and 200% text. These contain only fixture data.
+
+Changed-file analysis and 143 affected VM tests passed. After adding explicit
+keyboard assertions, the targeted VM journey passed again. The final native
+command **passed both cases**: the native window reported foreground focus,
+and the complete recovery journey passed, including synthetic keyboard dispatch.
+The native images above come from that final run.
+
+Earlier native commands failed the separate foreground assertion while the
+recovery journey passed. Mounting a first frame and allowing three seconds did
+not resolve the failure: the window was visible and not minimized, but not
+focused. The final run enabled `HARNESS_NATIVE_FOCUS_REVIEW=1`, which permits a
+reviewer to activate the exact synthetic window within 60 seconds while keeping
+the assertion required. Focus was observed within the first second, without a
+manual click or any app-control action. Flutter still printed its launcher
+warning, `Failed to foreground app; open returned 1`.
+
+The earlier failures remain failed; the intermittent startup-focus cause is
+unestablished. This is not a production focus fix or proof that launcher
+activation is reliable. Physical AppKit keyboard/IME and VoiceOver behavior
+remain unverified. The [evidence manifest](2026-10-03-memory-recovery/evidence.json)
+binds the final images and source, and retains the separate outcomes.
+
+The native fixture uses `FLUTTER_TEST=1`, `HARNESS_TEST=true`, in-memory persistence
+and fake memory/agent transports. It does not read real conversations or launch
+a real companion. The installed app, daemon, model, account and memory were not
+changed. This is a recovery affordance, not completion of the live-learning,
+semantic-quality or coding-benefit requirements.
diff --git a/docs/research/2026-10-03-memory-recovery/dark-large-text.png b/docs/research/2026-10-03-memory-recovery/dark-large-text.png
new file mode 100644
index 000000000..b4b9416dc
Binary files /dev/null and b/docs/research/2026-10-03-memory-recovery/dark-large-text.png differ
diff --git a/docs/research/2026-10-03-memory-recovery/evidence.json b/docs/research/2026-10-03-memory-recovery/evidence.json
new file mode 100644
index 000000000..42aaee8fe
--- /dev/null
+++ b/docs/research/2026-10-03-memory-recovery/evidence.json
@@ -0,0 +1,94 @@
+{
+ "schemaVersion": 1,
+ "baseCommit": "6052d9f4b33248316d4591f78465fd6975fa2c60",
+ "evidence": "Synthetic fixture only; no real agent/model/owner data or live recovery.",
+ "sourceSha256": {
+ "desktop/lib/companions/coding_memory_view.dart": "c5efa081550c209297d5335e50e73573a8d0e0b726657c8a1e195e8176573039",
+ "desktop/lib/companions/companion_home.dart": "96fca204df0634bf2a9e48e3d2cf0c40acc6a18f0c757fff1636f59acd3311eb",
+ "desktop/lib/screens/swarm_screen.dart": "6269670b2bf3de3ecb89f41e0750ab8c01a4b474eaba4c1c0b22c48622301d6c",
+ "desktop/test/coding_memory_view_test.dart": "aed8930292ec1935043b25cae03b67d30bdf6081779593024f30d53be71f23ea",
+ "desktop/test/memory_companion_recovery_test.dart": "441de7376b04275ba225351e1a31bfa5177df3fbdf09d28eb59f8e4d8ef6c176",
+ "desktop/integration_test/native_memory_companion_recovery_test.dart": "50dd759d3e65e22dcd8280ec1ba3a8240993b03e5ff1347bfc773a9d3286dd9c"
+ },
+ "images": {
+ "native-waiting.png": {
+ "sha256": "08eacee52c2323eac3d575497f8285ef2504a6b67454f0e2c6cb116d01f86c3c",
+ "surface": "macOS native fixture",
+ "receipt": "20261003T025115.842925Z-50706"
+ },
+ "native-retry.png": {
+ "sha256": "282e5f547cc49300146360d796cafdeb29b687c0cca498855a3326c234c1d7c5",
+ "surface": "macOS native fixture",
+ "receipt": "20261003T025115.842925Z-50706"
+ },
+ "native-resumed.png": {
+ "sha256": "3f27b0b592a20172d2b22dcd04fb481d85206bf2f50de1b58c37d7b9b57c30c7",
+ "surface": "macOS native fixture",
+ "receipt": "20261003T025115.842925Z-50706"
+ },
+ "dark-large-text.png": {
+ "sha256": "cf372b49f0f7585c08746e2425ab8525dc2888214b965907234686e0f6eb9762",
+ "surface": "VM fixture, 440x1100, 200% text"
+ },
+ "light-large-text.png": {
+ "sha256": "f478230f9a30d59b1162ed2321e5e5146c990eda810607e51a0dde29b4db96a3",
+ "surface": "VM fixture, 440x1100, 200% text"
+ }
+ },
+ "validation": {
+ "affectedVm": {
+ "passed": 143,
+ "receipt": "20261003T020505.521210Z-10127",
+ "scope": "Production changes and initial workspace fixture before adding keyboard assertions."
+ },
+ "keyboardVm": {
+ "passed": 1,
+ "receipt": "20261003T021815.346665Z-7196",
+ "scope": "Final VM fixture, including keyboard delivery and in-memory persistence."
+ },
+ "native": {
+ "status": "passed",
+ "passed": 2,
+ "failed": 0,
+ "receipt": "20261003T025115.842925Z-50706",
+ "log": "native-memory-focus-review.log",
+ "elapsedSeconds": 52.176,
+ "passedCases": [
+ "native recovery test window has foreground focus",
+ "Memories reopens the same companion after failure without duplicate requests or changing its DSH"
+ ],
+ "focusReviewEnabled": true,
+ "focusObservedWithinFirstSecond": true,
+ "manualAppControlAction": false,
+ "launcherWarning": "Failed to foreground app; open returned 1",
+ "limitation": "Earlier foreground failures are preserved. Their intermittent cause is not established."
+ },
+ "analysis": "Production and VM analysis passed previously; final native wrapper analysis passed with the final native command.",
+ "previousNative": {
+ "status": "failed",
+ "passed": 1,
+ "failed": 1,
+ "passedCase": "Memories reopens the same companion after failure without duplicate requests or changing its DSH",
+ "failedCase": "native recovery test window has foreground focus",
+ "failure": "windowManager.isFocused() returned false after show/focus; cause unestablished.",
+ "receipt": "20261003T022209.491128Z-33644",
+ "elapsedSeconds": 46.5
+ },
+ "readinessAttempt": {
+ "status": "failed",
+ "passed": 1,
+ "failed": 1,
+ "receipt": "20261003T024613.986749Z-14439",
+ "log": "native-memory-focus-readiness.log",
+ "elapsedSeconds": 53.785,
+ "failure": "After first frame and three seconds, visible=true and minimized=false but native focus=false."
+ }
+ },
+ "limitations": [
+ "Native functional journey and synthetic key dispatch do not establish physical AppKit keyboard/IME or VoiceOver behavior.",
+ "Earlier native startup focus assertions failed; final assertion passed without manual activation. Intermittent cause remains unestablished.",
+ "No learning-quality, native inference, framework account change or provider-recovery claim.",
+ "No release or installation."
+ ],
+ "recordedAt": "2026-10-03T02:52:08.380385+00:00"
+}
diff --git a/docs/research/2026-10-03-memory-recovery/light-large-text.png b/docs/research/2026-10-03-memory-recovery/light-large-text.png
new file mode 100644
index 000000000..b0f4df331
Binary files /dev/null and b/docs/research/2026-10-03-memory-recovery/light-large-text.png differ
diff --git a/docs/research/2026-10-03-memory-recovery/native-resumed.png b/docs/research/2026-10-03-memory-recovery/native-resumed.png
new file mode 100644
index 000000000..db0c6e9b0
Binary files /dev/null and b/docs/research/2026-10-03-memory-recovery/native-resumed.png differ
diff --git a/docs/research/2026-10-03-memory-recovery/native-retry.png b/docs/research/2026-10-03-memory-recovery/native-retry.png
new file mode 100644
index 000000000..433929916
Binary files /dev/null and b/docs/research/2026-10-03-memory-recovery/native-retry.png differ
diff --git a/docs/research/2026-10-03-memory-recovery/native-waiting.png b/docs/research/2026-10-03-memory-recovery/native-waiting.png
new file mode 100644
index 000000000..6e527749a
Binary files /dev/null and b/docs/research/2026-10-03-memory-recovery/native-waiting.png differ