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(mobile): arriving on an agent takes its terminal again

Dev jacobff95483a8261
diff --git a/mobile/RELEASE.md b/mobile/RELEASE.md
index aae6316f5..0b3787322 100644
--- a/mobile/RELEASE.md
+++ b/mobile/RELEASE.md
@@ -73,8 +73,9 @@ icon size in thirty seconds instead of in an email twenty minutes later.
| `1.0.0 (22)` | 2026-09-21 | TestFlight. Named **Harness** on the home screen and in the app, with a new icon; the terminal runs to the bottom edge of the screen; only an explicit Take control press claims a terminal from the desktop |
| `1.0.0 (23)` | 2026-09-21 | TestFlight. The tabs mark unrolls the account's tabs as a rail of names under the header — the tab you are in wears a bar under its name — instead of opening a sheet; picking one switches and puts the rail away |
| `1.0.0 (24)` | 2026-09-21 | TestFlight. The tabs mark brings a panel up from the bottom: the account's tabs as a row of names, and the agents of the one picked as cards beside each other. A name changes the cards alone — another tab can be read into without leaving the terminal you are in — and a card is what opens an agent |
+| `1.0.0 (25)` | 2026-09-22 | TestFlight. Opening an agent takes its terminal again: no read-only stream and no "Take control" band in front of an agent a desktop has open, including the one the app opens on. The band is left for the case it is about — a terminal taken back off this phone |
-`pubspec.yaml` is therefore at `1.0.0+25`: the repo always holds the NEXT build number, so a release
+`pubspec.yaml` is therefore at `1.0.0+26`: the repo always holds the NEXT build number, so a release
runs clean without anyone having to remember the last one.
### Why the app is iPhone-only
diff --git a/mobile/lib/phone/phone_status.dart b/mobile/lib/phone/phone_status.dart
index 1be665848..aeebdead5 100644
--- a/mobile/lib/phone/phone_status.dart
+++ b/mobile/lib/phone/phone_status.dart
@@ -116,16 +116,10 @@ PhoneSummary phoneAgentSummary(MachineState machine, Agent agent) {
/// page opens before the pane has one.
/// [takerName]: who took the terminal, when known ([phoneTakerName]) — the
/// dot's tooltip then says "Taken over by Mac mini" rather than just that it was.
-/// [held]: nothing is attaching, on purpose — see `TerminalPane.heldForTakeControl`. "Attaching…"
-/// is what a null session normally means, and it would be a promise nothing is going to keep.
PhoneSummary phoneSessionSummary(
TerminalSession? session, {
String? takerName,
- bool held = false,
}) {
- if (held && session == null) {
- return (label: 'Not connected', tone: PhoneTone.attention);
- }
// ⚠️ Checked BEFORE the status, because a watcher's status is `controlling` — it holds a live
// stream and renders every byte; what it does not hold is the terminal. "Live" would promise a
// prompt that ignores typing. See [TerminalSession.watching].
@@ -164,20 +158,10 @@ String? phoneTakerName(
/// The one line under the header while another client drives this terminal —
/// the desktop's banner, at phone size. Null in every other state.
-/// [held]: nothing has been opened here at all, so nobody "took" anything — the line says why the
-/// terminal is not on screen and what the button will do. See `TerminalPane.heldForTakeControl`.
-String? phoneTakeoverNotice(
- TerminalSession? session,
- String? takerName, {
- bool held = false,
-}) {
- if (held && session == null) {
- return 'Opening this terminal would take it from another app';
- }
- return session?.status == TerminalSessionStatus.takenOver
- ? '${takerName ?? 'Another app'} took control of this terminal'
- : null;
-}
+String? phoneTakeoverNotice(TerminalSession? session, String? takerName) =>
+ session?.status == TerminalSessionStatus.takenOver
+ ? '${takerName ?? 'Another app'} took control of this terminal'
+ : null;
/// The way back into a session this device is not driving, or is no longer
/// driving — and what the button offers to do about it.
@@ -189,15 +173,7 @@ String? phoneTakeoverNotice(
/// The desktop puts the same two words on the same two states, in the tile
/// header it draws (`widgets/terminal_panel.dart`); a phone hides that header
/// and draws its own, which is how the way out went missing here.
-/// [held]: the tile has no session because opening one would have taken the terminal — an older
-/// CLI, where every open is a takeover, so nothing but a press may open at all. See
-/// `TerminalPane.heldForTakeControl`.
-PhoneSummary? phoneReclaimAction(TerminalSession? session, {bool held = false}) {
- // Before the status switch: there is no session to read one off, and "Attaching…" is exactly
- // the wrong thing to say about a tile that is deliberately not attaching.
- if (held && session == null) {
- return (label: 'Take control', tone: PhoneTone.attention);
- }
+PhoneSummary? phoneReclaimAction(TerminalSession? session) {
// A watcher is the ordinary way onto an agent another app is driving: output is already on
// screen, and this is the button that asks for the keyboard. See [TerminalSession.watching].
if (session != null && session.watching) {
diff --git a/mobile/lib/phone/terminal_page.dart b/mobile/lib/phone/terminal_page.dart
index 44c8223af..b77a20eea 100644
--- a/mobile/lib/phone/terminal_page.dart
+++ b/mobile/lib/phone/terminal_page.dart
@@ -893,23 +893,18 @@ class _TerminalPageState extends State<TerminalPage>
machine.agentLoadStatus == AgentLoadStatus.loaded;
// Captured while the agent is still listed, for the sentence above.
if (agent != null) _cachedAgentName = agent.name;
- // Deliberately not attaching, rather than still on its way: an older CLI cannot be asked for a
- // terminal politely, so only a press opens one there. See [TerminalPane.heldForTakeControl].
- final held = !agentGone && pane != null && pane.heldForTakeControl;
- final reclaim = phoneReclaimAction(session, held: held);
+ final reclaim = phoneReclaimAction(session);
// Read-only either way — the terminal was never this pane's (a watcher) or was taken from it.
// `_AgentGone` owns the page when the agent itself is missing, so this stays out of its way.
final blocked =
!agentGone &&
- (held ||
- (session != null &&
- (session.watching ||
- session.status == TerminalSessionStatus.takenOver)));
+ session != null &&
+ (session.watching || session.status == TerminalSessionStatus.takenOver);
final takerName = phoneTakerName(
session,
(id) => widget.notifier.stateOf(id)?.machine.displayName,
);
- final takeoverNotice = phoneTakeoverNotice(session, takerName, held: held);
+ final takeoverNotice = phoneTakeoverNotice(session, takerName);
// Creating needs the machine to list its folders and name its engines,
// so one that is offline or still wants its password cannot host a new
// agent — the same gate the Agents tab puts on its fab.
@@ -995,14 +990,6 @@ class _TerminalPageState extends State<TerminalPage>
name: _cachedAgentName,
onPickAnother: _pickAnotherAgent,
)
- // Nothing is attaching and nothing will until
- // the band above is pressed, so the skeleton
- // would be a promise with nobody behind it —
- // sweeping once and then sitting still for
- // good. An empty ground under the band
- // instead. See [_ControlBanner].
- : held
- ? ColoredBox(color: AppPalette.windowBg)
: pane == null || session == null
? const _Attaching()
: TerminalPanel(
@@ -1194,7 +1181,6 @@ class _TerminalPageState extends State<TerminalPage>
status: phoneSessionSummary(
session,
takerName: takerName,
- held: held,
),
trailing: [
// Read-only is a state to get OUT of, so its way
@@ -1474,11 +1460,7 @@ class _TerminalPageState extends State<TerminalPage>
Future<void> _takeControl() async {
final notifier = widget.notifier;
if (!_takingControl) setState(() => _takingControl = true);
- await notifier.selectAgent(
- widget.machineId,
- widget.agentId,
- takeControl: true,
- );
+ await notifier.selectAgent(widget.machineId, widget.agentId);
if (!mounted) return;
final session = notifier
.paneOfAgent(widget.machineId, widget.agentId)
diff --git a/mobile/lib/state/app_state.dart b/mobile/lib/state/app_state.dart
index 5e22fd038..508ac0ad6 100644
--- a/mobile/lib/state/app_state.dart
+++ b/mobile/lib/state/app_state.dart
@@ -2548,8 +2548,7 @@ class AppNotifier extends ChangeNotifier {
final updater = desktopUpdater ?? DesktopUpdater();
final staged = await updater.downloadAndStage(info);
if (staged == null) {
- updateError =
- 'Could not download and verify Harness ${info.version}.';
+ updateError = 'Could not download and verify Harness ${info.version}.';
return false;
}
final applied = await updater.applyStaged(staged, selfPid: pid);
@@ -5196,28 +5195,20 @@ class AppNotifier extends ChangeNotifier {
await selectAgent(machineId, agentId);
}
- /// Look at [agentId], opening its terminal if it has none.
+ /// Open [agentId] on this phone, taking its terminal.
///
- /// ⚠️ **Looking is not taking.** The daemon keeps ONE controller per agent, so every
- /// `terminal_open` this sends is a claim — and going to an agent another app is driving used to
- /// be enough to pull the terminal out from under it: swiping past an agent open on the desktop
- /// took it, every time, for as long as it took to swipe past. Arriving somewhere is not asking
- /// for it. So this opens POLITELY (see [TerminalSession.takeover]) and a terminal somebody else
- /// holds stays theirs; the page shows it as taken over, with the way in beside the words.
+ /// ⚠️ **Arriving IS the claim.** The daemon keeps ONE controller per agent, so every
+ /// `terminal_open` this sends takes the terminal from whoever held it — the desktop included.
+ /// That is the point: a phone is picked up to type at an agent, and asking politely first put a
+ /// read-only stream and a "Take control" band in front of every agent a desktop had open,
+ /// including the one the app opens on.
///
- /// [takeControl] is that way in, and the only thing that sets it is a person pressing "Take
- /// control" — see `phoneReclaimAction`. It is the one gesture that means the claim, rather than
- /// merely arriving where the claim could be made.
+ /// The displaced app is told who took it and has the same one press back; the phone's own band
+ /// is for exactly that case, a terminal taken back off this device — see `phoneReclaimAction`.
///
- /// A machine whose CLI predates the key cannot be asked politely — it takes over regardless — so
- /// on one of those NOTHING here opens a terminal except a press: arriving at an agent leaves the
- /// tile empty rather than taking a terminal the desktop may be working in, and the button is
- /// what opens it. See [_attachSession] and [MachineState.terminalNoTakeoverAvailable].
- Future<void> selectAgent(
- String machineId,
- String agentId, {
- bool takeControl = false,
- }) async {
+ /// The one open that stays polite is [warmAgentPane]'s guess about the next swipe, which is
+ /// nobody arriving anywhere. See [_attachSession].
+ Future<void> selectAgent(String machineId, String agentId) async {
final existing = paneOfAgent(machineId, agentId);
if (existing != null) {
selectedMachineId = machineId;
@@ -5233,36 +5224,29 @@ class AppNotifier extends ChangeNotifier {
}
final terminal = existing.session;
if (terminal != null) {
- // A press arms the NEXT open, and only that one: the flag is lowered again the moment an
- // open it armed is answered (see the `terminal_ready` branch of `TerminalSession`), so a
- // claim cannot outlive the press that made it and come back as a reconnect hours later.
- //
- // Arriving is never a claim, so anything else lowers it — but not out from under an open
- // already in flight or a stream being held, where lowering it mid-stream would hand the
- // terminal to a reconnect.
- if (takeControl) {
- terminal.takeover = true;
- } else if (!terminal.holdsTerminal) {
- terminal.takeover = false;
- }
+ // Arming the NEXT open, and only that one: the flag is lowered again the moment an open it
+ // armed is answered (see the `terminal_ready` branch of `TerminalSession`), so a claim
+ // cannot outlive the arrival that made it and come back as a reconnect hours later. Coming
+ // back to the agent raises it again, because that is another arrival.
+ terminal.takeover = true;
}
if (terminal == null) {
// The pane wanted this agent before `_attachSession` could actually attach it (the agent's
// terminal wasn't verified yet, the machine was briefly offline, ...). Nothing else retries a
// null session on its own — see `_attachPendingPanes` — so a click here has to.
- await _attachSession(existing, takeControl: takeControl);
- } else if (takeControl && terminal.watching) {
+ await _attachSession(existing);
+ } else if (terminal.watching) {
// ⚠️ **The one reopen that replaces a perfectly live stream.** A watcher renders the
// terminal without holding it (see [TerminalSession.watching]), so by every other measure
// here it is healthy — `controlling`, with a stream id — and the branches below would
- // leave it alone. The press is a request for the KEYBOARD, and the only way to ask for it
- // is a fresh open that takes the lease. Its retained output stays on screen meanwhile.
+ // leave it alone. What this page wants is the KEYBOARD, and the only way to ask for it is
+ // a fresh open that takes the lease. Its retained output stays on screen meanwhile.
if (!_canAttachPane(existing)) return;
await terminal.reopen(force: true);
} else if (terminal.status == TerminalSessionStatus.takenOver) {
- // Somebody else is driving it. Only the press reopens — see [takeControl]. Arriving here
- // leaves it exactly as it is, which is what the button in the header is FOR.
- if (!takeControl || !_canAttachPane(existing)) return;
+ // Somebody else took it while this page held it. Arriving back on the page asks for it
+ // again — the same open the band's button makes.
+ if (!_canAttachPane(existing)) return;
await terminal.reopen();
} else if (terminal.status != TerminalSessionStatus.opening &&
terminal.status != TerminalSessionStatus.controlling &&
@@ -5274,7 +5258,7 @@ class AppNotifier extends ChangeNotifier {
}
return;
}
- await addAgentToSwarm(machineId, agentId, takeControl: takeControl);
+ await addAgentToSwarm(machineId, agentId, takeControl: true);
}
/// Opens [agentId]'s stream for a tile nobody is looking at yet — the phone's
@@ -5294,19 +5278,18 @@ class AppNotifier extends ChangeNotifier {
/// `_paneNeedsAttach` exists to avoid, and a page nobody is looking at has no
/// business starting it.
///
- /// ⚠️ **Never takes a terminal another app is driving** — like every other
- /// open the phone makes now (see [selectAgent]); the machine answers only if
- /// the terminal is free. The tile then sits as `takenOver`, a dead end
- /// nothing retries, and landing on it changes nothing: only a person pressing
- /// "Take control" claims a terminal somebody else holds.
+ /// ⚠️ **The one open that never takes a terminal another app is driving.**
+ /// Landing on an agent claims it (see [_attachSession]); this is a guess
+ /// about the next swipe, and a guess must cost the desktop nothing. The
+ /// machine answers only if the terminal is free; otherwise the tile sits as
+ /// `takenOver` until a person actually arrives on it, and arriving is what
+ /// claims it.
///
/// ⚠️ **Nothing is opened at all on an OLDER machine.** A CLI that predates
/// the key ignores it and takes the terminal over like any other open — so on
- /// such a machine this guess would cost the desktop its terminal silently,
- /// which is the one thing it must never do. [_attachSession] refuses there
- /// for every caller now, a press excepted; this returns first only to avoid
- /// building a tile for a stream that would be refused a line later. See
- /// [MachineState.terminalNoTakeoverAvailable].
+ /// such a machine the politeness above is not available, and a guess there
+ /// would cost the desktop its terminal with nobody having arrived anywhere.
+ /// See [MachineState.terminalNoTakeoverAvailable].
Future<void> warmAgentPane(String machineId, String agentId) async {
if (_disposed) return;
if (machineStates[machineId]?.terminalNoTakeoverAvailable != true) return;
@@ -5331,7 +5314,7 @@ class AppNotifier extends ChangeNotifier {
// Told, so the parked page for this agent builds its panel — which is what
// measures the viewport `_attachSession` is about to wait for.
notifyListeners();
- await _attachSession(pane);
+ await _attachSession(pane, takeControl: false);
}
/// Show a MACHINE in the grid, for the states that belong to the machine
@@ -5524,9 +5507,19 @@ class AppNotifier extends ChangeNotifier {
);
}
+ /// ⚠️ **Every session built here CLAIMS the terminal** — [takeControl] is
+ /// true unless the caller is a guess about where the thumb goes next
+ /// ([warmAgentPane]), and nothing else opens a stream.
+ ///
+ /// The phone used to ask politely and land on a read-only stream with a "Take
+ /// control" band over it, which is what opening the app looked like whenever
+ /// a desktop had the agent — a band, an empty terminal, and a press before a
+ /// single key could be typed. A phone is picked up to type at an agent, so
+ /// arriving IS the claim now; the desktop it displaces says who took it and
+ /// has the same button back.
Future<void> _attachSession(
TerminalPane pane, {
- bool takeControl = false,
+ bool takeControl = true,
}) async {
if (_disposed || !allPanes.contains(pane) || pane.session != null) return;
final wantedAgentId = pane.agentId;
@@ -5535,29 +5528,6 @@ class AppNotifier extends ChangeNotifier {
if (machine == null) return;
if (machine.nodeOnline == false) return;
if (!machine.terminalCapabilityAvailable) return;
- // ⚠️ **On a machine that cannot be asked politely, only a press may open at all.**
- //
- // `takeover: false` is the whole of the phone's politeness, and a CLI that predates the key
- // ignores it and takes the terminal over like any other open. So on such a machine EVERY open
- // is a takeover, whatever this was called with — and the ones that are not a press (a tile
- // restored at launch, a page swiped onto, a machine coming back online) would take the
- // desktop's terminal silently, which is the one thing that must never happen.
- //
- // [warmAgentPane] already refused to guess here. This is the same refusal, moved to the one
- // place every session is built, so no caller can reach a silent takeover by another route.
- // A press still opens: that IS a person asking, and it is the only thing that is.
- //
- // Marked rather than merely refused, so the page can offer the press instead of sitting on
- // "Attaching…" — a null session says nothing about WHY on its own. See
- // [TerminalPane.heldForTakeControl].
- if (!takeControl && !machine.terminalNoTakeoverAvailable) {
- if (!pane.heldForTakeControl) {
- pane.heldForTakeControl = true;
- notifyListeners();
- }
- return;
- }
-
Agent? agent;
for (final candidate in machine.agents) {
if (candidate.id == wantedAgentId) {
@@ -5566,11 +5536,6 @@ class AppNotifier extends ChangeNotifier {
}
}
if (agent == null || !agent.terminalAvailable) return;
- // Cleared only once this is certain to build a session. Cleared any earlier, a press that
- // fell out above (the agent withdrawn between the tap and here) would leave the tile with no
- // session AND no mark — which the page reads as "attaching", forever, with the button that is
- // its only way forward now gone.
- pane.heldForTakeControl = false;
final terminal = TerminalSession(
machineId: pane.machineId,
@@ -5602,15 +5567,10 @@ class AppNotifier extends ChangeNotifier {
await connection.forceReconnect();
return true;
},
- // ⚠️ **Opening is not taking.** The only thing that claims a terminal another app is
- // driving is a person pressing "Take control" ([selectAgent]'s `takeControl`). Everything
- // else — a warm tile the pager opened ahead of the thumb, a page swiped to, a tile restored
- // at launch — asks for the terminal only if it is FREE, and is told no otherwise. See
- // [TerminalSession.takeover].
- //
- // A machine whose CLI predates the key ignores it and takes over anyway; nothing is opened
- // AHEAD of a person there at all (see [warmAgentPane]), so what reaches this line on such a
- // machine is a tile somebody is looking at.
+ // ⚠️ **Opening IS taking, for everything a person does.** A page opened, swiped onto or
+ // restored at launch claims the terminal; the one open that still asks politely is the warm
+ // tile the pager builds ahead of the thumb, which is a guess and must not cost the desktop
+ // anything. See [TerminalSession.takeover] and [warmAgentPane].
takeover: takeControl,
);
pane.session = terminal;
diff --git a/mobile/lib/state/terminal_pane.dart b/mobile/lib/state/terminal_pane.dart
index a5feb8a8e..014393e7f 100644
--- a/mobile/lib/state/terminal_pane.dart
+++ b/mobile/lib/state/terminal_pane.dart
@@ -87,22 +87,6 @@ class TerminalPane {
/// Also what keeps the closed-history clean: a warm tile closed by the pager
/// was never something the person had open, so it is not remembered as such.
bool warm = false;
-
- /// Whether this tile has no session because opening one would have TAKEN the
- /// terminal from whoever is driving it.
- ///
- /// Only ever set on a machine whose CLI predates `takeover: false` (see
- /// `MachineState.terminalNoTakeoverAvailable`). There, every open is a
- /// takeover, so `AppNotifier._attachSession` refuses each one that is not a
- /// person pressing "Take control" — and a tile left with a null session is
- /// otherwise indistinguishable from one still attaching, which would leave
- /// the page on "Attaching…" for good with no way forward.
- ///
- /// This is what gives it the way forward: the page reads it as "another app
- /// may be driving this — press to take it", the same offer a `takenOver`
- /// session gets. Cleared by the press itself, and by anything else that
- /// attaches the tile.
- bool heldForTakeControl = false;
}
/// A tile as it survives a restart: intent only, never the session.
diff --git a/mobile/lib/terminal/terminal_session.dart b/mobile/lib/terminal/terminal_session.dart
index e073f28dc..27db0bfa4 100644
--- a/mobile/lib/terminal/terminal_session.dart
+++ b/mobile/lib/terminal/terminal_session.dart
@@ -183,16 +183,16 @@ class TerminalSession extends ChangeNotifier {
/// for a terminal that is FREE, and is answered `CONTROL_LEASE_HELD` while anyone else holds it.
///
/// Read by every open this session sends, its own recoveries included, so a polite session never
- /// turns into a takeover behind a reconnect. The ONLY thing that sets it is a person pressing
- /// "Take control" (`AppNotifier.selectAgent`'s `takeControl`) — arriving on a page does not, and
- /// a refusal that arrives after a press asks again, properly — see the `terminal_error` branch of
- /// [handleFrame].
+ /// turns into a takeover behind a reconnect. What raises it is a person ARRIVING on the agent —
+ /// `AppNotifier.selectAgent`, whether that is the app opening, a swipe landing, a card in the
+ /// tabs panel or the "Take control" band — and a refusal that arrives after one asks again,
+ /// properly: see the `terminal_error` branch of [handleFrame].
///
- /// ⚠️ **A press arms ONE open.** Lowered again as soon as an open it armed is answered (the
+ /// ⚠️ **An arrival arms ONE open.** Lowered again as soon as an open it armed is answered (the
/// `terminal_ready` branch of [handleFrame]), because by then the claim has become a lease this
- /// session holds and later opens rest on holding it. Left standing it would outlive the press:
+ /// session holds and later opens rest on holding it. Left standing it would outlive the arrival:
/// a phone in a pocket reconnecting hours later would take the terminal off whoever had it by
- /// then, which is the silent takeover a press is meant to be the only cause of.
+ /// then, with nobody having picked the phone up at all.
///
/// ⚠️ Only meaningful against a daemon that advertises `noTakeover`: an older one ignores the key
/// and takes over regardless. The caller checks — `MachineState.terminalNoTakeoverAvailable`.
diff --git a/mobile/lib/widgets/terminal_pane_header.dart b/mobile/lib/widgets/terminal_pane_header.dart
index 56e611039..9dbbbc789 100644
--- a/mobile/lib/widgets/terminal_pane_header.dart
+++ b/mobile/lib/widgets/terminal_pane_header.dart
@@ -207,13 +207,11 @@ class TerminalPaneHeader extends StatelessWidget {
message: status.detail,
child: TextButton(
onPressed: canReconnect
- // The press is the claim: nothing else takes a
- // terminal another app holds. See
+ // Opening it again is the claim — see
// [AppNotifier.selectAgent].
? () => notifier.selectAgent(
session.machineId,
session.agentId,
- takeControl: true,
)
: null,
style: TextButton.styleFrom(
diff --git a/mobile/pubspec.yaml b/mobile/pubspec.yaml
index ee9e9d55a..ab3347ed5 100644
--- a/mobile/pubspec.yaml
+++ b/mobile/pubspec.yaml
@@ -2,7 +2,7 @@ name: harness_mobile
description: "Harness viewer for iOS and Android."
publish_to: 'none'
-version: 1.0.0+25
+version: 1.0.0+26
environment:
sdk: ^3.13.0
diff --git a/mobile/test/phone_open_claims_test.dart b/mobile/test/phone_open_claims_test.dart
new file mode 100644
index 000000000..d0c2c1e3a
--- /dev/null
+++ b/mobile/test/phone_open_claims_test.dart
@@ -0,0 +1,80 @@
+import 'dart:async';
+
+import 'package:flutter/widgets.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:harness_mobile/state/app_state.dart';
+
+import 'agent_pager_fixture.dart';
+
+/// Arriving on an agent TAKES its terminal.
+///
+/// ⚠️ **Why this has a test of its own.** The phone asked politely for a while, and what that
+/// looked like was opening the app onto a read-only stream with a band over it — "Take control" to
+/// type — whenever a desktop had the agent open. A phone is picked up to type at an agent. So an
+/// open a person causes is a claim, and the one open that still asks politely is the tile the pager
+/// builds ahead of the thumb, which is a guess (see `AppNotifier.warmAgentPane`).
+///
+/// The wire says it by OMISSION: `takeover: false` is the polite key, and a claim leaves it out —
+/// see `TerminalSession.openTerminal`.
+void main() {
+ /// The frames a terminal open sends, once the viewport it waits for has given up and fallen back
+ /// (`waitForViewportSize`) — nothing here mounts a panel to measure.
+ Future<Map<String, dynamic>> openedWith(
+ WidgetTester tester,
+ Future<void> Function(AppNotifier app) open,
+ PagerConn conn,
+ AppNotifier app,
+ ) async {
+ await tester.pumpWidget(const SizedBox.shrink());
+ unawaited(open(app));
+ await tester.pump(const Duration(seconds: 3));
+ expect(conn.opens, hasLength(1), reason: 'one open, for one agent');
+ // The keyframe the machine would answer with, which disarms the open's watchdog — a timer
+ // still pending at teardown fails the test. See [goLive].
+ final session = app.paneOfAgent('m', 'a')?.session;
+ if (session != null) await goLive(session);
+ // The keyframe's ack and the view's first resize each coalesce over a frame, and the binding
+ // fails a test that leaves one pending — the same two pumps the pager's tests spend.
+ await tester.pump(const Duration(milliseconds: 100));
+ await tester.pump(const Duration(milliseconds: 100));
+ return conn.opens.single;
+ }
+
+ testWidgets('opening an agent claims its terminal', (tester) async {
+ final conn = PagerConn();
+ final app = pagerApp(conn);
+ addTearDown(app.dispose);
+
+ final open = await openedWith(
+ tester,
+ (app) => app.selectAgent('m', 'a'),
+ conn,
+ app,
+ );
+
+ expect(open['agentId'], 'a');
+ expect(
+ open.containsKey('takeover'),
+ isFalse,
+ reason: 'no `takeover: false` — the open takes the terminal',
+ );
+ });
+
+ testWidgets('a tile opened ahead of the thumb asks politely', (tester) async {
+ final conn = PagerConn();
+ final app = pagerApp(conn);
+ addTearDown(app.dispose);
+ // A guess is only made where the daemon honours the key at all — see [warmAgentPane].
+ app.stateOf('m')!.terminalNoTakeoverAvailable = true;
+
+ final open = await openedWith(
+ tester,
+ (app) => app.warmAgentPane('m', 'a'),
+ conn,
+ app,
+ );
+
+ expect(open['agentId'], 'a');
+ expect(open['takeover'], isFalse, reason: 'a guess never takes a terminal');
+ });
+}