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): a harness the daemon holds back says it is waiting, and why (#1117)

Deed6f0098cc5f7
diff --git a/desktop/lib/core/models.dart b/desktop/lib/core/models.dart
index 7a02f0e1f..918425a5a 100644
--- a/desktop/lib/core/models.dart
+++ b/desktop/lib/core/models.dart
@@ -548,9 +548,14 @@ class Agent {
final launch = launchRaw is Map
? Map<String, dynamic>.from(launchRaw)
: const <String, dynamic>{};
+ // `held`: the daemon will not start it yet, and says why, such as a
+ // conversation another process may have open. Read as `ready` it showed
+ // only its name over an empty pane ("Unavailable"), with no reason
+ // (onboarding reopening a team's recent conversations, 2026-10-09).
final launchState = switch (launch['state']) {
'starting' => 'starting',
'failed' => 'failed',
+ 'held' => 'held',
_ => 'ready',
};
final grid = j['grid'] as Map<String, dynamic>?;
@@ -609,7 +614,7 @@ class Agent {
status: (j['status'] as String?) ?? 'active',
launchState: launchState,
launchError: launchState == 'failed' ? _safeLabel(launch['error']) : null,
- launchDetail: launchState == 'failed'
+ launchDetail: launchState == 'failed' || launchState == 'held'
? _safeDetail(launch['detail'])
: null,
terminalAvailable: terminalAvailable,
diff --git a/desktop/lib/screens/swarm_screen.dart b/desktop/lib/screens/swarm_screen.dart
index 493862a4c..97822db9a 100644
--- a/desktop/lib/screens/swarm_screen.dart
+++ b/desktop/lib/screens/swarm_screen.dart
@@ -7462,6 +7462,7 @@ class _SwarmScreenState extends State<SwarmScreen> {
agent != null &&
agent.terminalAvailable &&
agent.launchState != 'failed' &&
+ agent.launchState != 'held' &&
machine.nodeOnline != false &&
!(machine.isLocalMachine && !machine.usesLocalTransport) &&
!(machine.isRemote && !machine.isLocalMachine && machine.needsLink) &&
diff --git a/desktop/lib/state/harness_activity.dart b/desktop/lib/state/harness_activity.dart
index 36108b6de..333b40f1c 100644
--- a/desktop/lib/state/harness_activity.dart
+++ b/desktop/lib/state/harness_activity.dart
@@ -70,7 +70,9 @@ HarnessActivity? harnessActivity(
return HarnessActivity.offline;
}
if (agent.isStopped) return HarnessActivity.paused;
- if (agent.launchState == 'starting') return HarnessActivity.starting;
+ if (agent.launchState == 'starting' || agent.launchState == 'held') {
+ return HarnessActivity.starting;
+ }
if (agent.launchState == 'failed') {
return agent.launchError == 'RESUME_UNCONFIRMED'
? HarnessActivity.needsInput
diff --git a/desktop/lib/state/harness_sessions.dart b/desktop/lib/state/harness_sessions.dart
index bda15f96b..47be8f4e1 100644
--- a/desktop/lib/state/harness_sessions.dart
+++ b/desktop/lib/state/harness_sessions.dart
@@ -40,10 +40,18 @@ String? harnessSessionUnavailable(MachineState? machine, Agent? agent) {
return switch (agent.launchState) {
'starting' => 'Starting',
'failed' => 'Start failed',
+ 'held' => 'Waiting',
_ => 'Unavailable',
};
}
+/// What a harness the daemon holds back says: its reason, such as a
+/// conversation another process may have open, and the way out. Closing the
+/// pane cancels the held start (a move from a terminal included).
+String heldLaunchDetail(Agent agent) =>
+ '${agent.launchDetail ?? 'Harness is not starting it yet.'} '
+ 'It starts here when that clears; close this pane to cancel.';
+
/// A session appears once, however many tabs or viewers show it.
class HarnessSession {
const HarnessSession({
@@ -98,6 +106,8 @@ class HarnessSession {
? 'Start failed'
: agent.launchState == 'starting'
? 'Starting'
+ : agent.launchState == 'held'
+ ? 'Waiting'
: needsInput
? 'Needs input'
: agent.closePlanState == 'failed'
diff --git a/desktop/lib/widgets/notification_inbox.dart b/desktop/lib/widgets/notification_inbox.dart
index f4647ac42..fba0301d1 100644
--- a/desktop/lib/widgets/notification_inbox.dart
+++ b/desktop/lib/widgets/notification_inbox.dart
@@ -328,7 +328,7 @@ class _NotificationInboxState extends State<NotificationInbox> {
? HarnessActivity.starting
: switch (row.unavailable) {
null => row.activity,
- 'Starting' => HarnessActivity.starting,
+ 'Starting' || 'Waiting' => HarnessActivity.starting,
'Start failed' => HarnessActivity.failed,
_ => HarnessActivity.offline,
};
diff --git a/desktop/lib/widgets/pane_grid.dart b/desktop/lib/widgets/pane_grid.dart
index bb554e605..b11d75c2a 100644
--- a/desktop/lib/widgets/pane_grid.dart
+++ b/desktop/lib/widgets/pane_grid.dart
@@ -21,6 +21,7 @@ import '../shared/theme/appearance_prefs_store.dart';
import '../shortcuts/app_shortcuts.dart' hide TerminalKey;
import '../state/account_devices.dart' show registerRefusalSentence;
import '../state/app_state.dart';
+import '../state/harness_sessions.dart' show heldLaunchDetail;
import '../state/pane_preset.dart';
import '../state/pane_arrangement.dart';
import '../state/terminal_pane.dart';
@@ -1630,6 +1631,15 @@ class _PaneContent extends StatelessWidget {
onAction: () => notifier.openSavedPane(pane.id).ignore(),
banner: true,
);
+ } else if (agent != null && agent.launchState == 'held') {
+ // Held back by the daemon until it can start it safely: say why,
+ // rather than "Unavailable" over an empty pane.
+ notice = terminalNotice(
+ label: 'Waiting',
+ icon: AppIcons.hourglass,
+ detail: heldLaunchDetail(agent),
+ banner: true,
+ );
} else if (agent == null || !agent.terminalAvailable) {
notice = terminalNotice(
label: 'Unavailable',
@@ -1692,12 +1702,15 @@ class _PaneContent extends StatelessWidget {
// Launch progress/failure describes the engine, not permission to
// type into its terminal. Connection and control ownership still
// gate input independently in TerminalPanel/TerminalSession.
+ // A held harness's terminal is the daemon's waiting shell, which
+ // ignores what is typed: nothing there reaches the agent.
readOnly:
machine == null ||
needsLink ||
offline ||
agent == null ||
- !agent.terminalAvailable,
+ !agent.terminalAvailable ||
+ agent.launchState == 'held',
notice: notice,
onToggleComposer: () => notifier.toggleComposer(pane.id),
onClose: single && !swarmMode ? null : close,
@@ -1852,6 +1865,19 @@ class _PaneContent extends StatelessWidget {
onAction: () => notifier.openSavedPane(pane.id).ignore(),
);
}
+ // Held back by the daemon until it can start it safely (a conversation
+ // another process may have open): it says so and why, and starts by
+ // itself. It read "terminal unavailable (no verified terminal pane)".
+ if (agent != null && agent.launchState == 'held') {
+ return _PaneStatus(
+ activity: activityMark,
+ title: agentName,
+ icon: AppIcons.hourglass,
+ message: heldLaunchDetail(agent),
+ onClose: close,
+ busy: true,
+ );
+ }
if (agent != null && !agent.terminalAvailable) {
return _PaneStatus(
activity: activityMark,
diff --git a/desktop/test/pane_launch_failure_test.dart b/desktop/test/pane_launch_failure_test.dart
index 149faea0d..96d73fa6d 100644
--- a/desktop/test/pane_launch_failure_test.dart
+++ b/desktop/test/pane_launch_failure_test.dart
@@ -156,6 +156,81 @@ void main() {
await tester.pumpWidget(const SizedBox());
});
+ testWidgets(
+ 'a harness the daemon holds back says it is waiting, and why, not "Unavailable"',
+ (tester) async {
+ // Onboarding reopening a team's recent conversations, 2026-10-09: held
+ // until the daemon could tell who had them open, each pane showed only
+ // its name and "Unavailable".
+ await app.handleEventForTest('m', {
+ 'type': 'agent_synced',
+ 'payload': {
+ 'agent': {
+ 'id': 'a0',
+ 'name': 'Session a0',
+ 'engine': 'claude',
+ 'terminal': {'available': false},
+ 'launch': {
+ 'state': 'held',
+ 'service': 'search',
+ 'detail':
+ "The conversation's current owner could not be verified.",
+ },
+ },
+ },
+ });
+ final agent = app.stateOf('m')!.agents.singleWhere((a) => a.id == 'a0');
+ expect(agent.launchState, 'held');
+ expect(
+ agent.launchDetail,
+ "The conversation's current owner could not be verified.",
+ );
+ await pump(tester);
+ expect(
+ find.textContaining(
+ "could not be verified. It starts here when that clears; close this pane to cancel.",
+ ),
+ findsWidgets,
+ );
+ expect(find.text('Unavailable'), findsNothing);
+ expect(find.textContaining('terminal unavailable'), findsNothing);
+ await tester.pumpWidget(const SizedBox());
+ },
+ );
+
+ testWidgets(
+ 'a held harness whose waiting shell is up says Waiting, and takes no typing',
+ (tester) async {
+ // The daemon's waiting pane is a live shell (`heldPaneArgv`) that ignores
+ // input: what is typed there would be lost.
+ await app.handleEventForTest('m', {
+ 'type': 'agent_synced',
+ 'payload': {
+ 'agent': {
+ 'id': 'a0',
+ 'name': 'Session a0',
+ 'engine': 'claude',
+ 'terminal': {'available': true},
+ 'launch': {
+ 'state': 'held',
+ 'service': 'search',
+ 'detail':
+ 'Waiting for the search service to verify this conversation.',
+ },
+ },
+ },
+ });
+ await pump(tester);
+ expect(find.text('Waiting'), findsWidgets);
+ expect(find.textContaining('close this pane to cancel'), findsWidgets);
+ expect(
+ tester.widget<TerminalPanel>(find.byType(TerminalPanel)).readOnly,
+ isTrue,
+ );
+ await tester.pumpWidget(const SizedBox());
+ },
+ );
+
testWidgets('a launch that really failed offers Restart, with its reason', (
tester,
) async {