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.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
feat(mobile): open the phone straight into the last agent's terminal
tonye7e1d5e661f7
diff --git a/mobile/lib/core/last_opened_agent.dart b/mobile/lib/core/last_opened_agent.dartindex ab0fac6f4..df45f838d 100644--- a/mobile/lib/core/last_opened_agent.dart+++ b/mobile/lib/core/last_opened_agent.dart@@ -6,11 +6,13 @@ typedef AgentRef = ({String machineId, String agentId});/// The agent the phone had on screen, so a relaunch can put the person back on it.///-/// ⚠️ **Cleared when the terminal is LEFT, not when the app goes away.** A process the OS kills —-/// swiped out of recents, reclaimed in the background — never runs `dispose`, so the record it-/// leaves behind is exactly "the agent that was open when the app closed". Backing out of the-/// terminal does run it, and then there is nothing to reopen: the person had already gone back to-/// the list.+/// ⚠️ **In practice only ever overwritten, never cleared.** [forget] still exists and still works,+/// but nothing calls it: it was the pager's way of saying "the terminal was left", back when leaving+/// it meant landing on a list of agents that the next launch could start on instead. There is no+/// such list any more — the terminal is the phone's home screen — so the only question this answers+/// is *which* agent it opens on, and "none" is not one of the answers. A record naming an agent that+/// has since been deleted simply matches nothing, and the home screen falls through to the first+/// agent it can reach.class LastOpenedAgent {LastOpenedAgent(this._storage);@@ -52,6 +54,13 @@ class LastOpenedAgent {////// A terminal replaced by another one can be disposed AFTER its successor has remembered itself,/// and an unconditional clear would then erase the agent actually on screen.+ ///+ /// ⚠️ **Nothing calls this now, and that is the point rather than an oversight.** The pager used+ /// to call it on the way out, back when leaving the terminal meant landing on a list of agents;+ /// the terminal is the home screen now, so there is no "left the terminal" to report and clearing+ /// the record would only cost the next launch its reopen. Kept because the reopen is a flag away+ /// from being turned off again (`_showTabBar` in `phone_shell.dart` restores the list screens),+ /// and this is the half of the pair that would have to come back with it.void forget(AgentRef agent) {if (_value != agent) return;_value = null;diff --git a/mobile/lib/phone/agent_home.dart b/mobile/lib/phone/agent_home.dartnew file mode 100644index 000000000..3649b6934--- /dev/null+++ b/mobile/lib/phone/agent_home.dart@@ -0,0 +1,505 @@+import 'dart:async';++import 'package:flutter/foundation.dart' show ValueListenable;+import 'package:flutter/material.dart';+import 'package:lucide_icons_flutter/lucide_icons.dart';++import 'package:harness_mobile/shared/theme/app_theme.dart';+import 'package:harness_mobile/shared/widgets/empty_state.dart';+import 'package:harness_mobile/state/app_state.dart';++import 'agent_index.dart';+import 'agent_swipe.dart';+import 'agents_page.dart' show openNewAgent;+import 'machines_tab.dart';+import 'phone_fab.dart';+import 'phone_header.dart';+import 'phone_search_button.dart';+import 'phone_status.dart';++/// The phone's home: one agent's terminal, at the ROOT of the stack rather than pushed over a list.+///+/// ⚠️ **The root is what removes the back button, and that is the whole point of this widget.**+/// [PhoneHeader] draws its chevron from `Navigator.canPop()`, and the terminal used to sit on top of+/// an agents list — so there was always somewhere to go back TO. Here there is not: the terminal is+/// the first page, `canPop()` answers false, and the header loses its chevron without being told+/// anything. Nothing about the terminal page itself changed.+///+/// Which agent it shows is [AppNotifier.lastOpenedAgent]'s record, and failing that the first agent+/// the account can reach — see [_target]. Moving between agents is the pager's horizontal swipe,+/// which is why the neighbours below are the whole visible list rather than one entry: with no list+/// screen left, a pager over a single agent would be a home screen with no way off it.+class AgentHome extends StatefulWidget {+ const AgentHome({super.key, required this.notifier, this.openMachineId});++ final AppNotifier notifier;++ /// A machine whose password has just been accepted, whose first agent should take the screen once+ /// it answers. Holds null the rest of the time.+ ///+ /// ⚠️ **Without it, entering a password appears to do nothing.** The home screen holds the agent+ /// it is showing ([_AgentHomeState._showing]) and keeps it while it is still openable, which is+ /// exactly right for an agent list reshuffling underneath — and exactly wrong here: somebody who+ /// has just unlocked a machine is waiting for THAT machine's agents, and a perfectly healthy+ /// agent on another machine would hold the screen against them indefinitely.+ ///+ /// ⚠️ **Listened to rather than read as a plain field, and the difference is the whole feature.**+ /// This widget is a tab's root, built inside `onGenerateRoute` — which a nested [Navigator] runs+ /// once, when the route is created. A plain `String?` would therefore be read on the first launch+ /// frame, before any machine could have been linked, and never updated again however many times+ /// the shell rebuilt.+ ///+ /// Null where there is no shell to provide one, which is how a page pumped on its own still works.+ final ValueListenable<String?>? openMachineId;++ @override+ State<AgentHome> createState() => _AgentHomeState();+}++class _AgentHomeState extends State<AgentHome> {+ /// The agent the pager is currently built around, or null while nothing can be opened.+ ///+ /// ⚠️ **Held as state rather than recomputed every build, and it is what keeps the screen still.**+ /// [visibleAgents] sorts partly on state that moves by itself — an agent that starts working sorts+ /// upward — so a home screen reading "the first agent" on every rebuild would swap the terminal+ /// under somebody mid-sentence, for a reason nothing on screen explains. Once an agent is chosen+ /// it is kept until it can no longer be opened.+ ({String machineId, String agentId})? _showing;++ /// Whether the record of the last agent has been read. Until it has, the screen must not fall back+ /// to "the first agent": the record usually names a different one, and the fallback would be+ /// replaced a frame later — a terminal flashing past on every launch.+ bool _readingLast = true;++ /// A machine to jump to as soon as it reports an agent — [AgentHome.openMachineId], held until it+ /// is satisfied.+ ///+ /// Cleared the moment an agent of that machine takes the screen, and not before: the machine is+ /// still connecting when this arrives, so the first few rebuilds have nothing of its to offer and+ /// must not be mistaken for the request having been met.+ ///+ /// ⚠️ Also cleared by a SWIPE, in [_onAgentChanged]. Somebody who has swiped away has chosen an+ /// agent by hand, and a pending jump firing over that choice a second later is the screen moving+ /// on its own after the person started using it.+ String? _awaitingMachine;++ /// The neighbour list handed to the pager currently on screen, frozen for as long as that pager+ /// lives.+ ///+ /// ⚠️ **Rebuilding this on every frame silently breaks the pager, which is why it is held.**+ /// [AgentSwipeHost] works out its page index once, in `initState`, and then reads `neighbours` by+ /// that index on every build — the list and the index have to stay in step. [visibleAgents] does+ /// not: it sorts partly on state that moves by itself, so an agent that starts working sorts+ /// upward and every index after it shifts. A fresh list each build would therefore leave the pager+ /// drawing a DIFFERENT agent at the page it thinks it is on, mid-session, with nothing on screen+ /// to explain it.+ ///+ /// So the snapshot is taken when a pager opens, and replaced only when a new one does — which is+ /// exactly the rule every pushed pager already followed by being built once from a list the person+ /// had just been looking at.+ AgentSwipeList? _neighbours;++ /// The agent [_neighbours] was taken for. A different one means a different pager, and therefore a+ /// fresh snapshot.+ ({String machineId, String agentId})? _neighboursFor;++ /// How long the loading screen may hold the app before it gives up and shows the empty state.+ ///+ /// ⚠️ **A guard against a spinner that never stops, which the states below can genuinely produce.**+ /// `agentLoadStatus` is not guaranteed to reach a terminal value: `_performMachineDataLoad` returns+ /// early — leaving it on `loading` — when the auth revision moves under it, and a machine linked+ /// but not yet dialled sits on `idle` until something asks it to load. Neither is common, and both+ /// would otherwise be permanent, on the one screen where "stuck" and "still working" look alike.+ ///+ /// The empty state it falls back to is honest about not knowing — it names what to do next, and+ /// `RefreshIndicator` is not reachable here, so the value is set long enough that a slow-but-fine+ /// launch is never cut short. Matches the 45s the shell's old landing rules allowed.+ static const _loadingTimeout = Duration(seconds: 45);++ /// Set once [_loadingTimeout] has passed. From then on [_loadingMessage] answers null and the+ /// screen stops waiting — an agent that arrives later is still picked up by the ordinary rebuild.+ bool _gaveUpWaiting = false;+ Timer? _loadingDeadline;++ @override+ void initState() {+ super.initState();+ // Whatever it already holds counts: a relink that happened while this root was being rebuilt+ // would otherwise be missed between the write and the listen.+ _awaitingMachine = widget.openMachineId?.value;+ widget.openMachineId?.addListener(_onLinkedMachineChanged);+ _loadingDeadline = Timer(_loadingTimeout, () {+ if (!mounted || _gaveUpWaiting) return;+ setState(() => _gaveUpWaiting = true);+ });+ _readLast();+ }++ @override+ void dispose() {+ widget.openMachineId?.removeListener(_onLinkedMachineChanged);+ _loadingDeadline?.cancel();+ super.dispose();+ }++ @override+ void didUpdateWidget(AgentHome old) {+ super.didUpdateWidget(old);+ // The shell hands over one notifier for its lifetime, so this is belt and braces — but a+ // listener left on a replaced notifier would keep this State alive against a dead object.+ if (!identical(old.openMachineId, widget.openMachineId)) {+ old.openMachineId?.removeListener(_onLinkedMachineChanged);+ widget.openMachineId?.addListener(_onLinkedMachineChanged);+ _onLinkedMachineChanged();+ }+ }++ /// A machine's password was accepted somewhere in the app: its first agent now outranks whatever+ /// is on screen. See [AgentHome.openMachineId].+ void _onLinkedMachineChanged() {+ final requested = widget.openMachineId?.value;+ // Null is the notifier at rest, not a request to stop waiting for anything — a jump already+ // pending stands.+ if (requested == null || requested == _awaitingMachine) return;+ setState(() => _awaitingMachine = requested);+ }++ Future<void> _readLast() async {+ final last = await widget.notifier.lastOpenedAgent.read();+ if (!mounted) return;+ // The deadline has done its job either way once this lands, and a timer left running would fire+ // into a screen that is no longer waiting.+ _loadingDeadline?.cancel();+ setState(() {+ _readingLast = false;+ // ⚠️ Not applied if a pager is already up, which only happens when this read came back AFTER+ // the screen gave up waiting and opened an agent on its own. Taking the record then would move+ // somebody off a terminal they are already looking at, seconds after it opened.+ if (last != null && _neighboursFor == null) _showing = last;+ });+ }++ /// The agent to draw, given what the account can currently reach.+ ///+ /// In order:+ /// - a machine just unlocked has the first claim, once it has an agent to offer;+ /// - otherwise the pager already up keeps the screen, wherever its own swipes have taken it;+ /// - failing that the agent this screen last held, then the first openable one — a home screen+ /// with no list behind it cannot afford to show nothing while agents exist;+ /// - nothing openable at all → null, and the empty state says so.+ AgentEntry? _target(List<AgentEntry> entries) {+ // A machine just unlocked outranks what is on screen — see [AgentHome.openMachineId]. Until it+ // has an agent to offer, everything below carries on as usual, so the screen keeps showing+ // something real while the machine dials rather than blanking to a skeleton.+ final awaiting = _awaitingMachine;+ if (awaiting != null) {+ final arrival = entries+ .where(+ (entry) =>+ entry.machineId == awaiting && entry.agent.terminalAvailable,+ )+ .firstOrNull;+ if (arrival != null) return arrival;+ }+ // ⚠️ **The pager the screen already holds is asked FIRST, before [_showing], and that ordering+ // is what keeps swiping alive.** A swipe moves the pager and reports the agent it arrived at,+ // which lands in [_showing] — so asking [_showing] first would name an agent the live pager was+ // not built for, the key below would change, and the pager would be torn down and rebuilt on+ // every swipe. Asked in this order, a pager that is still openable simply stays.+ final opened = _neighboursFor;+ if (opened != null) {+ final live = _entryFor(entries, opened);+ if (live != null) return live;+ }+ final showing = _showing;+ if (showing != null) {+ final held = _entryFor(entries, showing);+ if (held != null) return held;+ }+ return entries.where((entry) => entry.agent.terminalAvailable).firstOrNull;+ }++ /// Whether any machine can currently host an agent.+ ///+ /// The gate between the two empty screens, and the same test every `+` in the app applies: an+ /// agent needs a machine that answers, so while none does there is nothing an Agents screen could+ /// offer and the machines screen is the whole answer.+ bool _anyMachineReady() => filterableMachines(+ widget.notifier,+ ).any((machine) => phoneMachineStatusOf(machine) == PhoneMachineStatus.ready);++ /// What to tell somebody who is waiting, or null once there is nothing left to wait for.+ ///+ /// Null is the whole point of the return type: it is what separates "still coming" from "answered,+ /// and the answer is nothing", and only the second one may draw an empty state. Getting that+ /// backwards in either direction is a real bug on a launch screen — a spinner that never stops+ /// looks broken, and "No agents yet" shown a second before the agents arrive is a lie the person+ /// acts on.+ ///+ /// The message names the step actually in progress rather than saying "Loading…" throughout. On a+ /// cold launch these run several seconds each, and a line that changes is how somebody can tell a+ /// slow connection from a stuck one.+ String? _loadingMessage() {+ // Waited long enough — see [_loadingTimeout]. ⚠️ Checked before [_readingLast] and not after:+ // the local read is the one step that cannot be retried from the empty state, so if even that+ // has not landed in 45 seconds the screen has to stop waiting on it too.+ if (_gaveUpWaiting) return null;+ // The local record first: it is read from storage and decides which agent is even wanted, so+ // until it lands nothing else has been decided either.+ if (_readingLast) return 'Getting things ready…';+ final notifier = widget.notifier;+ // Then the account's machines, over the network.+ if (notifier.machines.isEmpty) {+ return notifier.machinesLoading ? 'Looking for your machines…' : null;+ }+ final machines = filterableMachines(notifier);+ // Then each machine's own socket. `connecting` covers both the dial and the handshake after it.+ if (machines.any(+ (machine) =>+ phoneMachineStatusOf(machine) == PhoneMachineStatus.connecting,+ )) {+ return 'Connecting to your machine…';+ }+ // And finally the agent list a connected machine still owes. ⚠️ Only from machines that are+ // READY: an offline one is left at whatever `agentLoadStatus` it had when it dropped, and+ // waiting on that never ends.+ final loadingAgents = machines.any((machine) {+ if (phoneMachineStatusOf(machine) != PhoneMachineStatus.ready) {+ return false;+ }+ return switch (machine.agentLoadStatus) {+ AgentLoadStatus.idle || AgentLoadStatus.loading => true,+ AgentLoadStatus.loaded ||+ AgentLoadStatus.error ||+ AgentLoadStatus.needsLink => false,+ };+ });+ return loadingAgents ? 'Loading your agents…' : null;+ }++ /// The entry naming [agent], if it is in [entries] and can actually be opened.+ AgentEntry? _entryFor(+ List<AgentEntry> entries,+ ({String machineId, String agentId}) agent,+ ) => entries+ .where(+ (entry) =>+ entry.machineId == agent.machineId &&+ entry.agent.id == agent.agentId &&+ entry.agent.terminalAvailable,+ )+ .firstOrNull;++ @override+ Widget build(BuildContext context) => ListenableBuilder(+ listenable: widget.notifier,+ builder: (context, _) {+ AppTheme.watch(context);+ final entries = visibleAgents(agentIndex(widget.notifier));+ // ⚠️ `_readingLast` holds the screen back so the record gets to name the agent before the+ // fallback does — but only while the screen is still willing to wait at all. Past+ // [_loadingTimeout] a read that has not returned is not going to, and going on to pick an+ // agent beats holding an empty screen against one that is sitting right there.+ final target = (_readingLast && !_gaveUpWaiting)+ ? null+ : _target(entries);+ if (target == null) {+ // ⚠️ Still on its way in and actually empty are two different screens, and the difference+ // matters more here than it did on a list. A list could show its own shape greyed out while+ // it filled; what is coming here is a TERMINAL, so a placeholder in the shape of a list of+ // cards promises the wrong thing and then never delivers it. [_AgentHomeLoading] says what+ // is happening in words instead, and hands over to the terminal's own "Attaching…" — the+ // two are built to read as one sequence.+ final loading = _loadingMessage();+ if (loading != null) return _AgentHomeLoading(message: loading);+ // ⚠️ **No machine is open → this is a MACHINE problem, so the machine screen is what the+ // person gets.** An "Agents" header over "No machines are open yet" named the thing that is+ // missing rather than the thing to do about it, and the only route to a password form was+ // the search glyph in the corner — the least likely place to look for one. An agent cannot+ // exist before a machine is linked, so until one is, this screen IS the machines screen:+ // rows to tap, a password form behind the one that wants it, and pull-to-refresh.+ //+ // The Machines TAB itself is untouched and still reachable by every other route; this just+ // borrows its body rather than growing a second, drifting copy of the same list.+ if (!_anyMachineReady()) {+ return MachinesTab(notifier: widget.notifier);+ }+ return _AgentHomeEmpty(notifier: widget.notifier);+ }+ final chosen = (machineId: target.machineId, agentId: target.agent.id);+ // A pager already up for this agent is LEFT ALONE — same key, same snapshot, so it keeps the+ // page it is on, and [_showing] keeps naming whatever it has been swiped to. A pager is built+ // here only when there is none, or when the one there opened on an agent that can no longer be+ // opened; only then does this screen's own idea of where it is get overwritten.+ //+ // ⚠️ **[_showing] is set HERE and not from [target] unconditionally, which is a bug that was+ // in this line.** While a pager is live, `target` is by construction the agent it OPENED on+ // (see [_target]) — not the agent on screen — so assigning it every build would quietly undo+ // every swipe the pager reported, one frame after it reported it.+ if (_neighboursFor != chosen) {+ _neighboursFor = chosen;+ _neighbours = AgentSwipeList(entries);+ _showing = chosen;+ }+ // Spent only by an agent of the machine the jump actually named. Not by [_onAgentChanged],+ // which would treat the unrelated agent drawn while that machine is still dialling as the jump+ // having been met — and it would then never fire.+ if (_awaitingMachine == chosen.machineId) _awaitingMachine = null;+ final opened = chosen;+ // ⚠️ **Keyed by the agent the pager OPENED on, not by the agent on screen, and the two come+ // apart the moment somebody swipes.** The pager moves through its own pages internally; this+ // screen hears about it through [_onAgentChanged] and records it in [_showing] — but if the key+ // followed that, every swipe would hand Flutter a new key, tear the pager down and build a+ // fresh one around the agent just arrived at. The swipe would appear to work once and then the+ // screen would sit frozen on it, having thrown away the pager whose pages are the only way on.+ //+ // So the key changes only when [_target] picks a DIFFERENT agent than the pager was built for,+ // which happens when the one it opened on can no longer be opened at all.+ return AgentSwipeHost(+ key: ValueKey('${opened.machineId}/${opened.agentId}'),+ notifier: widget.notifier,+ machineId: opened.machineId,+ agentId: opened.agentId,+ // The whole reachable list, so a swipe walks every agent on the account. There is no list+ // screen to go back to any more, which makes this the only way to another agent.+ neighbours: _neighbours,+ // Told where it has swiped to, so [_showing] follows the pager rather than the pager being+ // dragged back to where this screen last put it.+ onAgentChanged: _onAgentChanged,+ );+ },+ );++ /// The pager reports a SWIPE: the agent arrived at is the one this screen now holds.+ ///+ /// ⚠️ Assigned without setState on purpose. This arrives during the pager's own rebuild, and+ /// nothing on screen is derived from the field in the frame it changes — it exists so the NEXT+ /// rebuild keeps the agent the person swiped to instead of snapping back to the one opened on.+ void _onAgentChanged(({String machineId, String agentId}) agent) {+ _showing = agent;+ // A swipe is a choice made by hand, so any jump still pending is abandoned rather than allowed+ // to move the screen again a second later. See [_awaitingMachine].+ _awaitingMachine = null;+ }+}++/// The screen the app opens on while it is still working out which terminal to show.+///+/// ⚠️ **Deliberately not a skeleton, and that is the point of it.** A skeleton is a promise about+/// the SHAPE of what is coming, and it used to be right here because the Agents tab's root was a+/// list of cards. What lands now is one agent's terminal, so a column of grey cards promised a+/// screen that never arrived — visible for the seconds a cold launch takes, which is exactly when+/// somebody is deciding whether the app is working.+///+/// ⚠️ **No header either.** "Agents" over a big empty area is the list screen's chrome, and search+/// sitting in the corner offers something to do at the one moment nothing can be done yet. The+/// screen is one centred line saying what is happening, which is also what [_Attaching] in+/// `terminal_page.dart` looks like — same spinner, same size, same type — so the two read as one+/// sequence rather than two unrelated waits.+class _AgentHomeLoading extends StatelessWidget {+ const _AgentHomeLoading({required this.message});++ /// The step in progress, in the person's words — see [_AgentHomeState._loadingMessage].+ final String message;++ @override+ Widget build(BuildContext context) {+ AppTheme.watch(context);+ return Scaffold(+ backgroundColor: AppPalette.windowBg,+ body: SafeArea(+ child: Center(+ child: Column(+ mainAxisSize: MainAxisSize.min,+ children: [+ SizedBox.square(+ dimension: 22,+ child: CircularProgressIndicator(+ strokeWidth: 2,+ color: AppPalette.accent,+ ),+ ),+ const SizedBox(height: 14),+ // ⚠️ Keyed by the text so a change between steps CROSS-FADES rather than snapping.+ // These lines replace each other while somebody is reading them, and a hard swap at+ // that moment reads as a glitch instead of as progress.+ AnimatedSwitcher(+ duration: const Duration(milliseconds: 220),+ child: Text(+ message,+ key: ValueKey(message),+ textAlign: TextAlign.center,+ style: TextStyle(+ color: AppPalette.textSecondary,+ fontSize: 14,+ ),+ ),+ ),+ ],+ ),+ ),+ ),+ );+ }+}++/// The one empty case left on this screen: a machine is open and able to host an agent, and there+/// simply is not an agent yet.+///+/// ⚠️ **Every other empty case belongs to [MachinesTab] and is routed there instead.** No machines+/// on the account, machines that all want a password, machines that are switched off — those are+/// machine problems wearing an Agents header, and the thing to do about them is a row on the+/// machines list, not a sentence pointing at one. By the time this widget is built the only thing+/// missing is the agent, which is exactly what its `+` creates.+class _AgentHomeEmpty extends StatelessWidget {+ const _AgentHomeEmpty({required this.notifier});++ final AppNotifier notifier;++ @override+ Widget build(BuildContext context) {+ AppTheme.watch(context);+ // ⚠️ Recomputed rather than passed in. This is built from a `build`, so the machine that was+ // ready a frame ago may not be now — and `ready.first` below is dereferenced.+ final ready = [+ for (final machine in filterableMachines(notifier))+ if (phoneMachineStatusOf(machine) == PhoneMachineStatus.ready) machine,+ ];+ // The caller only builds this when a machine is ready, but a rebuild can arrive between that+ // test and this one. Falling back to the machines screen keeps the two in step rather than+ // drawing a `+` that cannot fire.+ if (ready.isEmpty) return MachinesTab(notifier: notifier);+ return Scaffold(+ backgroundColor: AppPalette.windowBg,+ floatingActionButton: PhoneFab(+ icon: LucideIcons.plus300,+ tooltip: 'New agent',+ // The first machine that can host one. Which machine is the form's first question, and it+ // is changed there.+ onPressed: () =>+ openNewAgent(context, notifier, ready.first.machine.machineId),+ ),+ body: SafeArea(+ bottom: false,+ child: Column(+ children: [+ PhoneHeader(+ large: true,+ title: 'Agents',+ trailing: [PhoneSearchButton(notifier: notifier)],+ ),+ const Expanded(+ child: EmptyState(+ icon: LucideIcons.squareTerminal300,+ title: 'No agents yet',+ message:+ 'Tap + to start one, or launch an agent from Harness on a '+ 'machine and it will appear here.',+ ),+ ),+ ],+ ),+ ),+ );+ }+}diff --git a/mobile/lib/phone/agent_swipe.dart b/mobile/lib/phone/agent_swipe.dartindex bce3fa1a5..3ea4b4e5d 100644--- a/mobile/lib/phone/agent_swipe.dart+++ b/mobile/lib/phone/agent_swipe.dart@@ -70,6 +70,7 @@ class AgentSwipeHost extends StatefulWidget {required this.machineId,required this.agentId,required this.neighbours,+ this.onAgentChanged,});final AppNotifier notifier;@@ -82,6 +83,14 @@ class AgentSwipeHost extends StatefulWidget {/// Null for a page opened without neighbours, which is then simply the page.final AgentSwipeList? neighbours;+ /// Told which agent a swipe has arrived at, for a host that has to keep up with the pager.+ ///+ /// Only [AgentHome] passes it, and it needs it: the pager lives at the ROOT there and is rebuilt+ /// whenever the account's state moves, so a host still naming the agent this opened on would snap+ /// the screen back to it mid-session. Every pushed pager is popped rather than rebuilt around a+ /// different agent, and passes null.+ final ValueChanged<({String machineId, String agentId})>? onAgentChanged;+@overrideState<AgentSwipeHost> createState() => _AgentSwipeHostState();}@@ -167,9 +176,14 @@ class _AgentSwipeHostState extends State<AgentSwipeHost> {_voice.dispose();_controller?.dispose();_detachAll();- // Leaving the terminal means the next launch starts on the list. A process the OS kills never- // gets here, which is what leaves the record behind for the reopen.- widget.notifier.lastOpenedAgent.forget(_current);+ // ⚠️ **The record is deliberately NOT cleared here, and it used to be.** The old rule was+ // "leaving the terminal means the next launch starts on the list" — but there is no list to+ // start on any more: the terminal IS the home screen (see [AgentHome]), and a pager is disposed+ // every time the home screen rebuilds around a different agent. Forgetting on the way out would+ // erase, on an ordinary rebuild, the very record the next launch is supposed to reopen.+ //+ // Nothing else has to clear it either. A record naming an agent that no longer exists costs one+ // lookup that finds nothing, and [AgentHome] falls through to the first reachable agent.super.dispose();}@@ -254,6 +268,9 @@ class _AgentSwipeHostState extends State<AgentSwipeHost> {// and finds none._attached.add(arrived);widget.notifier.lastOpenedAgent.remember(arrived);+ // Before the setState, so a host that rebuilds this pager in response already names the agent+ // swiped to — told afterwards, it would rebuild still pointing at the previous one.+ widget.onAgentChanged?.call(arrived);setState(() {_page = index;_current = arrived;diff --git a/mobile/lib/phone/phone_shell.dart b/mobile/lib/phone/phone_shell.dartindex 9fb8c7a6a..a08c282d4 100644--- a/mobile/lib/phone/phone_shell.dart+++ b/mobile/lib/phone/phone_shell.dart@@ -1,3 +1,5 @@+// `Timer` — used only by the kept-but-dead landing rules below, which is also why+// `phone_navigation.dart` and `phone_status.dart` are still imported here.import 'dart:async';import 'package:flutter/material.dart';@@ -5,8 +7,8 @@ import 'package:flutter/material.dart';import 'package:harness_mobile/state/app_state.dart';import '../p2p/phone_terminal_p2p.dart';+import 'agent_home.dart';import 'agent_index.dart';-import 'agents_tab.dart';import 'machines_tab.dart';import 'phone_navigation.dart';import 'phone_shell_scope.dart';@@ -16,19 +18,17 @@ import 'settings_page.dart';/// Whether the shell draws its tab bar.///-/// Off because the terminal is where the phone opens: the landing rules below-/// reopen the last agent, fall back to Machines when nothing answers, and carry-/// a freshly linked machine through to its first agent — so the app puts itself-/// where it belongs, and a bar for steering it there by hand is a row of chrome-/// under every screen paying for the case those rules already cover.+/// Off because the terminal is where the phone opens and stays: [AgentHome] is+/// the Agents tab's root, it picks the agent itself, and a bar for steering+/// between tabs by hand is a row of chrome under every screen paying for a case+/// that no longer arises.////// ⚠️ It hides the BAR, not the tabs. All three still exist, still hold their-/// own page stacks, [_PhoneShellState._select] still pops one back to its root,-/// and the landing rules still choose between them — nothing below this flag-/// knows it is off. What goes with it is the only way to REACH a tab by hand,-/// so with it off the app can only be where it was put: fine while that place-/// is one agent's terminal, and the reason this is a flag rather than a-/// deletion.+/// own page stacks, and [_PhoneShellState._select] still pops one back to its+/// root — nothing below this flag knows it is off. What goes with it is the only+/// way to REACH a tab by hand, so with it off the app can only be where it was+/// put: fine while that place is one agent's terminal, and the reason this is a+/// flag rather than a deletion.const bool _showTabBar = false;/// The signed-in phone app: three tabs, each with its own page stack.@@ -66,15 +66,12 @@ class _PhoneShellState extends State<PhoneShell> with WidgetsBindingObserver {void initState() {super.initState();WidgetsBinding.instance.addObserver(this);- widget.notifier.addListener(_onAppChanged);- unawaited(_reopenLastAgent());}@overridevoid dispose() {WidgetsBinding.instance.removeObserver(this);- widget.notifier.removeListener(_onAppChanged);- _pendingDeadline?.cancel();+ _linkedMachineId.dispose();for (final controller in _heroControllers.values) {controller.dispose();}@@ -83,32 +80,84 @@ class _PhoneShellState extends State<PhoneShell> with WidgetsBindingObserver {// ── Where the app lands ───────────────────────────────────────────────────────────────────────//- // Three moves the shell makes on its own, each at most once and each abandoned the moment the- // person picks a tab themselves — a screen that jumps after somebody has started using it is- // worse than one that never jumped at all:+ // Almost nothing, now — and that is the change. The shell used to reopen the last agent itself,+ // fall back to Machines when nothing answered, and time the wait out after 45 seconds, because+ // the thing it was steering towards was a page it had to PUSH over an agents list. There is no+ // list and no push: [AgentHome] is the Agents tab's root, and it reads the last-agent record,+ // waits for the machines to answer and picks the agent, all as part of drawing itself.//- // - the agent open when the app last closed is opened again ([_reopenLastAgent]);- // - failing that, a phone linked to no machine that answers opens on Machines ([_decideLanding]),- // because the Agents tab would only be an empty list pointing there;- // - a password accepted on the Machines tab carries on to that machine's first agent- // ([_followLinkedMachine]).+ // One move is left, because it crosses tabs and no page can make it alone: a password accepted on+ // the Machines tab takes the person back to Agents, where the machine they just opened is about+ // to bring its agents with it.++ /// The machine whose password was just accepted, for [AgentHome] to open once it answers.+ ///+ /// ⚠️ **A notifier and not a field on this State, because a field cannot reach [AgentHome] at+ /// all.** Each tab's root is built inside `onGenerateRoute`, which a nested [Navigator] runs ONCE+ /// when it creates that route — so the root keeps forever whatever arguments it was first given,+ /// and `setState` here rebuilds this widget without ever rebuilding it. A value passed down as a+ /// constructor field would have been read on the first launch frame, when no machine had been+ /// linked, and never again.+ ///+ /// Handed over once, at construction, and written to afterwards: [AgentHome] listens, so a value+ /// set at any point reaches it. Never reset here — [AgentHome] spends the request itself, on the+ /// agent arriving or on a swipe away from it.+ final _linkedMachineId = ValueNotifier<String?>(null);++ /// A password was accepted: the agent is what the person came for, so the phone points itself at+ /// that machine and shows the tab an agent lives on.+ ///+ /// No waiting and no timeout here, which is what this used to be full of. The machine is still+ /// connecting at this point and [AgentHome] is already watching for exactly that — it holds+ /// whatever is on screen while the machine dials, then opens the first agent it reports.+ void _followLinkedMachine(String machineId) {+ _linkedMachineId.value = machineId;+ setState(() {+ _tab = PhoneTab.agents;+ _tabCanPop =+ _navigators[PhoneTab.agents]?.currentState?.canPop() ?? false;+ });+ }++ // ── The landing rules this replaced, kept and not called ──────────────────────────────────────+ //+ // ⚠️ **Dead on purpose: nothing below this line runs.** It is the shell's old way of deciding+ // where the app opens, from when the Agents tab's root was a LIST and a terminal had to be pushed+ // over it — so the shell waited for a machine to answer, pushed the pager itself, gave up after+ // [_pendingTimeout], and fell back to Machines when no machine answered at all. [AgentHome] now+ // does all of that as part of drawing itself, without a push and without a timeout, so none of+ // this is wired up any more.+ //+ // Kept because the list screens are kept: `_showTabBar` above and `AgentsTab` are both still here+ // for the same reason, and bringing them back would need these rules back with them.+ // [_followLinkedMachine] above is the live one; the copy here is renamed so the two can sit side+ // by side.+ //+ // `ignore_for_file` is deliberately NOT used: the ignores are per-member, so an unused member+ // added to this class later still gets flagged./// An agent waiting for its machine to answer before it can be opened.+ // ignore: unused_field({String machineId, String? agentId, bool afterLink})? _pending;+ // ignore: unused_fieldTimer? _pendingDeadline;/// How long a machine gets to answer. Past this the phone stays where it is — on a list the person/// can act on — rather than jumping into a terminal a minute after they stopped expecting it.+ // ignore: unused_fieldstatic const _pendingTimeout = Duration(seconds: 45);/// The last-agent record has not been read yet, so the landing tab cannot be chosen: a reopen/// would override it.+ // ignore: unused_fieldbool _readingLastAgent = true;/// The landing has been decided — by the shell or by the person — and nothing moves on its own- /// again except [_followLinkedMachine], which the person asked for by entering a password.+ /// again except [_followLinkedMachineLegacy], which the person asked for by entering a password.+ // ignore: unused_fieldbool _landed = false;+ // ignore: unused_elementFuture<void> _reopenLastAgent() async {final last = await widget.notifier.lastOpenedAgent.read();if (!mounted) return;@@ -120,7 +169,8 @@ class _PhoneShellState extends State<PhoneShell> with WidgetsBindingObserver {}}- void _followLinkedMachine(String machineId) {+ // ignore: unused_element+ void _followLinkedMachineLegacy(String machineId) {_landed = true;// Straight to Agents, before the machine has finished connecting: the row it lands on says// "Connecting…", which is what is actually happening, and the agent opens over it once it can.@@ -132,6 +182,7 @@ class _PhoneShellState extends State<PhoneShell> with WidgetsBindingObserver {_wait(machineId: machineId, agentId: null, afterLink: true);}+ // ignore: unused_elementvoid _wait({required String machineId,required String? agentId,@@ -143,6 +194,7 @@ class _PhoneShellState extends State<PhoneShell> with WidgetsBindingObserver {_onAppChanged();}+ // ignore: unused_elementvoid _dropPending() {_pending = null;_pendingDeadline?.cancel();@@ -150,6 +202,7 @@ class _PhoneShellState extends State<PhoneShell> with WidgetsBindingObserver {if (mounted) _onAppChanged();}+ // ignore: unused_elementvoid _onAppChanged() {if (!mounted) return;final pending = _pending;@@ -231,6 +284,7 @@ class _PhoneShellState extends State<PhoneShell> with WidgetsBindingObserver {/// it, so a phone that IS linked reads exactly like one that is not for the first second or two./// An empty account decides nothing either — until the list arrives, empty is indistinguishable/// from not loaded.+ // ignore: unused_elementvoid _decideLanding() {if (_landed || _readingLastAgent) return;final notifier = widget.notifier;@@ -258,6 +312,7 @@ class _PhoneShellState extends State<PhoneShell> with WidgetsBindingObserver {});}+ // ignore: unused_elementvoid _afterFrame(VoidCallback action) {WidgetsBinding.instance.addPostFrameCallback((_) {if (mounted) action();@@ -265,6 +320,8 @@ class _PhoneShellState extends State<PhoneShell> with WidgetsBindingObserver {WidgetsBinding.instance.ensureVisualUpdate();}+ // ── End of the kept-but-dead landing rules ────────────────────────────────────────────────────+/// Back in the foreground: a p2p retry waiting out its delay fires now, and so does every machine/// socket the phone lost while it was away. Going to the background needs nothing — the OS/// suspends the socket, and the redial tears the old wire down and negotiates a fresh one.@@ -283,9 +340,6 @@ class _PhoneShellState extends State<PhoneShell> with WidgetsBindingObserver {NavigatorState? get _currentNavigator => _navigators[_tab]?.currentState;void _select(PhoneTab tab) {- // The person chose where to be: nothing the shell was waiting to open lands on them later.- _landed = true;- if (_pending != null) _dropPending();if (tab == _tab) {// A second tap on the tab you are already on pops that tab back to its root — the phone// convention, and the only way back out of a deep stack without walking every page.@@ -301,7 +355,10 @@ class _PhoneShellState extends State<PhoneShell> with WidgetsBindingObserver {}Widget _rootFor(PhoneTab tab) => switch (tab) {- PhoneTab.agents => AgentsTab(notifier: widget.notifier),+ PhoneTab.agents => AgentHome(+ notifier: widget.notifier,+ openMachineId: _linkedMachineId,+ ),PhoneTab.machines => MachinesTab(notifier: widget.notifier),PhoneTab.settings => SettingsPage(notifier: widget.notifier),};@@ -406,9 +463,8 @@ class _PhoneShellState extends State<PhoneShell> with WidgetsBindingObserver {: PhoneTabBar(current: _tab,onSelect: _select,- waitingCount: waitingAgents(- agentIndex(widget.notifier),- ).length,+ waitingCount: waitingAgents(agentIndex(widget.notifier))+ .length,),),),diff --git a/mobile/lib/phone/terminal_page.dart b/mobile/lib/phone/terminal_page.dartindex e78127c11..700c29148 100644--- a/mobile/lib/phone/terminal_page.dart+++ b/mobile/lib/phone/terminal_page.dart@@ -643,6 +643,13 @@ class _TerminalPageState extends State<TerminalPage>/// this one. Popping from here then took down the NEW agent's terminal, the page underneath/// surfaced, found its pane gone too and popped again, and the person landed on the list instead/// of in the agent they had just made.+ ///+ /// ⚠️ **Does nothing at all on the home screen, and that is correct rather than a gap.** The+ /// terminal is the root of its stack there ([AgentHome]), so `canPop` is false and the guard below+ /// returns — but the reason this is called is that the agent went away, and [AgentHome] watches+ /// the same agent list: the agent leaves it, the home screen's target stops matching, and it+ /// rebuilds onto another agent or onto its empty state. Leaving the route was never what fixed+ /// this case; it only uncovered the list that did.void _leave() {WidgetsBinding.instance.addPostFrameCallback((_) {if (!mounted) return;