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: a resume waiting to be confirmed is invisible to the scan that heals it

0xken154fd43693df16
diff --git a/cli/src/lib/terminalAgentReconciler.spec.ts b/cli/src/lib/terminalAgentReconciler.spec.ts
index 19a5fcf77..e846407d0 100644
--- a/cli/src/lib/terminalAgentReconciler.spec.ts
+++ b/cli/src/lib/terminalAgentReconciler.spec.ts
@@ -392,6 +392,57 @@ describe('verified process adoption', () => {
expect(validate).toHaveBeenCalledWith(tmux, { engine: 'claude', processIdentity: undefined })
})
+ it('sees a resumed row that has its conversation but not yet its process', async () => {
+ // `resumePendingAgent` keeps the archived sessionId and clears processIdentity, so this row can
+ // only be matched by its route. It used to be skipped for having an id at all — leaving the one
+ // row that is waiting to be confirmed invisible to every scan, and its launch state stuck.
+ const current = {
+ ...session([tmux]),
+ sessionId: 'archived-conversation',
+ processIdentity: null,
+ resumeOnly: true as const,
+ active: false,
+ launch: { state: 'failed' as const, error: 'RESUME_UNCONFIRMED', detail: 'not confirmed' },
+ }
+ const onObserved = vi.fn()
+ const reconciler = new TerminalAgentReconciler({
+ current: () => [current], backends: [], backendOrder: ['tmux'], herdrSessionOrder: [],
+ onDiscovered: vi.fn(), onObserved, onDormant: vi.fn(), onRemoved: vi.fn(),
+ probe: async () => probe(
+ [{ instanceId: 'tmux:default', result: { state: 'available', roots: [{ runtime: tmux, rootPid: 1, cwd: '/work' }] } }],
+ [observed([tmux])],
+ ),
+ })
+
+ await reconciler.trigger()
+
+ expect(onObserved).toHaveBeenCalledOnce()
+ expect(onObserved.mock.calls[0][1]).toBe(current)
+ })
+
+ it('leaves a bound row with its own process to process identity alone', async () => {
+ // Both an id and a process: the stricter rule still holds, so another engine in the same pane
+ // cannot inherit this row's transcript through the route.
+ const current = { ...session([tmux]), sessionId: 'bound-conversation' }
+ const onObserved = vi.fn()
+ const intruder: DiscoveredTerminalAgent = {
+ ...observed([tmux]),
+ processIdentity: { pid: 999, executable: 'claude', startMarker: 'Tue Sep 24 09:00:00 2026' },
+ }
+ const reconciler = new TerminalAgentReconciler({
+ current: () => [current], backends: [], backendOrder: ['tmux'], herdrSessionOrder: [],
+ onDiscovered: vi.fn(), onObserved, onDormant: vi.fn(), onRemoved: vi.fn(),
+ probe: async () => probe(
+ [{ instanceId: 'tmux:default', result: { state: 'available', roots: [{ runtime: tmux, rootPid: 1, cwd: '/work' }] } }],
+ [intruder],
+ ),
+ })
+
+ await reconciler.trigger()
+
+ expect(onObserved).not.toHaveBeenCalled()
+ })
+
it('reports no adopted agent when the registry callback rejects the process', async () => {
const onDiscovered = vi.fn()
const reconciler = new TerminalAgentReconciler({
diff --git a/cli/src/lib/terminalAgentReconciler.ts b/cli/src/lib/terminalAgentReconciler.ts
index e1190082c..93241e4ca 100644
--- a/cli/src/lib/terminalAgentReconciler.ts
+++ b/cli/src/lib/terminalAgentReconciler.ts
@@ -70,11 +70,27 @@ function unboundRouteOwner(
return matches.length === 1 ? matches[0] : undefined
}
+/**
+ * The observation for a row that cannot be matched by process identity, because it does not have one
+ * yet. Its terminal route is the only identity it has.
+ *
+ * ⚠️ `!sessionId` is NOT the test, and that was a real bug. A RESUMED row keeps the archived session
+ * id while `resumePendingAgent` clears its `processIdentity` — so it has an id and no process, and
+ * the old test made exactly the row that is waiting to be confirmed invisible to every scan. Nothing
+ * else looks at it either: `bindObservedAgent` keys on `byProcess`, and the dormancy branch below
+ * skips it because a failed launch already cleared `active`. A resume whose engine never sent a
+ * startup hook therefore sat at "Starting" — measured at 19 hours over a pane its owner could type
+ * in (openharness#189) — with the heal in cli.ts's `onObserved` (`if (wasLaunching) setLaunch(ready)`)
+ * never reached.
+ *
+ * A row with BOTH an id and a process keeps the stricter rule: process identity is authoritative
+ * again, so a different process in the same pane cannot inherit its transcript.
+ */
function unboundRouteObservation(
current: RegisteredSession,
observed: readonly DiscoveredTerminalAgent[],
): DiscoveredTerminalAgent | undefined {
- if (current.sessionId) return undefined
+ if (current.sessionId && current.processIdentity) return undefined
const matches = observed.filter((candidate) => (
routeEngineMatches(current, candidate) && sharesPlacement(current, candidate)
))
diff --git a/desktop/lib/state/app_state.dart b/desktop/lib/state/app_state.dart
index 516e45097..2aab71e1d 100644
--- a/desktop/lib/state/app_state.dart
+++ b/desktop/lib/state/app_state.dart
@@ -5979,10 +5979,22 @@ class AppNotifier extends ChangeNotifier {
_announceOpenPanesToDial();
}
if (agent.launchState == 'failed' && previous?.launchState != 'failed') {
- _lastError = agent.launchDetail ?? 'Failed to start ${agent.name}';
- // The launch already ran and failed (e.g. the engine's automatic
- // install failed) — reloading the machine list will not install it.
- _lastErrorRetryable = false;
+ // Only where the person would otherwise never see it. A harness with a
+ // pane open says this in the pane, with the button that answers it
+ // (`pane_grid`'s notice) — and this push reaches EVERY client watching
+ // the machine, so the window-wide band told people who had pressed
+ // nothing to go and check a harness they were not looking at.
+ final shown = allPanes.any(
+ (pane) =>
+ pane.machineId == machine.machine.machineId &&
+ pane.agentId == agent.id,
+ );
+ if (!shown) {
+ _lastError = agent.launchDetail ?? 'Failed to start ${agent.name}';
+ // The launch already ran and failed (e.g. the engine's automatic
+ // install failed) — reloading the machine list will not install it.
+ _lastErrorRetryable = false;
+ }
}
}
diff --git a/desktop/lib/widgets/pane_grid.dart b/desktop/lib/widgets/pane_grid.dart
index 9a79d00c9..876379819 100644
--- a/desktop/lib/widgets/pane_grid.dart
+++ b/desktop/lib/widgets/pane_grid.dart
@@ -1,5 +1,6 @@
import '../sharing/shared_harness_panel.dart';
+import 'dart:async';
import 'dart:typed_data';
import 'package:desktop_drop/desktop_drop.dart';
@@ -1470,12 +1471,31 @@ class _PaneContent extends StatelessWidget {
'This agent is unavailable on ${machine.machine.displayName}. Retained output is read only.',
);
} else if (agent.launchState == 'failed') {
+ // A resume the daemon could not CONFIRM is not a start that failed: the
+ // engine is usually still running in this pane, which is why output
+ // keeps arriving while the keyboard is locked. Asking again is cheap —
+ // the daemon re-checks a resume it never confirmed rather than
+ // relaunching (`resumeStoppedAgent.ts`) — so that is the button, and
+ // Restart is kept for the failures where something really must be
+ // started again.
+ final unconfirmed = agent.launchError == 'RESUME_UNCONFIRMED';
notice = terminalNotice(
- label: 'Start failed',
- icon: Icons.error_outline,
- detail:
- agent.launchDetail ??
- 'The engine failed to start. Terminal output is preserved.',
+ label: unconfirmed ? 'Not confirmed' : 'Start failed',
+ icon: unconfirmed ? Icons.help_outline : Icons.error_outline,
+ detail: unconfirmed
+ ? 'The engine is still running here; the daemon has not confirmed '
+ 'which conversation it reopened.'
+ : agent.launchDetail ??
+ 'The engine failed to start. Terminal output is preserved.',
+ // The one notice that needs saying out loud rather than hovering:
+ // the pane keeps printing while its keyboard is locked, and nothing
+ // about a chip explains that.
+ banner: true,
+ actionLabel: unconfirmed ? 'Check again' : 'Restart',
+ onAction: unconfirmed
+ ? () => unawaited(notifier.selectAgent(pane.machineId, agent.id))
+ : () =>
+ restartHarness(context, notifier, pane.machineId, agent.id),
);
} else {
notice = null;
diff --git a/desktop/lib/widgets/terminal_panel.dart b/desktop/lib/widgets/terminal_panel.dart
index 1af32014b..b958f6268 100644
--- a/desktop/lib/widgets/terminal_panel.dart
+++ b/desktop/lib/widgets/terminal_panel.dart
@@ -52,6 +52,14 @@ typedef TerminalNotice = ({
/// the state is merely reported and nothing here would fix it.
String? actionLabel,
VoidCallback? onAction,
+
+ /// Whether this one also earns the band across the top of the pane, over the
+ /// output. The chip is the resting place for a notice; the band is for the
+ /// few that are CONFUSING as well as blocking — a pane still printing while
+ /// its keyboard is locked — where the sentence has to be read, not hovered.
+ /// An offline machine is neither confusing nor rare, and a band on every one
+ /// of those would cost rows in every tile.
+ bool banner,
});
/// A [TerminalNotice] without spelling out the fields it does not have.
@@ -65,12 +73,14 @@ TerminalNotice terminalNotice({
required IconData icon,
String? actionLabel,
VoidCallback? onAction,
+ bool banner = false,
}) => (
label: label,
detail: detail,
icon: icon,
actionLabel: actionLabel,
onAction: onAction,
+ banner: banner,
);
class TerminalPanel extends StatefulWidget {
@@ -1668,6 +1678,13 @@ class _TerminalPanelState extends State<TerminalPanel>
// frozen output itself, where the eyes already are, and
// stays through `opening` so the pane does not jump when
// it is answered.
+ //
+ // It also carries a pane-level notice that has something to
+ // DO about itself (a failed start offering Check again or
+ // Restart). One strip, never two: a noticed pane is already
+ // excluded from `_inputBlocked` — nothing the takeover band
+ // offers would help a pane whose machine or launch is the
+ // problem — so these two conditions cannot both hold.
if (_inputBlocked ||
(_retakingControl &&
session.status == TerminalSessionStatus.opening))
@@ -1689,6 +1706,14 @@ class _TerminalPanelState extends State<TerminalPanel>
? () => unawaited(_takeControl())
: null,
),
+ )
+ else if (widget.notice case final notice?
+ when notice.banner && notice.onAction != null)
+ Positioned(
+ top: 0,
+ left: 0,
+ right: 0,
+ child: _ControlBanner.notice(notice),
),
if (session.uploadProgress != null ||
_previewProgress != null)
@@ -2345,21 +2370,38 @@ class _ControlBanner extends StatelessWidget {
/// null from an older daemon or a taker that did not introduce itself.
final String? takerName;
+ /// The pane-level notice this band is speaking for instead, when it is one a
+ /// person can act on. Null for the takeover band above.
+ final TerminalNotice? notice;
+
const _ControlBanner({
required this.busy,
required this.nudged,
required this.nudge,
required this.onTakeControl,
this.takerName,
- });
-
- String get title => busy
+ }) : notice = null;
+
+ /// The band for a notice that offers a way out — the same strip, the same
+ /// wording rules, so a pane never grows a second one. The header's chip says
+ /// the same thing in a corner; this is where it can be read.
+ const _ControlBanner.notice(TerminalNotice this.notice)
+ : busy = false,
+ nudged = false,
+ nudge = 0,
+ onTakeControl = null,
+ takerName = null;
+
+ String get title => notice != null
+ ? notice!.label
+ : busy
? 'Taking control…'
: takerName == null
? 'Another app took control of this terminal'
: '$takerName took control of this terminal';
String? get detail {
+ if (notice != null) return notice!.detail;
if (busy) return null;
if (nudged) return 'Keys are ignored — press ⏎ to take control.';
return 'Typing is paused. Click here or press ⏎ to take control.';
@@ -2368,7 +2410,11 @@ class _ControlBanner extends StatelessWidget {
@override
Widget build(BuildContext context) {
grid.AppTheme.watch(context);
- final ink = AppColors.warning;
+ // A notice that failed is red; everything else on this strip is the amber
+ // of "paused, and you can do something about it".
+ final ink = notice != null && notice!.icon == Icons.error_outline
+ ? AppColors.danger
+ : AppColors.warning;
final detail = this.detail;
final reduceMotion = MediaQuery.disableAnimationsOf(context);
// Composited over the pane's own ground, as [UpdateNotice] is over the
@@ -2413,7 +2459,9 @@ class _ControlBanner extends StatelessWidget {
// its own under the title rather than running off the edge.
final narrow =
constraints.maxWidth < 340 * grid.appTextScaleOf(context);
- final lead = !busy
+ final lead = notice != null
+ ? Icon(notice!.icon, size: 16, color: ink)
+ : !busy
? Icon(Icons.lock_outline, size: 16, color: ink)
: SizedBox(
width: 16,
@@ -2463,7 +2511,15 @@ class _ControlBanner extends StatelessWidget {
],
),
);
- final button = busy
+ final button = notice != null
+ ? (notice!.actionLabel == null
+ ? null
+ : _ControlBannerButton(
+ label: notice!.actionLabel!,
+ onPressed: notice!.onAction,
+ showReturnKey: false,
+ ))
+ : busy
? null
: _ControlBannerButton(onPressed: onTakeControl);
if (narrow) {
@@ -2499,7 +2555,16 @@ class _ControlBanner extends StatelessWidget {
/// the accent.
class _ControlBannerButton extends StatelessWidget {
final VoidCallback? onPressed;
- const _ControlBannerButton({required this.onPressed});
+ final String label;
+
+ /// ⏎ is drawn only where the key really does this — taking the stream back
+ /// (`_onTerminalKey`). A notice's action has no chord behind it.
+ final bool showReturnKey;
+ const _ControlBannerButton({
+ required this.onPressed,
+ this.label = 'Take control',
+ this.showReturnKey = true,
+ });
@override
Widget build(BuildContext context) {
@@ -2515,19 +2580,21 @@ class _ControlBannerButton extends StatelessWidget {
child: Row(
mainAxisSize: MainAxisSize.min,
children: [
- Flexible(child: Text('Take control', style: grid.AppType.label())),
- const SizedBox(width: 8),
- Container(
- padding: const EdgeInsets.symmetric(horizontal: 4, vertical: 1),
- decoration: BoxDecoration(
- border: Border.all(color: onAccent.withValues(alpha: 0.6)),
- borderRadius: BorderRadius.circular(4),
- ),
- child: Semantics(
- label: 'Return',
- child: Icon(Icons.keyboard_return, size: 12, color: onAccent),
+ Flexible(child: Text(label, style: grid.AppType.label())),
+ if (showReturnKey) ...[
+ const SizedBox(width: 8),
+ Container(
+ padding: const EdgeInsets.symmetric(horizontal: 4, vertical: 1),
+ decoration: BoxDecoration(
+ border: Border.all(color: onAccent.withValues(alpha: 0.6)),
+ borderRadius: BorderRadius.circular(4),
+ ),
+ child: Semantics(
+ label: 'Return',
+ child: Icon(Icons.keyboard_return, size: 12, color: onAccent),
+ ),
),
- ),
+ ],
],
),
);
diff --git a/desktop/test/pane_launch_failure_test.dart b/desktop/test/pane_launch_failure_test.dart
new file mode 100644
index 000000000..3dc1033f1
--- /dev/null
+++ b/desktop/test/pane_launch_failure_test.dart
@@ -0,0 +1,105 @@
+import 'package:flutter/material.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:harness/state/app_state.dart';
+import 'package:harness/widgets/pane_grid.dart';
+
+import 'swarm_screen_test.dart' show terminal;
+import 'swarm_state_test.dart' show createApp;
+
+/// What a pane offers when its harness did not come up — and, for the one case
+/// where the engine is in fact still running, what it offers INSTEAD of
+/// pretending the start failed.
+void main() {
+ late AppNotifier app;
+
+ setUp(() {
+ app = createApp();
+ app.stateOf('m')!
+ ..nodeOnline = true
+ ..terminalCapabilityAvailable = true;
+ app.adoptSessionForTest(terminal('a0', []));
+ });
+
+ tearDown(() => app.dispose());
+
+ /// Through the daemon's own push, so the window-band rule in `_upsertAgent`
+ /// is exercised rather than stepped over.
+ Future<void> agentWith({required String launchError}) =>
+ app.handleEventForTest('m', {
+ 'type': 'agent_synced',
+ 'payload': {
+ 'agent': {
+ 'id': 'a0',
+ 'name': 'Session a0',
+ 'engine': 'codex',
+ 'terminal': {'available': true},
+ 'launch': {
+ 'state': 'failed',
+ 'error': launchError,
+ 'detail': 'The daemon said so.',
+ },
+ },
+ },
+ });
+
+ Future<void> pump(WidgetTester tester) async {
+ await tester.pumpWidget(
+ MaterialApp(
+ home: Scaffold(
+ body: ListenableBuilder(
+ listenable: app,
+ builder: (_, _) => PaneGrid(notifier: app, swarmMode: false),
+ ),
+ ),
+ ),
+ );
+ await tester.pump();
+ }
+
+ testWidgets('a resume the daemon could not confirm offers Check again', (
+ tester,
+ ) async {
+ // The engine is usually still running in the pane — output keeps arriving
+ // while the keyboard is locked — so the pane says that and offers the cheap
+ // question, not a relaunch.
+ await agentWith(launchError: 'RESUME_UNCONFIRMED');
+ await pump(tester);
+ expect(find.text('Not confirmed'), findsWidgets);
+ expect(find.textContaining('still running here'), findsWidgets);
+ expect(find.widgetWithText(FilledButton, 'Check again'), findsOneWidget);
+ expect(find.text('Start failed'), findsNothing);
+ await tester.pumpWidget(const SizedBox());
+ });
+
+ testWidgets('a launch that really failed offers Restart, with its reason', (
+ tester,
+ ) async {
+ await agentWith(launchError: 'ENGINE_MISSING');
+ await pump(tester);
+ expect(find.text('Start failed'), findsWidgets);
+ expect(find.textContaining('The daemon said so.'), findsWidgets);
+ expect(find.widgetWithText(FilledButton, 'Restart'), findsOneWidget);
+ await tester.pumpWidget(const SizedBox());
+ });
+
+ testWidgets('a harness whose pane says it keeps the window band quiet', (
+ tester,
+ ) async {
+ // The push reaches every client watching the machine. One that is looking
+ // at the pane is already told; a window-wide band would be a second copy of
+ // the same sentence, addressed to people who pressed nothing.
+ expect(app.lastError, isNull);
+ await agentWith(launchError: 'RESUME_UNCONFIRMED');
+ await pump(tester);
+ expect(app.lastError, isNull);
+ await tester.pumpWidget(const SizedBox());
+ });
+
+ testWidgets('a harness with no pane still raises the window band', (
+ tester,
+ ) async {
+ await app.closePane(app.panes.single.id);
+ await agentWith(launchError: 'ENGINE_MISSING');
+ expect(app.lastError, 'The daemon said so.');
+ });
+}
diff --git a/desktop/test/terminal_control_banner_test.dart b/desktop/test/terminal_control_banner_test.dart
index c52080b9b..e66c8dc23 100644
--- a/desktop/test/terminal_control_banner_test.dart
+++ b/desktop/test/terminal_control_banner_test.dart
@@ -250,6 +250,105 @@ void main() {
await finish(tester);
});
+ testWidgets('a notice with a way out gets the band, and its button works', (
+ tester,
+ ) async {
+ // The header's chip says the same in a corner at 11pt; this is where it can
+ // be read, and where the one action lives.
+ var checked = 0;
+ await pump(
+ tester,
+ notice: terminalNotice(
+ label: 'Not confirmed',
+ icon: Icons.help_outline,
+ detail:
+ 'The engine is still running here; the daemon has not confirmed '
+ 'which conversation it reopened.',
+ banner: true,
+ actionLabel: 'Check again',
+ onAction: () => checked++,
+ ),
+ );
+ // Twice: the header's chip, and the band that can be read.
+ expect(find.text('Not confirmed'), findsNWidgets(2));
+ expect(find.textContaining('still running here'), findsWidgets);
+ final button = find.widgetWithText(FilledButton, 'Check again');
+ expect(button, findsOneWidget);
+ // ⏎ belongs to taking the stream back; this action has no chord behind it.
+ expect(
+ find.descendant(of: button, matching: find.byIcon(Icons.keyboard_return)),
+ findsNothing,
+ );
+ await tester.tap(button);
+ await tester.pump();
+ expect(checked, 1);
+ await finish(tester);
+ });
+
+ testWidgets(
+ 'an actionable notice that did not ask for the band stays a chip',
+ (tester) async {
+ // Link required, offline, unavailable: all have a button already, and a
+ // band on every one of those would cost rows in every tile.
+ await pump(
+ tester,
+ notice: terminalNotice(
+ label: 'Link required',
+ icon: Icons.link_off,
+ detail: 'Test host needs linking.',
+ actionLabel: 'Link',
+ onAction: () {},
+ ),
+ );
+ expect(find.byType(FilledButton), findsNothing);
+ expect(find.text('Link required'), findsOneWidget);
+ await finish(tester);
+ },
+ );
+
+ testWidgets('a notice with nothing to do stays in the header alone', (
+ tester,
+ ) async {
+ await pump(
+ tester,
+ notice: terminalNotice(
+ label: 'Offline',
+ icon: Icons.cloud_off,
+ detail: 'Test host is offline.',
+ ),
+ );
+ expect(find.byType(FilledButton), findsNothing);
+ // The chip carries it alone; the band is for what a person can answer.
+ expect(find.text('Offline'), findsOneWidget);
+ await finish(tester);
+ });
+
+ testWidgets('a noticed pane keeps its own band when the stream is taken', (
+ tester,
+ ) async {
+ await pump(
+ tester,
+ notice: terminalNotice(
+ label: 'Not confirmed',
+ icon: Icons.help_outline,
+ detail: 'Still checking.',
+ banner: true,
+ actionLabel: 'Check again',
+ onAction: () {},
+ ),
+ );
+ takeOver();
+ await tester.pump();
+ // A noticed pane is not "blocked" in the takeover sense — `_inputBlocked`
+ // excludes it, because nothing the takeover band offers would help a pane
+ // whose machine or launch is the problem. So the strip stays the notice's,
+ // and there is still exactly one band.
+ expect(takenOverTitle, findsNothing);
+ expect(find.text('Not confirmed'), findsNWidgets(2));
+ expect(find.widgetWithText(FilledButton, 'Check again'), findsOneWidget);
+ await finish(tester);
+ });
+
testWidgets('⏎ in the terminal takes control back, once', (tester) async {
await pump(tester);
takeOver();