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
import '../core/app_version.dart';
import '../core/client_build.dart';
import '../core/install_source.dart';
import '../core/test_run.dart';
import '../measurement/launch_measurement.dart';
import '../measurement/onboarding_measurement.dart';
import '../measurement/product_connections.dart';
import '../measurement/product_measurement.dart';
import '../measurement/product_resumes.dart';
import '../measurement/setup_transport.dart';
import 'dart:async';
import 'dart:convert' show jsonDecode, jsonEncode;
import 'dart:math' show Random, min;
import 'package:dio/dio.dart';
import 'package:xterm/xterm.dart' show RemoteScrollMemory, Terminal;
import 'package:flutter/foundation.dart';
// The 80-character limit on a fork's name counts what a person sees, as the desktop's does.
import 'package:flutter/widgets.dart'
show AppLifecycleListener, StringCharacters;
import 'package:flutter_riverpod/flutter_riverpod.dart';
import '../api/api_client.dart';
import '../viewer/direct_auth_api.dart';
import '../viewer/direct_link.dart';
import '../viewer/direct_login.dart';
import '../viewer/group_sync.dart';
import '../e2ee/bytes.dart' show b64e;
import '../viewer/sign_in_browser.dart';
import '../viewer/viewer_services.dart';
import '../auth/auth_session.dart';
import '../auth/peer_link_client.dart';
import '../auth/sign_in_client.dart';
import '../auth/sign_in_provider.dart';
import '../auth/cli_link.dart';
import '../core/config.dart';
import '../core/agent_git_context.dart';
import '../core/agent_preference.dart';
import '../core/engine_availability.dart';
import '../core/device_name.dart';
import '../core/agent_handoff.dart';
import '../core/permission_modes.dart';
import '../core/last_opened_agent.dart';
import '../core/phone_search_history.dart';
import '../core/machine_cache.dart';
import '../core/models.dart';
import '../core/project_folder.dart';
import '../core/project_history.dart';
import '../core/retry.dart';
import '../logging/app_log.dart';
import '../logging/startup_trace.dart';
import '../logging/typing_trace.dart';
import '../notify/agent_announcer.dart';
import '../notify/done_notice.dart';
import '../notify/push_channel.dart';
import '../notify/push_tokens.dart';
import '../notify/system_notices.dart';
import '../settings/config_store.dart';
import '../stats/harness_stats.dart';
import '../terminal/terminal_session.dart';
import '../terminal/remote_media_download.dart';
import '../widgets/engine_identity.dart' show allEngines, engineIdentity;
import 'dial_status.dart';
import 'kept_screens.dart';
import 'retarget_refusal.dart';
import 'pane_layout_store.dart';
import 'session_preview.dart';
import 'terminal_pane.dart';
import 'desk_sync.dart';
import 'machine_profile.dart';
import 'phone_desk.dart';
import '../daemons/daemon_habits.dart';
import '../daemons/individual_art.dart';
import '../daemons/zoo_client.dart';
import 'swarm.dart';
import '../terminal/terminal_binary.dart';
import '../ws/ws_conn.dart';
import '../ws/ws_pool.dart';
import 'pending_question.dart';
import 'search_when.dart';
import 'session_content_search.dart';
import '../usage/remote_usage.dart';
import '../usage/usage_accounts.dart';
import '../usage/usage_summary.dart';
import '../phone/phone_name_store.dart';
import '../viewer/device_log.dart';
import '../viewer/device_history.dart';
import '../viewer/device_log_sync.dart';
import '../swarm/swarm_file_picker.dart' show clearSwarmPickerCopies;
import '../swarm/swarm_notices.dart';
import '../swarm/swarm_outgoing_files.dart' show SwarmOutgoingFile;
import '../swarm/swarm_request.dart';
enum AppStatus { bootstrapping, unauthenticated, authenticated }
enum AgentLoadStatus { idle, needsLink, loading, loaded, error }
/// Result of [AppNotifier.restartAgent]. [error] null means the RPC succeeded; [resumed] then says
/// whether the daemon reattached the agent's prior session or fell back to a fresh one (e.g. the
/// engine's resume flag wasn't recognized) — worth telling the user about, since it's not a failure
/// but the conversation may not have continued the way "Restart" implies.
///
/// A non-null [error] is a sentence to show as it is, and not always a failure: a restart whose
/// reply never came says it could not be confirmed (see `AppNotifier._restartUnconfirmed`).
class RestartAgentResult {
final String? error;
final bool resumed;
const RestartAgentResult({this.error, this.resumed = true});
}
/// What became of a Change agent ([AppNotifier.changeAgent]).
///
/// [error] is a sentence to show as it is; with it the old agent is either still running or saved
/// and stopped, and choosing the same agent again carries the same switch on (it never starts a
/// second harness). Without it [agentId] is the harness to open now, and [notice], when set, is the
/// desktop's line for a switch that carried no history.
class AgentChangeResult {
final String? error;
final String? agentId;
final String? notice;
const AgentChangeResult({this.error, this.agentId, this.notice});
}
/// What became of a Fork ([AppNotifier.forkAgent]) — the desktop's `ForkAgentResult`.
///
/// [error] is a sentence to show as it is. Without it [agentId] is the fork to open now, and
/// [level] says what it got: `native` (the engine's own fork, the whole context) or `handoff` (a
/// first message composed from what the machine remembers of the source, for an engine that cannot
/// fork). [notice], when set, is a line to say once it is open.
class ForkAgentResult {
final String? error;
final String level;
final String? agentId;
final String? notice;
const ForkAgentResult({
this.error,
this.level = 'native',
this.agentId,
this.notice,
});
}
/// The Fork form's draft and its one deliberate fork — the desktop's `AgentForkAttempt`.
///
/// ⚠️ **Kept while the form is closed, receipt and all.** A fork starts a process, and its reply can
/// be lost: then the attempt is locked on its choices until Check status asks `agent_create_status`
/// about the SAME `creationId`, or the person explicitly starts another
/// ([AppNotifier.discardForkAttempt]). Reopening the form while it is on its way joins it.
class AgentForkAttempt {
AgentForkAttempt._(
this._machine,
this.source,
this._authRevision, {
this.name = '',
this.prompt = '',
});
/// The machine as it was when the form opened: a fork belongs to that connection.
final MachineState? _machine;
/// The agent as it was when the form opened. A fork is sent only while the machine still lists
/// this one — same id, same conversation.
final Agent? source;
final int _authRevision;
/// What the form holds: the fork's name and its first task.
String name, prompt;
String? _id;
bool _awaitingConfirmation = false;
Future<ForkAgentResult>? _inFlight;
/// The last answer, so the form opened again says what the last one ended on.
ForkAgentResult? result;
/// The fork was sent and its outcome is not known: Check status, not Fork.
bool get awaitingConfirmation => _awaitingConfirmation;
bool get busy => _inFlight != null;
/// The form's choices are held — while it is on its way, and while its outcome is unknown.
bool get locked => busy || awaitingConfirmation;
Future<ForkAgentResult>? get pending => _inFlight;
}
/// One deliberate creation, retained by the form if its reply is lost. Reusing
/// it checks the original request; opening New agent starts a fresh intent.
/// The id a lifecycle request is checked by when its reply is lost — see `agent_create_status`.
String _newReceiptId() {
final random = Random.secure();
return List.generate(
16,
(_) => random.nextInt(256),
).map((byte) => byte.toRadixString(16).padLeft(2, '0')).join();
}
class AgentCreationAttempt {
AgentCreationAttempt() : _id = _newReceiptId();
final String _id;
String? _machineId, _targetId;
/// The desk tab the agent joins once started, picked before it was asked for — see
/// [PhoneDesk.adopt]. Null joins the tab the phone is in.
String? _deskTabId;
/// The agent opens a desk tab of its own once started — the `+` at the end of Find's tab chips.
/// See [PhoneDesk.adopt].
bool _newDeskTab = false;
Map<String, dynamic>? _choices;
Future<String?>? _inFlight;
bool _awaitingConfirmation = false, _finished = false;
/// The Codex profile came off an agent the machine already runs on it (Clone), so the machine
/// is known to take one — the desktop's `_codexHomeTrusted`. The New form, which offers profiles
/// only from the machine's own engine list, leaves it false.
bool _codexHomeTrusted = false;
/// What the machine holds the request on — "Installing Kilo. The harness starts once it is
/// installed." — from a `pending` answer that names one. Null when it holds nothing: then it is
/// already starting the harness, and there is nothing left to cancel.
String? _holdReason;
bool _cancelling = false;
String? _outcome;
String? _agentId;
/// The machine's code for the refusal this attempt ended on, if it did.
String? _refusal;
/// The launch model the machine refused, so the agent runs its engine's
/// own (Desktop's `launchModelRefused`); null when it took it or none was
/// asked for.
({String model, String? effort})? get launchModelRefused => _launchRefused;
({String model, String? effort})? _launchRefused;
/// After the machine refused a launch model before launching anything: the
/// request may be sent again without it.
void _retryWithoutLaunchModel(({String model, String? effort}) refused) {
_launchRefused = refused;
_finished = false;
_outcome = null;
_refusal = null;
}
bool get awaitingConfirmation => _awaitingConfirmation;
/// The machine holds this request before starting anything (an engine it is installing), so it
/// can still be called off — the desktop's `canCancelPending`, behind the form's Cancel request.
bool get canCancelPending => _awaitingConfirmation && _holdReason != null;
/// A cancel is on its way to the machine.
bool get cancelling => _cancelling;
/// The agent this attempt started, once the machine has confirmed it.
///
/// The form that asked for an agent is the one screen that knows it was just
/// asked for, so it is the one that can open it. Without this the id is known
/// only inside the notifier, and the new agent has to be found again in the
/// list — a step nobody wants after naming a folder and an engine.
String? get agentId => _agentId;
String? _complete(String? error) {
_finished = true;
_awaitingConfirmation = false;
_holdReason = null;
return _outcome = error;
}
}
/// One Change agent: the harness it moves off, the engine it moves to, and what it has done so far
/// — the desktop's `_AgentChange`.
///
/// ⚠️ **Kept across a retry, receipt and all.** The switch is several round trips (write the record,
/// save and stop the old agent, start the new one), and any of them can lose its reply. Choosing
/// the same agent again carries THIS switch on: the same [creation] asks `agent_create_status`
/// about the harness it may already have started instead of starting a second, and the same
/// [creation] id names the same handoff file. See [AppNotifier.changeAgent] for when it is let go.
class _AgentChange {
_AgentChange(this.source, this.engine, this.revision);
/// The harness as it was when the switch was chosen. Every step checks the machine still lists
/// this one — same registration, same conversation — before acting on it.
final Agent source;
final String engine;
/// The account session the switch belongs to; signing out ends it.
final int revision;
/// The new harness's creation receipt. Its id is also the handoff's `changeId`.
final AgentCreationAttempt creation = AgentCreationAttempt();
Future<AgentChangeResult>? pending;
/// The new agent's first message: the machine's record of the conversation, or, from an older
/// machine, the last requests and answer. Null when there was nothing to hand off.
String? handoff;
/// The handoff was settled (the record written, or confirmed empty), so a retry reads nothing.
bool contextLoaded = false;
/// The machine prepared the handoff under this switch's id (`agent_handoff_prepare`), so its
/// close names the switch — a Swarm Product Manager's machine stops it only for that switch
/// (cli superTabs/leadSwitch.ts). Never set by the older machines' `agent_recent` road.
bool handoffPrepared = false;
/// The machine recorded which harness took over (`agent_handoff_complete`), so a retry of this
/// switch reports nothing again.
bool replacementReported = false;
/// The switch is held on the handoff, with the old agent still running: only the same engine
/// carries it on.
bool handoffHeld = false;
/// Settled with nothing to hand off, and whether that is because the reads failed rather than
/// because there was no conversation — which notice the switch ends on.
bool handoffEmpty = false, handoffFailed = false;
/// The old agent is being, or has been, saved and stopped: the switch must be finished, never
/// dropped, or the person is left with neither agent.
bool preservingViews = false;
/// The machine said the old agent is saved and stopped. A retry starts the new one without
/// closing again: this phone's list can still show the old one running until the machine's
/// update arrives, and a second Stop of it is not this switch's to send.
bool closed = false;
/// The new agent's launch failed: another engine may be chosen.
bool launchFailed = false;
}
class MachineState {
Machine machine;
ConnectionStatus connectionStatus = ConnectionStatus.disconnected;
// Set when the local CLI's relay reports NO_PEER_LINK for this (non-local) machine — it needs
// `harness link connect <machineId>` (the other machine's remote password) before it can
// connect. The CLI owns E2EE entirely now; this is just "is trust established yet", not a
// crypto/pairing state the app has any data for.
bool needsLink = false;
/// When this machine was first refused while the account's device key log named no key for it:
/// a computer that signed in a moment ago and has not put its key in yet, not one to pair by
/// hand. Null otherwise ([AppNotifier] `_awaitMachineKey`).
DateTime? keyAwaitedSince;
/// How long a machine with no key in the log is shown as connecting before its password form.
static const keyAwaitLimit = Duration(minutes: 3);
/// Refused only because its key is not in the log yet, and not for long: the screen says it is
/// connecting, never "locked" (owner, 2026-11-03: Intern 3, set up from this very phone, sat on
/// Unlock with a QR and a password it never needed, while its slow Wi-Fi kept its key out).
bool get awaitingKey =>
needsLink &&
keyAwaitedSince != null &&
DateTime.now().difference(keyAwaitedSince!) < keyAwaitLimit;
List<Agent> agents = [];
/// True while [agents] came from the last run's cache rather than from this
/// machine ([MachineCache], `_warmStartMachines`).
///
/// ⚠️ **What it marks is a list that may name an agent that no longer
/// exists** — one deleted from another device since this phone last looked.
/// The names are good enough to draw a terminal around immediately, which is
/// the whole point; what they cannot do is be trusted as the final word, so
/// the terminal an agent from here opens says so if the machine disowns it.
///
/// Cleared by `_replaceAgents`, i.e. by the first real `agents_list` — from
/// that moment the list is the machine's own and nothing is provisional.
bool agentsFromCache = false;
/// When this machine last answered `agents_list` over the socket it is on now — null before the
/// first answer, and again once that socket drops, since the pushes that keep a list current
/// went nowhere while it was down. What Find asks before asking again (`_listStillCurrent`).
DateTime? agentsListedAt;
AgentLoadStatus agentLoadStatus = AgentLoadStatus.idle;
bool agentsRefreshing = false;
String? agentsLoadError;
Future<void>? agentsLoadInFlight;
Future<void>? terminalCapabilityLoadInFlight;
String? activeAgentId;
bool terminalCapabilityLoaded = false;
bool terminalCapabilityAvailable = false;
String? terminalCapabilityError;
/// The negotiation got no answer — a timeout, a dropped socket — rather than the machine saying
/// no. That is not a fact about the machine, so the next sync that does get an answer asks again
/// (see `_syncAgentsIfChanged`); a refusal or `available: false` is an answer, and stands.
bool terminalCapabilityUnanswered = false;
// Whether this machine's CLI daemon understands `terminal_paste` (a clipboard paste delivered as
// one atomic tmux paste-buffer, not chunked like ordinary keystrokes — see TerminalSession.pasteText).
// False for any CLI published before this existed; the panel falls back to the old chunked path.
bool terminalPasteRawAvailable = false;
// Whether this machine's CLI daemon understands TerminalBinaryKind.imagePaste (a native clipboard
// IMAGE paste — see TerminalSession.pasteImage). False for any CLI published before this existed;
// the phone then says the machine is too old to receive images (phone/terminal_paste.dart) and
// never forwards a bare Ctrl+V, which would paste the far machine's clipboard, not the phone's.
bool terminalImagePasteAvailable = false;
// Whether this machine's CLI daemon understands TerminalBinaryKind.pasteFile (a dropped non-image
// file, written to disk on that machine and pasted as a path — see TerminalSession.pasteFile).
// Only consulted for a REMOTE pane; a local one pastes its own path directly and never needs this.
bool terminalPasteFileAvailable = false;
bool mediaPreviewAvailable = false;
// Whether this machine's CLI understands `projectSource` on agent_create — a folder it makes or
// clones for itself, rather than one the client names with `cwd`.
//
// ⚠️ False is not "the feature is off", it is "this machine would MISREPORT the failure". An
// older CLI ignores the keys, finds no `cwd`, and refuses with INVALID_CWD — which reaches the
// person as "the project folder is unavailable, choose another folder", advice about a folder
// they never chose and that has nothing to do with what went wrong.
bool projectFolderAvailable = false;
// Whether this machine's CLI honours `takeover: false` on `terminal_open` — open only a terminal
// no other app is driving, refused with CONTROL_LEASE_HELD otherwise. See
// [TerminalSession.takeover].
//
// ⚠️ False is not "opens are polite anyway", it is the opposite: an older CLI ignores the key and
// takes the terminal over like any other open. So nothing may be opened AHEAD of a person on a
// machine that does not say this — see [AppNotifier.warmAgentPane].
bool terminalNoTakeoverAvailable = false;
// Which engines this machine actually has, as this machine answered it. Kept
// on MachineState rather than globally because that is the whole point: two
// machines on one account hold different engines, and the Docker rig holds
// exactly one. See `engines_probe` in the CLI's backendSocket.
final MachineEngines engines = MachineEngines();
// Adapter/manager presence for this machine, from `node_status` pushes —
// distinct from `connectionStatus`, which only reflects OUR websocket to
// the backend. null = not seen yet (initial connect).
bool? nodeOnline;
// The agent the user selected while the Harness adapter was offline. Keep
// this separate from activeAgentId so the UI can show a join guide without
// opening a terminal stream against an unavailable node.
String? pendingOfflineAgentId;
final Set<String> processingAgentIds = {};
/// When this app last SAW each agent's conversation move — a turn starting,
/// beating or ending on this socket — by agentId.
///
/// Newer than [Agent.updatedAt] whenever the machine has not re-sent that
/// agent since, which is the normal case: the daemon pushes an agent when the
/// agent changes, not on every turn. Without this, an agent somebody had just
/// talked to kept the age of its last list fetch and sank below idle ones the
/// moment its turn ended.
final Map<String, DateTime> agentActivityAt = {};
/// Agents on this machine that have stopped to ask something, by agentId.
/// At most one per agent: a pane shows one dialog at a time, and the daemon
/// re-announces the same open question rather than queueing a second.
final Map<String, PendingQuestion> blockedAgents = {};
final Map<String, String> sessionAgentIds = {};
// Turn events can arrive while the initial agents_list RPC is still in
// flight. Retain session correlation until that snapshot binds the row.
final Set<String> pendingProcessingSessions = {};
MachineState(this.machine);
bool get isRemote => machine.authMode == MachineAuthMode.remote;
Agent? get activeAgent {
for (final agent in agents) {
if (agent.id == activeAgentId) return agent;
}
return null;
}
}
/// What every `agents_list` asks for.
///
/// ⚠️ **`includeStopped` is not optional polish — without it the fleet is
/// silently incomplete.** The daemon answers a plain `agents_list` with
/// `registry.advertised()`, which is live agents only, and adds saved-but-
/// stopped work only when asked (`cli/src/backendSocket.ts`, `agents_list`).
/// This app did not ask, so a machine with nine stopped harnesses reported
/// none of them and the phone showed a different fleet than the desktop on the
/// same account — for the search, the Agents tab and every count drawn off them.
///
/// The daemon ignores the flag for the hardware dial (`sessionRole == 'device'`);
/// this app pairs as `'web'`, so it is honoured here.
const kAgentsListPayload = {'includeStopped': true};
/// Who asked for a terminal to be opened.
///
/// A terminal has ONE controller and an ordinary `terminal_open` wins it, so
/// every attach has to say whether a person on THIS phone asked for it.
/// [person] may take the terminal from whoever holds it; [automatic] never may
/// — it opens as a watcher where the daemon supports that (`noTakeover`), and
/// does not open at all where it does not. The dial turning, a reconnect, a
/// desk another screen wrote, a push: all automatic.
enum AttachIntent { person, automatic }
class AppNotifier extends ChangeNotifier {
final AuthSession session;
AppConfig config;
late ApiClient api;
late final ProductMeasurement productMeasurement;
/// The phone's onboarding steps after sign-in, counted through [productMeasurement]. A wait for a
/// computer is remembered in the app's own store, for the launch that finds the computer.
late final onboardingMeasurement = OnboardingMeasurement(
productMeasurement,
storage: _paneLayout?.storage,
);
final _measurementConnections = <String, void Function(ProductOutcome)>{};
/// Each machine's dials, the person's (`connect_user`) apart from the app's own (`connect_auto`).
late final productConnections = ProductConnections(productMeasurement);
/// A stopped harness resumed from here, until it works again (`resume_recovery`).
late final productResumes = ProductResumes(productMeasurement);
/// This launch, to its first computer (`app_start`). The app's alone: none in a test or the sample.
LaunchMeasurement? launchMeasurement;
/// Says whether this device is signed in, and signs it out: [ViewerServices.login], the app's own
/// session. The name is the desktop's, where the harness CLI holds the session instead.
late final SignInClient cliLogin;
/// Links to other machines by remote password — the app itself, through [ViewerServices.links].
/// A viewer is not a machine, so it has no password of its own for anyone to link to.
late final PeerLinkClient peerLinks;
/// This app's stand-ins for the harness CLI (`lib/viewer/`). It is always a viewer: no CLI runs
/// beside it, on a phone or anywhere else this package is built.
final ViewerServices viewer;
final ConfigStore? _store;
final Duration turnActivityTimeout;
@visibleForTesting
final WsConn Function(String machineId)? connectionForTest;
final Map<String, Timer> _turnActivityWatchdogs = {};
/// What each agent was last asked and answered, as search matches it — the
/// desktop's own store (see `session_preview.dart`), fed by every turn event
/// this socket carries, so a reply is findable the moment it lands, and by an
/// `agent_recent` read ONLY where a screen asks for one (`agents_list_page.dart`).
///
/// ⚠️ **No reads in the background, on purpose (owner, 2026-10-01).** It used
/// to be read for every agent whenever an agent list arrived (32 a machine, again
/// after every reconnect), for every agent a push updated, and for every row
/// Find drew — a hundred-odd reads at launch on one machine, and several hundred
/// on eight, all on the same relay socket as the terminal somebody was waiting
/// for. A launch measured with them showed that socket going silent for 4–7s
/// with the terminal's open queued behind them. What they fed is gone (the recap
/// under Find's rows) or answered by the machines themselves (`session_search`
/// finds what a session said), so the reads went and the store stayed.
///
/// Read again after [freshFor] at the soonest, not the desktop's minute: a
/// phone pays for the bytes, and the live events already keep a connected
/// machine's agents current.
late final sessionPreviews = SessionPreviewStore(
canFetch: _canFetchPreview,
freshFor: const Duration(minutes: 5),
maxInFlight: 4,
fetchRecent: (key) => _conn(key.machineId).request(
'agent_recent',
payload: {'agentId': key.agentId, 'n': 3},
timeout: const Duration(seconds: 6),
),
);
/// What a finished turn or a question is worth — a tap, an unread mark, a
/// system notice — decided by the dial's rules (`notify/`).
final AgentAnnouncer agentNotices;
SessionPreviewKey previewKey(String machineId, Agent agent) =>
(machineId: machineId, agentId: agent.id, sessionId: agent.sessionId);
/// Asks only a machine this app is already connected to, and never dials one:
/// warming search must not be what wakes a relay socket.
bool _canFetchPreview(SessionPreviewKey key) {
if (_disposed || (_pool == null && connectionForTest == null)) return false;
final machine = machineStates[key.machineId];
return machine != null &&
machine.nodeOnline != false &&
!machine.needsLink &&
machine.connectionStatus == ConnectionStatus.connected &&
machine.agents.any(
(agent) =>
agent.id == key.agentId && agent.sessionId == key.sessionId,
);
}
/// Has the next warm re-read [agent]'s content when its machine says the
/// conversation moved since [before] — a turn this phone may have slept
/// through. Compared on the machine's own clock, so a phone whose clock
/// disagrees cannot make every refresh look like news.
void _staleIfMoved(MachineState machine, Agent? before, Agent agent) {
final moved = agent.updatedAt;
if (before == null || moved == null) return;
final was = before.updatedAt;
if (was != null && !moved.isAfter(was)) return;
sessionPreviews.markStale(previewKey(machine.machine.machineId, agent));
}
final Map<String, Timer> _offlineRetryTimers = {};
// Safety-net reconciliation for a connected machine's agent list, on top of the push events
// (agent_synced/agent_created/agent_renamed/agent_deleted) that normally keep it live — catches the
// rare case a push event was dropped. Runs silently: see _syncAgentsIfChanged.
final Map<String, Timer> _agentSyncTimers = {};
final Set<String> _offlinePollsInFlight = {};
final Set<String> _offlineRecoveryInFlight = {};
bool _disposed = false;
// Account and inventory replies belong to the session that requested them.
// Signing out invalidates them before asynchronous connection cleanup.
int _authRevision = 0;
Future<void>? _profileInFlight;
bool _authWorkCurrent(int revision) =>
!_disposed && revision == _authRevision;
int _invalidateAuthWork() {
// A chat file on its way stops: the next account takes no step of it, and its bytes stop
// going to the link the last one was given.
for (final upload in _swarmUploadsGoing) {
upload.cancel('account changed');
}
_swarmUploadsGoing.clear();
for (final write in _swarmWritesGoing) {
write.cancel('account changed');
}
_swarmWritesGoing.clear();
// The copies large chat files were kept in went with the chats that held them.
unawaited(clearSwarmPickerCopies());
_profileInFlight = null;
_profileAgain?.cancel();
_profileFailures = 0;
_keptAccountId = null;
_retryInFlight = null;
machinesLoading = false;
_registeringDevice = false;
_deviceRegisteredAt = null;
_awaitingVouched.clear();
_vouchedRedials.clear();
return ++_authRevision;
}
WsPool? _pool;
late String _autonomousEnv;
String? _lastError;
// Retrying re-runs `refreshMachines()` — a real fix for "could not load
// machines" or a daemon hiccup, but a no-op for a failure that already
// finished (an agent's launch), where the only honest control is to
// dismiss it.
bool _lastErrorRetryable = true;
// Shown on the pre-navigation `bootstrapping` screen while [_finishBootstrapSignedIn] restores the
// local state — null the rest of the time, including once [status] flips to `authenticated`.
String? _bootStatusMessage;
AppStatus status = AppStatus.bootstrapping;
CurrentUserProfile? currentUser;
List<Machine> machines = [];
final Map<String, MachineState> machineStates = {};
final Set<String> expandedMachines = {};
String? selectedMachineId;
// ── the desk: the account's tabs, the same on every computer ─────────────
//
// `phone_desk.dart` holds the whole of it, including why a phone follows the
// desk instead of projecting itself onto it the way a window does. Everything
// here is a hand-off: the closures read `api` LAZILY, because signing in
// replaces that client and a tear-off taken now would go on talking to the
// old one.
late final PhoneDesk _desk = PhoneDesk(
read: () => api.desk(),
write: (ops) => api.deskOps(ops),
onChanged: notifyListeners,
);
// ── the zoo: the account's daemons and eggs ──────────────────────────────
//
// `daemons/zoo_client.dart` holds it. Its own document, like the desk and
// separate from it: read on sign-in, on `zoo_changed`, and when the app comes
// back to the front. The closures read `api` lazily for the desk's reason.
late final ZooClient zoo = ZooClient(
read: () => api.zoo(),
write: (ops) => api.zooOps(ops),
);
/// Individuals' own plates, drawn by harnessd on one of the account's
/// computers and asked for over the sealed `pair_plate_get` frame
/// (`daemons/individual_art.dart`). Until one arrives, and where none can
/// be asked, the species plate is shown in the individual's colours.
late final IndividualArt individualArt = IndividualArt(
request: requestIndividualPlate,
);
/// Ask the account's connected computers for an
/// individual's plates (`pair_plate_get { uid, id, seed, size, version,
/// mood }` → `pair_plate { ..., frames, frameMs }`). The first that answers
/// wins; a computer whose harnessd predates individual art says
/// `UNSUPPORTED` or stays silent (a sealed frame it cannot open), which is a
/// timeout and the next one. A first render can take tens of seconds;
/// the recoloured species plate remains visible while it draws.
Future<Map<String, dynamic>?> requestIndividualPlate(
Map<String, dynamic> payload,
) async {
if (_disposed || (_pool == null && connectionForTest == null)) return null;
final machines = [
for (final machine in machineStates.values)
if (machine.connectionStatus == ConnectionStatus.connected &&
!machine.needsLink &&
machine.nodeOnline != false)
machine,
];
for (final machine in machines) {
try {
final answer = await _conn(machine.machine.machineId).request(
'pair_plate_get',
payload: payload,
timeout: const Duration(minutes: 2),
);
if (answer['error'] == null && answer['frames'] is List) return answer;
} catch (_) {
// Too old, asleep, or not there: the next one.
}
}
return null;
}
/// The first egg's habits this phone can see for itself — see
/// `daemons/daemon_habits.dart` for which, and why the rest are left to the
/// computers. The days it was used are kept where the layout is: nowhere in
/// a test.
late final PhoneHabits daemonHabits = PhoneHabits(
zoo,
storage: _paneLayout?.storage,
);
/// The account's tabs, in the desk's order. Empty where the desk has nothing
/// or has not answered — the phone then swipes the whole account, as it did
/// before the desk existed.
List<DeskTab> get deskTabs => _desk.tabs;
/// The tabs this phone SHOWS: [deskTabs] narrowed to the computer chosen under Settings ▸ Profile
/// ([machineProfileId]). What the swipe's groups, Find's tab chips and the launch's choice of tab
/// read (`phone/desk_groups.dart`). [deskTabs] stays the whole desk for what has to agree with
/// every other computer — what each tab is called, above all.
List<DeskTab> get profileDeskTabs =>
deskTabsForMachineProfile(_desk.tabs, machineProfileId);
/// The computer whose tabs this phone shows, or null for every computer.
///
/// A choice naming a computer the account no longer has — removed here or elsewhere — reads as
/// every computer, rather than hiding tabs behind a machine that is not coming back. Before the
/// list has arrived nothing is known either way, so the choice stands.
String? get machineProfileId {
final chosen = machineProfile.value;
if (chosen == null) return null;
if (machines.isEmpty || machines.any((m) => m.machineId == chosen)) {
return chosen;
}
return null;
}
/// Show every computer's tabs ([machineId] null), or only [machineId]'s. Only this phone changes:
/// the desk keeps every tab, and no other computer's view moves — the desktop's
/// `setMachineProfile`.
void setMachineProfile(String? machineId) {
if (!machineProfile.select(machineId)) return;
_keepActiveDeskTabShown();
notifyListeners();
}
/// The tab this phone counts itself in, moved to the first one still shown when a profile hides it
/// — the desktop's `_ensureProfileFocus`, for the reason that matters most on a phone: a harness
/// made here joins that tab ([PhoneDesk.adopt]), and must not land in one the phone no longer
/// shows. Silent ([PhoneDesk.note]): the caller notifies.
void _keepActiveDeskTabShown() {
final active = _desk.activeTabId;
if (active == null) return;
// ⚠️ Nothing to judge before the desk has answered: the profile lands from disk long before the
// tabs do from the network, and an empty list would read as "the tab is hidden" and lose the
// tab the last run was in.
if (_desk.tabs.isEmpty) return;
final shown = profileDeskTabs;
if (shown.any((tab) => tab.id == active)) return;
final first = shown.firstOrNull?.id;
_desk.note(first);
_rememberDeskTab(first);
}
/// The profile kept from the last run. Disk only, and off the launch's critical path: the screen
/// waits for the desk's network read before it picks a tab (`AgentHome._target`), and this lands
/// long before that.
Future<void> _loadMachineProfile() async {
final before = machineProfile.value;
await machineProfile.load();
if (_disposed || machineProfile.value == before) return;
_keepActiveDeskTabShown();
notifyListeners();
}
/// The tab the phone is in, or null for an agent no tab holds.
String? get activeDeskTabId => _desk.activeTabId;
/// Whether the desk's first read has come back — see [PhoneDesk.settled].
bool get deskSettled => _desk.settled;
/// A tab picked by hand, in the tabs panel — set as the agent chosen there
/// is opened, so the swipe walks that tab from then on.
void selectDeskTab(String? tabId) {
_desk.select(tabId);
_rememberDeskTab(tabId);
}
/// The tab the screen has worked out it is showing — see [PhoneDesk.note].
void noteDeskTab(String? tabId) {
_desk.note(tabId);
_rememberDeskTab(tabId);
}
/// Kept for the next launch to fall back on — see [LastOpenedAgent.rememberTab]. Only a real
/// tab: an agent opened from search, in none, leaves the last tab standing.
void _rememberDeskTab(String? tabId) {
if (tabId != null) lastOpenedAgent.rememberTab(tabId);
}
/// Whether the desk can be WRITTEN to — what the two `+`s on the tabs panel
/// are drawn on. False before the first read answers, and on a backend with
/// no desk at all: a `+` there would queue ops nothing will ever take.
bool get deskWritable => _desk.enabled;
/// An agent that already exists joins the tab the person picked — the `+` at
/// the foot of a tab's list. See [PhoneDesk.addToTab].
void addAgentToDeskTab(String tabId, AgentRef agent) =>
_desk.addToTab(tabId, agent);
/// A tab renamed by hand, from holding its chip in Find.
/// See [PhoneDesk.renameTab].
void renameDeskTab(String tabId, String name) => _desk.renameTab(tabId, name);
/// A tab closed by hand, from holding its chip in Find. Its harnesses keep
/// running. See [PhoneDesk.closeTab].
void closeDeskTab(String tabId) => _desk.closeTab(tabId);
/// An agent that already exists opens a tab of its own — the `+` on the tab
/// row. See [PhoneDesk.createTabFor].
String? createDeskTabFor(AgentRef agent, {String? name}) =>
_desk.createTabFor(agent, name: name);
/// The next agent made on this phone gets a tab of its own — armed by the `+`
/// on the tab row before the new-agent form opens, and spent (or forgotten)
/// by the time that form closes. See [PhoneDesk.openNextAgentInNewTab].
void openNextAgentInNewDeskTab({String? name}) =>
_desk.openNextAgentInNewTab(name: name);
/// Read the desk now and wait for it, so a write that follows has a desk to go to.
Future<void> readDesk() => _desk.refresh();
/// That form closed without making anything.
void forgetNewDeskTabIntent() => _desk.forgetNewTabIntent();
/// Read the desk now, and wait for it — what a sign-in and the app coming
/// back to the foreground both start without waiting.
@visibleForTesting
Future<void> deskSyncForTest() => _desk.refresh();
/// Swarms own arrangements; a shared pane owns one live terminal controller.
final List<Swarm> swarms = [Swarm(id: 'swarm-1')];
String _activeSwarmId = 'swarm-1';
int _nextSwarmId = 2;
static const maxSwarms = 24;
static const maxClosedSwarms = 24;
final List<ClosedWork> _closedHistory = [];
int _nextClosedHistoryId = 1;
List<ClosedWork> get closedHistory =>
List.unmodifiable(_closedHistory.reversed);
List<ClosedSwarm> get closedSwarms =>
List.unmodifiable(_closedHistory.reversed.whereType<ClosedSwarm>());
bool get canReopenClosedSwarm {
final saved = _closedHistory.whereType<ClosedSwarm>().lastOrNull;
return saved != null && _canReopenSwarm(saved);
}
bool get canReopenLastClosed =>
_closedHistory.isNotEmpty &&
canReopenClosed(_closedHistory.last.historyId);
bool canReopenClosed(String historyId) {
if (_disposed) return false;
final entry = _closedHistory
.where((entry) => entry.historyId == historyId)
.firstOrNull;
if (entry is ClosedSwarm) return _canReopenSwarm(entry);
if (entry is! ClosedAgent) return false;
final target = swarms.where((s) => s.id == entry.swarmId).firstOrNull;
return target == null
? swarms.length < maxSwarms
: target.panes.length < maxPanes ||
target.panes.any(
(p) =>
p.machineId == entry.machineId &&
p.agentId == entry.agentId,
);
}
bool _canReopenSwarm(ClosedSwarm saved) {
if (_disposed) return false;
final target = swarms.where((swarm) => swarm.id == saved.id).firstOrNull;
if (target == null) return swarms.length < maxSwarms;
final present = {
for (final pane in target.panes) (pane.machineId, pane.agentId),
};
final missing = {
for (final pane in saved.panes)
if (!present.contains((pane.machineId, pane.agentId)))
(pane.machineId, pane.agentId),
};
return target.panes.length + missing.length <= maxPanes;
}
void _rememberClosed(ClosedWork entry) {
// An unused starter has no work to recover. This also covers empty pages
// restored from builds that did not mark them as drafts.
if (entry is ClosedSwarm &&
entry.name == Swarm.defaultName &&
entry.panes.isEmpty) {
return;
}
_closedHistory.add(entry);
if (_closedHistory.length > maxClosedSwarms) _closedHistory.removeAt(0);
}
Swarm get activeSwarm => swarms.firstWhere(
(s) => s.id == _activeSwarmId,
orElse: () => swarms.first,
);
List<TerminalPane> get panes => activeSwarm.panes;
Iterable<TerminalPane> get allPanes => swarms.expand((s) => s.panes).toSet();
String get activeSwarmId => activeSwarm.id;
bool get canOpenNewTab =>
swarms.length < maxSwarms || swarms.any((swarm) => swarm.isEmptyStarter);
// An untitled tab remains temporary until it has content or a custom name.
// The return destination is session-local; abandoned drafts are never saved.
final _draftSwarmReturns = <String, String>{};
bool isDraftSwarm(String id) {
if (!_draftSwarmReturns.containsKey(id)) return false;
final swarm = swarms.where((swarm) => swarm.id == id).firstOrNull;
return swarm != null &&
swarm.panes.isEmpty &&
swarm.name == Swarm.defaultName;
}
void newSwarm({String name = Swarm.defaultName, bool draft = false}) {
// Every New Tab entry point reuses the existing start page, including
// when another tab is selected or the tab limit has been reached.
if (name == Swarm.defaultName) {
final starter = activeSwarm.isEmptyStarter
? activeSwarm
: swarms.where((swarm) => swarm.isEmptyStarter).firstOrNull;
if (starter != null) {
if (starter.id != activeSwarmId) selectSwarm(starter.id);
return;
}
}
if (swarms.length >= maxSwarms) return;
while (swarms.any((s) => s.id == 'swarm-$_nextSwarmId')) {
_nextSwarmId++;
}
final swarm = Swarm(id: 'swarm-${_nextSwarmId++}', name: name);
if (draft) {
_draftSwarmReturns[swarm.id] =
_draftSwarmReturns[activeSwarmId] ?? activeSwarmId;
}
swarms.add(swarm);
selectSwarm(swarm.id);
}
void selectSwarm(String id, {bool attachPending = true}) {
if (!swarms.any((s) => s.id == id)) return;
if (id != activeSwarmId && isDraftSwarm(activeSwarmId)) {
final abandoned = activeSwarmId;
swarms.removeWhere((swarm) => swarm.id == abandoned);
_draftSwarmReturns.remove(abandoned);
}
_activeSwarmId = id;
final pane = focusedPane;
selectedMachineId = pane?.machineId;
_persistLayout();
if (attachPending) {
for (final machine in machineStates.values) {
// A tab the person switched to.
_attachPendingPanes(
machine,
retryExisting: false,
intent: AttachIntent.person,
);
}
}
notifyListeners();
}
/// Cancel an untouched new tab without closing a session or recording
/// Recently Closed. A sole workspace remains the app's starting screen.
bool cancelSwarmDraft(String id) {
final returnId = _draftSwarmReturns[id];
final target = swarms.where((swarm) => swarm.id == id).firstOrNull;
if (returnId == null ||
target == null ||
target.panes.isNotEmpty ||
target.name != Swarm.defaultName ||
swarms.length == 1) {
return false;
}
final wasActive = activeSwarmId == id;
swarms.remove(target);
_draftSwarmReturns.remove(id);
if (wasActive) {
selectSwarm(
swarms.any((swarm) => swarm.id == returnId) ? returnId : swarms.last.id,
);
} else {
_persistLayout();
notifyListeners();
}
return true;
}
/// Navigate to an existing view without opening, retrying or taking control
/// of a terminal. A shared view prefers the current Swarm, then the requested
/// owner. Publish the destination and its focus together, preserving layout.
bool revealAgentView(
String machineId,
String agentId, {
String? preferredSwarmId,
}) {
if (_disposed) return false;
bool contains(Swarm swarm) => swarm.panes.any(
(p) => p.machineId == machineId && p.agentId == agentId,
);
final owner = contains(activeSwarm)
? activeSwarm
: swarms
.where((s) => s.id == preferredSwarmId && contains(s))
.firstOrNull ??
swarms.where(contains).firstOrNull;
if (owner == null) return false;
final pane = owner.panes.firstWhere(
(p) => p.machineId == machineId && p.agentId == agentId,
);
if (owner == activeSwarm) {
focusPane(pane.id, reveal: true);
return true;
}
if (owner.focusedPaneId != pane.id) {
owner.previousPaneId = owner.focusedPaneId;
owner.focusedPaneId = pane.id;
}
if (owner.zoomedPaneId != null) owner.zoomedPaneId = pane.id;
_activeSwarmId = owner.id;
selectedMachineId = machineId;
_persistLayout();
notifyListeners();
return true;
}
/// Command-number follows the current visual tab order, retaining each tab's
/// focused pane. A missing position is a no-op, never a pane selection.
void selectSwarmByIndex(int index) {
if (index < 0 || index >= swarms.length) return;
selectSwarm(swarms[index].id);
}
void stepSwarm(int delta) {
final index = swarms.indexOf(activeSwarm);
selectSwarm(swarms[(index + delta) % swarms.length].id);
}
void renameSwarm(String id, String name) {
final clean = name.trim();
if (clean.isEmpty) return;
final swarm = swarms.where((s) => s.id == id).firstOrNull;
if (swarm == null) return;
swarm.name = clean.length > 80 ? clean.substring(0, 80) : clean;
_persistLayout();
notifyListeners();
}
void reorderSwarm(String id, int destination) {
final index = swarms.indexWhere((s) => s.id == id);
if (index < 0) return;
final swarm = swarms.removeAt(index);
swarms.insert(destination.clamp(0, swarms.length), swarm);
_persistLayout();
notifyListeners();
}
Future<void> closeSwarm(String id) async {
if (cancelSwarmDraft(id)) return;
final index = swarms.indexWhere((s) => s.id == id);
if (index < 0) return;
// Held ⌘W must not manufacture and close an endless sequence of blank
// welcome tabs, evicting the real work from recently closed history.
if (swarms.length == 1 &&
swarms.single.panes.isEmpty &&
swarms.single.name == Swarm.defaultName) {
return;
}
final removed = swarms.removeAt(index);
Swarm? replacement;
if (swarms.isEmpty) {
replacement = Swarm(id: 'swarm-${_nextSwarmId++}');
swarms.add(replacement);
}
_rememberClosed(
ClosedSwarm(
removed,
historyId: 'closed-${_nextClosedHistoryId++}',
index: index,
replacement: replacement,
engine: removed.panes.length == 1
? stateOf(removed.panes.single.machineId)?.agents
.where(
(agent) => agent.id == removed.panes.single.agentId,
)
.firstOrNull
?.engine ??
removed.panes.single.session?.engineId
: null,
),
);
if (_activeSwarmId == id) {
_activeSwarmId = swarms[index.clamp(0, swarms.length - 1)].id;
}
_persistLayout();
notifyListeners();
selectedMachineId = focusedPane?.machineId;
for (final machine in machineStates.values) {
// A tab closed here; the tiles behind it are theirs.
_attachPendingPanes(machine, intent: AttachIntent.person);
}
for (final pane in removed.panes) {
if (!allPanes.contains(pane)) await _detachSession(pane, sendClose: true);
}
}
void reopenClosedSwarm({String? historyId}) {
if (_disposed) return;
final index = _closedHistory.lastIndexWhere(
(entry) =>
entry is ClosedSwarm &&
(historyId == null || entry.historyId == historyId),
);
if (index < 0) return;
final saved = _closedHistory[index] as ClosedSwarm;
if (!_canReopenSwarm(saved)) return;
_closedHistory.removeAt(index);
if (swarms.length == 1 && saved.replacesUntouchedWelcome(swarms.single)) {
swarms.clear();
}
final pool = {
for (final pane in allPanes) (pane.machineId, pane.agentId): pane,
};
final target = swarms.where((swarm) => swarm.id == saved.id).firstOrNull;
if (target != null) {
// Reopening an individual agent may have restored this swarm already.
// Reunite its missing views without cloning the tab or overwriting edits
// made since then. Live peers keep their terminal, draft and selection.
final present = {
for (final pane in target.panes) (pane.machineId, pane.agentId),
};
for (final entry in saved.panes) {
if (!present.add((entry.machineId, entry.agentId))) continue;
target.panes.add(
pool.putIfAbsent(
(entry.machineId, entry.agentId),
() => TerminalPane(
id: _nextPaneId++,
machineId: entry.machineId,
agentId: entry.agentId,
),
),
);
}
target.focusedPaneId ??= target.panes.firstOrNull?.id;
selectSwarm(target.id);
return;
}
final restored = Swarm(id: saved.id, name: saved.name);
for (final entry in saved.panes) {
final pane = pool.putIfAbsent(
(entry.machineId, entry.agentId),
() => TerminalPane(
id: _nextPaneId++,
machineId: entry.machineId,
agentId: entry.agentId,
),
);
restored.panes.add(pane);
if (entry.pinnedSlot != null) {
restored.pinnedSlots[pane.id] = entry.pinnedSlot!;
}
}
int? paneAt(int index) => index >= 0 && index < restored.panes.length
? restored.panes[index].id
: null;
restored.focusedPaneId =
paneAt(saved.focus) ?? restored.panes.firstOrNull?.id;
restored.previousPaneId = paneAt(saved.previousFocus);
restored.zoomedPaneId = paneAt(saved.zoom);
swarms.insert(saved.index.clamp(0, swarms.length), restored);
selectSwarm(restored.id);
}
/// Reopen the chosen closure, or the newest closure for Cmd-Shift-T.
/// Membership is restored synchronously; a slow detach cannot resurrect an
/// old controller or redirect the destination after a network wait.
bool reopenClosed({String? historyId}) {
final id = historyId ?? _closedHistory.lastOrNull?.historyId;
if (id == null || !canReopenClosed(id)) return false;
final index = _closedHistory.indexWhere((entry) => entry.historyId == id);
final saved = _closedHistory[index];
if (saved is ClosedSwarm) {
reopenClosedSwarm(historyId: id);
return true;
}
final agent = saved as ClosedAgent;
_closedHistory.removeAt(index);
var target = swarms.where((s) => s.id == agent.swarmId).firstOrNull;
if (target == null) {
target = Swarm(id: agent.swarmId, name: agent.swarmName);
swarms.add(target);
}
final pane =
allPanes
.where(
(p) =>
p.machineId == agent.machineId && p.agentId == agent.agentId,
)
.firstOrNull ??
TerminalPane(
id: _nextPaneId++,
machineId: agent.machineId,
agentId: agent.agentId,
);
if (!target.panes.contains(pane)) {
target.panes.insert(agent.index.clamp(0, target.panes.length), pane);
if (agent.pinnedSlot != null &&
!target.pinnedSlots.containsValue(agent.pinnedSlot)) {
target.pinnedSlots[pane.id] = agent.pinnedSlot!;
}
}
if (target.focusedPaneId != pane.id) {
target.previousPaneId = target.focusedPaneId;
}
target.focusedPaneId = pane.id;
if (agent.zoomed || target.zoomedPaneId != null) {
target.zoomedPaneId = pane.id;
}
_activeSwarmId = target.id;
_settlePins();
selectSwarm(target.id);
return true;
}
/// Capture the destination before any network wait or tab change.
Future<void> addAgentToSwarm(
String machineId,
String agentId, {
String? swarmId,
bool takeControl = false,
}) => assignAgentToPane(
null,
machineId,
agentId,
swarmId: swarmId,
takeControl: takeControl,
);
/// Which tile the keyboard, the dial and the rail's highlight all mean.
///
/// Typing itself does NOT go through this on macOS — the renderer is a
/// WebView, so a click makes that pane's WKWebView the first responder and
/// AppKit routes keys there without asking. This is for everything that has
/// no pointer behind it: the dial's scroll and focus frames, and which agent
/// the rail draws as current.
int? get focusedPaneId => activeSwarm.focusedPaneId;
set focusedPaneId(int? value) => activeSwarm.focusedPaneId = value;
int _nextPaneId = 1;
static const maxPanes = 64;
/// True from the moment a code is handed in — emailed or scanned — until the flow settles, one
/// way or the other.
///
/// It spans the whole flow, restoring the tiles and fetching the machines included, so the
/// screen the user pressed a button on stays put: `RootShell` keeps the signed-out screen up
/// while it is set, rather than dropping them onto a bare full-screen spinner.
bool signingIn = false;
/// The account whose sign-in page is up, from the press of its button until the flow settles —
/// so the welcome screen's pressed button says what it is waiting on, and only it.
SignInProvider? signInProvider;
/// Signed in on this phone during this run — from the welcome — rather than a session the app
/// came back with. The onboarding after a sign-in reads it: home draws its waits on the
/// onboarding's picture, eased from the welcome's, and the computer joining gets its moment
/// (`phone/welcome/onboarding_frame.dart`). Cleared with the session.
bool signedInThisRun = false;
/// The one line the phone says by the mic the first time the onboarding opens a session — "Send
/// it, or say anything." — and the session it is for. Set by home as it hands over
/// (`phone/agent_home.dart`), spent by that session's page on its first send or when it goes
/// (`phone/terminal_page.dart`). Null the rest of the time; cleared with the session.
({String machineId, String agentId, String text})? firstSessionLine;
AppNotifier({
required AppConfig config,
required AuthSession authSession,
ConfigStore? configStore,
this.connectionForTest,
ProductMeasurement? productMeasurement,
SignInClient? cliLogin,
PeerLinkClient? peerLinks,
ViewerServices? viewer,
PaneLayoutStore? paneLayoutStore,
SystemNotices? systemNotices,
PushTokens? pushTokens,
MachineCache? machineCache,
KeptScreenStore? keptScreenStore,
GroupSync? groupSync,
this.turnActivityTimeout = const Duration(seconds: 12),
}) : _paneLayout = paneLayoutStore,
// On the machine cache's terms, below: a real app keeps screens (in memory), a test only
// when it hands over a store of its own.
_keptScreenStore =
keptScreenStore ??
(paneLayoutStore == null ? null : KeptScreenStore()),
// On the same terms as the stores below: no layout store means a test,
// which must never reach the OS notification centre.
agentNotices = AgentAnnouncer(
system:
systemNotices ??
(paneLayoutStore == null
? SilentSystemNotices()
: LocalSystemNotices()),
),
// Remembers "a dial has been seen here" on the same terms the pane
// layout is remembered: with a layout store there is a state file, and
// without one (the tests) nothing is written anywhere.
dial = DialState(paneLayoutStore?.storage),
agentPreference = AgentPreference(paneLayoutStore?.storage),
projectHistory = ProjectHistory(paneLayoutStore?.storage),
lastOpenedAgent = LastOpenedAgent(paneLayoutStore?.storage),
machineProfile = MachineProfileStore(paneLayoutStore?.storage),
searchHistory = PhoneSearchHistory(paneLayoutStore?.storage),
// On the same terms as the stores above: a layout store means this is a
// real app with a real Harness home to cache into, and its absence means
// a test, which must not read or write one — unless it hands over a
// cache of its own, kept in memory.
_machineCache =
machineCache ?? (paneLayoutStore == null ? null : MachineCache()),
session = authSession,
_store = configStore,
config = configStore?.config ?? config,
viewer =
viewer ??
ViewerServices(
config: configStore?.config ?? config,
session: authSession,
) {
this.cliLogin = cliLogin ?? this.viewer.login;
this.peerLinks = peerLinks ?? this.viewer.links;
_groupSyncOverride = groupSync;
// A teammate's agent in a Harness Team account on this person's Mac is not their news.
agentNotices.inTeamAccount = (ref) =>
stateOf(ref.machineId)?.machine.sessionKind == 'team';
_autonomousEnv = this.config.autonomousEnv;
api = _newApiClient();
this.productMeasurement =
productMeasurement ??
ProductMeasurement(
surface: kIsWeb ? 'web' : 'phone',
automatic: !kUnderTest,
// Signed-out counts start on, as the desktop's do, where an opt-out can be kept: the app's
// own store. A test or the sample (`demo/`) has none, and stays off.
setupStorage: paneLayoutStore?.storage,
sendSetup: (report) =>
sendSetupMeasurement(this.config.apiBaseUrl, report),
);
// On the stores' terms above: no layout store is a test or the sample (`demo/`), and neither is
// a launch of this app.
if (!kUnderTest && paneLayoutStore != null) {
launchMeasurement = LaunchMeasurement(this.productMeasurement);
// The install's first launch, once: the step between a store's download and a sign-in.
unawaited(this.productMeasurement.noteFirstOpen());
}
addListener(_syncProductMeasurement);
unawaited(_measurementContext());
_initDeviceLog();
_initPush(pushTokens, paneLayoutStore);
}
/// Which build this phone's reports come from ([ProductMeasurement.context]): the public release
/// and the OS family, nothing that tells one phone from another. A debug build reports as
/// `development`, which the backend does not keep. Not the web, which has no such context.
Future<void> _measurementContext() async {
if (kIsWeb || kUnderTest) return;
var release = 'unknown';
try {
release = await runningAppVersion();
} catch (_) {}
final source = await installSource();
if (_disposed) return;
productMeasurement.context = {
'surface': 'phone',
// The backend refuses a whole report whose release is not a plain x.y.z.
'release':
RegExp(r'^(0|[1-9]\d{0,2})(\.(0|[1-9]\d{0,2})){2}$').hasMatch(release)
? release
: 'unknown',
'platform': switch (defaultTargetPlatform) {
TargetPlatform.iOS => 'ios',
TargetPlatform.android => 'android',
_ => 'other',
},
// A tester's build (TestFlight) is `testing`: the backend keeps its totals apart.
'channel': measurementChannel(release: kReleaseMode, source: source),
};
}
void _syncProductMeasurement() {
final scope =
!signingIn &&
status == AppStatus.authenticated &&
currentUser?.id != null
? (api, currentUser!.id)
: null;
productMeasurement.account(
scope,
choice: () => productUsageSettings(),
send: api.productUsageReport,
);
launchMeasurement?.account(
signedIn: scope != null,
restored: !signedInThisRun,
);
if (scope == null) {
_measurementConnections.clear();
productConnections.clear();
productResumes.clear();
}
}
/// The account's product-usage choice — or, while an opt-out made before sign-in waits to be
/// carried to the account, set off: the desktop's rule. Pending until the server confirms it, so a
/// failed request or a default-on answer never quietly restores sharing.
Future<Map<String, dynamic>> productUsageSettings({bool? enabled}) async {
await productMeasurement.setupChoiceReady;
return api.productUsageSettings(
enabled:
enabled ?? (productMeasurement.accountOptOutPending ? false : null),
);
}
// Connection keys already belong to the app. Only fixed outcomes reach measurement, never the key.
void _measureConnection(
String key,
ConnectionStatus status,
ProductFlow flow,
) {
if (status == ConnectionStatus.connecting ||
status == ConnectionStatus.reconnecting) {
if (_measurementConnections.length < 64) {
_measurementConnections.putIfAbsent(
key,
() => productMeasurement.begin(flow),
);
}
} else {
_measurementConnections
.remove(key)
?.call(
status == ConnectionStatus.connected
? ProductOutcome.ok
: ProductOutcome.failed,
);
}
}
/// The app went to the background with dials or a launch still open. Every dial ends `cancelled` —
/// `remote_connect`'s ([_cancelMeasurementConnections]) and `connect_user`/`connect_auto`'s
/// ([ProductConnections.cancelOpen]) — and the launch, if no computer has answered, `unknown`
/// ([LaunchMeasurement.foreground]), as it does when the app is hidden. Only the background ends them: a
/// system sheet or the app switcher (`inactive`) is not leaving, and a dial after the app is back is a
/// new count.
void _endOpenMeasurementsForBackground() {
_cancelMeasurementConnections();
productConnections.cancelOpen();
launchMeasurement?.foreground(false);
}
/// Ends every dial still going as `cancelled`: the person left the screen before it had an answer,
/// which is neither a success nor a failure of the socket. Each count is dropped from
/// [_measurementConnections] as it ends, so the socket's own answer later finds none to end again
/// (no second outcome), and a dial after the app is back starts a fresh count.
void _cancelMeasurementConnections() {
if (_measurementConnections.isEmpty) return;
final open = _measurementConnections.values.toList();
_measurementConnections.clear();
for (final finish in open) {
finish(ProductOutcome.cancelled);
}
}
/// Straight to the backend, signed with this app's own session.
ApiClient _newApiClient() =>
ApiClient(config: config, session: session, auth: viewer.auth);
/// Where the harnesses this notifier sees are counted — the app's own [harnessStats], kept on
/// disk. Sample mode (`lib/demo/`) counts into one of its own: its harnesses are not the
/// person's, and must not land in their figures.
HarnessStats get stats => harnessStats;
String? get lastError => _lastError;
bool get lastErrorRetryable => _lastErrorRetryable;
String? get bootStatusMessage => _bootStatusMessage;
/// Clears the error strip without retrying anything, for a failure retrying
/// cannot fix (see [_lastErrorRetryable]).
void dismissError() {
_lastError = null;
notifyListeners();
}
/// Why this phone was signed out while it was in use — its session ended for good, or another
/// device removed it from the account — for the welcome screen to say. Without it the phone lands
/// on the first-run welcome as if it had never been signed in. Null after a Sign out by hand, and
/// cleared the moment a sign-in starts.
String? signedOutReason;
/// A Sign out by hand is under way or done, until the next sign-in. ⚠️ That sign-out takes this
/// phone's key out of the device log, and the log reading its own removal back calls
/// [ViewerDeviceLog.onSignedOut] — the very call a removal from another device makes. This is what
/// tells the two apart, so the person who pressed Sign out is not told the phone was removed.
bool _leftByHand = false;
static const _signedOutEnded =
'You were signed out. Sign in again to reach your computers.';
static const _signedOutRemoved =
'This phone was removed from your account on another device. Sign in again to use it here.';
String get autonomousEnv => _autonomousEnv;
static const offlineRetryInterval = Duration(seconds: 5);
/// How often a connected machine's agent list is read again, under the pushes — see
/// [_syncAgentsIfChanged].
///
/// ⚠️ **Two minutes, not one.** The pushes keep the list live; this catches only what they miss,
/// and a relay session gone stale ([agentSyncStaleTicks] of these timing out in a row). And it is
/// not cheap where it lands: the machine reads every agent's git state and history to answer —
/// one to two seconds for 150 of them — and every keystroke sent to it meanwhile waits behind
/// that answer. Once a minute, on each machine, was a stall in somebody's typing every minute.
static const agentSyncInterval = Duration(seconds: 120);
MachineState? stateOf(String machineId) => machineStates[machineId];
// ── the grid ────────────────────────────────────────────────────────────────────────────────────
/// Null means "remember nothing", which is what a test gets by default.
///
/// Deliberately NOT `?? PaneLayoutStore()` like the stores above it. Those
/// only read, and only when asked; this one WRITES on every pane change, and
/// a widget test that opens an agent would otherwise rewrite the layout in
/// the developer's own ~/.harness state file. Production passes one; see
/// [appStateProvider].
final PaneLayoutStore? _paneLayout;
/// The dial on this desk, for the rail's device row. Fed by `dial_status`
/// frames from the local daemon; its own notifier, so the row rebuilds
/// without dragging the whole rail through a machine-list rebuild.
final DialState dial;
final AgentPreference agentPreference;
/// Folders agents have been started in, per machine, kept across launches.
///
/// ⚠️ Not the same list as the folders this machine's agents are using right now. That one comes
/// from `machine.agents` and a deleted agent takes its folder off it; this one is a HISTORY and
/// outlives the agent — which is what "recent" has to mean for the word to be true.
final ProjectHistory projectHistory;
/// The agent the phone's terminal had open, kept across launches — see [LastOpenedAgent].
final LastOpenedAgent lastOpenedAgent;
/// Which computer's tabs this phone shows — Settings ▸ Profile. See [MachineProfileStore] and
/// [profileDeskTabs].
final MachineProfileStore machineProfile;
/// The agents and commands reached from the search, most recent first — what
/// ranks the box before a word is typed. See [PhoneSearchHistory].
///
/// ⚠️ **On the app, not on the search screen.** It has to outlive one opening
/// of the box: a history built per page would load the last run's visits and
/// then forget every visit made since, which is exactly the half that matters
/// while somebody is switching between two agents.
final PhoneSearchHistory searchHistory;
/// Last run's machine list, used to start dialling before this run's
/// `/api/machines` answers — see [MachineCache] and [_warmStartMachines].
/// Null in tests, which have no Harness home to cache into.
final MachineCache? _machineCache;
TerminalPane? get focusedPane {
final id = focusedPaneId;
if (id == null) return null;
for (final pane in panes) {
if (pane.id == id) return pane;
}
return null;
}
/// The one tile everything single-terminal still means.
///
/// Kept as a getter rather than deleted because the alternative — teaching
/// every caller about tiles — would have spread the grid across code that has
/// no business knowing there is one (a rename arriving, an agent being
/// deleted, the window closing). The handful of callers that must reach EVERY
/// tile of a machine, rather than only the focused one, call [panesFor]
/// instead; those are the transport-wide events, and they are marked.
TerminalSession? get activeTerminal => focusedPane?.session;
bool get canAddPane => panes.length < maxPanes;
Iterable<TerminalPane> panesFor(String machineId) =>
allPanes.where((pane) => pane.machineId == machineId);
TerminalPane? paneOfAgent(String machineId, String agentId) {
for (final pane in panes) {
if (pane.machineId == machineId && pane.agentId == agentId) return pane;
}
return null;
}
bool isAgentInPane(String machineId, String agentId) =>
paneOfAgent(machineId, agentId) != null;
void focusPane(int paneId, {bool reveal = false}) {
if (!panes.any((pane) => pane.id == paneId)) return;
final moved = focusedPaneId != paneId;
// Remembered only on a REAL move. Re-focusing the tile you are already on
// happens constantly, and recording it would make ⌘; a key that returns you
// to where you already are, which is the same as a key that does nothing.
if (moved) _previousPaneId = focusedPaneId;
focusedPaneId = paneId;
selectedMachineId = focusedPane?.machineId;
if (zoomedPaneId != null) zoomedPaneId = paneId;
// ⚠️ **Nothing is told which agent is on screen.** The desktop sends `app_focus` and
// `app_panes` here for the dial beside it; only the CLI's loopback server reads them
// (`localWsServer.ts`), and a phone's socket is the relay, where nothing does — and the types
// are not in `encryptedDownTypes`, so every swipe sent the agent id past the backend in the
// clear for no one to read.
if (moved) _persistLayout();
if (moved || reveal) notifyListeners();
}
/// Machines whose link prompt the user has waved away.
///
/// Dismissing cannot mean "deselect": [activeMachineState] falls back to the
/// first expanded machine, so clearing the selection would often re-arrive at
/// the very machine that was just closed. And it must not mean "linked" —
/// nothing changed about the machine, which still cannot be read and still
/// says so in the rail. It means only that the pane stops insisting.
///
/// Held in memory, not on disk, and cleared the moment the machine is chosen
/// again: someone who clicks that row is asking to see it.
final Set<String> _dismissedLinkPrompts = {};
bool isLinkPromptDismissed(String machineId) =>
_dismissedLinkPrompts.contains(machineId);
void dismissLinkPrompt(String machineId) {
if (_dismissedLinkPrompts.add(machineId)) notifyListeners();
}
/// The person asked to see the prompt again — a deliberate open, not the
/// reactive gate. Without this, every way in that does not go through
/// [showMachinePane] (the welcome's Machines row) opened a dialog that its
/// own "still needed?" check closed on the first frame: one popup, then
/// nothing, for as long as the app ran.
void revisitLinkPrompt(String machineId) {
if (_dismissedLinkPrompts.remove(machineId)) notifyListeners();
}
MachineState? get activeMachineState {
final terminal = activeTerminal;
if (terminal != null) return machineStates[terminal.machineId];
final selected = selectedMachineId;
if (selected != null) return machineStates[selected];
return expandedMachines.isEmpty
? null
: machineStates[expandedMachines.first];
}
bool? _nodeOnlineFromStatus(String? status) {
switch (status?.trim().toLowerCase()) {
case 'running':
case 'online':
case 'connected':
case 'ready':
return true;
case 'offline':
case 'stopped':
case 'disconnected':
case 'unreachable':
case 'error':
case 'failed':
return false;
default:
return null;
}
}
Future<void> bootstrap() async {
// ⚠️ **Started before anything is awaited (owner, 2026-10-01).** The launch's dial waits on
// these two reads: the last-opened agent names its machine, the cache says that machine was up
// ([_warmStartMachines]). Started after the config and the sign-in check, they landed after
// the first frame, ~250ms into the dial's wait. Disk only; dropped when nobody is signed in.
lastOpenedAgent.prefetch();
// Copies of large chat files a run that ended first left behind; none is held yet.
unawaited(clearSwarmPickerCopies());
final cache = _machineCache;
if (cache != null) {
// Read before the first frame by `startHarness` — see [_preDialFromHint].
_launchHint = MachineCache.takeLaunchHint();
_launchCacheRead = StartupTrace.time(
'boot.machineCacheRead',
cache.readRaw,
);
// The small one beside it, which the launch's own machine is drawn from first.
_launchRecordRead = StartupTrace.time(
'boot.machineLaunchRead',
cache.readLaunchRaw,
);
}
try {
if (_store != null) {
try {
config = await StartupTrace.time(
'boot.configLoad',
() => _store.load().timeout(const Duration(seconds: 5)),
);
} catch (error) {
// Connection settings are optional local preferences. An unavailable
// state file must not invalidate an otherwise recoverable SSO flow;
// use the store's safe cached/default production config.
debugPrint(
'bootstrap: config store unavailable, using defaults: $error',
);
config = _store.config;
}
// Forced, not read from persisted config: staging is a dev-only
// escape hatch with no UI to reach it anymore (see the desktop's
// login_screen.dart history) — a stale `stag` value saved before that removal must
// never silently resurrect it.
_autonomousEnv = 'prod';
api = _newApiClient();
}
await _checkSignIn();
} catch (error, stack) {
debugPrint('bootstrap: fallback to login after error: $error\n$stack');
currentUser = null;
status = AppStatus.unauthenticated;
notifyListeners();
} finally {
// Taken by the warm start when signed in; otherwise last run's text has no reader.
_launchCacheRead = null;
_launchRecordRead = null;
_launchHint = null;
}
}
/// The machine the launch hint names ([MachineCache.preloadLaunchHint]), for [_preDialFromHint]
/// — during the bootstrap that took it, and only then.
String? _launchHint;
/// The machine [_preDialFromHint] dialled, until the warm start has read which agent the launch
/// reopens and either keeps that dial as its own or lets it go ([_warmStartMachines]).
String? _preDialled;
/// Dial the machine the launch hint names, now — before the first frame, before anything else is
/// read — when the launch is signed in and nothing is on screen yet.
///
/// ⚠️ **A head start, not a decision (owner, 2026-10-02).** Which agent the launch reopens is
/// still [lastOpenedAgent]'s to say, and the hold on the other machines is still the warm start's
/// to make; this only puts the socket — TCP, TLS, the upgrade — under way ~400ms sooner than the
/// warm start could, which had to wait out the first frame to read anything. The warm start takes
/// the dial over when the agent it reopens is on this machine, which is what the hint is written
/// for; otherwise the socket is closed again, one dial wasted, as a hint behind a crash is.
void _preDialFromHint() {
final hint = _launchHint;
_launchHint = null;
if (hint == null || _pool == null || _disposed) return;
if (machines.isNotEmpty || machineStates.isNotEmpty) return;
_preDialled = hint;
StartupTrace.mark(
'launch: dialling ${_shortId(hint)} from the launch hint',
);
_conn(hint);
}
/// The machine cache as [bootstrap] began reading it, for the launch's [_warmStartMachines] —
/// once, and only during the bootstrap that started it.
Future<String?>? _launchCacheRead;
/// The cache's launch record ([MachineCache.readLaunchRaw]), read beside [_launchCacheRead] and
/// on the same terms.
Future<String?>? _launchRecordRead;
/// Whether this device is signed in, and everything behind the login screen when it is — what
/// `bootstrap()` does once its config is loaded.
Future<void> _checkSignIn() async {
final revision = _authRevision;
if (!_authWorkCurrent(revision)) return;
// The boot spinner holds while the sign-in is checked.
status = AppStatus.bootstrapping;
notifyListeners();
// The session is the app's own (`viewer/direct_auth.dart`): this asks whether one is kept.
try {
final authStatus = await StartupTrace.time(
'boot.checkSignIn',
cliLogin.checkStatus,
);
if (!_authWorkCurrent(revision)) return;
if (!authStatus.loggedIn) {
// The session ended while the app was closed (revoked from another device): the OS stops
// delivering this account's pushes to the phone. The backend drop fails without a session.
if (_push case final push?) unawaited(push.forgetIfTold(api));
currentUser = null;
status = AppStatus.unauthenticated;
notifyListeners();
return;
}
await _finishBootstrapSignedIn();
} catch (error, stack) {
if (!_authWorkCurrent(revision)) return;
debugPrint('checkSignIn: fallback to login after error: $error\n$stack');
currentUser = null;
status = AppStatus.unauthenticated;
notifyListeners();
}
}
/// Both `bootstrap()` (already signed in) and a sign-in that just finished land here once a
/// session exists — fetch the profile and machine list, and restore the tiles meanwhile.
Future<void> _finishBootstrapSignedIn() async {
final revision = _authRevision;
if (!_authWorkCurrent(revision)) return;
// Before ANYTHING below can start a connection, a machine refresh or a pane restore — each can
// end in a read of the device log, which must be judged by THIS sign-in (a hand sign-in mints its
// id here), not the previous account's. Synchronous: no await may come first.
_beginDeviceLogSignIn(revision);
// Signed in again: a removal the log reads from here on was made by another device. Not before
// this line — the last Sign out by hand may still be reading its own removal back until the log
// knows about this sign-in, which the line above just told it.
_leftByHand = false;
// Stays on the pre-navigation `bootstrapping` screen (main.dart) until the local state is
// restored. A phone has no local service to start — the desktop's "Starting local service…"
// was a sentence about somebody else's computer shown while this one read its own disk.
_bootStatusMessage = 'Getting your machines…';
notifyListeners();
// Which agent to reopen is the first thing the phone's home screen asks for
// and the last thing it can draw without, so the read starts no later than
// here rather than when that screen mounts — several state-file operations
// later, behind every one of their locks. A launch has already started it
// (top of [bootstrap]); a sign-in in this run starts it here. See
// [LastOpenedAgent.prefetch].
lastOpenedAgent.prefetch();
// Which computer's tabs to show (Settings ▸ Profile). Queued behind the record above on
// purpose, and not awaited: nothing picks a tab before the desk's network read lands.
unawaited(_loadMachineProfile());
unawaited(_loadHarnessOsComputers());
// No screen from the last run: the agent that record names is drawn as the skeleton until its
// keyframe lands — see [KeptScreenStore]. What an earlier build kept of it on disk goes. Only in
// the app, on the store's terms: a test never reaches the real cache directory.
if (_keptScreenStore != null) {
unawaited(KeptScreenStore.deleteLegacyFile());
}
// Before the machines, deliberately: the tiles are intent, they render as
// "waiting for that machine" on their own, and each attaches as its machine
// answers. Waiting for the machine list first would leave the window empty
// for as long as the slowest one takes, and would hand the first-run
// auto-pick a window in which the grid still looks empty.
//
// `dial` is not restored beside them: it describes a USB device plugged
// into a desktop, which a phone has no port for, so the read could only
// ever return the default it already holds.
//
// ⚠️ **The machine list is asked for HERE, not after the disk work, and that
// ordering is the point.** A viewer reaches every machine over the network,
// so `/api/machines` depends on nothing below it — yet it used to be the
// last thing started, behind several exclusive locks on one state file. The
// request now overlaps that disk work instead of queueing behind it, which
// takes a whole HTTP round-trip off the stretch the phone spends saying
// "Connecting to your computer…".
//
// ⚠️ The pool is built BEFORE the fetch is started, not after the restore
// below. A returning list dials each machine through `_conn`, which reads
// `_pool` and would throw on a null one — reachable only because this fetch
// can now finish while the restore is still holding the file lock. It is
// cheap and idempotent, and nothing it needs comes off disk.
//
// The failure is held rather than thrown: nothing awaits this future until
// the end of the method, and an unhandled rejection in between would reach
// the zone's error handler and be reported as a crash. It is re-raised at
// that await, where the existing handler words it for the user and offers
// the retry.
_ensurePool();
// The launch's machine first of all, from the hint read before the first frame.
_preDialFromHint();
final machineRefresh = StartupTrace.time<Object?>(
'boot.refreshMachines',
() async {
try {
await refreshMachines();
return null;
} catch (error) {
return error;
}
},
);
// Dial last run's machines WHILE that fetch is in the air. The socket,
// the relay and the E2EE handshake are the slowest part of the launch by
// far, and none of them needed the fetch to have finished — only a
// machine id, which the last run already wrote down.
unawaited(_warmStartMachines());
// Not awaited before the fetch above starts: the screen still wants to
// appear as soon as the local state is restored, and these two now overlap.
await StartupTrace.time('boot.restoreLocalState', _restorePaneLayout);
if (!_authWorkCurrent(revision)) return;
// Before the shell is up, so its first frame can already open what Swarm
// kept for this account. Only a nicety: nothing here is worth a failed boot.
final kept = await session.accountId().catchError((Object _) => null);
if (!_authWorkCurrent(revision)) return;
_keptAccountId = kept;
_bootStatusMessage = null;
status = AppStatus.authenticated;
notifyListeners();
// What the device log announced while the app was still starting up (see [_whenSignedIn]).
_flushDeviceNotices(revision);
// The device log is joined NOW, not after the machine list or the profile: a read of it that
// landed first (a push, a reconnect) would judge a just-signed-in phone by the old sign-in's
// file, and the log has to know the sign-in is fresh before anything waits.
_registerDeviceLog(revision);
// With no machine connected nothing is pushed to this phone: the machine list is read again now
// and then until one is ([_rereadMachinesWhileDeaf]).
_startDeafPoll();
// Signed in. Display-name/avatar metadata is independent of machine
// discovery and must not delay work.
unawaited(_loadProfile());
// The desk too: its tabs are what a swipe stays inside, and they are read
// over REST rather than from any machine — so they can land before the
// first machine has finished dialling.
_desk.ensure();
// The zoo the same way: the daemon on the chip is account state.
zoo.ensure();
try {
// The request already in flight (above).
final failure = await machineRefresh;
if (failure != null) throw failure;
} catch (error) {
if (!_authWorkCurrent(revision)) return;
_lastError = 'Could not load machines: ${describeApiError(error)}';
_lastErrorRetryable = true;
}
if (_authWorkCurrent(revision)) notifyListeners();
}
/// Signed in, and who as is still to come: the shell is up before the account
/// is read, and a read that fails is tried again ([_profileNotRead]).
bool get accountReading =>
status == AppStatus.authenticated &&
currentUser == null &&
_keptAccountId == null;
/// The account this sign-in last said it was, until it says so again.
String? _keptAccountId;
/// Whose Swarm to open: the account, or before it has answered, who this
/// sign-in last said it was: a launch's kept Home need not wait on
/// `/api/auth/me` with everything it needs on disk.
/// Should the account answer otherwise, its answer wins and Swarm starts over
/// ([SwarmHost]), taking what it kept with it.
String? get swarmAccountId =>
currentUser?.id ??
(status == AppStatus.authenticated ? _keptAccountId : null);
void _keepAccount(String id) {
if (id == _keptAccountId) return;
_keptAccountId = id;
unawaited(
session.saveAccountId(id).catchError((Object error) {
appLog.warn('auth', 'Account id not kept', error: error);
}),
);
}
/// Who is signed in, from the account. Shared by the boot path and by the
/// retry path, because a profile the boot could not read is asked for again
/// there — and a session that never learns its own account has an empty
/// footer.
Future<void> _loadProfile() {
final pending = _profileInFlight;
if (pending != null) return pending;
final revision = _authRevision;
late final Future<void> load;
load = _readProfile(revision).whenComplete(() {
if (identical(_profileInFlight, load)) _profileInFlight = null;
});
_profileInFlight = load;
return load;
}
/// Saves the signed-in person's own account name (Profile, task #2655) and shows it at once; answers why it was
/// refused, in one short line, or null once saved. As the desktop's (`setAccountName`, #2917).
Future<String?> setAccountName(String name) async {
final revision = _authRevision;
try {
final me = await api.updateMe(name: name);
if (me == null || !_authWorkCurrent(revision)) return null;
final profile = CurrentUserProfile.fromMe(me);
// Another account's answer is not this one's name: the next profile read settles it.
if (currentUser?.id != null && profile.id != currentUser?.id) return null;
currentUser = profile;
notifyListeners();
return null;
} on ApiException catch (error) {
// A backend from before the route.
if (error.status == 404) return 'Update Harness to change your name.';
return error.message;
} catch (_) {
return 'Your name was not saved. Try again.';
}
}
Future<void> _readProfile(int revision) async {
try {
final me = await api.me();
if (!_authWorkCurrent(revision) || status != AppStatus.authenticated) {
return;
}
if (me == null) {
_profileNotRead(revision, null);
} else {
_profileFailures = 0;
currentUser = CurrentUserProfile.fromMe(me);
// Made by a sign-in in this run, or coming back to it.
onboardingMeasurement.accountCreated(currentUser?.createdAt);
// A sign-in by hand: the device log keeps which account it was made to.
if (currentUser?.id case final id?) {
unawaited(_deviceLog?.signedInAs(id));
_keepAccount(id);
}
_syncPush();
notifyListeners();
}
} catch (error) {
if (_authWorkCurrent(revision)) _profileNotRead(revision, error);
}
}
Timer? _profileAgain;
/// Reads of the profile that failed in a row: the first goes in the log.
int _profileFailures = 0;
/// A read that brought no account: asked for again, less often each time,
/// from 5 seconds up to a minute. Swarm waits on it, and nothing else asks
/// while the machines are well.
void _profileNotRead(int revision, Object? error) {
if (_profileFailures == 0) {
appLog.warn('auth', 'Account not read', error: error);
}
final wait = min(60, 5 << min(_profileFailures, 4));
_profileFailures++;
_profileAgain?.cancel();
_profileAgain = Timer(Duration(seconds: wait), () {
if (_disposed || !_authWorkCurrent(revision) || currentUser != null) {
return;
}
unawaited(_loadProfile());
});
}
/// The session went away while the app was already running — send the user to the signed-out screen with a
/// reason, and stop the background work that can only fail from here.
///
/// Cold start already handles this: [bootstrap] asks whether a session is kept. The hole this
/// fills is the app that was ALREADY authenticated when the session disappeared underneath it —
/// a relay socket finding it gone for good ([WsCredentialRevoked]).
void _signedOutAtRuntime(String message) {
if (status == AppStatus.unauthenticated) {
return; // idempotent: several sources can race here
}
// ⚠️ A Sign out by hand is under way ([_leftByHand]): it clears the saved session before it
// closes the sockets, and one dialling in between finds the session gone and says so. That is
// the sign-out in progress, not news — answered here, it invalidated the auth work under that
// sign-out, which then stopped halfway, and put "You were signed out" in front of the person
// who had just pressed Sign out. The sign-out finishes the job itself.
if (_leftByHand) return;
_invalidateAuthWork();
// As on a sign-out here ([_endSession]): no lock-screen notice of this account after it. The
// backend drop fails without a session; the OS one still stops delivery.
if (_push case final push?) unawaited(push.forget(api));
currentUser = null;
signingIn = false;
signInProvider = null;
// The code was scanned into the session that just ended — see [logout].
pendingPairing = null;
pendingComputerSignIn = null;
_clearDeviceNotices();
_stopAccountTimers();
_desk.reset();
zoo.reset();
_forgetLaunchHold();
// Signed out from elsewhere: the kept screens go as on a sign-out here (see [logout]).
_keptScreens.clear();
_forgetScrollMemories();
_keptScreenStore?.clear();
unawaited(_pool?.closeAll());
_pool = null;
// ⚠️ **The account's machines go with it, as on a sign-out by hand ([_endSession]).** Kept,
// the next sign-in — perhaps another account's — started on this account's list: it was not
// empty, so no "Looking for your computers…", and this account's computers were drawn as the
// next one's until its own fetch landed. The warm-start cache on disk went on naming them too,
// and the next launch dialled them with the new session.
_stopAllOfflineRetries();
_stopAllAgentSyncTimers();
_relaySaid.clear();
// Reads [machineStates], so before it is emptied.
_clearAllTurnActivity();
machines = [];
machineStates.clear();
unawaited(_machineCache?.clear());
sessionPreviews.clear();
agentNotices.reset();
// The Settings row's usage figure was this account's — see [lastUsageSummary].
lastUsageSummary.value = null;
expandedMachines.clear();
selectedMachineId = null;
// ⚠️ The saved session goes too. The socket that said so (a refresh refused, 4403) is the only
// judge of it, and a session left on disk signed the NEXT launch straight back in — only to be
// refused again, with the person never told why. Best effort, as [logout]'s own: a store that
// cannot be written to must not surface as an unhandled error on the way out.
unawaited(cliLogin.logout().catchError((Object _) {}));
_lastError = message;
_lastErrorRetryable = true;
signedOutReason = _signedOutEnded;
signedInThisRun = false;
onboardingMeasurement.reset();
welcomedMachines.clear();
firstSessionLine = null;
status = AppStatus.unauthenticated;
notifyListeners();
}
/// A session was just saved: load everything behind the login screen. The
/// one road in for every way of signing in.
Future<void> _enterSignedIn(int revision) async {
await _finishBootstrapSignedIn();
}
/// The phone's sign-in, first step: email [email] a one-time code. Throws the
/// service's own reason ("Email is invalid") for the form to show. See
/// `viewer/email_code_api.dart`.
Future<void> sendLoginCode(String email) => viewer.emailLogin.sendCode(email);
/// A sign-in attempt, counted as `sign_in` and under the welcome-screen button that started it:
/// every outcome for a signed-out session that opted in, and a success once more under the
/// account's own sharing ([OnboardingMeasurement.signedIn]).
void Function(ProductOutcome) _measureSignIn(ProductFlow method) {
final finish = productMeasurement.beginEach([ProductFlow.signIn, method]);
final watch = Stopwatch()..start();
var done = false;
return (outcome) {
finish(outcome);
// Called again by each attempt's `finally`: only its first outcome is the attempt's.
if (done) return;
done = true;
onboardingMeasurement.attempted(method, outcome);
if (outcome == ProductOutcome.ok) {
onboardingMeasurement.signedIn(method, watch.elapsed);
}
};
}
/// The phone's sign-in, second step: trade the emailed [code] for a session
/// and go in.
///
/// A wrong or expired code is thrown for the form to show beside the field —
/// never raised to [lastError], which would put a second, generic error under
/// the one the person is already reading. The login card stays up throughout:
/// [signingIn] keeps it there (see `RootShell`), so the form keeps what was
/// typed into it.
Future<void> signInWithCode({
required String email,
required String code,
}) async {
final login = viewer.emailLogin;
if (_disposed || signingIn) return;
final measureSignIn = _measureSignIn(ProductFlow.signInEmail);
final revision = _invalidateAuthWork();
_closedHistory.clear();
_lastError = null;
signedOutReason = null;
signingIn = true;
notifyListeners();
try {
await login.signIn(email: email, code: code);
if (!_authWorkCurrent(revision)) return;
signedInThisRun = true;
measureSignIn(ProductOutcome.ok);
status = AppStatus.bootstrapping;
notifyListeners();
await _enterSignedIn(revision);
} catch (_) {
measureSignIn(ProductOutcome.failed);
if (_authWorkCurrent(revision)) {
status = AppStatus.unauthenticated;
}
rethrow;
} finally {
measureSignIn(
_authWorkCurrent(revision)
? ProductOutcome.unknown
: ProductOutcome.cancelled,
);
if (_authWorkCurrent(revision)) {
signingIn = false;
notifyListeners();
}
}
}
/// Sign in with the one-time code a signed-in computer's Add Phone QR
/// carries — no email, no digits — and go in. Thrown and kept like
/// [signInWithCode]: the welcome screen falls back to an emailed code.
Future<void> signInWithScan(String code) async {
final login = viewer.emailLogin;
if (_disposed || signingIn) return;
final measureSignIn = _measureSignIn(ProductFlow.signInScan);
final revision = _invalidateAuthWork();
_closedHistory.clear();
_lastError = null;
signedOutReason = null;
signingIn = true;
notifyListeners();
try {
await login.signInWithScan(code, label: phoneClientDescriptor().name);
if (!_authWorkCurrent(revision)) return;
signedInThisRun = true;
measureSignIn(ProductOutcome.ok);
status = AppStatus.bootstrapping;
notifyListeners();
await _enterSignedIn(revision);
} catch (_) {
measureSignIn(ProductOutcome.failed);
if (_authWorkCurrent(revision)) {
status = AppStatus.unauthenticated;
}
rethrow;
} finally {
measureSignIn(
_authWorkCurrent(revision)
? ProductOutcome.unknown
: ProductOutcome.cancelled,
);
if (_authWorkCurrent(revision)) {
signingIn = false;
notifyListeners();
}
}
}
/// Sign in with [provider]'s account — "Continue with Google", "Continue with Apple" — through
/// the SSO page, opened in the app (`viewer/direct_login.dart`, `viewer/sign_in_browser.dart`),
/// and go in.
///
/// Thrown and kept like [signInWithCode], for the welcome screen to show — except a cancel
/// ([cancelProviderSignIn]), which the person chose and needs no sentence.
Future<void> signInWithProvider(SignInProvider provider) async {
final login = viewer.login;
if (_disposed || signingIn) return;
final measureSignIn = _measureSignIn(switch (provider) {
SignInProvider.google => ProductFlow.signInGoogle,
SignInProvider.apple => ProductFlow.signInApple,
});
final revision = _invalidateAuthWork();
_closedHistory.clear();
_lastError = null;
signedOutReason = null;
signingIn = true;
signInProvider = provider;
notifyListeners();
try {
await login.login(
provider: provider,
onAuthorizeUrl: (url) =>
unawaited(_openSignInPage(url, login, revision)),
);
// iOS takes its sheet down here; Android's Custom Tab is the person's to close.
unawaited(closeSignInPage());
if (!_authWorkCurrent(revision)) return;
signedInThisRun = true;
measureSignIn(ProductOutcome.ok);
status = AppStatus.bootstrapping;
notifyListeners();
await _enterSignedIn(revision);
} on SignInCancelled {
measureSignIn(ProductOutcome.cancelled);
unawaited(closeSignInPage());
if (_authWorkCurrent(revision)) status = AppStatus.unauthenticated;
} catch (_) {
measureSignIn(ProductOutcome.failed);
unawaited(closeSignInPage());
if (_authWorkCurrent(revision)) status = AppStatus.unauthenticated;
rethrow;
} finally {
measureSignIn(
_authWorkCurrent(revision)
? ProductOutcome.unknown
: ProductOutcome.cancelled,
);
if (_authWorkCurrent(revision)) {
signingIn = false;
signInProvider = null;
notifyListeners();
}
}
}
/// The page [signInWithProvider] waits on, shown. One that cannot be shown ends that sign-in
/// with the reason — it would otherwise wait out its timeout on a page nobody can see — and one
/// the person closes ends it as a cancel ([DirectLogin.pageClosed]): the welcome screen is back
/// as it was, with nothing to say. Either only while it is still the sign-in in flight: a later
/// one is not this page's to end.
Future<void> _openSignInPage(Uri url, DirectLogin login, int revision) async {
bool inFlight() => _authWorkCurrent(revision) && signInProvider != null;
try {
await openSignInPage(
url,
onClosed: () {
if (inFlight()) login.pageClosed();
},
);
} catch (error) {
debugPrint('signInWithProvider: could not open the sign-in page: $error');
if (inFlight()) {
login.cancel(
const DirectAuthException(
'Could not open the sign-in page. Check your connection and try again.',
),
);
}
}
}
/// Stop the sign-in [signInWithProvider] is waiting on — the person closed the page, or chose
/// another way in. The welcome screen settles back with nothing to report.
void cancelProviderSignIn() {
if (signInProvider == null) return;
viewer.login.cancel();
}
/// The Sign out by hand under way, from the confirm to the welcome screen — see [logout].
Future<void>? _signingOut;
/// A Sign out by hand is under way: it takes a few seconds (the device log, the sockets) before
/// the welcome screen comes up, and the screens that offer it say so meanwhile.
bool get signingOut => _signingOut != null;
/// Sign out by hand — Settings ▸ account ▸ Sign out. The welcome screen it lands on says nothing:
/// the person knows why they are there.
///
/// ⚠️ **One at a time: a second call joins the first.** The first can take up to 5 seconds with
/// nothing on screen changing ([_endSession] waits on the device log), long enough to press Sign
/// out again — and the second, finishing after the first, invalidated the auth work of a sign-in
/// the person had started on the welcome screen meanwhile (Continue with Google, into the right
/// account): dropped, with nothing said.
Future<void> logout() {
final running = _signingOut;
if (running != null) return running;
_leftByHand = true;
late final Future<void> run;
run = () async {
try {
await _endSession();
} finally {
if (identical(_signingOut, run)) {
_signingOut = null;
// A sign-out cut short (another sign-in or -out moved the session on) changes no status
// of its own: whatever drew "Signing out…" is told it is over.
if (!_disposed) notifyListeners();
}
}
}();
_signingOut = run;
notifyListeners();
return run;
}
/// Everything a sign-out does, whoever asked for it. [reason] is what the welcome screen says
/// ([signedOutReason]): null when the person chose it.
Future<void> _endSession({String? reason}) async {
// Chosen by the person, the sign-out is itself a step's end ("Not you? Sign out"): end the steps
// it abandons, then send what is queued while the session can still send it — the queue goes
// with the account.
if (reason == null) {
onboardingMeasurement.reset();
await productMeasurement.sendBeforeSignOut();
}
// Signing out takes this phone's key out of the account's devices, while the sign-in still works
// to say so. Best effort, and brief.
if (_deviceLog case final log?) {
try {
await log.leave().timeout(const Duration(seconds: 5));
} catch (_) {}
}
// So does where to push to it: no notice of this account reaches a phone signed out of it.
if (_push case final push?) {
try {
await push.forget(api).timeout(const Duration(seconds: 5));
} catch (_) {}
}
final revision = _invalidateAuthWork();
signingIn = false;
signInProvider = null;
// A scanned code belongs to the session it was scanned into. Held past this,
// the next sign-in — perhaps another account's — would spend it on the first
// locked machine of that id and show a pairing error where its password form
// belongs. Not in [_invalidateAuthWork]: signing IN starts there too, and the
// code is set before that sign-in on purpose (`phone_welcome.dart`). The same for a computer's
// sign-in code: held for the sign-in it asked for, not the one after this.
pendingPairing = null;
pendingComputerSignIn = null;
// The Settings row's usage figure was this account's — see [lastUsageSummary]. Here, before the
// awaits below: a sign-in started meanwhile ends this early, and must not inherit the figure.
lastUsageSummary.value = null;
_closedHistory.clear();
// Best-effort and fire-and-forget: local state is cleared below regardless, but the saved
// session goes too, so the NEXT launch doesn't silently sign back in without ever showing the
// login screen.
unawaited(cliLogin.logout());
_stopAllOfflineRetries();
_stopAllAgentSyncTimers();
_relaySaid.clear();
_forgetLaunchHold();
_stopAccountTimers();
// Tiles go, the saved layout stays: signing out and back in is the same
// person at the same desk, and the file is only read once machines exist.
await _closeAllPanes(persist: false);
if (!_authWorkCurrent(revision)) return;
_closedHistory.clear();
await _pool?.closeAll();
if (!_authWorkCurrent(revision)) return;
_pool = null;
_clearAllTurnActivity();
// The desk belongs to the account, not to the phone: its tabs go with the
// session, writes this phone never managed to send included.
_desk.reset();
// The zoo is the account's too.
zoo.reset();
individualArt.reset();
currentUser = null;
machines = [];
machineStates.clear();
// ⚠️ The warm-start cache is this account's machine ids, so it goes with the
// session. Left behind, the next launch would dial the previous account's
// machines before its own fetch could say they are not its own — reaching
// for computers the person signing in may have no relationship to at all.
// Not awaited: sign-out must not wait on a disk write, and the cache is only
// ever read after a sign-in that this clears the way for.
unawaited(_machineCache?.clear());
// The kept screens are this account's terminals — they go with it, as the cache does.
_keptScreenStore?.clear();
sessionPreviews.clear();
agentNotices.reset();
// The account's device notices go with it: the next sign-in may be another account's, and what
// is still pending comes back from its own log once it registers.
_clearDeviceNotices();
expandedMachines.clear();
selectedMachineId = null;
signedOutReason = reason;
signedInThisRun = false;
onboardingMeasurement.reset();
welcomedMachines.clear();
firstSessionLine = null;
status = AppStatus.unauthenticated;
notifyListeners();
}
/// Forget every device notice of the account that just left (banner, removals), and make a read of
/// its `pending` that is still in flight drop its result: the next sign-in may be another account's.
void _clearDeviceNotices() {
_pendingSyncGen++;
_startupDeviceNotices.clear();
newDevices.clear();
departedDevices.clear();
deviceRemovals.clear();
_failedDismissals.clear();
_deviceListFrozen = false;
_deviceListTooMany = false;
}
/// What an account leaving takes with it: the refusals being settled, the machine list re-read
/// while deaf, and when each machine last swapped trust groups (the next account's swap is its own).
void _stopAccountTimers() {
_forgetAllTrustSettles();
_stopDeafPoll();
_groupSyncedAt.clear();
_keyWatch?.cancel();
_keyWatch = null;
}
void _onLocalFailure(String machineId, int code, String reason) {
final machine = machineStates[machineId];
if (machine == null || code != 4404) return;
// A refusal for want of trust is usually only early: this phone's key not yet in the account's
// device log, or the machine not yet in this phone's copy of it — a computer signed in after the
// phone was. That is settled first ([_settleTrust]), while the machine keeps showing as
// connecting; only a refusal that outlasts it asks for a password. Not for a machine a scanned
// code waits for: its pairing screen is the way in, at once.
if (_deviceLog != null &&
(reason == 'NO_PEER_LINK' || reason == 'E2E_DENIED') &&
pendingPairing?.machineId != machineId) {
if ((_trustRounds[machineId] ?? 0) < _trustSettleRounds) {
if (_trustSettling.add(machineId)) {
unawaited(_settleTrust(machineId, reason));
}
return;
}
if (!machine.needsLink) {
appLog.info(
'link',
'${_shortId(machineId)} still refused ($reason) after the device list was checked',
);
}
}
// A machine the account's device key log names may simply not have read it yet: read it again;
// a machine it pins is dialled again as soon as it lands.
if (_deviceLog case final log?) unawaited(log.refresh());
_markNeedsLink(machine);
}
void _markNeedsLink(MachineState machine) {
// The relay found no linked trust for this machine: it waits for this phone's password form (or
// a scanned code), which reconnects when it lands. Nothing is polled — the desktop retries every
// few seconds for a `harness link connect` run elsewhere, which a phone's links never come from.
machine.needsLink = true;
machine.agentLoadStatus = AgentLoadStatus.needsLink;
launchMeasurement?.waiting(LaunchWait.locked);
unawaited(_awaitMachineKey(machine));
// …unless the log already vouches for it and this phone's key is new to it: then the machine
// has only not read that key yet — see [_redialOnceVouched].
unawaited(_redialOnceVouched(machine.machine.machineId));
// A 4404 can also arrive MID-SESSION ("peer revoked trust" in the CLI's
// remoteRelay.ts) with terminals open on this machine. The disconnect
// that follows deliberately no longer marks the node offline (see the
// onStatus branch in _ensurePool), so the tiles have to be told here
// instead — otherwise they keep rendering as live until a heartbeat
// fails, and nothing records what to reattach once the machine is linked
// again.
_markSessionsUnreachable(
machine,
'This machine is no longer linked. Link it again to reconnect.',
);
notifyListeners();
}
// -- a refusal for want of trust ([_onLocalFailure]) ---------------------------------------------
/// How many refusals of each machine were settled since it last connected, and the ones under way —
/// each with what ends its wait early (a pin landing: [_redialNewlyTrusted]).
final Map<String, int> _trustRounds = {};
final Set<String> _trustSettling = {};
final Map<String, Completer<void>> _trustWakes = {};
static const _trustSettleRounds = 2;
/// How long one settling round waits for the machine's key to land before dialling again: two
/// rounds, about fifteen seconds, before a password is asked for.
@visibleForTesting
Duration trustSettleRound = const Duration(milliseconds: 7500);
/// How long a machine that denied this phone's key gets to read the account's log again (its CLI
/// does on a hello from a key it does not know) before the first hello is said again.
@visibleForTesting
Duration trustDeniedWait = const Duration(seconds: 1);
/// Hears every [_redial], for a test with no pool to dial through.
@visibleForTesting
void Function(String machineId)? onRedialForTest;
/// The first eight characters of a machine id — enough to tell an account's machines apart in
/// a log line.
static String _shortId(String id) => id.length > 8 ? id.substring(0, 8) : id;
/// One round of settling [machineId]'s refusal ([reason]: `NO_PEER_LINK`, no key here for it, or
/// `E2E_DENIED`, the machine does not know this phone's): put this phone into the account's device
/// log and read it, then dial again — at once when the machine's key just landed, after a moment for
/// a machine that has to read the log itself. A frozen log can settle nothing: the password it is.
Future<void> _settleTrust(String machineId, String reason) async {
final log = _deviceLog;
if (log == null) return;
final revision = _authRevision;
final round = _trustRounds[machineId] = (_trustRounds[machineId] ?? 0) + 1;
final wake = _trustWakes[machineId] = Completer<void>();
final short = _shortId(machineId);
bool current() =>
!_disposed &&
_authWorkCurrent(revision) &&
identical(_trustWakes[machineId], wake) &&
machineStates.containsKey(machineId);
final started = Stopwatch()..start();
try {
final registration = await log.ensureRegistered().timeout(
trustSettleRound,
onTimeout: () => DeviceLogRegistration.missing,
);
if (!current()) return;
if (registration == DeviceLogRegistration.frozen) {
appLog.info(
'link',
'$short refused ($reason): the device list is frozen',
);
// The machine's password form says so (deviceListNeedsReview), from the listing.
unawaited(_syncPendingDevices());
_trustRounds[machineId] = _trustSettleRounds;
_endTrustSettle(machineId);
final machine = machineStates[machineId]!
..connectionStatus = ConnectionStatus.disconnected;
_markNeedsLink(machine);
return;
}
if (registration == DeviceLogRegistration.registered) {
appLog.info(
'link',
'$short refused ($reason): this phone joined the device list',
);
}
final pinned = await _holdsMachineKey(machineId);
if (!current()) return;
if (reason == 'E2E_DENIED' || !pinned) {
final rest = trustSettleRound - started.elapsed;
final wait = reason == 'E2E_DENIED' && round == 1
? trustDeniedWait
: rest.isNegative
? Duration.zero
: rest;
await Future.any([Future<void>.delayed(wait), wake.future]);
if (!current()) return;
}
final now = pinned || await _holdsMachineKey(machineId);
if (!current()) return;
appLog.info(
'link',
'$short refused ($reason): ${now ? 'pinned' : 'no key yet'}, dialling again (round $round)',
);
_endTrustSettle(machineId);
_redial(machineId);
} finally {
// However the round ended, a machine no longer being settled can be settled again.
if (identical(_trustWakes[machineId], wake)) _endTrustSettle(machineId);
}
}
void _endTrustSettle(String machineId) {
_trustSettling.remove(machineId);
final wake = _trustWakes.remove(machineId);
if (wake != null && !wake.isCompleted) wake.complete();
}
/// [machineId] connected, or the account is left: its refusals start counting again.
void _forgetTrustSettle(String machineId) {
_trustRounds.remove(machineId);
_endTrustSettle(machineId);
}
void _forgetAllTrustSettles() {
for (final machineId in [..._trustRounds.keys, ..._trustSettling]) {
_forgetTrustSettle(machineId);
}
}
Future<bool> _holdsMachineKey(String machineId) async {
try {
return await viewer.keys.peer(machineId) != null;
} catch (_) {
return false;
}
}
/// Re-reads the log while a machine waits for its key to land ([MachineState.awaitingKey]), in
/// case its `device_keys_changed` reaches nobody, and turns the machine to its password form once
/// the wait is over. Null while no machine waits.
Timer? _keyWatch;
@visibleForTesting
Duration keyWatchEvery = const Duration(seconds: 10);
/// A machine just refused for want of trust ([_markNeedsLink]) whose key the log does not hold:
/// most likely one that signed in a moment ago and has not put its key in yet (its daemon could
/// not reach the backend: Intern 3 on a slow Wi-Fi, 2026-11-03). It reads as connecting, and the
/// log is read again until the key lands ([_redialNewlyTrusted] dials it then) or
/// [MachineState.keyAwaitLimit] runs out. A machine whose key the log holds refused this phone
/// for another reason: its password form, as before.
Future<void> _awaitMachineKey(MachineState machine) async {
final machineId = machine.machine.machineId;
if (_deviceLog == null || await _holdsMachineKey(machineId)) return;
if (_disposed || !machine.needsLink) return;
// Kept across refusals: the wait is from the first, not reset by every redial.
machine.keyAwaitedSince ??= DateTime.now();
_armKeyWatch();
notifyListeners();
}
/// Starts [_keyWatch] unless it runs already — or the app is in a pocket, where nobody is looking
/// ([handleAppPaused]): [handleAppResumed] starts it then ([_resumeBackgroundPolls]).
void _armKeyWatch() {
if (_pausedAt != null) return;
_keyWatch ??= Timer.periodic(keyWatchEvery, (_) => _watchAwaitedKeys());
}
void _watchAwaitedKeys() {
var waiting = false;
for (final state in machineStates.values) {
if (state.keyAwaitedSince == null) continue;
if (!state.needsLink) {
state.keyAwaitedSince = null;
continue;
}
if (state.awaitingKey) waiting = true;
}
if (waiting) {
unawaited(_deviceLog?.refresh());
} else {
_keyWatch?.cancel();
_keyWatch = null;
}
// Every tick: the one past the limit is what turns a machine from connecting to locked.
if (!_disposed) notifyListeners();
}
/// Dial [machineId] again from scratch: a refused connection is closed for good, so it is closed
/// and replaced.
void _redial(String machineId) {
final machine = machineStates[machineId];
if (machine == null) return;
onRedialForTest?.call(machineId);
unawaited(_pool?.closeMachine(machineId));
_connectMachine(machine);
}
/// The token a viewer's relay socket dials with.
Future<String> _socketToken(bool force, String? failedToken) =>
// Only a session that is gone for good may sign the person out — see
// [WsCredentialRevoked]. An outage fails the refresh too, and is retried.
viewer.auth
.accessToken(force: force, failedToken: failedToken)
.onError<DirectAuthException>(
(error, _) => throw WsCredentialRevoked(error.message),
test: (error) => error.signedOut,
);
/// [_socketToken], for a test: the pool that asks for it dials for real.
@visibleForTesting
Future<String> socketTokenForTest({
bool force = false,
String? failedToken,
}) => _socketToken(force, failedToken);
void _ensurePool() {
if (_pool != null) return;
_pool = WsPool(
wsBaseUrl: config.wsBaseUrl,
autonomousEnv: _autonomousEnv,
accessTokenProvider: _socketToken,
// Which release, and whether a debug or simulator build, goes in the socket's query. A test dials
// as itself, with a fake channel, and says neither.
clientBuild: kIsWeb || kUnderTest ? null : runningClientBuild,
relayCodecs: viewer.relayCodecs,
transportPlugins: viewer.transportPlugins,
onAuthFailure: _signedOutAtRuntime,
onLocalFailure: _onLocalFailure,
onEvent: _handleEvent,
onStatus: _onConnectionStatus,
);
}
/// What a machine's socket coming up, dropping or re-dialling does to the model.
void _onConnectionStatus(String machineId, ConnectionStatus nextStatus) {
final machine = machineStates[machineId];
if (machine == null) return;
// A refusal being settled against the device log ([_settleTrust]) is still connecting.
final settling =
nextStatus == ConnectionStatus.disconnected &&
_trustSettling.contains(machineId);
_measureConnection(
machineId,
settling ? ConnectionStatus.connecting : nextStatus,
ProductFlow.remoteConnect,
);
// A socket retries only once a dial ended without the machine's welcome (`WsConn`).
if (nextStatus == ConnectionStatus.reconnecting &&
!machine.needsLink &&
_nodeOnlineFromStatus(machine.machine.status) == true) {
launchMeasurement?.waiting(LaunchWait.connectFailed);
}
productConnections.status(
machineId,
connecting:
settling ||
nextStatus == ConnectionStatus.connecting ||
nextStatus == ConnectionStatus.reconnecting,
connected: nextStatus == ConnectionStatus.connected,
failed: machine.needsLink || machine.nodeOnline == false,
);
machine.connectionStatus = settling
? ConnectionStatus.connecting
: nextStatus;
if (kTypingTrace) {
typingEvent('link ${_shortId(machineId)} → ${nextStatus.name}');
}
if (nextStatus == ConnectionStatus.connected) {
// The first computer to answer ends the launch.
launchMeasurement?.ready();
// Back with a new sign-in, maybe: a Swarm read it refused may be asked of it again.
_swarmRefused.remove(machineId);
_refreshDeviceLogAfterReconnect();
machine.needsLink = false;
machine.keyAwaitedSince = null;
// Let in: a later refusal is a new story ([_redialOnceVouched], [_settleTrust]).
_vouchedRedials.remove(machineId);
_forgetTrustSettle(machineId);
// A relay socket reports `connected` only after the machine's welcome
// proved the link (`WsConn._markReady`), so a code held to pair this
// machine has nothing left to do. Kept, it would be spent the next time
// the machine locks — an unlink, say — in place of its password form.
if (pendingPairing?.machineId == machineId) pendingPairing = null;
// Route through _applyNodeStatus (not just `machine.nodeOnline = true`) for every machine,
// not only the local one — a successful select IS the machine being reachable again, and
// this is what lets a pending agent (captured below on disconnect) reattach automatically
// instead of leaving the user stuck on the empty "select a machine" placeholder.
unawaited(_applyNodeStatus(machine, true));
unawaited(_loadMachineData(machine, force: true));
_startAgentSyncTimer(machineId);
// A session came up: the moment to compare trust groups with this machine.
unawaited(_syncGroup(machineId));
} else if (nextStatus == ConnectionStatus.reconnecting ||
nextStatus == ConnectionStatus.disconnected) {
// A dial that failed is a turn spent: the next machine need not wait out its limit.
_endReleaseTurn(machineId, 'dial failed');
// Pushes sent while this socket is down reach nobody: the list is no longer current.
machine.agentsListedAt = null;
_stopAgentSyncTimer(machineId);
_clearMachineActivity(machine);
// Same reasoning as above, mirrored: capture pendingOfflineAgentId from the currently-open
// terminal (if any) so the connected branch above can reattach it, for every machine — this
// used to be local-only, which is why a remote machine's terminal never came back on its own
// after `harness start` on that machine, even though the guide screen promised it would.
//
// NOT while the machine is unlinked. NO_PEER_LINK is a lookup failing in a peer table
// before anything is dialled, so that close says nothing about whether the OTHER computer is
// up — our socket never reaches it. needsLink is set by onLocalFailure, which runs before
// this branch for 4404 (see WsConn._onDone).
//
// ⚠️ And the machine is not marked offline. The socket is the phone's own line to the
// relay — backgrounding the app drops it, and so does a tunnel — and losing it says nothing
// about the machine at the other end, which `node_status`, `/api/machines` and a timed-out
// request still report. Read as offline, every return to the app flashed "Offline" and
// threw the pager away. The streams on it are dead all the same: told so, and put back once
// the socket is.
if (!machine.needsLink && !settling) {
_markSessionsUnreachable(machine, 'Connection lost. Reconnecting…');
}
}
notifyListeners();
}
/// One tick of the agent-list safety net ([_syncAgentsIfChanged]), which the
/// app itself only reaches through its [agentSyncInterval] timer.
@visibleForTesting
Future<void> syncAgentsForTest(String machineId) async {
final machine = machineStates[machineId];
if (machine == null) return;
await _syncAgentsIfChanged(machine);
}
@visibleForTesting
void connectionStatusForTest(String machineId, ConnectionStatus status) =>
_onConnectionStatus(machineId, status);
/// The machine list is being fetched and there is nothing to show meanwhile.
///
/// Only the FIRST fetch sets it: a refresh over a list already on screen
/// keeps that list up (the rows are still true, just not from a moment ago)
/// and reports nothing. The rail reads this to tell "loading" from "no
/// machines", which an empty list alone cannot say.
bool machinesLoading = false;
/// The sign-in ([_authRevision]) whose machine list has been asked for at least once — answered
/// or failed. From then on the list is what the account HAS, empty included.
///
/// ⚠️ **"The first fetch", and not "a fetch over an empty list".** An account with no computer
/// yet has an empty list after every fetch, so every refresh used to raise [machinesLoading] —
/// and the phone's "Waiting for your computer…" page (`phone/welcome/connect_computer.dart`),
/// which refreshes every 5 seconds, was swapped for "Looking for your computers…" by the home
/// screen each time and built again from scratch: a flash every 5 seconds, a scan's result
/// dropped with the page that started it. Keyed to the sign-in, so the next one starts over.
int? _machinesFetchedFor;
/// The sign-in whose machine list has come back from the account — unlike [_machinesFetchedFor],
/// not set by a fetch that failed.
int? _machinesAnsweredFor;
/// Whether this sign-in's machine list has come back at least once, empty or not: from then on a
/// machine missing from [machines] is one the account does not have, not one still on its way.
///
/// ⚠️ An empty [machines] cannot say this alone — it is also what a list not asked for yet looks
/// like. The home screen read "empty" as "not answered" and held the agent of a previous run (a
/// record never cleared, `core/last_opened_agent.dart`) as still coming: an account with no
/// computer — a first sign-in on a phone used before, another account's agent remembered — sat
/// on "Connecting to your computer…" for the whole 30-second restore wait (`AgentHome`).
bool get machinesAnswered => _machinesAnsweredFor == _authRevision;
Future<void> refreshMachines() async {
final revision = _authRevision;
if (!_authWorkCurrent(revision)) return;
if (machines.isEmpty &&
!machinesLoading &&
_machinesFetchedFor != revision) {
machinesLoading = true;
notifyListeners();
}
try {
await _refreshMachines(revision);
if (_authWorkCurrent(revision) && _machinesAnsweredFor != revision) {
_machinesAnsweredFor = revision;
// The list's own notify came before this was set. The first fetch notifies again below
// (dropping [machinesLoading]); one that answers only after an earlier failure does not.
if (!machinesLoading) notifyListeners();
}
} catch (_) {
if (_authWorkCurrent(revision)) {
launchMeasurement?.waiting(LaunchWait.listFailed);
}
rethrow;
} finally {
if (_authWorkCurrent(revision)) _machinesFetchedFor = revision;
// Said out loud: the list's own notify fires before this, so a flag
// dropped silently here would leave the rail on its placeholders.
if (_authWorkCurrent(revision) && machinesLoading) {
machinesLoading = false;
notifyListeners();
}
}
}
/// Tell the device log who is signed in, once per sign-in, synchronously (see
/// [ViewerDeviceLog.beginSignIn]); [_registerDeviceLog] then finds it done.
void _beginDeviceLogSignIn(int revision) {
if (_deviceLogBegun == revision) return;
_deviceLogBegun = revision;
_deviceLog?.beginSignIn(fresh: viewer.auth.consumeFreshSignIn());
}
/// The account's device key log: this phone's key joins it (an existing sign-in too, from
/// before the log existed), and every machine it names is reached with no password. Once per
/// sign-in, the moment the app is authenticated ([_finishBootstrapSignedIn]) — before the machine
/// list and the profile, and not waiting for either. Which account the log belongs to is a local
/// fact the log keeps itself ([_beginDeviceLogSignIn]), never something the backend says, so
/// there is nothing to read first.
void _registerDeviceLog(int revision) {
if (!_authWorkCurrent(revision) ||
status != AppStatus.authenticated ||
_deviceLogRegistered == revision) {
return;
}
_deviceLogRegistered = revision;
final log = _deviceLog;
if (log == null) return;
// Normally already begun at the top of [_finishBootstrapSignedIn]; a no-op then.
_beginDeviceLogSignIn(revision);
// Through [_registerDevice], which holds [deviceTrustSettling] while it runs and stamps the
// moment a machine the log vouches for may still not have read this key ([_redialOnceVouched]).
unawaited(_registerDevice(log, revision));
}
Future<void> _refreshMachines(int revision) async {
// No machine is "this computer" to a viewer, which has no local CLI: every one — even the one
// it runs on — is reached through the relay.
final list = await _fetchMachines();
if (!_authWorkCurrent(revision)) return;
machines = list
.where((machine) => machine.authMode == MachineAuthMode.remote)
.toList();
// A wait for a computer that an earlier launch left open, with the computer now here.
if (machines.isNotEmpty) unawaited(onboardingMeasurement.computersSeen());
// What this launch's wait for a computer is up against, as the list says.
if (machines.isEmpty) {
launchMeasurement?.waiting(LaunchWait.noComputer);
} else if (machines.every(
(machine) => _nodeOnlineFromStatus(machine.status) == false,
)) {
launchMeasurement?.waiting(LaunchWait.offline);
}
final visible = machines.map((machine) => machine.machineId).toSet();
// A code scanned for a machine this account does not have can never be
// spent: the pairing screen waits for that machine to show up locked.
if (pendingPairing case final pending?
when !visible.contains(pending.machineId)) {
pendingPairing = null;
}
for (final entry in machineStates.entries) {
if (!visible.contains(entry.key)) {
_clearMachineActivity(entry.value);
_stopOfflineRetry(entry.key);
_stopAgentSyncTimer(entry.key);
// ⚠️ The SOCKET goes too, not just the bookkeeping above. Dropping the
// state alone left the pool holding a live connection to a machine
// nothing referred to any more — it kept dialling and reconnecting for
// the rest of the session, with `_onConnectionStatus` discarding every
// event because the state it looks up no longer exists.
//
// Reachable before [_warmStartMachines] only when a machine left the
// account between two refreshes; reachable on every launch now, because
// the warm start dials from a cache that can name a machine this fetch
// does not return. Same fix either way.
unawaited(_pool?.closeMachine(entry.key));
}
}
machineStates.removeWhere((id, _) => !visible.contains(id));
for (final machine in machines) {
final isNew = !machineStates.containsKey(machine.machineId);
final state = machineStates.update(
machine.machineId,
(state) => state..machine = machine,
ifAbsent: () => MachineState(machine),
);
final reportedOnline = _nodeOnlineFromStatus(machine.status);
if (reportedOnline != null &&
(state.nodeOnline == null || state.nodeOnline != reportedOnline)) {
unawaited(_applyNodeStatus(state, reportedOnline));
}
// The launch's machine may already be dialled with no state to report to — when this fetch
// beats the cache parse it was dialled ahead of. See [_adoptConnection].
if (isNew) _adoptConnection(state);
}
// A machine come or gone changes how often the deaf poll reads — one asleep or several.
_retuneDeafPoll();
_autoConnectAndLoadMachines();
// The list that just landed is what the NEXT launch starts from. Never
// awaited: it is a hint for a future run and must not add a disk write to
// the one a person is waiting on right now.
final cache = _machineCache;
if (cache != null) _writeMachineCache(cache);
notifyListeners();
}
/// [cache] written out with this run's machines, and the launch record for the machine the next
/// launch reopens ([MachineCache.save]). Never awaited: it is for a future launch, and must not
/// add a disk write to anything a person is waiting on now.
void _writeMachineCache(MachineCache cache) {
unawaited(
cache.save(
machines,
isOnline: (machine) => _nodeOnlineFromStatus(machine.status) == true,
launchMachineId: lastOpenedAgent.current?.machineId,
),
);
}
// The daemon reports `connected` only once its own backend socket is open, but
// `/api/machines` is a separate REST leg (fresh token refresh + fetch) that can still stall
// briefly right after that — a bounded retry absorbs that transient window without falling
// back to the 30s Dio timeout. Never retries an `ApiException` (a real HTTP error response);
// only a `DioException` (timeout/connection failure) is worth a second try.
// Capped at 2 attempts, not 3: `receiveTimeout` is 30s, so every retried attempt can cost
// another 30s on a genuine failure — one retry absorbs the transient window above without
// tripling how long a truly broken backend takes to surface its error.
Future<List<Machine>> _fetchMachines() => withRetry(
api.machines,
maxAttempts: 2,
initialDelay: const Duration(milliseconds: 500),
isRetryable: (error) => error is DioException,
);
void _startOfflineRetry(MachineState machine) {
final machineId = machine.machine.machineId;
if (machine.nodeOnline != false || machine.pendingOfflineAgentId == null) {
_stopOfflineRetry(machineId);
return;
}
if (_offlineRetryTimers.containsKey(machineId)) return;
// In a pocket, nothing polls: [handleAppResumed] starts it again ([_resumeBackgroundPolls]).
if (_pausedAt != null) return;
_offlineRetryTimers[machineId] = Timer.periodic(
offlineRetryInterval,
(_) => unawaited(_pollOfflineMachine(machineId)),
);
}
void _stopOfflineRetry(String machineId) {
_offlineRetryTimers.remove(machineId)?.cancel();
}
void _stopAllOfflineRetries() {
for (final timer in _offlineRetryTimers.values) {
timer.cancel();
}
_offlineRetryTimers.clear();
_offlinePollsInFlight.clear();
}
void _startAgentSyncTimer(String machineId) {
if (_agentSyncTimers.containsKey(machineId)) return;
// A machine that connects while the app is in a pocket has its first list read all the same
// ([_onConnectionStatus]); its safety net waits for the app to come back ([_resumeBackgroundPolls]).
if (_pausedAt != null) return;
_agentSyncTimers[machineId] = Timer.periodic(
agentSyncInterval,
(_) => _agentSyncTick(machineId, DateTime.now()),
);
}
/// How recently a keystroke must have gone to a machine for its agent-list tick to wait.
static const _typingQuiet = Duration(seconds: 8);
/// The longest a tick waits on somebody typing before it goes anyway: a safety net held back
/// for as long as somebody keeps typing would never run at all.
static const _typingWaitLimit = Duration(seconds: 60);
/// How far short of a whole [agentSyncInterval] a list may have been read and still let a tick
/// run: a tick's own list is read a second or two after the tick, so the next one finds it a
/// little under an interval old, and that is the clock working, not a list read lately.
static const _listedLatelySlack = Duration(seconds: 15);
/// Per machine, a tick waiting — for the typing on it to stop, or for its list to come due —
/// see [_agentSyncTick].
final Map<String, Timer> _agentSyncHolds = {};
/// Whether somebody is typing into a terminal on [machineId]: a keystroke sent to it in the last
/// [_typingQuiet].
bool _typingOn(String machineId, DateTime now) =>
panesFor(machineId).any((pane) {
final at = pane.session?.lastInputAt;
return at != null && now.difference(at) < _typingQuiet;
});
/// One tick of the agent-list safety net, first due at [dueSince].
///
/// ⚠️ **Held while somebody types on that machine.** The machine answers `agents_list` on the
/// same queue it takes keystrokes from, and the answer takes it a second or two (see
/// [agentSyncInterval]) — a tick landing mid-sentence froze the echo for that long. So a tick
/// that finds a keystroke gone in the last [_typingQuiet] waits that long and looks again, up to
/// [_typingWaitLimit] from when it was due; the periodic ticks meanwhile leave it to the one
/// waiting.
///
/// ⚠️ **Due one interval after the list was last read, not on the timer's own clock.** Find
/// opening ([reachAllMachines]) and a push that falls back to a reload read the whole list as
/// well, and a tick landing a minute later asked the machine for the same answer again — a second
/// or two of its queue, keystrokes included, for nothing. A list read over this socket within the
/// interval did the tick's job, liveness included (it was answered), so the tick waits until that
/// list comes due and looks again. The gap between two answered lists stays one interval, which
/// is what [agentSyncStaleTicks] counts on.
void _agentSyncTick(String machineId, DateTime dueSince) {
final machine = machineStates[machineId];
if (machine == null) {
_stopAgentSyncTimer(machineId);
return;
}
if (_agentSyncHolds.containsKey(machineId)) return;
final now = DateTime.now();
final listedAt = machine.agentsListedAt;
final sinceListed = listedAt == null ? null : now.difference(listedAt);
// A clock set back puts the list in the future: no telling when it was read, so the tick runs.
if (sinceListed != null &&
!sinceListed.isNegative &&
sinceListed < agentSyncInterval - _listedLatelySlack) {
if (kTypingTrace) {
typingEvent(
'list tick ${_shortId(machineId)}: read ${sinceListed.inSeconds}s ago,'
' waits ${(agentSyncInterval - sinceListed).inSeconds}s',
);
}
_agentSyncHolds[machineId] = Timer(agentSyncInterval - sinceListed, () {
_agentSyncHolds.remove(machineId);
if (_disposed || !_agentSyncTimers.containsKey(machineId)) return;
_agentSyncTick(machineId, DateTime.now());
});
return;
}
if (_typingOn(machineId, now) &&
now.difference(dueSince) < _typingWaitLimit) {
_agentSyncHolds[machineId] = Timer(_typingQuiet, () {
_agentSyncHolds.remove(machineId);
if (_disposed || !_agentSyncTimers.containsKey(machineId)) return;
_agentSyncTick(machineId, dueSince);
});
return;
}
unawaited(_syncAgentsIfChanged(machine));
}
void _stopAgentSyncTimer(String machineId) {
_agentSyncTimers.remove(machineId)?.cancel();
_agentSyncHolds.remove(machineId)?.cancel();
_agentSyncTimeouts.remove(machineId);
}
void _stopAllAgentSyncTimers() {
for (final timer in _agentSyncTimers.values) {
timer.cancel();
}
_agentSyncTimers.clear();
for (final hold in _agentSyncHolds.values) {
hold.cancel();
}
_agentSyncHolds.clear();
_agentSyncTimeouts.clear();
}
/// How many [agentSyncInterval] ticks in a row may time out before the machine
/// is treated as gone and redialled ([_recoverStaleSession]).
///
/// Two, not one: a single missed tick is a busy machine or a slow relay, and a
/// forced redial costs every terminal on it a resync. Two in a row is minutes
/// of a machine not answering a request it always answers, which nothing
/// healthy does.
@visibleForTesting
static const agentSyncStaleTicks = 2;
/// Consecutive timed-out [_syncAgentsIfChanged] ticks, per machine. Cleared by
/// any answer, by any other failure, and by the timer stopping.
final Map<String, int> _agentSyncTimeouts = {};
/// Silent safety-net reconciliation, ticked every [agentSyncInterval] while a machine is connected.
/// Only writes/notifies if the fetched list actually differs from what's already shown — a steady
/// state where push events (agent_synced et al.) have kept everything in sync produces zero visible
/// effect. Deliberately does not touch agentLoadStatus/agentsLoadError/notifyListeners on failure:
/// a real connectivity problem is already surfaced by the push path, and a quiet background tick
/// should not fight it.
///
/// ⚠️ **Except a timeout, which this is the only thing left watching for.** A
/// stale relay session (see [_recoverStaleSession]) leaves the transport
/// "connected", the machine `nodeOnline`, its list `loaded` — so no screen is
/// wrong, no push arrives to correct it, and nothing calls
/// [_performMachineDataLoad], which is where the offline detection this used
/// to defer to actually lives. Swallowed here, that state was permanent:
/// measured at 16 minutes and still going, a phone showing a machine's agent
/// list from before its Harness restarted, with every agent made since
/// invisible — and, with the list feeding `deskGroups`, a desk tab whose
/// harnesses had all silently vanished off the phone.
///
/// ⚠️ **One at a time per machine.** A phone back from minutes in the background finds every
/// timer due at once — a tick held for a fresh list ([_agentSyncTick]) and the periodic one
/// beside it — and both asked the machine for the whole list in the same instant (measured,
/// 2026-10-08).
Future<void> _syncAgentsIfChanged(MachineState machine) async {
final machineId = machine.machine.machineId;
if (!_agentSyncInFlight.add(machineId)) return;
try {
await _syncAgentsOnce(machine);
} finally {
_agentSyncInFlight.remove(machineId);
}
}
/// Per machine, a [_syncAgentsIfChanged] still waiting on its answer.
final Set<String> _agentSyncInFlight = {};
Future<void> _syncAgentsOnce(MachineState machine) async {
if (machine.connectionStatus != ConnectionStatus.connected) return;
if (machine.agentsLoadInFlight != null) {
return; // a real (foreground) load already owns this tick
}
final machineId = machine.machine.machineId;
final revision = _authRevision;
final connection = _conn(machineId);
final tickAsked = kTypingTrace ? (Stopwatch()..start()) : null;
if (kTypingTrace) typingEvent('list tick ${_shortId(machineId)}: ask');
try {
final response = await connection.request(
'agents_list',
payload: kAgentsListPayload,
timeout: const Duration(seconds: 10),
);
if (tickAsked != null) {
typingEvent(
'list tick ${_shortId(machineId)}: answered'
' in ${tickAsked.elapsedMilliseconds}ms',
);
}
_agentSyncTimeouts.remove(machineId);
if (!_machineWorkCurrent(machine, revision)) return;
// ⚠️ A terminal switched off by a negotiation that never got an answer stayed off until
// the next reconnect: the machine answered this, so the link is up — ask again.
if (machine.terminalCapabilityUnanswered) {
unawaited(_loadTerminalCapabilities(machine, connection, revision));
}
final handling = kTypingTrace ? (Stopwatch()..start()) : null;
final rawAgents = response['agents'] as List<dynamic>? ?? const [];
final agents = rawAgents
.map((item) => Agent.fromJson(item as Map<String, dynamic>))
.toList();
// Answered over this socket, changed or not: the list is current as of now. Only once the
// machine's list has been confirmed — a tick never stands in for that first one.
if (machine.agentLoadStatus == AgentLoadStatus.loaded &&
!machine.agentsFromCache) {
machine.agentsListedAt = DateTime.now();
}
if (agentsEqual(machine.agents, agents)) {
if (handling != null) {
typingEvent(
'agents sync: ${agents.length} unchanged · parsed and compared on this'
' thread in ${handling.elapsedMilliseconds}ms',
);
}
return;
}
// The machine's own list for the next launch too: what changed reached this phone without a
// push (one sent while the socket was away). A harness added or gone goes out soon, the rest
// with the app leaving the screen — see [_saveMachineCacheSoon].
final cache = _machineCache;
if (cache != null) {
final had = {for (final agent in machine.agents) agent.id};
cache.rememberAgents(machineId, [
for (final item in rawAgents)
if (item is Map<String, dynamic>) item,
]);
if (agents.length != had.length ||
!agents.every((agent) => had.contains(agent.id))) {
_saveMachineCacheSoon();
}
}
_replaceAgents(machine, agents);
notifyListeners();
if (handling != null) {
typingEvent(
'agents sync: ${agents.length} changed · parsed, replaced and redrawn on'
' this thread in ${handling.elapsedMilliseconds}ms',
);
}
} on WsRequestTimeout {
if (!_machineWorkCurrent(machine, revision)) return;
final missed = (_agentSyncTimeouts[machineId] ?? 0) + 1;
_agentSyncTimeouts[machineId] = missed;
if (missed < agentSyncStaleTicks) return;
_agentSyncTimeouts.remove(machineId);
appLog.warn(
'ws',
'agents_list timed out $missed× on $machineId — redialling',
);
_recoverStaleSession(machine, connection);
} catch (_) {
// Silent by design — see doc comment above. A socket that dropped
// mid-request is already redialling, so the count starts over.
_agentSyncTimeouts.remove(machineId);
}
}
/// Order-insensitive value equality for [Agent] lists — [Agent] has no operator== override, and a
/// backend that returns the same agents in a different order must not register as "changed".
///
/// ⚠️ Every field of [Agent] that the UI reads belongs here. This list is hand-maintained, and the
/// cost of forgetting one is silent: the poll fetches the truth, compares it, decides nothing
/// happened, and throws it away — so the field stays frozen at whatever it was for as long as the
/// app runs. Add the field here in the same commit you add it to [Agent].
@visibleForTesting
static bool agentsEqual(List<Agent> a, List<Agent> b) {
if (a.length != b.length) return false;
final byId = {for (final agent in a) agent.id: agent};
for (final agent in b) {
final prev = byId[agent.id];
if (prev == null || !agentEqual(prev, agent)) return false;
}
return true;
}
/// One agent of [agentsEqual]: the same agent, with nothing the UI reads changed. The same
/// hand-kept list, and the same rule — a field added to [Agent] is added here.
@visibleForTesting
static bool agentEqual(Agent prev, Agent agent) =>
!(prev.id != agent.id ||
prev.name != agent.name ||
// What search and the Recent list read: a turn that ends moves
// `updatedAt` and often `title`, and a sync that ignored them left
// the phone sorting and searching by the list it had an hour ago.
prev.title != agent.title ||
prev.updatedAt != agent.updatedAt ||
prev.lastOpenedAt != agent.lastOpenedAt ||
prev.gridModel != agent.gridModel ||
// The model sheet's sentence under a Local model.
prev.gridWebSearch != agent.gridWebSearch ||
prev.selectedModel != agent.selectedModel ||
// What a tab's name votes with — see `identityEngine`.
prev.dsh != agent.dsh ||
prev.dshName != agent.dshName ||
prev.sessionId != agent.sessionId ||
prev.engine != agent.engine ||
prev.engineDisplayName != agent.engineDisplayName ||
prev.engineIconHint != agent.engineIconHint ||
prev.codexHome != agent.codexHome ||
prev.parentAgentId != agent.parentAgentId ||
prev.project != agent.project ||
prev.gitContext != agent.gitContext ||
prev.launchState != agent.launchState ||
prev.launchError != agent.launchError ||
prev.launchDetail != agent.launchDetail ||
prev.status != agent.status ||
prev.terminalAvailable != agent.terminalAvailable ||
prev.terminalUnavailableReason != agent.terminalUnavailableReason ||
// A row's stats line (`sheet_agent_lines.dart`) — the desktop
// compares these three too.
prev.tokensUsed != agent.tokensUsed ||
prev.tokensUpdatedAt != agent.tokensUpdatedAt ||
prev.outputStats != agent.outputStats ||
// Whether a stopped row can be opened at all ([Agent.canPauseAndResume]).
prev.resumeMode != agent.resumeMode ||
// What Change agent closes the harness by, and the mode it carries over.
prev.createdAt != agent.createdAt ||
prev.closeSupported != agent.closeSupported ||
prev.permissionMode != agent.permissionMode);
/// Public retry hook used by the offline join guide's "Retry now" action.
Future<void> retryOfflineMachine(String machineId) =>
_pollOfflineMachine(machineId);
/// Links [machineId] by its remote password — the exchange `harness link connect` runs on a
/// desktop, run here by [peerLinks] (`viewer/password_link.dart`) — for a machine the relay
/// reported `NO_PEER_LINK` for, then reconnects it. Returns null on success, or an error
/// message to show inline.
Future<String?> connectWithPassword(
String machineId,
String password, {
void Function(String stage)? onProgress,
}) async {
if (password.isEmpty) return 'Enter the remote password first';
final finish = productMeasurement.begin(ProductFlow.computerLink);
try {
final result = await peerLinks.connect(
machineId,
password,
onProgress: onProgress,
displayName: machineStates[machineId]?.machine.displayName,
label: phoneClientDescriptor().name,
);
finish(result.error == null ? ProductOutcome.ok : ProductOutcome.failed);
if (result.error != null) return result.error;
final targetId = result.linkedMachineId ?? machineId;
final state = machineStates[targetId];
// Already in by another way meanwhile — see [_keepsOpenConnection]: nothing to redial.
if (state != null && !_keepsOpenConnection(state)) {
state.needsLink = false;
state.agentLoadStatus = AgentLoadStatus.idle;
notifyListeners();
// The old WsConn closed itself permanently on NO_PEER_LINK — connFor() would otherwise see a
// matching endpointKey and hand back that dead connection instead of dialing a fresh one.
await _pool?.closeMachine(targetId);
_connectMachine(state);
}
// One password, the whole group: this machine learns the phone's other machines, and they it.
unawaited(_syncGroup(targetId, spread: true));
return null;
} catch (_) {
finish(ProductOutcome.failed);
rethrow;
} finally {
finish(ProductOutcome.unknown);
}
}
// -- the account's devices: the device key log (viewer/device_log_sync.dart) --------------------
ViewerDeviceLog? _deviceLog;
int? _deviceLogRegistered;
int? _deviceLogBegun;
/// What the device log announced (a new device, a removal) while the app was still starting up:
/// the OS notice and the banner wait for [_flushDeviceNotices], so a read that lands before the
/// app is `authenticated` is not lost. Each carries the sign-in it belongs to; only a signed-out
/// app drops them.
final List<({int revision, void Function() run})> _startupDeviceNotices = [];
/// Run [notice] now when the app is signed in; park it while it is still starting up; drop it
/// when signed out (an in-flight read of the account that just left must not raise anything).
void _whenSignedIn(void Function() notice) {
if (_disposed || status == AppStatus.unauthenticated) return;
if (status == AppStatus.bootstrapping) {
_startupDeviceNotices.add((revision: _authRevision, run: notice));
return;
}
notice();
}
void _flushDeviceNotices(int revision) {
final parked = [..._startupDeviceNotices];
_startupDeviceNotices.clear();
for (final p in parked) {
// Another sign-in began meanwhile: these are the previous account's.
if (p.revision != revision || !_authWorkCurrent(revision)) continue;
p.run();
}
// The replay put keys on the banner as they were when they were read; the log may have moved
// on since (dismissed, removed): the banner is what the log holds now.
if (parked.isNotEmpty) unawaited(_syncPendingDevices());
}
/// Devices that joined the account and this phone had never trusted, not yet dismissed. Rebuilt
/// from the log's persisted `pending` ([_syncPendingDevices]), so a restart does not lose them.
final List<DevLogMember> newDevices = [];
/// Computers this phone was waiting for when they joined the account — the onboarding's "On your
/// computer, go to" — and so already named on its screen ("MacBook Pro is ready."). The device
/// log's "New device" for one of them is what the person just did: confirmed as theirs, with no
/// banner and no notice ([welcomeMachine]). Cleared with the session.
final Set<String> welcomedMachines = {};
/// [machineId] joined while this phone waited for it: see [welcomedMachines]. A "New device" for
/// it the log already announced goes too.
void welcomeMachine(String machineId) {
if (!welcomedMachines.add(machineId)) return;
for (final device in [...newDevices]) {
if (device.kind == 'machine' && device.machineId == machineId) {
dismissNewDevice(device.pub);
}
}
}
/// Which of [newDevices] a fork suspended (not trusted here until the list is reviewed), as of the
/// last read of the log. "Mine" on the banner cannot lift that, so for these it opens the device's
/// page, which says why.
final Set<String> _suspendedNew = {};
bool newDeviceSuspended(String pub) => _suspendedNew.contains(pub);
/// Devices taken out of the account by another device, until dismissed. Not persisted: the device
/// history is the durable record.
final List<DeviceRemovalNotice> deviceRemovals = [];
/// Devices that joined and left the account before anyone here looked, until "Got it" (read from
/// the log's persisted `departed`, so a restart does not lose them), oldest first.
final List<DeviceLogDeparted> departedDevices = [];
/// The key that removed [d] is itself a device nobody looked at (still new, or itself gone before
/// anyone looked) — the alarming case. A device that signed itself out is never red.
bool departedRed(DeviceLogDeparted d) =>
!d.selfRemoved &&
d.removedBy.isNotEmpty &&
(newDevices.any((n) => n.pub == d.removedBy) ||
departedDevices.any((o) => o.pub == d.removedBy));
/// "Got it" on a device that left before it was looked at: saved, so the banner does not come back.
void dismissDeparted(String pub) {
_pendingSyncGen++;
departedDevices.removeWhere((d) => d.pub == pub);
// A "signed out" notice for the same key is the same ghost: the banner leaves it out while the
// departed mark is up, so this "Got it" is its dismissal too (it must not surface afterwards).
deviceRemovals.removeWhere((r) => r.pub == pub && r.selfRemoved);
unawaited(_dismissInLog(pubs: [pub]));
devicesRevision++;
notifyListeners();
}
/// Bumped whenever the account's devices may have changed; the Devices page re-reads on it.
int devicesRevision = 0;
ViewerDeviceLog? get deviceLog => _deviceLog;
/// This phone's copy of the device log is frozen, so it pins no machine from it until someone
/// reviews the list (Your devices). A machine asking for its password says so.
bool get deviceListNeedsReview => _deviceListFrozen;
bool _deviceListFrozen = false;
@visibleForTesting
set deviceListNeedsReviewForTest(bool frozen) {
_deviceListFrozen = frozen;
notifyListeners();
}
/// The backend refused this phone a place on the account: it has too many devices (`TOO_MANY`).
/// A machine asking for its password says so, beside [deviceListNeedsReview].
bool get deviceListTooMany => _deviceListTooMany;
bool _deviceListTooMany = false;
@visibleForTesting
set deviceListTooManyForTest(bool tooMany) {
_deviceListTooMany = tooMany;
notifyListeners();
}
/// Devices this phone dismissed whose write to the log failed: the banner must not bring them back
/// on the next read of `pending`. Gone with the sign-in, or when the key is announced afresh.
final Set<String> _failedDismissals = {};
/// [confirm]: "It's mine" for the one device named — the account's other devices are told too, and
/// stop showing it as new.
Future<void> _dismissInLog({
String? pub,
List<String>? pubs,
bool confirm = false,
}) async {
final log = _deviceLog;
if (log == null) return;
try {
await log.dismiss(pub: pub, pubs: pubs, confirm: confirm);
} catch (error) {
debugPrint('devices: could not save the dismissal: $error');
_failedDismissals.addAll([...?pubs, ?pub]);
}
}
// -- where to push to this phone (notify/push_tokens.dart) ---------------------------------------
/// Null in a test and in the sample, which never reach the OS, and on the web, which has no push.
PushTokens? _push;
AppLifecycleListener? _pushLifecycle;
void _initPush(PushTokens? given, PaneLayoutStore? paneLayoutStore) {
final push = _push =
given ??
(kIsWeb || kUnderTest || paneLayoutStore == null
? null
: PushTokens(
channel: PushChannel(),
storage: paneLayoutStore.storage,
allowed: () => noticesEnabled(agentNotices.system),
));
if (push == null) return;
// Before the shell is up, so the push that launched the app is waiting for it as a tapped
// notice is.
push.channel.listen(
onOpened: (data) => openPushed(data, agentNotices.system),
onChanged: _syncPush,
);
if (agentNotices.system case final LocalSystemNotices notices) {
notices.onAllowed = _syncPush;
// Android: the channels a push is drawn on, before the first can arrive (task #3248).
unawaited(notices.preparePush());
}
// Back from the phone's Settings, where notices may have been turned on or off.
_pushLifecycle = AppLifecycleListener(onResume: _syncPush);
}
/// The keys of this app's pushes still in the notification centre (notify/push_channel.dart):
/// none where there is no push.
Future<Set<String>> pushesShown() async =>
await _push?.channel.shown() ?? const {};
/// Tells the backend where to push to this phone while signed in: once the account is known, when
/// notices are allowed, when the OS hands over a new address, and back in the app.
void _syncPush() {
final push = _push;
final account = swarmAccountId;
if (push == null || _disposed || _signingOut != null || account == null) {
return;
}
final revision = _authRevision;
unawaited(
push.sync(
account: account,
api: api,
current: () =>
_authWorkCurrent(revision) &&
_signingOut == null &&
status == AppStatus.authenticated,
),
);
}
void _initDeviceLog() {
final log = _deviceLog = ViewerDeviceLog(
keys: viewer.keys,
// This phone's own key rides each read, so the backend counts it as used (not as abandoned).
fetch: (since) async => api.deviceKeys(
since,
self: await viewer.keys.identity().then<String?>(
(i) => b64e(i.pub),
onError: (Object _) => null,
),
),
append: (entry) => api.appendDeviceKey(entry),
// "It's mine", once for the account: read what other devices confirmed, share what this one does.
fetchAcks: (since) => api.deviceAcks(since),
postAck: (ack) => api.postDeviceAck(ack),
label: () => phoneClientDescriptor().name,
// The log saves "announced" before it calls back, so a call that found the app still starting
// up and was dropped would never be made again: [_whenSignedIn] parks it instead. Only a
// signed-out app (an in-flight read of the account that just left) drops one.
onAnnounce: (m) => _whenSignedIn(() {
_failedDismissals.remove(m.pub);
if (newDevices.any((d) => d.pub == m.pub)) return;
// The computer the onboarding was waiting for: the person is looking at its name already.
if (m.kind == 'machine' && welcomedMachines.contains(m.machineId)) {
_pendingSyncGen++;
unawaited(_dismissInLog(pubs: [m.pub], confirm: true));
return;
}
newDevices.add(m);
devicesRevision++;
final name = m.label.isEmpty ? 'A device' : m.label;
unawaited(
agentNotices.system.showAccountNotice(
key: m.pub,
title: 'New device on your account',
body:
'$name ${m.kind == 'machine' ? 'joined' : 'signed in to'} your account and can reach '
'your machines. Not yours? Remove it in Settings ▸ Your devices.',
),
);
if (!_disposed) notifyListeners();
}),
onRemoved: (n) => _whenSignedIn(() => announceDeviceRemoval(n)),
onSignedOut: () async {
// Sign out first: it takes this phone's key out of the log, which needs the key it is about.
// After a Sign out by hand this is that sign-out reading its own removal back — nothing to
// tell anyone ([_leftByHand]). Otherwise another device removed this phone, and the welcome
// screen it lands on says so.
await _endSession(reason: _leftByHand ? null : _signedOutRemoved);
await viewer.keys.forgetIdentity();
},
onChanged: () {
devicesRevision++;
unawaited(_syncPendingDevices());
unawaited(_redialNewlyTrusted());
if (!_disposed) notifyListeners();
},
);
final links = peerLinks;
if (links is DirectLink) links.deviceLog = log;
}
/// True while trust between this phone and the account's machines is still being settled by the
/// device key log: this phone reading the log and putting its own key into it
/// ([ViewerDeviceLog.register]), or a machine the log vouches for being dialled again because it
/// had not caught up with this phone's key yet ([_redialOnceVouched]).
///
/// ⚠️ **A machine is "locked" the moment a fresh phone dials it, and that is not yet an answer.**
/// With nothing pinned, the relay codec refuses the dial on the spot (`NO_PEER_LINK`, 16ms in), long
/// before the log has been read and verified — seconds on a phone; and once it is, the machine
/// itself still has to read this phone's new key before it stops answering `e2e_denied`. The home
/// screen fell through to the machines list, "locked · scan its code", in between. While this is
/// set it waits on a locked machine instead (`phone/agent_home.dart` `_loadingMessage`); once it
/// clears, a machine still locked really wants its password.
///
/// ⚠️ **Only the first [_vouchedRedialsHeld] redials count, not all of them.** Every step of
/// [_vouchedRedialDelays] used to: a machine that never read this phone's key held a fresh sign-in
/// on "Connecting to your computer…" for the whole schedule — 36s, measured — before its "scan its
/// code" came up, the one thing that could let the phone in.
bool get deviceTrustSettling =>
_registeringDevice ||
_awaitingVouched.any(
(id) => (_vouchedRedials[id] ?? 0) <= _vouchedRedialsHeld,
);
bool _registeringDevice = false;
/// When this phone's key last went into the log, in this sign-in — see [_vouchedRedialWindow].
DateTime? _deviceRegisteredAt;
/// Machines waiting out a [_vouchedRedialDelays] step, and how many each has been through (the
/// step under way included).
final Set<String> _awaitingVouched = {};
final Map<String, int> _vouchedRedials = {};
/// How many of [_vouchedRedialDelays] hold the screen ([deviceTrustSettling]): a machine that
/// reads the log when it hears `device_keys_changed` has read this phone's key by then. The rest
/// are dialled behind the machine shown locked, and one that lets the phone in opens it by itself.
static const _vouchedRedialsHeld = 2;
/// [_deviceTrustSettleCap]: a log that never answers still lets the screen move on.
static const _deviceTrustSettleCap = Duration(seconds: 20);
/// How long after this phone's key went into the log a machine the log vouches for may still not
/// have read it — its CLI hears `device_keys_changed` and reads the log itself, a few seconds.
static const _vouchedRedialWindow = Duration(minutes: 1);
static const _vouchedRedialDelays = [
Duration(milliseconds: 1500),
Duration(seconds: 3),
Duration(seconds: 5),
Duration(seconds: 8),
Duration(seconds: 12),
];
Future<void> _registerDevice(ViewerDeviceLog log, int revision) async {
_registeringDevice = true;
notifyListeners();
try {
// Whether the sign-in is fresh was told the log already ([_beginDeviceLogSignIn]).
await log
.register()
// Then what is still pending from before (a restart) comes back as the banner.
.whenComplete(_syncPendingDevices)
.timeout(_deviceTrustSettleCap);
} catch (_) {
// Timed out: the register goes on by itself, and a machine it vouches for is still redialled.
} finally {
if (_authWorkCurrent(revision)) {
_registeringDevice = false;
_deviceRegisteredAt = DateTime.now();
notifyListeners();
}
}
}
/// A machine refused this phone ([_onLocalFailure]) although the device key log vouches for it —
/// this phone pins it — while this phone's own key is new to the log: the machine has most likely
/// just not read that key yet, so it is dialled again, a few times, a little later each time.
///
/// ⚠️ **Nothing else would ever dial it again.** [_redialNewlyTrusted] runs when the log CHANGES,
/// and from this phone's side it already has: the pin landed, the dial went out, and THEN the
/// phone's key went in — so the machine, still behind, answered `e2e_denied` to a dial nobody
/// retried, and a fresh sign-in sat on "locked" over a machine that would have let it in seconds
/// later. Outside [_vouchedRedialWindow] a refusal stands: that is trust revoked, not trust late.
///
/// Past [_vouchedRedialsHeld] the machine stays locked through the redial: on screen it is the
/// machine to pair by its code, and a dial that gets in unlocks it ([_onConnectionStatus]).
Future<void> _redialOnceVouched(String machineId) async {
final revision = _authRevision;
final attempt = _vouchedRedials[machineId] ?? 0;
if (attempt >= _vouchedRedialDelays.length) return;
final held = attempt < _vouchedRedialsHeld;
final registeredAt = _deviceRegisteredAt;
final keyIsNew =
_registeringDevice ||
(registeredAt != null &&
DateTime.now().difference(registeredAt) < _vouchedRedialWindow);
if (!keyIsNew) return;
if (await viewer.keys.peer(machineId) == null) return;
if (!_authWorkCurrent(revision) || _awaitingVouched.contains(machineId)) {
return;
}
_vouchedRedials[machineId] = attempt + 1;
_awaitingVouched.add(machineId);
notifyListeners();
await Future<void>.delayed(_vouchedRedialDelays[attempt]);
// A sign-out meanwhile emptied the set and moved the revision on: nothing here is ours.
if (!_authWorkCurrent(revision)) return;
_awaitingVouched.remove(machineId);
final state = machineStates[machineId];
// Still locked: a password or a code that linked it meanwhile already redialled it.
if (state != null && state.needsLink && state.nodeOnline != false) {
if (held) {
// Unlocked before the socket goes, as [_redialNewlyTrusted] does: the screen reads it as
// connecting from here on, never as locked in between.
state.needsLink = false;
state.agentLoadStatus = AgentLoadStatus.idle;
}
await _pool?.closeMachine(machineId);
_connectMachine(state);
}
notifyListeners();
}
/// A device was taken out of the account (not by this phone): say so, once. A removal by a new
/// device nobody looked at is the alarming one; its notice opens that signer, the rest open the list.
void announceDeviceRemoval(DeviceRemovalNotice n) {
if (deviceRemovals.any((r) => r.pub == n.pub)) return;
deviceRemovals.add(n);
devicesRevision++;
unawaited(
agentNotices.system.showAccountNotice(
key: n.red ? 'removedBy:${n.signer}:${n.pub}' : 'removed:${n.pub}',
title: n.title,
body: n.sentence,
),
);
if (!_disposed) notifyListeners();
}
void dismissDeviceRemoval(String pub) {
// Only the notice. The same event may also be kept by the log as "left before you looked" (the
// departed band, which has its own "Got it" and is a durable mark): a notice dismissed here —
// however benign it reads, e.g. a self sign-out — never clears it.
deviceRemovals.removeWhere((r) => r.pub == pub);
notifyListeners();
}
/// Bumped by every read of `pending` and every local dismissal: a read that started before either
/// is stale and must not put dismissed devices back on the banner.
int _pendingSyncGen = 0;
/// Rebuild [newDevices] from the log's persisted `pending`, oldest first: what survived a restart,
/// and what another path (a `group_sync`, a dismiss) changed.
Future<void> _syncPendingDevices() async {
final log = _deviceLog;
if (log == null) return;
final gen = ++_pendingSyncGen;
final DeviceLogListing listing;
try {
listing = await log.list();
} catch (_) {
return;
}
if (_disposed ||
gen != _pendingSyncGen ||
status != AppStatus.authenticated)
return;
final frozen = listing.frozen != null;
final tooMany = listing.registerError == 'TOO_MANY';
final frozenChanged =
frozen != _deviceListFrozen || tooMany != _deviceListTooMany;
_deviceListFrozen = frozen;
_deviceListTooMany = tooMany;
final pending = listing.pending.toSet();
_suspendedNew
..clear()
..addAll([
for (final r in listing.members)
if (r.suspended) r.member.pub,
]);
final next = [
for (final r in listing.members)
if (pending.contains(r.member.pub) &&
!r.self &&
!_failedDismissals.contains(r.member.pub))
r.member,
]..sort((a, b) => a.seq.compareTo(b.seq));
final nextDeparted = [
for (final d in listing.departed)
if (!_failedDismissals.contains(d.pub)) d,
];
final same = listEquals(
[for (final m in next) m.pub],
[for (final m in newDevices) m.pub],
);
final sameDeparted = listEquals(
[for (final d in nextDeparted) d.pub],
[for (final d in departedDevices) d.pub],
);
if (same && sameDeparted && !frozenChanged) return;
newDevices
..clear()
..addAll(next);
departedDevices
..clear()
..addAll(nextDeparted);
notifyListeners();
}
/// A machine waiting on trust — being settled ([_settleTrust]), or asking for its password — that the
/// device key log now vouches for: dial it again, at once.
Future<void> _redialNewlyTrusted() async {
for (final state in [...machineStates.values]) {
final machineId = state.machine.machineId;
if (!state.needsLink && !_trustSettling.contains(machineId)) continue;
if (!await _holdsMachineKey(machineId)) continue;
if (_trustWakes[machineId] case final wake? when !wake.isCompleted) {
wake.complete();
continue;
}
if (!state.needsLink) continue;
state.needsLink = false;
state.agentLoadStatus = AgentLoadStatus.idle;
await _pool?.closeMachine(state.machine.machineId);
_connectMachine(state);
}
if (!_disposed) notifyListeners();
}
/// When each of the account's keys last opened a session (`{pub: ms}`), for the Devices page.
Future<Map<String, int>> devicesLastSeen() => api.deviceKeysSeen();
/// The account's devices as this phone verified them. A seam of its own so a test can answer
/// without a real device log.
Future<DeviceLogListing> deviceListing() async =>
await _deviceLog?.list() ?? DeviceLogListing.empty;
DateTime? _deviceLogReadAt;
/// A socket came back: a `device_keys_changed` sent while this phone was offline reached nobody, so
/// read the log again — and put this phone's key into it if the boot's register could not — at most
/// every half minute, since a reconnect is every machine at once.
void _refreshDeviceLogAfterReconnect() {
final log = _deviceLog;
if (log == null) return;
final now = DateTime.now();
if (_deviceLogReadAt case final last?
when now.difference(last) < const Duration(seconds: 30))
return;
_deviceLogReadAt = now;
unawaited(log.ensureRegistered());
}
/// The devices list was opened: every device announced so far has been seen — the banner's, and
/// [pending], what the list itself read from the log (after a restart, before the banner is rebuilt
/// from it). Persisted, so the banner does not come back.
///
/// [shown] is the banner's set as it was when the list was read: pass it when the page awaited
/// anything in between, or a device announced meanwhile — never shown — would be dismissed unseen.
/// Without it, the banner as it is now.
void seenNewDevices({
Iterable<String> pending = const [],
Iterable<String>? shown,
}) {
final bannerPubs = (shown ?? newDevices.map((d) => d.pub)).toList();
if (bannerPubs.isEmpty && pending.isEmpty) return;
// Exactly what was shown, never "all": a device added since (and not yet shown) stays pending.
// And a device that left before anyone looked is cleared by its own "Got it" only: opening the
// list is not that.
final departed = {for (final d in departedDevices) d.pub};
final marked = {
...pending,
...bannerPubs,
}.where((p) => !departed.contains(p)).toList();
// Nothing marked: a read of `pending` under way (the one a startup replay starts, which takes a
// departed key's stale "New device" down) is not stale — let it land.
if (marked.isEmpty) return;
// A read of `pending` already under way predates this: it must not put them back.
_pendingSyncGen++;
unawaited(_dismissInLog(pubs: marked));
final before = newDevices.length;
newDevices.removeWhere((d) => marked.contains(d.pub));
if (newDevices.length != before) notifyListeners();
}
/// "It's mine" on [pub]. Only the device's own page, which shows why a key is Suspended, passes
/// [liftSuspension]: that is the person vouching for it. Anywhere else the key stays suspended —
/// the banner never said so. Either way the account's other devices are told, and stop showing it as
/// new (opening the list, [seenNewDevices], tells nobody).
void dismissNewDevice(String pub, {bool liftSuspension = false}) {
newDevices.removeWhere((d) => d.pub == pub);
// A key that joined and left before anyone looked: a "New device" for it is a stale replay, and its
// flag is cleared by its own "Got it" only ([dismissDeparted]) — "It's mine" here takes the banner
// down and marks nothing.
if (departedDevices.any((d) => d.pub == pub)) {
notifyListeners();
return;
}
_pendingSyncGen++;
unawaited(
liftSuspension
? _dismissInLog(pub: pub, confirm: true)
: _dismissInLog(pubs: [pub], confirm: true),
);
notifyListeners();
}
/// "Got it" on the Devices page's "Already on your account" list: persisted, shown once.
Future<void> seeDeviceBaseline() async {
try {
await deviceLog?.seeBaseline();
} catch (error) {
debugPrint('devices: could not save the baseline as seen: $error');
}
}
/// Every add and remove on the account as this phone verified it. A seam of its own so a test can
/// answer without a real device log.
Future<DeviceLogHistory> deviceHistory() async =>
await _deviceLog?.history() ??
const DeviceLogHistory(rows: [], complete: false);
/// Take [pub] out of the account on every device. Null when done, else why not.
Future<String?> removeDevice(String pub) async {
final log = _deviceLog;
final error = log == null ? 'UNAVAILABLE' : await log.remove(pub);
if (error == null) newDevices.removeWhere((d) => d.pub == pub);
devicesRevision++;
notifyListeners();
return error;
}
/// A code scanned from a desktop app's "Add phone" QR, held across sign-in: once its machine shows
/// up locked, the phone pairs with the code ([connectWithCode]) instead of asking for a password.
/// See `phone/welcome/connect_code.dart`. Null the rest of the time.
({String machineId, String code})? pendingPairing;
/// A computer's own sign-in QR (the bare `hnq_…` code, [SignInCode] in
/// `phone/welcome/connect_code.dart`) read on the welcome screen by a phone not yet signed in —
/// `harness login --qr`'s. Only a signed-in phone can approve it, so the welcome
/// signs this one in first and holds the code across that sign-in; the signed-in shell then asks
/// to approve it (`phone/phone_shell.dart`), and spends it. Null the rest of the time.
///
/// Like [pendingPairing], set before the sign-in on purpose and so not cleared by
/// [_invalidateAuthWork]: a sign-out drops it instead.
String? pendingComputerSignIn;
/// The scanned code is spent (it failed, or the person chose the password): the computer's
/// password form is what the home screen shows next.
void dropPendingPairing() {
if (pendingPairing == null) return;
pendingPairing = null;
notifyListeners();
}
/// A code scanned, signed in, on "Waiting for your computer…" (`phone/welcome/connect_computer.dart`)
/// — a page the very computer it was waiting for takes away. Held like a code scanned at sign-in:
/// the home screen pairs with it once that computer is there and locked ([pendingPairing]).
///
/// That page looks the computer up on the account first, and holds no code the account answered
/// without; one held while the account could not be asked is let go by the next list that
/// answers without its computer ([_refreshMachines]).
///
/// Not for a computer already open: nothing is left to pair, and a code kept would be spent the
/// next time it locks, in place of its password form (see where [pendingPairing] is cleared on
/// connect). Not once signed out either: the page then went because the account did, and its
/// code is for a computer on that account — a sign-out clears [pendingPairing] for the same reason.
void holdPendingPairing(String machineId, String code) {
if (status != AppStatus.authenticated) return;
if (machineStates[machineId]?.connectionStatus ==
ConnectionStatus.connected) {
return;
}
pendingPairing = (machineId: machineId, code: code);
notifyListeners();
}
/// The pairing [pendingPairing]'s code is being spent on, while it runs — see [pairPendingCode].
({String machineId, String code, Future<String?> result})? _pairingRun;
/// The code [pendingPairing] held when the home screen began pairing by it — see
/// [pendingPairingTried].
({String machineId, String code})? _pairingTried;
/// Whether the home screen has begun pairing by the code [pendingPairing] holds now.
///
/// From then on its pairing page (`phone/welcome/pairing_with_code.dart`) stays up until the code
/// is spent or dropped, and not only while the machine reads locked: a redial that clears
/// [MachineState.needsLink] for a moment — the vouched redials of a fresh sign-in
/// ([_redialOnceVouched]) — took the page down mid-pairing, hid an error it then had, and built
/// it again a second later to pair a second time by the same one-time code.
bool get pendingPairingTried {
final pending = pendingPairing, tried = _pairingTried;
return pending != null &&
tried != null &&
pending.machineId == tried.machineId &&
pending.code == tried.code;
}
/// Pairs with [machineId] by [code], the code [pendingPairing] holds — once per code at a time.
///
/// ⚠️ **A second call for the same code while the first runs joins it.** The code is one-time: a
/// pairing page built again while one is still pairing (see [pendingPairingTried]) spent it a
/// second time, and the computer, mid-pairing, answered PAIRING_BUSY or CODE_MISMATCH while the
/// first went through. A call after one that has FINISHED pairs again: "Scan again" after a
/// timeout reads the same code back off Add Phone, and it is good again.
///
/// Success lets the code go here, not on the page: the page can be gone by then.
Future<String?> pairPendingCode(String machineId, String code) {
final running = _pairingRun;
if (running != null &&
running.machineId == machineId &&
running.code == code) {
return running.result;
}
_pairingTried = (machineId: machineId, code: code);
late final Future<String?> result;
result = () async {
String? error;
try {
error = await connectWithCode(machineId, code);
} catch (e) {
// [connectWithCode] answers with a result, not an exception; one that slips through must
// not leave "Connecting to…" up with nothing behind it.
appLog.warn('pair', 'pairing by code with $machineId threw: $e');
error = 'Couldn’t connect. Scan again.';
} finally {
if (identical(_pairingRun?.result, result)) _pairingRun = null;
}
final pending = pendingPairing;
if (error == null &&
pending != null &&
pending.machineId == machineId &&
pending.code == code) {
pendingPairing = null;
notifyListeners();
}
return error;
}();
_pairingRun = (machineId: machineId, code: code, result: result);
return result;
}
/// Pairs with [machineId] by the one-time code its desktop app showed, then reconnects it — the
/// QR's way in, where [connectWithPassword] is the password's. Null on success, or what to show.
Future<String?> connectWithCode(String machineId, String code) async {
final finish = productMeasurement.begin(ProductFlow.computerLink);
try {
final result = await peerLinks.connectWithCode(
machineId,
code,
label: phoneClientDescriptor().name,
displayName: machineStates[machineId]?.machine.displayName,
);
finish(result.error == null ? ProductOutcome.ok : ProductOutcome.failed);
if (result.error != null) return result.error;
final state = machineStates[result.linkedMachineId ?? machineId];
if (state != null && !_keepsOpenConnection(state)) {
state.needsLink = false;
state.agentLoadStatus = AgentLoadStatus.idle;
notifyListeners();
await _pool?.closeMachine(state.machine.machineId);
_connectMachine(state);
}
unawaited(_syncGroup(result.linkedMachineId ?? machineId, spread: true));
return null;
} catch (_) {
finish(ProductOutcome.failed);
rethrow;
} finally {
finish(ProductOutcome.unknown);
}
}
/// Whether a machine just linked (by password or code) is already connected — let in meanwhile
/// by another way, the device log's vouched redial above all ([_redialOnceVouched]), which goes
/// on dialling behind a machine shown locked.
///
/// ⚠️ **Then the link leaves its connection alone.** Both links used to close the machine and
/// dial it again whatever its state, to replace a socket that refused this phone — and an open
/// one went with it: the terminal on screen read "Connection lost. Reconnecting…" a moment after
/// the unlock that was meant to open it. A connected socket has passed the machine's welcome
/// (`WsConn._markReady`), so it is no refused one.
bool _keepsOpenConnection(MachineState state) =>
state.connectionStatus == ConnectionStatus.connected;
/// A test's stand-in for the trust-group roster swap; null uses [DirectLink.syncGroup].
late final GroupSync? _groupSyncOverride;
/// The trust-group roster swap (`viewer/group_sync.dart`). Only the app's own [DirectLink] dials
/// for it — a test that hands over fake links, or has no layout store (no state file), never does.
GroupSync? get _groupSync {
if (_groupSyncOverride case final sync?) return sync;
final links = peerLinks;
return links is DirectLink && _paneLayout != null ? links.syncGroup : null;
}
final Map<String, DateTime> _groupSyncedAt = {};
static const _groupResync = Duration(minutes: 5);
/// Swaps trust-group rosters with [machineId], at most every few minutes per machine — any
/// session this phone opens is the moment. With [spread] (a machine was just linked) or when the
/// swap taught this phone a new machine, every other linked machine hears of it straight away.
Future<void> _syncGroup(String machineId, {bool spread = false}) async {
final sync = _groupSync;
if (sync == null) return;
final now = DateTime.now();
final last = _groupSyncedAt[machineId];
if (!spread && last != null && now.difference(last) < _groupResync) return;
// Not stamped while the device log is still the last account's (DirectLink.syncGroup skips it
// then): stamped, a machine reached right after an account switch went five minutes unsynced.
if (await _deviceLog?.ownsLog() == false) return;
_groupSyncedAt[machineId] = now;
// Fire-and-forget from the connection handler: a state file that is locked for a moment must not
// surface as an unhandled error. The next session retries.
try {
final label = phoneClientDescriptor().name;
final outcome = await sync(machineId, label: label);
await _afterGroupSync(outcome);
if (!spread && outcome.pinned.isEmpty) return;
for (final other in [...machineStates.keys]) {
if (other == machineId || machineStates[other]?.nodeOnline == false) {
continue;
}
if (await viewer.keys.peer(other) == null) continue;
_groupSyncedAt[other] = DateTime.now();
await _afterGroupSync(await sync(other, label: label));
}
} catch (_) {
_groupSyncedAt.remove(machineId);
}
}
/// What a roster swap changed, applied to the machines on screen: a machine the group removed wants
/// its password again; a machine waiting for one that the group has now vouched for is dialed.
Future<void> _afterGroupSync(GroupSyncOutcome outcome) async {
var changed = false;
for (final id in outcome.unpinned) {
final machine = machineStates[id];
if (machine == null || machine.needsLink) continue;
machine.needsLink = true;
machine.agentLoadStatus = AgentLoadStatus.needsLink;
await _pool?.closeMachine(id);
_markSessionsUnreachable(
machine,
'This machine left your group. Enter its password to reconnect.',
);
changed = true;
}
for (final machine in [...machineStates.values]) {
if (!machine.needsLink) continue;
final id = machine.machine.machineId;
if (await viewer.keys.peer(id) == null) continue;
machine.needsLink = false;
machine.agentLoadStatus = AgentLoadStatus.idle;
await _pool?.closeMachine(id);
_connectMachine(machine);
changed = true;
}
if (changed) notifyListeners();
}
List<LinkedMachine> linkedMachines = [];
bool linkedMachinesLoading = false;
String? linkedMachinesError;
/// Refreshes the "machines this one trusts" list (`harness link list`).
Future<void> refreshLinkedMachines() async {
linkedMachinesLoading = true;
notifyListeners();
final result = await peerLinks.list();
linkedMachinesLoading = false;
linkedMachinesError = result.error;
linkedMachines = result.machines;
notifyListeners();
}
/// Removes a linked machine's trust pin, then refreshes the list. Returns null on success.
///
/// ⚠️ Dropping the pin does NOT end the connection by itself, and that is the whole reason the
/// teardown below exists. The pin is local to this device — the machine is never told — and the
/// socket already open has negotiated its session, so it keeps working exactly as before. No
/// close arrives, so nothing flips [MachineState.needsLink], and the row stays under "Linked"
/// looking connected because it IS connected.
///
/// So this does by hand what a `NO_PEER_LINK` close does on its own: shut the socket, mark the
/// machine as wanting its password, and tell the open terminals they are no longer reachable.
Future<String?> unlinkMachine(String machineId) async {
final error = await peerLinks.unlink(machineId);
if (error != null) return error;
await refreshLinkedMachines();
final machine = machineStates[machineId];
if (machine == null) return null;
// ⚠️ Marked unlinked BEFORE the socket is closed, not after. Closing reports `disconnected`, and
// the status handler reads a disconnect from a LINKED machine as the machine going away — it
// sets `nodeOnline = false`. Closed first, a computer that is still switched on came out of
// Unlink labelled "Offline" and unopenable, and stayed that way until the next machine refresh.
// Flagged first, the handler skips that (see the `!machine.needsLink` guard in `_ensurePool`) and
// presence stays whatever `/api/machines` last said: on → "Needs its password", off → "Offline".
machine.needsLink = true;
machine.agentLoadStatus = AgentLoadStatus.needsLink;
await _pool?.closeMachine(machineId);
_markSessionsUnreachable(
machine,
'This phone is no longer linked. Enter the password again to reconnect.',
);
notifyListeners();
return null;
}
Future<void> _pollOfflineMachine(String machineId) async {
final machine = machineStates[machineId];
if (machine == null ||
machine.nodeOnline != false ||
machine.pendingOfflineAgentId == null ||
_offlinePollsInFlight.contains(machineId)) {
return;
}
_offlinePollsInFlight.add(machineId);
try {
final latest = (await _fetchMachines()).where(
(item) => item.machineId == machineId,
);
if (latest.isEmpty) return;
final reportedOnline = _nodeOnlineFromStatus(latest.first.status);
if (reportedOnline == null) return;
machine.machine = latest.first;
await _applyNodeStatus(machine, reportedOnline);
} catch (error) {
debugPrint('offline node retry failed: $machineId: $error');
} finally {
_offlinePollsInFlight.remove(machineId);
}
}
/// Open only the machine data sockets after discovery. Terminal panes remain
/// lazy and are attached only when the user selects an agent row.
void _autoConnectAndLoadMachines() {
final visible = machines.map((machine) => machine.machineId).toSet();
expandedMachines
..removeWhere((machineId) => !visible.contains(machineId))
..addAll(visible);
if (machines.isEmpty) {
selectedMachineId = null;
return;
}
if (!visible.contains(selectedMachineId)) {
selectedMachineId = machines.first.machineId;
}
final dial = <MachineState>[];
for (final machine in machines) {
final state = machineStates[machine.machineId]!;
// ⚠️ **A machine the account says is down is not dialled, and this is the
// single biggest thing standing between launch and a usable screen.**
//
// `/api/machines` has already reported each machine's status by this
// point, and a phone commonly has several linked machines with one
// actually running. Dialling the rest anyway bought nothing and cost the
// full inventory budget EACH: the socket opens (the relay is up — it is
// the machine behind it that is not), then `waitUntilReady` sits there
// until it times out, because the machine that would answer is off. A
// real launch measured four of those, `10002ms` apiece, while the one
// live machine had been ready since 3s.
//
// The tiles say "Offline", which is both true and immediate, instead of
// "Connecting…" for ten seconds before saying the same thing.
//
// ⚠️ **This is NOT covered by the 5-second offline poll, whatever it
// looks like.** `_startOfflineRetry` bails for a REMOTE machine unless
// something is already waiting on one of its agents
// (`pendingOfflineAgentId`) — and on a phone every machine is remote. So
// a machine skipped here is not dialled again by anything on a timer: it
// stays invisible, its agents included, until a pull-to-refresh
// (`retryMachines`) or the search asks ([reachAllMachines]). That gap is
// what "it only shows the sessions on one machine" was.
//
// A null answer means the account did not say — an older backend, or a
// status this app does not recognise. That still dials: silence is not
// evidence of being down, and the previous behaviour is the safe one.
//
// Read from `machine.status` rather than `state.nodeOnline`, which the
// caller sets through an unawaited `_applyNodeStatus`: that happens to
// assign synchronously today, so both agree, but this loop should not be
// the thing that breaks if it ever gains an await before the assignment.
if (_nodeOnlineFromStatus(machine.status) == false) {
StartupTrace.mark('skipped offline machine ${machine.machineId}');
continue;
}
// Held until the launch's own terminal is up — see [_launchMachineId]. The cached ones were
// held by the warm start already; this catches the machines the cache did not know.
if (_heldForLaunch(machine.machineId)) {
_holdForLaunch(machine.machineId);
continue;
}
dial.add(state);
}
unawaited(_connectAfterDeviceLog(dial, load: true));
}
/// Dial [states]: at once a machine this phone holds a key for, one already asking for its password
/// and one a scanned code waits for. A machine with no key here may only be missing from this
/// phone's copy of the device log — a computer signed in after the phone was — so the log is read
/// first, briefly, rather than dialling a refusal. [load]: ask a machine that already answers for
/// its data ([_dialAndLoad]).
Future<void> _connectAfterDeviceLog(
List<MachineState> states, {
required bool load,
}) async {
final revision = _authRevision;
bool current(MachineState state) =>
_authWorkCurrent(revision) &&
identical(machineStates[state.machine.machineId], state);
final waiting = <MachineState>[];
for (final state in states) {
final machineId = state.machine.machineId;
if (state.needsLink ||
pendingPairing?.machineId == machineId ||
await _holdsMachineKey(machineId)) {
if (current(state)) _dialAndLoad(state, load: load);
} else {
waiting.add(state);
}
}
if (waiting.isEmpty) return;
await _deviceLog?.refresh().timeout(
const Duration(seconds: 5),
onTimeout: () {},
);
for (final state in waiting) {
if (current(state)) _dialAndLoad(state, load: load);
}
}
void _dialAndLoad(MachineState state, {required bool load}) {
_connectMachine(state);
if (!load) return;
// ⚠️ **Only ask a machine that is already answering.** `_connectMachine`
// starts a dial; it does not finish one. Asking here regardless meant
// `waitUntilReady` sat on a handshake that had not happened yet, spending
// the inventory budget on the connection rather than on the request — and
// on a first launch it spent ALL of it, which then read as the machine
// having gone offline and triggered a `forceReconnect()` that threw the
// working socket away and started over.
//
// A machine that is not ready yet loses nothing: `_onConnectionStatus`
// calls this the moment its handshake completes, with `force: true`, which
// is the path every reconnect in the app already takes.
//
// Read off the POOL rather than through `_conn`, which would build a
// connection as a side effect of being asked about one — for a machine
// `_connectMachine` had just declined to dial, that would be this method
// quietly undoing its own decision.
if (_connectionReady(state.machine.machineId)) {
unawaited(_loadMachineData(state));
}
}
/// A user-triggered reload is in flight.
///
/// Read by the rail's reload button, which spins its glyph and stops taking
/// clicks while this is true. It is deliberately NOT [machinesLoading]: that
/// one means "there is nothing on screen yet", and a refresh over a list
/// already up leaves it false on purpose.
bool get machinesRefreshing => _retryInFlight != null;
/// The run itself, so a second press joins the first instead of starting a
/// second `GET /api/machines` beside it. The button's disabled state makes
/// this hard to reach by pointer, but ⌘R has no such guard, and neither has
/// the error strip's own retry.
Future<void>? _retryInFlight;
Future<void> retryMachines() {
if (_disposed) return Future<void>.value();
final inFlight = _retryInFlight;
if (inFlight != null) return inFlight;
late final Future<void> run;
run = _performRetryMachines().whenComplete(() {
if (identical(_retryInFlight, run)) {
_retryInFlight = null;
if (!_disposed) notifyListeners();
}
});
_retryInFlight = run;
notifyListeners();
return run;
}
Future<void> _performRetryMachines() async {
final revision = _authRevision;
if (!_authWorkCurrent(revision) || status == AppStatus.unauthenticated) {
return;
}
if (currentUser == null) unawaited(_loadProfile());
// The desk is joined here as well, should the boot not have got that far —
// [PhoneDesk.ensure] makes that once.
_desk.ensure();
zoo.ensure();
try {
await refreshMachines();
if (!_authWorkCurrent(revision)) return;
_lastError = null;
} catch (error) {
if (!_authWorkCurrent(revision)) return;
_lastError = 'Could not load machines: ${describeApiError(error)}';
_lastErrorRetryable = true;
notifyListeners();
return;
}
await Future.wait(expandedMachines.toList().map(reloadMachineData));
if (_authWorkCurrent(revision)) notifyListeners();
}
void toggleExpand(String machineId) {
if (expandedMachines.contains(machineId)) {
expandedMachines.remove(machineId);
} else {
expandedMachines.add(machineId);
selectedMachineId = machineId;
final machine = machineStates[machineId];
if (machine != null) {
_connectMachine(machine);
unawaited(_loadMachineData(machine));
}
}
notifyListeners();
}
/// Selects a machine without toggling its tree. Setup/status rows use this
/// action so clicking an E2EE prompt always opens that machine's setup pane.
Future<void> selectMachineForSetup(String machineId) async {
final machine = machineStates[machineId];
if (machine == null) return;
_dismissedLinkPrompts.remove(machineId);
selectedMachineId = machineId;
expandedMachines.add(machineId);
// Nothing is torn down here any more. That line existed because the content
// area was one terminal belonging to whichever machine was selected, so
// browsing to a second machine's setup form would otherwise have left the
// first machine's terminal rendering underneath it. Tiles now say what they
// are on their own and outlive the rail's selection, which makes selecting
// a machine navigation again — and closing someone's running terminals
// because they clicked a row would be the surprise, not the fix.
//
// The form itself arrives as a tile, which is the only way it can arrive at
// all: a machine that needs linking has no agents to open.
showMachinePane(machineId);
_connectMachine(machine);
notifyListeners();
}
void _connectMachine(MachineState machine) {
// connFor() starts a new socket and reports `connecting` through onStatus,
// or returns the existing socket with its current status intact. Do not
// overwrite an already-connected socket when the user collapses and
// re-expands the machine row; doing so leaves the UI permanently yellow
// and disables every agent even though the transport is still ready.
if (_pool != null) _conn(machine.machine.machineId);
}
WsConn _conn(String machineId) {
final testConnection = connectionForTest;
if (testConnection != null) return testConnection(machineId);
// Every machine is dialled through the relay: there is no local CLI to proxy for it.
final connection = _pool!.connFor(machineId);
_wireConnectionHooks(connection, machineId);
return connection;
}
/// Whether [machineId]'s socket has finished its handshake — asked of the
/// connection the app already HOLDS, never of one built for the asking (see
/// [_autoConnectAndLoadMachines] for why that matters). A test's
/// [connectionForTest] stands in for the pool here, as it does in [_conn].
bool _connectionReady(String machineId) {
final testConnection = connectionForTest;
if (testConnection != null) return testConnection(machineId).isReady;
return _pool?[machineId]?.isReady == true;
}
/// [machineId]'s connection as the app already HOLDS it, or null — never one built for the
/// asking, for the same reason as [_connectionReady].
WsConn? _heldConnection(String machineId) {
final testConnection = connectionForTest;
if (testConnection != null) return testConnection(machineId);
return _pool?[machineId];
}
// Every machine hands over the same loopback (HTRL) frames: the relay codec has opened the E2EE
// envelope before a frame gets here (see `ws/relay_codec.dart`), so there is no per-machine
// branching left here at all.
void _wireConnectionHooks(WsConn connection, String machineId) {
connection.onBinaryFrame = (frame) =>
_handleTerminalBinary(machineId, frame);
}
/// Bulk terminal data for a machine, which may now be feeding several tiles.
///
/// Read the live session identity instead of maintaining a second registry.
/// Skip unrelated sessions before awaiting: every ignored async call adds a
/// scheduling turn to the socket's incoming queue. Matching frames enter the
/// session's ordered renderer queue synchronously, regardless of tab order.
Future<void> _handleTerminalBinary(String machineId, Uint8List raw) async {
final targets = panesFor(machineId)
.map((pane) => pane.session)
.whereType<TerminalSession>()
.toList();
if (targets.isEmpty) return;
final clear = decodeTerminalLocal(raw);
if (clear == null) {
// Undecodable says the transport is wrong, not that one stream is — so
// it goes to all of them.
for (final terminal in targets) {
terminal.transportLost('Binary terminal frame could not be decoded');
}
return;
}
for (final terminal in targets) {
if (terminal.streamId == clear.streamId) {
await terminal.handleBinary(clear);
}
}
}
Future<bool> _sendTerminalBinary(
String machineId,
TerminalBinaryFrame frame,
) async {
final encoded = encodeTerminalLocal(frame);
if (encoded == null) return false;
return _conn(machineId).sendTerminalBinary(encoded);
}
/// How long a `terminal_open` waits for its machine's handshake — see [_sendTerminalFrame].
/// The dial's own limit and a select's, near enough: past it the socket is not about to be up.
static const _openWaitsForHandshake = Duration(seconds: 15);
/// A terminal frame for [machineId]'s connection — a `terminal_open` held until the handshake
/// is done, every other frame sent (or refused) at once, as before.
///
/// ⚠️ **Why the open waits (owner, 2026-10-01).** A launch builds its terminal from the cached
/// agent and capabilities, so the open is made while the socket is still handshaking, and the
/// socket refused it: the session gave up on it ("Could not send terminal_open"), and nothing
/// asked again until the machine answered `terminal_capabilities` or its agent list, which reattach
/// waiting panes — measured at 0.6–0.75s after the socket was ready, every launch. Held here
/// instead, it leaves the moment the handshake lands, with the request it was made with. Bounded:
/// a handshake that does not land in [_openWaitsForHandshake] refuses it as before, and the
/// usual reattach on connect takes over.
Future<bool> _sendTerminalFrame(
String machineId,
String type,
Map<String, dynamic> payload,
) async {
final connection = _conn(machineId);
if (type == 'terminal_open' && !connection.isReady) {
try {
await connection.waitUntilReady(timeout: _openWaitsForHandshake);
} catch (_) {
// Timed out, or the connection was closed meanwhile: the socket refuses the frame below,
// which is the answer the session already knows how to take.
}
}
return connection.sendTerminalFrame(type, payload);
}
/// The machine a launch dials ALONE — the one the phone last had an agent open on — while every
/// other machine waits in [_heldMachines]; null once they have been let go, and on a launch that
/// had nothing to put first.
///
/// ⚠️ **Why a launch dials one machine first (owner, 2026-10-01).** Every machine the account
/// had was dialled at once: a relay socket, an E2EE handshake, `terminal_capabilities`, a full
/// agent list and a P2P negotiation EACH, seven or eight of them on a phone, all in the same
/// second as the one terminal the person is waiting to see — which is on one machine. On one
/// machine a launch measured 3.3s to a ready socket; the work on the others added nothing anybody
/// was looking at. The rest are let go the moment that terminal shows its first frame
/// ([_releaseOnFirstFrame]), when Find opens ([reachAllMachines]), or after
/// [_heldMachinesRelease] whatever happens; and a machine is dialled the moment one of its own
/// agents is opened, held or not ([_conn] dials what it does not hold).
///
/// What it costs: for those few seconds the other machines' sessions read from the cache, as
/// `connecting`, and anything they announce in that time (a finished turn, a question) arrives
/// as soon as they are dialled rather than at once.
String? _launchMachineId;
final Set<String> _heldMachines = {};
Timer? _heldMachinesTimer;
static const _heldMachinesRelease = Duration(seconds: 5);
/// Whether [machineId] is one the launch is holding back — see [_launchMachineId] — or one it has
/// let go of that is still waiting for its turn to dial ([_releaseQueue]).
bool _heldForLaunch(String machineId) =>
(_launchMachineId != null && machineId != _launchMachineId) ||
_releaseQueue.contains(machineId);
/// Hold [machineId] back for the launch — a machine [_heldForLaunch] says is held. Nothing to do
/// for one already let go: it is waiting in [_releaseQueue], which dials it in its turn.
void _holdForLaunch(String machineId) {
if (_launchMachineId != null) _heldMachines.add(machineId);
}
/// The machines the launch let go of that have not dialled yet, in the order they go — see
/// [_dialReleasedInTurn].
final List<String> _releaseQueue = [];
/// The let-go machines dialling now, each with the timer that ends its turn if nothing else does
/// first ([_endReleaseTurn]).
final Map<String, Timer> _releaseTurns = {};
/// How many let-go machines dial at once, and how long one may hold its turn.
static const _releaseTurnsAtOnce = 3;
static const _releaseTurnLimit = Duration(seconds: 4);
/// Since the launch let its held machines go — the offsets in their timeline lines.
Stopwatch? _releaseClock;
/// Let go of every machine the launch held back. Idempotent; [why] goes to the startup timeline.
///
/// [atOnce] dials all of them now, and with them any still waiting their turn — for a person
/// asking for every machine (Find), and for a launch that turned out to have nothing to put
/// first. Otherwise they dial a few at a time ([_dialReleasedInTurn]).
void _releaseHeldMachines(String why, {bool atOnce = false}) {
if (_launchMachineId != null) {
_launchMachineId = null;
_heldMachinesTimer?.cancel();
_heldMachinesTimer = null;
final held = _heldMachines.toList();
_heldMachines.clear();
if (_disposed) return;
StartupTrace.mark(
'launch: letting ${held.length} held machine(s) go '
'${atOnce ? 'at once' : '$_releaseTurnsAtOnce at a time'} · $why',
);
for (final machineId in held) {
if (!_releaseQueue.contains(machineId)) _releaseQueue.add(machineId);
}
_releaseClock = Stopwatch()..start();
} else if (!atOnce || _releaseQueue.isEmpty || _disposed) {
return;
} else {
StartupTrace.mark(
'launch: dialling the ${_releaseQueue.length} machine(s) still '
'waiting their turn · $why',
);
}
if (!atOnce) {
_dialReleasedInTurn();
return;
}
final waiting = _releaseQueue.toList();
_releaseQueue.clear();
for (final timer in _releaseTurns.values) {
timer.cancel();
}
_releaseTurns.clear();
_releaseClock = null;
for (final machineId in waiting) {
_dialReleased(machineId);
}
}
/// Dial the next let-go machines while fewer than [_releaseTurnsAtOnce] are dialling.
///
/// ⚠️ **Why a few at a time (owner, 2026-10-02).** Let go all at once, the six to nine other
/// machines of a large account each made a credential, a key mint and a signature, decrypted and
/// parsed an agent list, and wrote the machine cache — all on the UI thread, in the same second,
/// right after the terminal somebody had just opened came up. That second is the stutter in the
/// terminal at the start of every launch. A turn is over when the machine's list has been read
/// or its dial failed ([_endReleaseTurn]), or after [_releaseTurnLimit] whatever happens: a slow
/// machine never stops the next from dialling.
///
/// What it costs: the last of ten machines dials a few seconds later than it did. Anything that
/// asks for a machine still waiting dials it on the spot — opening one of its agents ([_conn]),
/// Find ([reachAllMachines]), a pull to refresh ([retryMachines]).
void _dialReleasedInTurn() {
while (!_disposed &&
_releaseTurns.length < _releaseTurnsAtOnce &&
_releaseQueue.isNotEmpty) {
final machineId = _releaseQueue.removeAt(0);
if (!_dialReleased(machineId)) continue;
StartupTrace.mark(
'launch: dialling ${_shortId(machineId)} · ${_releaseQueue.length} '
'still waiting${_sinceRelease()}',
);
_releaseTurns[machineId] = Timer(
_releaseTurnLimit,
() => _endReleaseTurn(machineId, 'turn limit'),
);
}
if (_releaseQueue.isEmpty &&
_releaseTurns.isEmpty &&
_releaseClock != null) {
StartupTrace.mark('launch: every held machine dialled${_sinceRelease()}');
_releaseClock = null;
}
}
/// [machineId]'s turn is over — its list landed, its dial failed, or its time ran out ([why]) —
/// and the next machine may dial. Nothing for a machine that has no turn.
void _endReleaseTurn(String machineId, String why) {
final turn = _releaseTurns.remove(machineId);
if (turn == null) return;
turn.cancel();
StartupTrace.mark(
'launch: ${_shortId(machineId)} turn over · $why${_sinceRelease()}',
);
_dialReleasedInTurn();
}
/// Dial one let-go machine. True when that started a dial; false for a machine gone from the
/// account, one it reports down, and one something else has dialled already.
bool _dialReleased(String machineId) {
final state = machineStates[machineId];
// Gone from the account since — `_refreshMachines` dropped it.
if (state == null) return false;
final listed = machines
.where((machine) => machine.machineId == machineId)
.firstOrNull;
// Down as the account last said: the launch skips those too ([_autoConnectAndLoadMachines]).
if (listed != null && _nodeOnlineFromStatus(listed.status) == false) {
return false;
}
final dialledAlready = _pool?[machineId] != null;
_connectMachine(state);
return !dialledAlready && _pool?[machineId] != null;
}
String _sinceRelease() {
final clock = _releaseClock;
return clock == null ? '' : ' +${clock.elapsedMilliseconds}ms';
}
/// A state just made for a machine whose socket the app ALREADY holds — dialled before there was
/// a state to report to (`_warmStartMachines` dials the launch's machine ahead of the cache parse).
/// Whatever that socket said meanwhile went nowhere ([_onConnectionStatus] needs the state), so it
/// is said again here: a socket that is up replays its `connected`, which is what starts the agent
/// list, the sync timer and the rest; one still dialling is at least shown as dialling.
void _adoptConnection(MachineState state) {
final machineId = state.machine.machineId;
final connection = _pool?[machineId];
if (connection == null) return;
if (connection.isReady) {
_onConnectionStatus(machineId, ConnectionStatus.connected);
} else if (state.connectionStatus == ConnectionStatus.disconnected) {
state.connectionStatus = ConnectionStatus.connecting;
}
}
/// Drop the launch's hold without dialling anything — signing out, or the notifier going away.
void _forgetLaunchHold() {
_preDialled = null;
_launchMachineId = null;
_heldMachines.clear();
_heldMachinesTimer?.cancel();
_heldMachinesTimer = null;
_releaseQueue.clear();
for (final turn in _releaseTurns.values) {
turn.cancel();
}
_releaseTurns.clear();
_releaseClock = null;
}
/// Let the held machines go once [terminal] shows its first frame — the screen a launch is for
/// is up, and nothing on it is waiting any more. See [_launchMachineId].
void _releaseOnFirstFrame(TerminalSession terminal) {
void check() {
if (!terminal.hasRenderedFrame) return;
terminal.removeListener(check);
_releaseHeldMachines('first terminal live');
}
terminal.addListener(check);
}
/// The longest an agent list waits for the terminal on screen — see [_yieldToFocusedTerminal].
static const _listYield = Duration(milliseconds: 1500);
/// Let the terminal on screen answer before [machine]'s agent list is asked for — at launch, and
/// on a reconnect.
///
/// ⚠️ **Why the list waits (owner, 2026-10-01).** The terminal a launch reopens and the machine's
/// agent list left on the same connection in the same instant, and the terminal came second: on
/// every launch measured (ten of ten) its `terminal_ready` arrived in the same second as the
/// list's reply, which took 1.1–3.0s for 134 agents. The machine builds that reply for every
/// agent at once, stopped ones included (`agents_list` in the CLI's `backendSocket.ts`), and the
/// one stream somebody was waiting to type into queued behind it.
///
/// Nothing on screen needs the list first. A launch draws from last run's
/// ([MachineState.agentsFromCache]); a reconnect — back after minutes in the background, or
/// across a network change — still holds the list it read before the drop
/// ([_listHeldThroughDrop]), and reopens the
/// terminal from it ([_reopenFromHeldList]). Any other read waits for nothing: the list there
/// is the news somebody asked for. Over the moment the terminal shows its first live frame or
/// stops opening (failed, taken, gone), and after [_listYield] whatever happens: the list never
/// waits on a terminal that is not coming.
///
/// What it costs: for up to that long, an agent deleted elsewhere since the list was read is
/// still drawn (`_AgentGone` in `terminal_page.dart` needs the real list), and the list's news —
/// a new agent, a rename — arrives that much later.
Future<void> _yieldToFocusedTerminal(MachineState machine) async {
if (!machine.agentsFromCache && !_listHeldThroughDrop(machine)) return;
final pane = focusedPane;
final terminal = pane?.session;
if (pane == null ||
terminal == null ||
pane.machineId != machine.machine.machineId) {
return;
}
await _untilTerminalLive(terminal, _listYield);
}
/// Whether [machine]'s agent list was read from it, but over a socket that has dropped since
/// ([MachineState.agentsListedAt] is cleared by the drop): a reconnect's list, still on screen
/// while the machine is asked again.
bool _listHeldThroughDrop(MachineState machine) =>
machine.agentLoadStatus == AgentLoadStatus.loaded &&
!machine.agentsFromCache &&
machine.agentsListedAt == null;
/// Until [terminal] shows its first live frame or stops opening (failed, taken, gone) — and never
/// longer than [bound], so nothing waits on a terminal that is not coming.
Future<void> _untilTerminalLive(
TerminalSession terminal,
Duration bound,
) async {
// `controlling` without a frame is a `terminal_ready` whose keyframe is on its way: still worth
// the wait, the screen is not live until it lands.
bool over() {
if (terminal.hasRenderedFrame) return true;
final status = terminal.status;
return status != TerminalSessionStatus.opening &&
status != TerminalSessionStatus.controlling;
}
if (over()) return;
final done = Completer<void>();
void check() {
if (!done.isCompleted && over()) done.complete();
}
// A session closed meanwhile never notifies again; this is what ends the wait then.
final timer = Timer(bound, () {
if (!done.isCompleted) done.complete();
});
terminal.addListener(check);
await done.future;
timer.cancel();
terminal.removeListener(check);
}
/// Start dialling last run's machines without waiting for `/api/machines`.
///
/// ⚠️ **The whole point is the socket, not the list.** A relay dial plus the
/// E2EE handshake is around 1.5 seconds on a phone, and it used to begin only
/// after the machine list had been fetched — ~700ms during which the app knew
/// every machine id it needed from the last run and did nothing with them. The
/// two overlap now, so by the time the real list lands its machines are
/// already connected or most of the way there.
///
/// **The fetch always wins.** `_refreshMachines` rebuilds `machineStates` from
/// what the account says, keeping the entries this made (`machineStates.update`
/// with `ifAbsent`) and dropping any machine that is no longer there — with
/// its socket, through the `removeWhere` that already handles a machine
/// disappearing between refreshes. Nothing here is shown to the user as fact:
/// the tiles it creates carry no agents until a real list arrives.
///
/// Skipped entirely once a fetch has already populated the list — a
/// re-bootstrap after a sign-in has nothing to warm up, and warming from a
/// cache that the fetch has already superseded would be a step backwards.
///
/// **The one visible cost.** A machine unlinked from the account since the
/// last run shows for the length of the fetch — under a second — and then goes
/// when the real list arrives. Accepted deliberately: the cache holds only
/// machines the account itself reported as up, unlinking is rare and is done
/// deliberately by the person who would see this, and the alternative is the
/// blank screen that every launch used to show instead.
Future<void> _warmStartMachines() async {
final cache = _machineCache;
if (cache == null || _disposed) return;
final revision = _authRevision;
// The reads were started at the top of [bootstrap] and are normally in hand by now. Taken
// before any await; the cache's once, so a later warm start (a sign-in in this run) reads what
// is on disk then.
final launchRead = lastOpenedAgent.prefetched;
final pendingRaw =
_launchCacheRead ??
StartupTrace.time('boot.machineCacheRead', cache.readRaw);
_launchCacheRead = null;
final pendingRecord =
_launchRecordRead ??
StartupTrace.time('boot.machineLaunchRead', cache.readLaunchRaw);
_launchRecordRead = null;
AgentRef? launchAgent;
if (launchRead != null) {
try {
// Bounded: a record slower than the cache is not worth holding the dial for, and a launch
// without it simply dials everything, as it always did.
launchAgent = await launchRead.timeout(
const Duration(milliseconds: 300),
onTimeout: () => null,
);
} catch (_) {
launchAgent = null;
}
}
if (_disposed || !_authWorkCurrent(revision)) return;
final launchMachine = launchAgent?.machineId;
// ⚠️ **The launch's machine is dialled before the cache is parsed (owner, 2026-10-01).** A dial
// needs nothing but the id, and the parse of every agent of every machine is the longest step
// before it (273–629ms measured, more on a bigger account). Only when the text names that
// machine, which means this account had it, up, at the end of the last run — the cache keeps
// nothing else. The state for it is made below, from the parse, and adopts the socket
// ([_adoptConnection]); a parse that turns out not to list it closes the socket again.
//
// The hold on the other machines ([_launchMachineId]) starts here too, not after the parse:
// `/api/machines` can land while the cache is still being parsed, and the dial-everything it
// does then ([_autoConnectAndLoadMachines]) has to find the hold already in place.
String? dialledEarly;
void holdAndDialEarly(String machineId, String source) {
_launchMachineId = machineId;
_heldMachinesTimer?.cancel();
_heldMachinesTimer = Timer(
_heldMachinesRelease,
() => _releaseHeldMachines('launch budget spent'),
);
if (_pool != null) {
final already = dialledEarly == machineId;
dialledEarly = machineId;
StartupTrace.mark(
already
? 'launch: its machine is already dialling from the hint · $source'
: 'launch: dialling its machine before the cache parse · $source',
);
_conn(machineId);
}
}
// A socket dialled above for a machine nothing went on to make a state for — closed, or it
// would redial for the rest of the session with nobody listening.
void dropUnclaimedDial() {
final machineId = dialledEarly;
if (machineId != null && !machineStates.containsKey(machineId)) {
unawaited(_pool?.closeMachine(machineId));
}
}
bool nothingYet() => machines.isEmpty && machineStates.isEmpty;
// The hint's dial ([_preDialFromHint]): this launch's early dial when the agent it reopens is
// on that machine — kept, adopted with its state below, closed by [dropUnclaimedDial] if no
// state ever claims it. A hint naming another machine was a guess that missed: let go.
final preDialled = _preDialled;
_preDialled = null;
if (preDialled != null) {
if (preDialled == launchMachine) {
dialledEarly = preDialled;
} else if (!machineStates.containsKey(preDialled)) {
StartupTrace.mark(
'launch: the hint dialled ${_shortId(preDialled)}, the agent reopened '
'is elsewhere — closing it',
);
unawaited(_pool?.closeMachine(preDialled));
}
}
// ⚠️ **The launch's own machine first, from the launch record (owner, 2026-10-02).** The
// record holds that one machine — its agents and its capabilities — and nothing else, so it is
// read and parsed in a fraction of the time the whole cache takes (see
// [MachineCache.parseLaunch]). Its terminal is drawn from it, and the rest of the account
// follows when the whole cache has been parsed below. Only when the record has the very agent
// being reopened: anything less, and the launch waits for the whole cache as it did before.
final record = await pendingRecord;
if (_disposed || !_authWorkCurrent(revision)) return;
CachedMachine? first;
List<Machine>? firstMachines;
if (launchAgent != null &&
record != null &&
nothingYet() &&
record.contains('"${launchAgent.machineId}"')) {
holdAndDialEarly(launchAgent.machineId, 'launch record');
first = await StartupTrace.time(
'boot.machineLaunchParse',
() => cache.parseLaunch(
record,
machineId: launchAgent!.machineId,
agentId: launchAgent.agentId,
),
);
if (_disposed || !_authWorkCurrent(revision)) {
dropUnclaimedDial();
return;
}
// The fetch landed during the parse: it is the truth, and made the state itself.
if (first != null && !nothingYet()) first = null;
if (first != null) {
final machine = first.machine;
final state = machineStates.putIfAbsent(
machine.machineId,
() => MachineState(machine),
);
_warmFromCache(state, first);
// Not held: it is the machine the hold puts first.
_connectMachine(state);
if (machine.machineId == dialledEarly) _adoptConnection(state);
// Kept to tell, after the parse below, whether the fetch has replaced it since.
firstMachines = [machine];
machines = firstMachines;
StartupTrace.mark(
'warm-started its machine from the launch record, '
'${first.agents.length} agent(s)',
);
notifyListeners();
}
}
final raw = await pendingRaw;
if (_disposed || !_authWorkCurrent(revision)) {
dropUnclaimedDial();
return;
}
if (raw == null) {
// No cache beside the record: whatever the record started is all there is. A hold it put in
// place has nothing else to hold — the fetch dials the rest.
_releaseHeldMachines('cache unreadable', atOnce: true);
dropUnclaimedDial();
return;
}
if (dialledEarly == null &&
_launchMachineId == null &&
launchMachine != null &&
nothingYet() &&
raw.contains('"$launchMachine"')) {
holdAndDialEarly(launchMachine, 'cache');
}
final cached = await StartupTrace.time(
'boot.machineCache',
() => cache.parse(raw),
);
if (_disposed || !_authWorkCurrent(revision)) {
dropUnclaimedDial();
return;
}
if (cached.isEmpty) {
// Nothing usable after all: the hold has no machine to put first, so it is let go — the
// fetch dials everything, as a launch with no cache always did.
_releaseHeldMachines('cache unreadable', atOnce: true);
dropUnclaimedDial();
return;
}
// The fetch got there first — it is the truth, and this has nothing to add. Its own dial
// honoured the hold; a launch machine the account no longer lists ends it. With the launch
// record drawn, `machines` is that record's list until the fetch replaces it.
final fetchLanded = firstMachines == null
? !nothingYet()
: !identical(machines, firstMachines);
if (fetchLanded) {
final held = _launchMachineId;
if (held != null && !machineStates.containsKey(held)) {
_releaseHeldMachines('launch machine not on the account', atOnce: true);
}
dropUnclaimedDial();
return;
}
// The text named the launch machine, but the parse did not list it as one to dial — a match
// elsewhere in the document. Nothing to put first, then. Not once the record has drawn it:
// that machine is real, and dialling.
final held = _launchMachineId;
if (first == null &&
held != null &&
!cached.any(
(entry) =>
entry.machine.machineId == held &&
entry.machine.authMode == MachineAuthMode.remote,
)) {
_releaseHeldMachines('launch machine not cached', atOnce: true);
}
var warmed = 0;
var warmedAgents = 0;
final warmMachines = <Machine>[];
final warmStates = <MachineState>[];
for (final entry in cached) {
final machine = entry.machine;
// A viewer reaches every machine through the relay; a cached entry that
// claims to be this computer has no meaning on a phone and no local
// endpoint to dial, so it waits for the fetch like it always did.
if (machine.authMode != MachineAuthMode.remote) continue;
// Drawn already, from the launch record, and dialling: kept where the cache lists it.
if (first != null && machine.machineId == first.machine.machineId) {
warmMachines.add(first.machine);
warmed++;
warmedAgents += first.agents.length;
continue;
}
final state = machineStates.putIfAbsent(
machine.machineId,
() => MachineState(machine),
);
_warmFromCache(state, entry);
warmedAgents += entry.agents.length;
// ⚠️ **The dial, and ONLY the dial. No `_loadMachineData` here.**
//
// Asking for the agent list at this point was a real bug, and an ugly one
// to watch: the socket is a few milliseconds old, so `waitUntilReady` was
// waiting on a handshake that had not begun. Any hiccup on that first dial
// — and a cold relay socket has them — reached `_onDone`, which rejects
// every waiter with "WS disconnected". That is NOT a `WsRequestTimeout`,
// so it fell to the generic branch and painted **Disconnected** over a
// machine that was merely still connecting. `_autoConnectAndLoadMachines`
// then asked again a second later, waited out the full ten-second
// inventory budget, and `forceReconnect()` tore the socket down and
// redialled from scratch. The screen showed Attaching → Disconnected →
// Attaching → Live across twelve seconds, for a machine that had answered
// in one.
//
// Nothing is lost by leaving it out. `_onConnectionStatus` calls
// `_loadMachineData` the moment the handshake actually completes — that is
// how every other connection in the app gets its list — and the agents
// from the cache are already on screen meanwhile. The warm start's job is
// to have the socket ALREADY OPEN when that happens, which is where its
// second and a half comes from; the request itself was never the part
// worth racing.
//
// Except for a machine the launch holds back — see [_launchMachineId]. Its cached
// agents are on screen all the same; only the socket waits.
if (_heldForLaunch(machine.machineId)) {
_holdForLaunch(machine.machineId);
} else if (machine.machineId == dialledEarly) {
// Its socket came up before this state existed — see `dialledEarly` above — and is taken
// now, before `dropUnclaimedDial` below closes it: not one to wait on the device log.
_connectMachine(state);
_adoptConnection(state);
} else {
// A machine with no key here reads the device log first ([_connectAfterDeviceLog]).
warmStates.add(state);
}
warmMachines.add(machine);
warmed++;
}
dropUnclaimedDial();
// The record's machine, which a cache from another write may not list: still on screen.
if (first != null &&
!warmMachines.any(
(machine) => machine.machineId == first!.machine.machineId,
)) {
warmMachines.insert(0, first.machine);
}
if (warmed == 0) return;
unawaited(_connectAfterDeviceLog(warmStates, load: false));
// ⚠️ Published to `machines` as well, because every screen indexes agents
// through THAT list (`agentIndex`, `filterableMachines`) rather than through
// `machineStates` — without this the warm start would have opened the
// sockets and drawn nothing, which is half the win and all of the risk.
//
// Replaced wholesale by `_refreshMachines` the moment the fetch lands: it
// assigns `machines` from the account's own answer and drops any state not
// in it, so nothing cached outlives the round-trip it was covering.
machines = warmMachines;
StartupTrace.mark(
'warm-started $warmed machine(s), $warmedAgents agent(s)',
);
notifyListeners();
}
/// What last run cached for [state]'s machine — its agents and its capability reply — put in
/// place for the launch to draw from ([_warmStartMachines]).
void _warmFromCache(MachineState state, CachedMachine entry) {
// ⚠️ **The agents go in as PROVISIONAL, and the flag below is what keeps
// them honest.** With them the phone draws its terminal — the right
// agent's name on it, from the record it already had — while the real list
// is still crossing the network, instead of showing a spinner for two
// seconds and then the same screen.
//
// `agentLoadStatus` stays `loading`, not `loaded`: every screen reads that
// to mean the machine still owes a list, so the refresh indicators, the
// empty states and `_machineStillComing` all keep behaving as though
// nothing had arrived — which is the truth. What these give is a name to
// draw and an id to open, not a claim that the list is settled.
if (entry.agents.isNotEmpty) {
state.agents = entry.agents;
state.agentsFromCache = true;
}
// ⚠️ **The capability reply is replayed so a terminal can attach without
// waiting for the negotiation round-trip.** `_canAttachAgent` requires
// `terminalCapabilityAvailable`, which is otherwise only true once
// `terminal_capabilities` has crossed the network — the last gate on the
// launch, and worth about 700ms of it.
//
// Safe in the direction that matters. Only a reply that SAID the terminal
// works is ever cached, the live negotiation runs regardless and
// overwrites this within the second, and a machine that has genuinely lost
// its tmux answers `available: false` — at which point
// `_applyTerminalCapabilities` clears the flag and every screen reverts to
// what it would have shown anyway. The narrow cost of being wrong is one
// `terminal_open` that fails and is retried, against a second saved on
// every launch that is right.
final capabilities = entry.capabilities;
if (capabilities != null) {
_applyTerminalCapabilities(state, capabilities);
// ⚠️ NOT `terminalCapabilityLoaded`-as-settled: the live negotiation
// still has to run, and `_loadTerminalCapabilities` keys off its own
// in-flight future rather than this flag, so replaying here cannot
// suppress it.
}
}
/// The least time `agents_list` gets, however long the handshake before it
/// took. Short enough that a dead machine is still reported promptly, long
/// enough for one round-trip over a relay on a mobile connection.
static const _agentsListFloor = Duration(seconds: 4);
static Duration _atLeast(Duration value, Duration floor) =>
value < floor ? floor : value;
Future<void> _loadMachineData(
MachineState machine, {
bool force = false,
}) async {
if (!_machineWorkCurrent(machine, _authRevision)) return;
if (machine.agentLoadStatus == AgentLoadStatus.loaded && !force) return;
final inFlight = machine.agentsLoadInFlight;
if (inFlight != null) return inFlight;
late final Future<void> load;
load = _performMachineDataLoad(machine).whenComplete(() {
if (identical(machine.agentsLoadInFlight, load)) {
machine.agentsLoadInFlight = null;
}
// A machine the launch let go of has had its say: the next one may dial
// ([_dialReleasedInTurn]).
_endReleaseTurn(
machine.machine.machineId,
machine.agentLoadStatus == AgentLoadStatus.loaded
? 'listed ${machine.agents.length} agent(s)'
: 'list not read',
);
});
machine.agentsLoadInFlight = load;
return load;
}
Future<void> _performMachineDataLoad(MachineState machine) async {
final revision = _authRevision;
// ⚠️ Agents restored from the cache do NOT count as "had agents". This is a
// first load wearing last run's names: `agentsRefreshing` would render it as
// a quiet background refresh over a list that had been confirmed, and this
// list has not been. Kept as `loading`, every screen treats the machine as
// still owing its list, which it does.
final hadAgents = machine.agents.isNotEmpty && !machine.agentsFromCache;
machine.agentsRefreshing = hadAgents;
if (!hadAgents) machine.agentLoadStatus = AgentLoadStatus.loading;
machine.agentsLoadError = null;
notifyListeners();
final connection = _conn(machine.machine.machineId);
final deadline = Stopwatch()..start();
// When the list was asked for — what a timeout is measured against, to tell a machine that
// went quiet from one that is answering everything else first (see the catch below).
DateTime? listAskedAt;
debugPrint('agents_list start: ${machine.machine.machineId}');
if (kTypingTrace) {
typingEvent(
'list load ${_shortId(machine.machine.machineId)}: start'
' (had list: $hadAgents)',
);
}
try {
const inventoryTimeout = Duration(seconds: 10);
// ⚠️ **The handshake has its OWN budget, and running out of it is not a
// failure.** These were one ten-second budget shared between waiting for
// the socket and asking through it, which is the single worst mechanism in
// this launch path: a caller that asked before the socket was up spent the
// whole budget waiting, the timeout landed on `agents_list`, the handler
// below read that as the node having gone offline, and `forceReconnect()`
// tore down a socket that was seconds from ready — then the redial did it
// all again. Measured on a cold launch: twelve seconds of
// `Attaching → Disconnected → Attaching → Live` for a machine that had
// answered in two.
//
// Separated, "the socket is not up yet" resolves as what it is — nothing
// has been asked, so nothing has failed. The load simply returns, leaving
// `agentLoadStatus` on `loading`; `_onConnectionStatus` runs it again with
// `force: true` the moment the handshake completes, which is how every
// reconnect in the app already gets its list.
//
// Callers still avoid asking early where they can (see
// `_autoConnectAndLoadMachines`, `_applyNodeStatus`) — this is the floor
// under all of them, not a licence to ignore it.
try {
await StartupTrace.time(
'agents.waitUntilReady',
() => connection.waitUntilReady(timeout: inventoryTimeout),
);
} on WsRequestTimeout {
if (!_machineWorkCurrent(machine, revision)) return;
machine.agentsRefreshing = false;
StartupTrace.mark(
'agents_list deferred: handshake pending '
'${machine.machine.machineId}',
);
notifyListeners();
return;
}
if (!_machineWorkCurrent(machine, revision)) return;
// What the connection spent is subtracted so a machine that is up but slow
// to answer still fails inside a sensible total, with a floor so the
// request always gets a fair hearing of its own.
final remaining = _atLeast(
inventoryTimeout - deadline.elapsed,
_agentsListFloor,
);
final capabilities = _loadTerminalCapabilities(
machine,
connection,
revision,
);
// The terminal on screen first, at launch and on a reconnect — see [_yieldToFocusedTerminal].
// Outside [remaining]: the wait is the phone's choice, not the machine being slow to answer.
await _yieldToFocusedTerminal(machine);
if (!_machineWorkCurrent(machine, revision)) return;
listAskedAt = DateTime.now();
final asked = kTypingTrace ? (Stopwatch()..start()) : null;
if (kTypingTrace) {
typingEvent('list load ${_shortId(machine.machine.machineId)}: ask');
}
final response = await StartupTrace.time(
'agents.list',
() => connection.request(
'agents_list',
payload: kAgentsListPayload,
timeout: remaining,
),
);
if (!_machineWorkCurrent(machine, revision)) return;
final rawAgents = response['agents'] as List<dynamic>? ?? [];
final agents = StartupTrace.timeSync(
'agents.parse ${_shortId(machine.machine.machineId)} '
'(${rawAgents.length} agent(s))',
() => rawAgents
.map((item) => Agent.fromJson(item as Map<String, dynamic>))
.toList(),
);
// Kept for the next launch, as the daemon sent it — see [MachineCache].
//
// ⚠️ Written out HERE, not left to the next refresh. The machine list is
// saved when `/api/machines` lands, which is always before any machine has
// answered with its agents — so a cache that only went out with that save
// would be a launch behind forever, and a first run would never cache
// agents at all. Never awaited: this is for the next launch and must not
// add a disk write to the one in progress.
final cache = _machineCache;
if (cache != null) {
cache.rememberAgents(machine.machine.machineId, [
for (final item in rawAgents)
if (item is Map<String, dynamic>) item,
]);
// Several machines answering together write once: a save asked for while an older one
// still waits replaces it, and the encode is off the UI thread ([MachineCache.save]).
_writeMachineCache(cache);
}
if (asked != null) {
typingEvent(
'list load ${_shortId(machine.machine.machineId)}: answered'
' in ${asked.elapsedMilliseconds}ms (${agents.length} agents)',
);
}
_replaceAgents(machine, agents);
machine.agentLoadStatus = AgentLoadStatus.loaded;
machine.agentsListedAt = DateTime.now();
machine.agentsRefreshing = false;
machine.agentsLoadError = null;
debugPrint(
'agents_list success: ${machine.machine.machineId} '
'(${machine.agents.length} agents)',
);
// Publish discovery immediately. The capability loader attaches waiting
// panes when its reply arrives; either response may finish first.
if (machine.terminalCapabilityLoadInFlight == null) {
// The machine answered its agent list; nobody asked.
_attachPendingPanes(machine, intent: AttachIntent.automatic);
_autoPickFirstAgent();
}
notifyListeners();
await capabilities;
return;
} catch (error) {
if (!_machineWorkCurrent(machine, revision)) return;
machine.agentsRefreshing = false;
final heard = connection.lastHeardFromMachineAt;
if (error is WsRequestTimeout &&
listAskedAt != null &&
heard != null &&
heard.isAfter(listAskedAt)) {
// ⚠️ **Slow, not gone (owner, 2026-10-01).** The machine sealed frames to this connection
// after the list was asked for, so its session is alive and the list is only behind the
// rest of its traffic. Read as offline, this took the machine down — its agents off every
// screen, the one on Home included — and redialled, which started the whole launch over
// on a relay already behind. Nothing is reported; the list is asked again shortly, while
// the cached one, if any, keeps standing in.
machine.agentsLoadError = null;
if (!hadAgents) _askSlowMachineAgain(machine, revision);
} else if (error is WsRequestTimeout) {
machine.agentsLoadError =
'Harness is offline — run harness start on that machine';
_recoverStaleSession(machine, connection);
} else if (connection.isClosed || machine.nodeOnline == false) {
machine.agentsLoadError = 'Could not load harnesses: $error';
} else {
// ⚠️ **The socket dropped mid-request and is already redialling — that
// is not a failure to report, it is a wait to keep waiting.**
//
// `_onDone` rejects every pending waiter with "WS disconnected" and then
// schedules a reconnect, so this branch is reached routinely on a first,
// cold dial. Treated as an error it painted **Disconnected** across a
// machine that was seconds from answering, and `_onConnectionStatus`
// re-requests the list the moment the retry lands anyway — so the error
// was not only wrong, it was about to be replaced by the right screen.
//
// Left null, every surface keeps showing the connecting state it was
// already showing, which is what is actually happening.
machine.agentsLoadError = null;
}
// A NO_PEER_LINK close already set needsLink (via onLocalFailure) perhaps a microtask before
// this catch runs — don't downgrade that specific, actionable state back to a generic error.
//
// A drop that is retrying is left alone for the same reason: `error` there
// would strand the machine on a dead end, when the redial is in flight.
if (!hadAgents &&
machine.agentsLoadError != null &&
machine.agentLoadStatus != AgentLoadStatus.needsLink) {
machine.agentLoadStatus = AgentLoadStatus.error;
}
debugPrint('agents_list failed: ${machine.machine.machineId}: $error');
}
if (!_machineWorkCurrent(machine, revision)) return;
// Order matters: a restored tile for THIS machine claims its agent before
// the first-run convenience gets to look, so the two can never both open.
// Same list, the other branch of its reply.
_attachPendingPanes(machine, intent: AttachIntent.automatic);
_autoPickFirstAgent();
notifyListeners();
}
/// A machine whose list timed out while it was plainly alive — see the catch in
/// [_performMachineDataLoad] — is asked again after a short pause, rather than left to the
/// next sync tick. Only a list never confirmed: a confirmed one stands until that sync.
void _askSlowMachineAgain(MachineState machine, int revision) {
Timer(const Duration(seconds: 2), () {
if (_disposed || !_machineWorkCurrent(machine, revision)) return;
if (machine.agentLoadStatus == AgentLoadStatus.loaded) return;
unawaited(_loadMachineData(machine, force: true));
});
}
/// An RPC timed out on a machine whose transport still calls itself connected:
/// take the machine down and dial it again.
///
/// A request timing out while the local relay session still nominally reports
/// "connected" means the node itself has stopped answering — exactly what a
/// REST-status flip to offline means elsewhere, so it is routed through
/// [_applyNodeStatus] (not just `nodeOnline = false`) so the pending agent gets
/// captured for auto-reattach, same as any other offline detection path.
///
/// ⚠️ **And then a fresh dial, for a remote machine.** The relay's cached
/// upstream session can go stale at the E2EE-session layer without the
/// underlying transport ever closing — most commonly the relayed machine's own
/// Harness process restarting, which drops its in-memory session state but
/// doesn't touch the socket. No close event ever fires, so nothing else would
/// ever notice; without this every future request keeps timing out against the
/// same dead session, for as long as the app runs.
void _recoverStaleSession(MachineState machine, WsConn connection) {
if (machine.nodeOnline != false) {
unawaited(_applyNodeStatus(machine, false));
}
unawaited(connection.forceReconnect());
}
/// A socket that still calls itself open but has stopped bringing anything from its machine:
/// put its terminals down as a dropped socket's are, and dial it again. True when it did; false
/// leaves everything as it was, for the caller's own repair.
///
/// Two callers, one rule each:
/// - a terminal stream quiet for 15s on a socket that heard nothing from the machine in that time
/// ([TerminalSession.onTransportSilent]);
/// - the app back from the background after [resumeRedialAfter], on a socket that heard nothing
/// while it was away ([handleAppResumed]).
///
/// ⚠️ **The sessions go down first, because [WsConn.forceReconnect] does not say so.** It drops
/// the old channel without a close event and dials again reporting `connecting`, which
/// [_onConnectionStatus] — rightly — does not read as a lost socket. Without this, every
/// terminal would stay `controlling` on a stream that left with the old socket, and wait out its
/// own watchdog all over again. Marked lost here, as the `reconnecting` branch there marks them,
/// the new socket's `connected` puts them back: the one on screen through
/// [MachineState.pendingOfflineAgentId], the rest through `_attachPendingPanes`, each in place
/// with its screen kept ([_reattachPane]).
///
/// ⚠️ **Not offline.** The machine may be perfectly fine — it is the phone's own line to the
/// relay that went (a network switch, a tunnel), so this is [_recoverStaleSession]'s redial
/// without its offline flag, which would flash "Offline" over a machine nobody lost.
///
/// ⚠️ **Only a connection that is up and can redial.** One mid-dial is already on its way back,
/// and redialling it would throw that dial away; one that cannot redial
/// ([WsConn.canForceReconnect]) would leave the sessions marked lost with no socket coming.
bool _redialStaleTransport(
MachineState machine,
WsConn connection, {
required String why,
}) {
if (_disposed || !connection.isReady || !connection.canForceReconnect) {
return false;
}
appLog.info(
'ws',
'${_shortId(machine.machine.machineId)}: $why — dialling the relay again',
);
_markSessionsUnreachable(machine, 'Connection lost. Reconnecting…');
notifyListeners();
unawaited(connection.forceReconnect());
return true;
}
bool _machineWorkCurrent(MachineState machine, int revision) =>
_authWorkCurrent(revision) &&
identical(machineStates[machine.machine.machineId], machine);
/// Whether the app has already opened a terminal on its own.
///
/// Once, at startup, and never again: a later refresh must not reopen a
/// terminal the user deliberately closed, and a machine that reconnects
/// mid-session must not yank the pane away from whatever they are watching.
bool _autoPickedAgent = false;
/// Open the first agent on this computer, so the app arrives at work instead
/// of at an instruction.
///
/// "Select a machine, then an agent terminal" is a correct sentence and a
/// poor first screen: in the ordinary case — one computer, agents already
/// running on it — there is exactly one thing the user was going to click.
///
/// Runs after a machine's data load rather than after the machine list,
/// because [selectAgent] refuses on three counts that are only settled by
/// then: the agent must exist, it must have a tmux terminal, and the
/// machine's terminal protocol must have been negotiated. Called on every
/// load and guarded, rather than wired to one specific load, because which
/// machine answers first is not something this side decides.
void _autoPickFirstAgent() {
if (_autoPickedAgent) return;
// V2 opens on the welcome screen; discovering an agent is not a request
// to attach its terminal. Keep the startup gate settled for this run.
_autoPickedAgent = true;
}
/// Ask a machine which engines it has.
///
/// Called when the New Agent dialog opens, not at connect: the answer costs
/// one interactive shell per engine on the far side, and it is only ever
/// looked at in that dialog.
///
/// That caller passes [force], and should: engines come and go through a
/// terminal this app never sees, and an install the dialog itself started
/// invalidates the stored answer as it finishes. Without it the app probes
/// once per run and then insists, for the rest of the session, on what was
/// true when it started. The cache is here to collapse a re-open into one
/// sweep, not to spare the machine the question.
///
/// Deduplicated on [MachineEngines.inFlight] so opening the dialog twice, or
/// reopening it mid-probe, does not start a second sweep. Never throws — a
/// machine that cannot answer leaves every engine unknown, and unknown is
/// rendered as the dialog behaved before this existed.
Future<void> probeEngines(String machineId, {bool force = false}) {
final machine = machineStates[machineId];
if (machine == null) return Future.value();
final existing = machine.engines.inFlight;
if (existing != null) return existing;
if (machine.engines.loaded && !force) return Future.value();
final work = _probeEngines(machine);
machine.engines.inFlight = work;
notifyListeners();
return work;
}
Future<void> _probeEngines(MachineState machine) async {
try {
final result = await _conn(machine.machine.machineId).request(
'engines_probe',
// The engine list travels so a machine only pays for what the dialog
// shows. An older CLI that does not know this request answers with an
// error, which lands in the catch below as "unknown" — never as a wrong
// "not installed", because a CLI predating the feature would otherwise
// report every engine missing and offer to install the ones already
// there.
payload: {'engines': allEngines.map((e) => e.id).toList()},
timeout: const Duration(seconds: 30),
);
final raw = result['engines'];
if (raw is! List) throw const FormatException('engines_probe: no list');
machine.engines.replace(
raw.map(EngineAvailability.fromJson).whereType<EngineAvailability>(),
);
} catch (error) {
// A CLI that predates `engines_probe` refuses it by code; `detail` already
// reads as a sentence when the peer sends one, so prefer it verbatim.
machine.engines.error = error is WsRequestFailure
? (error.detail?.isNotEmpty == true ? error.detail : error.code)
: 'This machine could not report its engines';
} finally {
machine.engines.inFlight = null;
notifyListeners();
}
}
Future<void> _loadTerminalCapabilities(
MachineState machine,
WsConn connection,
int revision,
) {
final pending = machine.terminalCapabilityLoadInFlight;
if (pending != null) return pending;
late final Future<void> load;
load = _readTerminalCapabilities(machine, connection, revision)
.whenComplete(() {
if (identical(machine.terminalCapabilityLoadInFlight, load)) {
machine.terminalCapabilityLoadInFlight = null;
}
});
machine.terminalCapabilityLoadInFlight = load;
return load;
}
/// Read a `terminal_capabilities` reply into [machine].
///
/// Shared by the live negotiation and by the warm start that replays last
/// run's reply from disk, so a cached machine and a freshly negotiated one are
/// described by exactly the same code — a second, parallel reader is how the
/// two would come to disagree about what `available` means.
void _applyTerminalCapabilities(
MachineState machine,
Map<String, dynamic> result,
) {
machine.terminalCapabilityLoaded = true;
machine.terminalCapabilityUnanswered = false;
machine.terminalCapabilityAvailable =
result['protocolVersion'] == TerminalSession.protocolVersion &&
result['backend'] == 'tmux' &&
result['available'] == true;
machine.terminalCapabilityError = machine.terminalCapabilityAvailable
? null
: 'tmux terminal streaming is unavailable';
final features = result['features'];
machine.terminalPasteRawAvailable =
features is Map && features['pasteRaw'] == true;
machine.terminalImagePasteAvailable =
features is Map && features['imagePaste'] == true;
machine.terminalPasteFileAvailable =
features is Map && features['pasteFile'] == true;
machine.mediaPreviewAvailable =
features is Map && features['mediaPreview'] == true;
machine.projectFolderAvailable =
features is Map && features['projectFolder'] == true;
machine.terminalNoTakeoverAvailable =
features is Map && features['noTakeover'] == true;
}
Future<void> _readTerminalCapabilities(
MachineState machine,
WsConn connection,
int revision,
) async {
try {
final result = await connection.request(
'terminal_capabilities',
payload: {'protocolVersion': TerminalSession.protocolVersion},
timeout: const Duration(seconds: 8),
);
if (!_machineWorkCurrent(machine, revision)) return;
_applyTerminalCapabilities(machine, result);
// Kept for the next launch, but only a reply that says the terminal works
// — see [MachineCache.rememberCapabilities]. Written out with the agent
// list, which lands moments later on this same connection.
if (machine.terminalCapabilityAvailable) {
_machineCache?.rememberCapabilities(machine.machine.machineId, result);
}
} catch (error) {
if (!_machineWorkCurrent(machine, revision)) return;
machine.terminalCapabilityLoaded = true;
machine.terminalCapabilityUnanswered = error is! WsRequestFailure;
machine.terminalCapabilityAvailable = false;
machine.terminalCapabilityError = 'Could not negotiate terminal protocol';
machine.terminalPasteRawAvailable = false;
machine.terminalImagePasteAvailable = false;
machine.terminalPasteFileAvailable = false;
machine.mediaPreviewAvailable = false;
machine.projectFolderAvailable = false;
machine.terminalNoTakeoverAvailable = false;
}
if (!_machineWorkCurrent(machine, revision)) return;
if (machine.agentLoadStatus != AgentLoadStatus.loading &&
!machine.agentsRefreshing) {
// Terminal capabilities landed; nobody asked.
_attachPendingPanes(machine, intent: AttachIntent.automatic);
_autoPickFirstAgent();
notifyListeners();
}
}
void _replaceAgents(MachineState machine, List<Agent> agents) {
final previousWork = {for (final agent in machine.agents) agent.id: agent};
agents = [
for (final agent in agents)
retainNewerGitContext(agent, previousWork[agent.id]),
];
// Whatever was here before, this list came from the machine itself — see
// [MachineState.agentsFromCache]. Cleared before the loops below, which are
// exactly the code that retires an agent the cache was wrong about.
machine.agentsFromCache = false;
final nextIds = agents.map((agent) => agent.id).toSet();
final previous = {for (final agent in machine.agents) agent.id: agent};
for (final old in machine.agents.where(
(agent) => !nextIds.contains(agent.id),
)) {
sessionPreviews.removeAgent(machine.machine.machineId, old.id);
// Gone from its machine's list: its kept screen is a terminal nobody can open again.
_keptScreenStore?.remove('${machine.machine.machineId}/${old.id}');
}
for (final agent in agents) {
sessionPreviews.retainAgent(
machine.machine.machineId,
agent.id,
agent.sessionId,
);
_staleIfMoved(machine, previous[agent.id], agent);
}
for (final agentId in machine.processingAgentIds.difference(nextIds)) {
_cancelTurnActivity(machine.machine.machineId, agentId);
}
machine.agents = agents;
final pending = machine.pendingOfflineAgentId;
if (pending != null && !nextIds.contains(pending)) {
machine.pendingOfflineAgentId = null;
_stopOfflineRetry(machine.machine.machineId);
}
if (machine.activeAgentId != null &&
!nextIds.contains(machine.activeAgentId) &&
panesFor(machine.machine.machineId).isEmpty) {
machine.activeAgentId = null;
}
machine.processingAgentIds.removeWhere((id) => !nextIds.contains(id));
machine.sessionAgentIds.clear();
for (final agent in agents) {
final sessionId = agent.sessionId;
if (sessionId != null) machine.sessionAgentIds[sessionId] = agent.id;
}
for (final sessionId in machine.pendingProcessingSessions.toList()) {
final agentId = machine.sessionAgentIds[sessionId];
if (agentId == null) continue;
machine.pendingProcessingSessions.remove(sessionId);
_markAgentProcessing(machine, agentId);
}
// No preview reads from here — see [sessionPreviews].
}
/// [json] is [agent] as the daemon sent it, where the caller has it: kept for the next launch
/// ([_cacheAgentJson]).
///
/// False when it changed nothing — the agent is held already, equal in everything a screen reads
/// ([agentEqual]), with the machine's list loaded and no turn waiting on its session — and then
/// nothing here is touched either. See `agent_synced` in [_handleEvent], the caller that skips
/// its redraw for it.
bool _upsertAgent(
MachineState machine,
Agent agent, {
Map<String, dynamic>? json,
}) {
if (json != null) _cacheAgentJson(machine, json);
final index = machine.agents.indexWhere((item) => item.id == agent.id);
final previous = index == -1 ? null : machine.agents[index];
agent = retainNewerGitContext(agent, previous);
final heldSession = agent.sessionId;
if (previous != null &&
agentEqual(previous, agent) &&
machine.agentLoadStatus == AgentLoadStatus.loaded &&
machine.agentsLoadError == null &&
(heldSession == null ||
(machine.sessionAgentIds[heldSession] == agent.id &&
!machine.pendingProcessingSessions.contains(heldSession)))) {
return false;
}
if (index == -1) {
machine.agents = [...machine.agents, agent];
} else {
machine.agents = [...machine.agents]..[index] = agent;
}
sessionPreviews.retainAgent(
machine.machine.machineId,
agent.id,
agent.sessionId,
);
// Marked, not read: the next screen that asks reads it again — see [sessionPreviews].
_staleIfMoved(machine, previous, agent);
machine.sessionAgentIds.removeWhere((_, id) => id == agent.id);
final sessionId = agent.sessionId;
if (sessionId != null) {
machine.sessionAgentIds[sessionId] = agent.id;
if (machine.pendingProcessingSessions.remove(sessionId)) {
_markAgentProcessing(machine, agent.id);
}
}
machine.agentLoadStatus = AgentLoadStatus.loaded;
machine.agentsLoadError = null;
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;
}
return true;
}
/// False when it changed nothing — no such agent, no name, or the name it already has.
bool _renameAgent(MachineState machine, String agentId, String name) {
final index = machine.agents.indexWhere((agent) => agent.id == agentId);
if (index == -1 || name.trim().isEmpty) return false;
final cleanName = name.trim();
if (machine.agents[index].name == cleanName) return false;
machine.agents = [...machine.agents]
..[index] = machine.agents[index].copyWith(name: cleanName);
// Written with the rest when the app leaves the screen — see [_keepMachineCache].
_machineCache?.renameAgent(machine.machine.machineId, agentId, cleanName);
for (final pane in panesFor(machine.machine.machineId)) {
if (pane.agentId != agentId) continue;
pane.session?.renameAgent(cleanName);
}
return true;
}
Future<void> _removeAgent(MachineState machine, String agentId) async {
machine.agents = machine.agents
.where((agent) => agent.id != agentId)
.toList();
// Out of the next launch's list too, and soon: reopening a harness that is gone is the one
// thing a stale entry would do — see [_saveMachineCacheSoon].
if (_machineCache?.forgetAgent(machine.machine.machineId, agentId) ??
false) {
_saveMachineCacheSoon();
}
sessionPreviews.removeAgent(machine.machine.machineId, agentId);
_keptScreens.remove('${machine.machine.machineId}/$agentId');
_keptScreenStore?.remove('${machine.machine.machineId}/$agentId');
_scrollMemories.remove('${machine.machine.machineId}/$agentId')?.clear();
agentNotices.forgetAgent((
machineId: machine.machine.machineId,
agentId: agentId,
));
machine.sessionAgentIds.removeWhere((_, id) => id == agentId);
machine.agentActivityAt.remove(agentId);
_cancelTurnActivity(machine.machine.machineId, agentId);
if (machine.activeAgentId == agentId) machine.activeAgentId = null;
if (machine.pendingOfflineAgentId == agentId) {
machine.pendingOfflineAgentId = null;
_stopOfflineRetry(machine.machine.machineId);
}
// Every tile showing it, not just the focused one — and without
// `terminal_close`, which would be addressed to an agent the machine has
// already destroyed.
final machineId = machine.machine.machineId;
for (final pane in allPanes.toList()) {
if (pane.machineId != machineId || pane.agentId != agentId) continue;
// Not kept: the agent is deleted, and its screen was just forgotten above.
await _detachSession(pane, sendClose: false, keepScreen: false);
for (final swarm in swarms) {
swarm.remove(pane);
}
}
_persistLayout();
}
String? _eventAgentId(
MachineState machine,
Map<String, dynamic> event,
Map<String, dynamic> payload,
) {
final explicit = payload['agentId'] ?? event['agentId'];
if (explicit is String && explicit.isNotEmpty) return explicit;
final session = payload['sessionId'] ?? event['dbSessionId'];
if (session is! String || session.isEmpty) return null;
return machine.sessionAgentIds[session];
}
String? _eventSessionId(
Map<String, dynamic> event,
Map<String, dynamic> payload,
) {
final session = payload['sessionId'] ?? event['dbSessionId'];
return session is String && session.isNotEmpty ? session : null;
}
/// One session event into [sessionPreviews], as the desktop feeds its own —
/// dropped when it belongs to a session the agent has already moved on from,
/// so a late frame from before a `/clear` cannot write into the new one.
void _ingestPreview(
MachineState machine,
Map<String, dynamic> event,
String type,
Map<String, dynamic> payload,
) {
final agentId = _eventAgentId(machine, event, payload);
final agent = machine.agents
.where((agent) => agent.id == agentId)
.firstOrNull;
if (agent == null) return;
final sessionId = _eventSessionId(event, payload);
if (sessionId != null &&
agent.sessionId != null &&
sessionId != agent.sessionId) {
return;
}
sessionPreviews.ingest(
previewKey(machine.machine.machineId, agent),
type,
payload,
streamingText: agent.engine == 'opencode' || agent.engine == 'kilo',
);
}
String _turnActivityKey(String machineId, String agentId) =>
'$machineId\u0000$agentId';
bool _markAgentProcessing(MachineState machine, String agentId) {
final changed = machine.processingAgentIds.add(agentId);
final key = _turnActivityKey(machine.machine.machineId, agentId);
_turnActivityWatchdogs.remove(key)?.cancel();
_turnActivityWatchdogs[key] = Timer(turnActivityTimeout, () {
_turnActivityWatchdogs.remove(key);
// Closed even when the machine has been replaced under us: this path is
// the only end a stalled turn ever gets, and a stats turn left open would
// sit there until quit and then bank every hour since as work.
stats.onTurnEnded(key);
final current = machineStates[machine.machine.machineId];
if (!identical(current, machine)) return;
if (machine.processingAgentIds.remove(agentId)) notifyListeners();
});
return changed;
}
/// Whether this agent is mid-turn, by the app's own reckoning.
///
/// Fed by `turn_started`/`turn_heartbeat`/`turn_ended` and by the same watchdog that clears a
/// stalled turn, so it answers what the tiles already draw rather than a second opinion.
///
/// Read by the model menu, which disables itself for exactly the agents the CLI would refuse with
/// AGENT_BUSY. It is deliberately NOT authoritative: only the CLI inspects the pane, and a turn
/// can begin between a build and a tap. This spares the user the round trip in the common case;
/// the refusal remains the thing that guarantees no turn is lost.
bool agentIsProcessing(String machineId, String agentId) =>
machineStates[machineId]?.processingAgentIds.contains(agentId) ?? false;
// ── blocked agents ────────────────────────────────────────────────────────
/// The question this agent stopped on, if it is waiting for one.
///
/// Read by the tile, which rings itself while its agent is blocked. That ring
/// is the whole surface: an agent asking something is a fact about the pane
/// you are looking at, not a queue to be worked through somewhere else.
PendingQuestion? questionFor(String machineId, String agentId) =>
machineStates[machineId]?.blockedAgents[agentId];
void _cancelTurnActivity(String machineId, String agentId) {
final key = _turnActivityKey(machineId, agentId);
_turnActivityWatchdogs.remove(key)?.cancel();
// Every ordinary end of a turn comes through here — `turn_ended`, a
// disconnect, a deleted agent — so this is where the clock stops. An end for
// a turn this process never saw start contributes nothing (see
// `HarnessStats.onTurnEnded`), which is what makes the disconnect sweep safe.
stats.onTurnEnded(key);
final machine = machineStates[machineId];
machine?.processingAgentIds.remove(agentId);
// A question cannot outlive its own turn — the daemon's watcher says the
// same thing from the other end, tearing down and announcing a close when
// the turn ends. Clearing here as well means the row cannot survive a close
// frame that was dropped, and this is also the path a deleted agent takes.
machine?.blockedAgents.remove(agentId);
}
void _clearMachineActivity(MachineState machine) {
for (final agentId in machine.processingAgentIds.toList()) {
_cancelTurnActivity(machine.machine.machineId, agentId);
}
machine.processingAgentIds.clear();
machine.pendingProcessingSessions.clear();
machine.blockedAgents.clear();
}
void _clearAllTurnActivity() {
for (final timer in _turnActivityWatchdogs.values) {
timer.cancel();
}
_turnActivityWatchdogs.clear();
for (final machine in machineStates.values) {
machine.processingAgentIds.clear();
machine.pendingProcessingSessions.clear();
machine.blockedAgents.clear();
}
}
Future<void> reloadMachineData(String machineId) async {
final machine = machineStates[machineId];
if (machine == null) return;
_connectMachine(machine);
await _loadMachineData(machine, force: true);
}
/// Dial and re-ask every machine on the account whose list is not already current, whatever the
/// account last said about any of them.
///
/// ⚠️ **Not the ones already current, nor the ones waiting for a password (owner, 2026-10-02).**
/// Every opening of Find asked every machine for its whole agent list again — stopped work
/// included, 1.1–1.4s and ~400KB for 167 agents, decrypted and parsed on the phone — though a
/// machine on a live socket keeps its list current by itself: `agent_synced`, `agent_created`,
/// `agent_deleted` and the turn events land as they happen, and [_syncAgentsIfChanged] re-reads
/// it every [agentSyncInterval] to catch what they miss. So a machine that answered over the
/// socket it is on now, within that interval and a margin, is left as it is ([_listStillCurrent]);
/// everything this method was written for — a machine launch skipped, one not answering, one back
/// from a dropped socket — has no such answer, and is asked as before. A machine that refused this
/// phone for want of a link is not dialled again: a password, a code or the group dials it the
/// moment one lands (`connectWithPassword`, `_afterGroupSync`, `_redialNewlyTrusted`), and until
/// then a dial can only be refused again.
///
/// For the screen that offers the whole fleet in one list — the search, which
/// is the one place somebody asks "where is that agent" without knowing which
/// machine holds it, and so the one place a missing machine is a wrong answer
/// rather than a shorter list.
///
/// ⚠️ **This deliberately dials machines [_autoConnectAndLoadMachines]
/// skipped.** Not dialling a machine the account reported down is right at
/// launch — finding out costs the full inventory budget EACH, and four dead
/// machines held the screen ten seconds apiece — and wrong here. That status
/// is a snapshot from before the app was opened; a machine that has come up
/// since contributes nothing, because [agentIndex] lists only a machine that
/// is answering. Reported as "it only shows the sessions on one machine".
///
/// ⚠️ Contrast [_canFetchPreview], which must never dial, and still must not.
/// That one is per AGENT — dozens of reads, each able to wake a relay socket
/// for one row's subtitle. This is one `agents_list` per machine, and the
/// list is what the search has nothing to offer without.
///
/// ⚠️ **No `/api/machines` round trip.** It asks the machines the app already
/// knows, so a phone on two bars still reaches all of them; an account fetch
/// that failed would otherwise take the dials down with it, which is exactly
/// what [retryMachines] does when it returns early. A machine ADDED to the
/// account since launch is therefore not found here — it arrives through the
/// Machines tab's pull-to-refresh, the screen whose job is listing them.
///
/// Nothing on screen waits for this: each machine publishes as it answers,
/// and the rows already drawn keep their places — the search ranks on the
/// visit history and the name, neither of which a late-answering machine
/// moves. See [PhoneSearchHistory] and `rankPhoneDestinations`.
Future<void> reachAllMachines() async {
// No transport yet — before sign-in, or in a test with no fake connection.
// The same guard [_canFetchPreview] uses, and for the same reason: `_conn`
// would build one out of a null pool.
if (_disposed || (_pool == null && connectionForTest == null)) return;
final reaching = kTypingTrace ? (Stopwatch()..start()) : null;
// Somebody is looking for a session, on any machine: the launch's hold is over — see
// [_launchMachineId]. Before the reloads below, so the held ones dial with the rest.
_releaseHeldMachines('search opened', atOnce: true);
final now = DateTime.now();
final asking = <String>[];
var current = 0;
var locked = 0;
var off = 0;
for (final machine in machines) {
final state = machineStates[machine.machineId];
if (state != null && state.needsLink) {
locked++;
} else if (state != null && _listStillCurrent(state, now)) {
current++;
} else if (_relaySaysOffline(machine.machineId, now)) {
// ⚠️ **Not dialled: the relay has just said it is off**, and a dial would only hear that
// again — a token, an end-to-end session and a socket for each, all on this thread while
// Find draws itself (four of them measured under a 936ms frame, 2026-10-05). Its list
// stays the one the phone has; once the relay says it is back, the next Find asks it.
off++;
} else {
asking.add(machine.machineId);
}
}
appLog.info(
'search',
'Find asks ${asking.length} machine(s) for their lists · '
'$current current already, $locked waiting for a password, $off offline',
);
final reloads = Future.wait([
for (final machineId in asking) reloadMachineData(machineId),
]);
if (reaching != null) {
typingEvent(
'find reach: ${asking.length} asked, $off offline skipped'
' — ${reaching.elapsedMilliseconds}ms on this thread before the replies',
);
}
await reloads;
}
/// Whether [state]'s list was answered over the socket it is on now, recently enough that the
/// pushes since have kept it current — see [reachAllMachines].
bool _listStillCurrent(MachineState state, DateTime now) {
final listedAt = state.agentsListedAt;
// Asked first, so a machine with no answer yet never reaches [_connectionReady].
if (listedAt == null) return false;
return state.agentLoadStatus == AgentLoadStatus.loaded &&
!state.agentsFromCache &&
state.connectionStatus == ConnectionStatus.connected &&
_connectionReady(state.machine.machineId) &&
now.difference(listedAt) < agentSyncInterval + _listCurrentMargin;
}
/// How far past one [agentSyncInterval] a list still counts as current: a sync tick lands a little
/// late, or a slow machine answers it late, and that is not a list gone stale.
static const _listCurrentMargin = Duration(seconds: 30);
/// What every connected machine's agent accounts have spent, asked in
/// parallel and read there with that machine's own credentials (`usage_read`).
///
/// A machine may be signed in to a different subscription, and a rate limit
/// belongs to an account rather than a computer, so the only honest way to
/// show that one is to ask the machine that holds it.
///
/// ⚠️ **A machine whose CLI predates `usage_read` does not refuse it — it goes
/// silent.** The frame reaches it as an E2EE envelope it does not know to
/// open, so the requestId inside is never read and nothing replies. That is a
/// timeout, not an `UNSUPPORTED`, which is why this asks with a short one and
/// treats every failure alike: a machine that cannot say has nothing to add,
/// and it must never hold up the figures of the ones that can.
Future<List<MachineUsage>> readRemoteUsage({String? machineId}) async {
final remotes = [
for (final machine in machineStates.values)
if (machine.connectionStatus == ConnectionStatus.connected &&
(machineId == null || machine.machine.machineId == machineId))
machine,
];
final answers = await Future.wait([
for (final machine in remotes) _readMachineUsage(machine),
]);
return [for (final answer in answers) ?answer];
}
Future<MachineUsage?> _readMachineUsage(MachineState machine) async {
try {
final reply = await _conn(machine.machine.machineId)
.request('usage_read', timeout: const Duration(seconds: 10));
final readings = parseUsageReadResult(reply);
if (readings.isEmpty) return null;
return MachineUsage(
machineName: machine.machine.displayName,
readings: readings,
);
} catch (_) {
return null;
}
}
/// Media uses the existing machine-scoped, encrypted file RPC. It is never
/// queued for a disconnected machine or resolved against this app's cwd.
Future<Map<String, dynamic>> readRemoteMediaChunk(
String machineId,
String agentId,
String target, {
required int offset,
String? revision,
}) async {
final machine = machineStates[machineId];
if (machine == null ||
machine.needsLink ||
machine.nodeOnline == false ||
machine.connectionStatus != ConnectionStatus.connected) {
throw const RemoteMediaException(
'This machine is disconnected. Reconnect and try opening the preview again.',
);
}
if (!machine.mediaPreviewAvailable) {
throw const RemoteMediaException(
'Update the Harness CLI on this remote machine to open image and video previews.',
);
}
final connection = _conn(machineId);
if (!connection.isReady) {
throw const RemoteMediaException(
'This machine is disconnected. Reconnect and try opening the preview again.',
);
}
try {
return await connection.request(
'agent_read_file',
payload: {
'agentId': agentId,
'path': target,
'media': true,
'offset': offset,
'revision': ?revision,
},
timeout: const Duration(seconds: 15),
);
} on WsRequestFailure catch (error) {
throw RemoteMediaException(switch (error.code) {
'MEDIA_NOT_FOUND' || 'NOT_FOUND' => 'This file is no longer available on the remote machine. It may have moved or been deleted.',
'MEDIA_TOO_LARGE' => 'Remote previews support files up to 512 MB. Use a smaller export or transfer this file separately.',
'MEDIA_CHANGED' => 'The file changed while downloading. Wait for it to finish generating and try again.',
'MEDIA_UNSUPPORTED' => 'This file is not a supported image or video.',
'MEDIA_INVALID_REQUEST' => 'This file is outside the folders Harness reads for this harness. Use one in its working folder or a temp folder.',
'AGENT_NOT_FOUND' =>
'This harness is no longer available. Reconnect and try again.',
'NOT_TEXT' || 'FILE_TOO_LARGE' => 'Update the Harness CLI on this remote machine to open media previews.',
_ => 'The remote machine could not read this file. Check that it is accessible and try again.',
});
} catch (_) {
throw const RemoteMediaException(
'The media download was interrupted. Check the connection and try again.',
);
}
}
/// One-level directory listing on the remote machine, for the New Agent folder browser.
/// Returns `{path, entries: [{name, isDir}], truncated}` or `{error}` — the caller renders both.
Future<Map<String, dynamic>> listRemoteFolder(
String machineId,
String? path,
) async {
final connection = _conn(machineId);
try {
return await connection.request(
'fs_list_dir',
payload: {
...?path == null ? null : {'path': path},
},
timeout: const Duration(seconds: 10),
);
} catch (error) {
return {'error': 'UNREACHABLE'};
}
}
/// The Git choices [path] offers, read ON the machine that owns it.
///
/// ⚠️ **The phone never looks at a repository itself, and could not.** The
/// folder is on somebody's laptop; `git` runs there. The desktop has a local
/// branch of this same call for its own machine — see `readGitProject` there
/// — and this is the half that is always remote.
///
/// Answers `{isGit, branch, branches: [...], defaultRef, root, ...}`, parsed
/// by [GitProjectInfo.fromJson], or `{error}` — which the form draws as "no
/// Git choices here" rather than as a failure, because a folder that is not a
/// repository answers the same way.
///
/// A short timeout on purpose: this runs while somebody is looking at a form
/// they have already half filled in, and a machine that cannot answer in six
/// seconds should leave the rest of the form working.
/// Machines whose daemon can be asked what was said in their sessions now — connected, never
/// dialled for it: a search must not be what wakes a relay socket.
Iterable<String> get searchableMachineIds => [
for (final machine in machineStates.values)
if (machine.connectionStatus == ConnectionStatus.connected &&
!machine.needsLink &&
machine.nodeOnline != false)
machine.machine.machineId,
];
/// The computers whose services can be connected from this phone: linked and online. Their
/// daemon answers `connectors` for the account's owner only, end to end encrypted.
List<MachineState> get connectorMachines => [
for (final machine in machineStates.values)
if (!machine.needsLink && machine.nodeOnline != false) machine,
];
/// `connectors` on [machineId] (cli/src/services/connectors.ts): `list`, `connect`, `flow`,
/// `callback`, `disconnect`. A machine that cannot answer reads as `{error: UNAVAILABLE}`.
/// Set by the phone shell: opens a page a harness's program asked for (`browser_open`,
/// phone/browser_handoff.dart).
void Function(String machineId, String agentId, String url)? onBrowserOpen;
/// Hands a sign-in this phone caught back to [machineId], to the program waiting for it there
/// (`browser_callback`, cli core/terminals/browser.ts). `{'error': 'UNAVAILABLE'}` when the line is down.
Future<Map<String, dynamic>> browserCallback(
String machineId,
String url,
) async {
final machine = machineStates[machineId];
if (machine == null || machine.needsLink) return {'error': 'UNAVAILABLE'};
try {
return await _conn(machineId)
.request('browser_callback', payload: {'url': url});
} catch (_) {
return {'error': 'UNAVAILABLE'};
}
}
/// A Harness OS computer, managed from here (CLI services/osDevice.ts): `status`, `update`,
/// `wifi_scan`, `wifi_join` {ssid, password}, `wifi_result`. `{error: 'UNAVAILABLE'}` while it
/// cannot be reached — as it is for a while after `update` and `wifi_join`.
Future<Map<String, dynamic>> osDevice(
String machineId,
Map<String, dynamic> payload, {
Duration timeout = const Duration(seconds: 25),
}) async {
final machine = machineStates[machineId];
if (machine == null || machine.needsLink) return {'error': 'UNAVAILABLE'};
try {
return await _conn(machineId)
.request('os_device', payload: payload, timeout: timeout);
} catch (_) {
return {'error': 'UNAVAILABLE'};
}
}
/// What each computer's `os_device` `status` said: whether it runs Harness OS, its update and its
/// Wi-Fi. Asked again at most every few minutes ([refreshOsStatus]).
final Map<String, Map<String, dynamic>> osStatus = {};
final Map<String, DateTime> _osAsked = {};
bool runsHarnessOs(String machineId) =>
osStatus[machineId]?['harnessOs'] == true;
/// What a Harness OS computer's daemon does for a phone beyond its update and Wi-Fi, as its status
/// says (CLI osDevice.ts `features`): `sign_out`, `password`, `ssh`, `github`, `check_update`, and
/// `computer_use` on one that carries them. An older one says none.
bool osFeature(String machineId, String feature) {
final features = osStatus[machineId]?['features'];
return features is List && features.contains(feature);
}
bool updateAvailable(String machineId) {
final update = osStatus[machineId]?['update'];
if (update is! Map || update['available'] != true) return false;
final parts = osParts(machineId);
// Named part by part: only what changes. A computer that does not name its parts says it whole.
if (parts.isEmpty) return true;
return osNewRelease(machineId) ||
parts['hn']?['available'] == true ||
parts['cli']?['available'] == true;
}
/// A Harness OS release newer than the one running — 0.1.9 after 0.1.8, not a later build of
/// 0.1.8, which a computer on 0.1.8 still offers (os/release_update.py compared whole packages).
bool osNewRelease(String machineId) {
final os = osParts(machineId)['os'];
if (os?['available'] != true) return false;
final next = os?['next'] as String?, running = os?['running'] as String?;
return next == null ||
running == null ||
releaseOf(next) != releaseOf(running);
}
/// A package version as its release: `0.1.8.r1792577066.g8df82cc2bc-1` is `0.1.8`.
static String releaseOf(String version) =>
RegExp(r'^\d+\.\d+\.\d+').firstMatch(version)?.group(0) ?? version;
/// Each part of a Harness OS computer, as its last status said (CLI osDevice.ts `update.parts`):
/// `os`, `hn`, `cli`, each `{running, available, next}`. Empty from a computer that does not say.
Map<String, Map<String, dynamic>> osParts(String machineId) {
final update = osStatus[machineId]?['update'];
final parts = update is Map ? update['parts'] : null;
if (parts is! Map) return const {};
return {
for (final entry in parts.entries)
if (entry.key is String && entry.value is Map)
entry.key as String: Map<String, dynamic>.from(entry.value as Map),
};
}
/// The update waiting needs the computer restarted: a new OS package, or one applied already that
/// is waiting for its restart. hn and the CLI alone do not.
bool updateRestarts(String machineId) {
final update = osStatus[machineId]?['update'];
if (update is! Map) return false;
if (update['restartRequired'] == true) return true;
return osNewRelease(machineId);
}
static const _harnessOsKey = 'harness_os_computers';
/// The Harness OS computers this phone has seen, kept between launches: the hotspot each opens and
/// whether its disk is encrypted. A computer switched off and on again is offline to the account,
/// waiting at its password; this is how the phone still knows to offer Unlock there.
final Map<String, ({String hotspot, bool encrypted})> harnessOsComputers = {};
Future<void> _loadHarnessOsComputers() async {
try {
final stored = await _paneLayout?.storage.read(_harnessOsKey);
if (stored == null || _disposed) return;
final decoded = jsonDecode(stored);
if (decoded is! Map) return;
for (final entry in decoded.entries) {
final value = entry.value;
if (entry.key is! String ||
value is! Map ||
value['hotspot'] is! String) {
continue;
}
harnessOsComputers[entry.key as String] = (
hotspot: value['hotspot'] as String,
encrypted: value['encrypted'] == true,
);
}
notifyListeners();
} catch (_) {
// Unreadable: learned again from each computer's next status.
}
}
void _rememberHarnessOs(String machineId, Map<String, dynamic> status) {
final hotspot = status['hotspot'];
if (status['harnessOs'] != true || hotspot is! String || hotspot.isEmpty) {
return;
}
final next = (hotspot: hotspot, encrypted: status['encrypted'] == true);
if (harnessOsComputers[machineId] == next) return;
harnessOsComputers[machineId] = next;
_saveHarnessOs();
}
/// Signed out from here: no Unlock for it any more. Its unlock would open the disk of a computer
/// that is set up again — with a sign-in, Set up Intern 3 — before it is online anywhere.
void forgetHarnessOs(String machineId) {
if (harnessOsComputers.remove(machineId) == null) return;
_saveHarnessOs();
notifyListeners();
}
void _saveHarnessOs() {
final json = jsonEncode({
for (final entry in harnessOsComputers.entries)
entry.key: {
'hotspot': entry.value.hotspot,
'encrypted': entry.value.encrypted,
},
});
unawaited(
_paneLayout?.storage.write(_harnessOsKey, json).catchError((_) {}),
);
}
/// Asks [machineId] what it is and whether it has an update, unless asked lately ([force] asks now).
Future<void> refreshOsStatus(String machineId, {bool force = false}) async {
final asked = _osAsked[machineId];
if (!force &&
asked != null &&
DateTime.now().difference(asked) < const Duration(minutes: 5)) {
return;
}
_osAsked[machineId] = DateTime.now();
final status = await osDevice(machineId, {'action': 'status'});
// An older CLI answers it UNSUPPORTED/SERVICE_UNAVAILABLE: not Harness OS as far as the phone knows.
if (status['error'] == 'UNAVAILABLE') {
_osAsked.remove(machineId);
return;
}
osStatus[machineId] = status;
_rememberHarnessOs(machineId, status);
notifyListeners();
}
/// The machine the Swarm was last asked through, kept while it stays up so the reads of one
/// screen do not hop between computers.
String? _swarmMachineId;
/// Machines that refused a Swarm read another machine then answered: passed over until they
/// reconnect ([_onConnectionStatus]).
///
/// ⚠️ Kept up, a refusing machine was asked for every read. On the owner's iPhone (2026-10-27)
/// the phone moved to a Team sign-in computer while the owner's Mac was briefly offline, then
/// read through it from 14:26 to 14:37 while the server refused every read, the Mac connected
/// all along — until the Team computer itself was marked offline.
final _swarmRefused = <String>{};
/// How long a Swarm call waits for a computer on its way back — a socket redialling — before it
/// says there is none.
@visibleForTesting
Duration swarmReconnectWait = const Duration(seconds: 8);
/// The machine the phone asks the Swarm through: one of the account's own whose socket is up —
/// the one asked last while it stays so, else the first by id, as the web build picks
/// (`desktop/lib/state/app_state.dart` `sharedTabsTarget`) — never one that refused. Null with
/// none up, or none but those in [except].
MachineState? _swarmMachine({Set<MachineState> except = const {}}) {
bool usable(MachineState? machine) =>
machine != null &&
!except.contains(machine) &&
machine.connectionStatus == ConnectionStatus.connected &&
!machine.needsLink &&
machine.nodeOnline != false &&
!_swarmRefused.contains(machine.machine.machineId);
final kept = machineStates[_swarmMachineId];
if (usable(kept)) return kept;
MachineState? best;
for (final machine in machineStates.values) {
if (!usable(machine)) continue;
if (best == null ||
machine.machine.machineId.compareTo(best.machine.machineId) < 0) {
best = machine;
}
}
// Looking past [except] chooses nothing yet: the read through it decides.
if (except.isEmpty) _swarmMachineId = best?.machine.machineId;
return best;
}
/// One Swarm backend call ([method] on [path], `/api/super-tabs…`). Answers the backend's value;
/// a refusal — the backend's, the machine's, or none to ask — is a [SuperTabFailure], and an
/// answer that lands after the account changed is dropped.
///
/// A read goes straight to the backend with the phone's own sign-in
/// ([ApiClient.swarmRead]), as the web build's does: on the iPhone (2026-10-31) a launch's first
/// list took 9 seconds through the machines, 6 of them on a Team sign-in's refusals and the wait
/// for the next machine, where the same backend answers the phone in 400 ms. What the backend
/// refuses stands, being about this person; with no answer, or one that says nothing of them
/// ([_swarmReadTriesMachine]), the read goes on through a machine as below.
///
/// Writes also go straight to the backend with the phone's sign-in. Only unavailable transport
/// or server responses fall back to a machine; write refusals stand. In-flight writes are
/// cancelled on account change, including bearer-refresh retries. The unchanged body keeps
/// each command's operation ID across every path.
///
/// A fallback uses one of the account's own machines with its session (`super_tabs`,
/// `action: backend`, cli/src/superTabs/service.ts): the machine checks that this connection
/// is its owner's, and the backend what that account may read or write.
///
/// A refusal is asked again through each other machine that is up, one after another, up to
/// [_swarmAsksPerCall] in all. One that answers shows the refusals before it were those
/// machines' own — a Team sign-in the server will not read the person's Swarm for, say — and
/// they are passed over until they reconnect. Refusals alone pass over none: on #1802's review
/// a Team computer's refusal of its own once passed over the Mac that had said the person left
/// the Swarm. A command asked twice is the same command, under its operation id.
///
/// With none answering, a refusal saying the person lost the Swarm stands over every other,
/// as everywhere: what was read of it must go. Otherwise, with no other machine up to ask, one
/// on its way back is waited for as below. With none, refusals from every machine up while
/// another of the account's is away tell nothing yet: no computer, so the list is read again
/// and Swarm soon retries ([SwarmInbox]). On the owner's iPhone (2026-10-27, 15:06) Swarm
/// showed a Team sign-in's refusal instead, and stayed on it until its next 15-second read,
/// 14 seconds after the Mac was back. With no other machine of the account, the last refusal
/// is the read's own.
///
/// Nor is one read lost on the way — a timeout, a socket dropped — the end of it: it is asked
/// again through another computer that is up. With none up but one redialling, the call waits
/// [swarmReconnectWait] for it: Swarm said "Connect one of your computers" for 10 to 25 seconds
/// at a time on the owner's iPhone (2026-10-27) while the computer stayed connected.
Future<Object?> swarmRequest(
String method,
String path, {
Map<String, dynamic>? body,
}) async {
final revision = _authRevision;
void stillThisAccount() {
if (!_authWorkCurrent(revision)) {
throw const SuperTabFailure(
'ACCOUNT_CHANGED',
'The account changed. Open Swarm again.',
);
}
}
if (method == 'GET') {
try {
final value = await api.swarmRead(path);
stillThisAccount();
_swarmReadFailed = false;
return value;
} on SuperTabFailure catch (refusal) {
stillThisAccount();
if (!_swarmReadTriesMachine(refusal)) rethrow;
_swarmReadGoesOn(refusal);
} catch (error) {
stillThisAccount();
_swarmReadGoesOn(error);
}
}
if (method == 'POST') {
final cancel = CancelToken();
_swarmWritesGoing.add(cancel);
try {
final value = await api.swarmWrite(path, body: body, cancel: cancel);
stillThisAccount();
return value;
} on SuperTabFailure catch (refusal) {
stillThisAccount();
// A write refusal belongs to this person. Never retry an expired
// sign-in, denied access or rate limit with a machine's credentials.
if (refusal.statusCode != 0 && refusal.statusCode < 500) rethrow;
} catch (_) {
stillThisAccount();
} finally {
_swarmWritesGoing.remove(cancel);
}
appLog.warn(
'swarm',
'Swarm write could not reach the backend, asking a machine',
);
}
var machine = _swarmMachine() ?? await _swarmMachineBack();
stillThisAccount();
if (machine == null) throw _swarmNoComputer();
final asked = <MachineState>{}, refused = <MachineState>[];
SuperTabFailure? lost;
late Object failure;
late StackTrace trace;
while (machine != null) {
stillThisAccount();
asked.add(machine);
try {
final value = await _swarmRequestVia(machine, method, path, body);
_swarmRefused.addAll([for (final m in refused) m.machine.machineId]);
_swarmMachineId = machine.machine.machineId;
return value;
} on SuperTabFailure catch (refusal, stack) {
if (refusal.code == 'ACCOUNT_CHANGED') rethrow;
(failure, trace) = (refusal, stack);
refused.add(machine);
if (const {'FORBIDDEN', 'NOT_FOUND'}.contains(refusal.code)) {
lost ??= refusal;
}
} catch (error, stack) {
(failure, trace) = (error, stack);
}
if (asked.length == _swarmAsksPerCall) break;
machine =
_swarmMachine(except: asked) ??
(failure is SuperTabFailure
? await _swarmMachineBack(except: asked)
: null);
}
stillThisAccount();
if (lost != null) throw lost;
if (machine == null &&
failure is SuperTabFailure &&
_swarmAnyOther(asked)) {
throw _swarmNoComputer();
}
Error.throwWithStackTrace(failure, trace);
}
/// Whether a machine might still read what the phone's own read could not: the backend was not
/// there to say (no status, a 5xx), or its answer was about this sign-in or this phone, not about
/// what the person may read (an expired session, a rate limit, a session of a limited kind).
static bool _swarmReadTriesMachine(SuperTabFailure refusal) =>
refusal.statusCode == 0 ||
refusal.statusCode >= 500 ||
refusal.statusCode == 401 ||
refusal.statusCode == 429 ||
refusal.code == 'TEAM_SESSION_LIMITED';
/// Whether the phone's own reads are failing: logged as they start to, not once per read.
bool _swarmReadFailed = false;
void _swarmReadGoesOn(Object failure) {
if (_swarmReadFailed) return;
_swarmReadFailed = true;
appLog.warn(
'swarm',
'Swarm read from the backend failed, asking a machine',
error: failure,
);
}
/// Sends one Swarm chat file to the backend ([SwarmUpload]): straight from this phone with its own
/// sign-in ([ApiClient.uploadSwarmAttachment]), with no machine fallback — the
/// backend takes a chat file only from the client, and a machine forwards only JSON. An answer
/// that lands after the account changed is dropped, and a sign-out or another sign-in stops the
/// upload where it is ([_invalidateAuthWork]).
Future<Map<String, dynamic>> swarmUpload({
required String tabId,
required String conversationId,
required String name,
required String mime,
required SwarmOutgoingFile file,
required CancelToken cancel,
required void Function(double sent) onProgress,
}) async {
final revision = _authRevision;
void stillThisAccount() {
if (!_authWorkCurrent(revision)) {
throw const SuperTabFailure(
'ACCOUNT_CHANGED',
'The account changed. Open Swarm again.',
);
}
}
// A token of this sign-in's, which the chat's [cancel] also ends.
final going = CancelToken();
_swarmUploadsGoing.add(going);
unawaited(cancel.whenCancel.then((_) => going.cancel('given up')));
try {
final answer = await api.uploadSwarmAttachment(
tabId: tabId,
conversationId: conversationId,
name: name,
mime: mime,
file: file,
cancel: going,
onProgress: onProgress,
// A file large enough to go up in steps stops between them once the
// account changed: no step is taken for the next one.
stillWanted: () => _authWorkCurrent(revision),
);
stillThisAccount();
return answer;
} catch (_) {
stillThisAccount();
rethrow;
} finally {
_swarmUploadsGoing.remove(going);
}
}
/// JSON writes cancelled before another account can refresh or retry them.
final _swarmWritesGoing = <CancelToken>{};
/// The chat file uploads of this sign-in on their way ([swarmUpload]).
final _swarmUploadsGoing = <CancelToken>{};
/// How many machines one Swarm call asks at most, one after another.
static const _swarmAsksPerCall = 5;
/// No computer to ask the Swarm through, with the list read again.
SuperTabFailure _swarmNoComputer() {
_swarmListAgain();
return const SuperTabFailure(
'MACHINE_UNAVAILABLE',
'Connect one of your computers to open Swarm.',
);
}
/// Another of the account's machines than those [asked] could be asked once it is up: linked,
/// and not passed over.
bool _swarmAnyOther(Set<MachineState> asked) => machineStates.values.any(
(other) =>
!asked.contains(other) &&
!other.needsLink &&
!_swarmRefused.contains(other.machine.machineId),
);
/// When the computer list was last read again for Swarm: at most once in [_swarmListGap].
DateTime? _swarmListedAt;
static const _swarmListGap = Duration(seconds: 2);
/// No computer to ask: the list is read again, as a refresh by hand would. What it says of each
/// one can be stale — a computer reported off at launch whose socket waits parked for a word
/// that it is back — and with any socket up, nothing else reads it again ([_rereadMachinesWhileDeaf]).
/// Swarm's own retries set the pace ([SwarmInbox]).
void _swarmListAgain() {
final now = DateTime.now();
final last = _swarmListedAt;
if (last != null && now.difference(last) < _swarmListGap) return;
_swarmListedAt = now;
_rereadMachines();
}
/// A computer that comes up within [swarmReconnectWait], when one is on its way: dialling or
/// redialling, linked, not reported off, and not passed over — nor in [except]. Null otherwise.
Future<MachineState?> _swarmMachineBack({
Set<MachineState> except = const {},
}) async {
bool coming(MachineState machine) =>
!except.contains(machine) &&
(machine.connectionStatus == ConnectionStatus.connecting ||
machine.connectionStatus == ConnectionStatus.reconnecting) &&
!machine.needsLink &&
machine.nodeOnline != false &&
!_swarmRefused.contains(machine.machine.machineId);
if (!machineStates.values.any(coming)) return null;
final back = Completer<MachineState?>();
void look() {
if (back.isCompleted) return;
final machine = _swarmMachine(except: except);
if (machine != null || !machineStates.values.any(coming)) {
back.complete(machine);
}
}
addListener(look);
final timer = Timer(swarmReconnectWait, () {
if (!back.isCompleted) back.complete(null);
});
try {
return await back.future;
} finally {
timer.cancel();
removeListener(look);
}
}
Future<Object?> _swarmRequestVia(
MachineState machine,
String method,
String path,
Map<String, dynamic>? body,
) async {
final revision = _authRevision;
void stillThisAccount() {
if (!_authWorkCurrent(revision)) {
throw const SuperTabFailure(
'ACCOUNT_CHANGED',
'The account changed. Open Swarm again.',
);
}
}
final Map<String, dynamic> answer;
try {
answer = await _conn(machine.machine.machineId).request(
'super_tabs',
payload: {
'action': 'backend',
'method': method,
'path': path,
'body': ?body,
},
timeout: const Duration(seconds: 30),
);
} on WsRequestFailure catch (failure) {
stillThisAccount();
throw SuperTabFailure(
failure.code,
failure.detail ?? 'Could not reach this Swarm.',
);
} catch (_) {
stillThisAccount();
rethrow;
}
stillThisAccount();
if (answer['error'] != null) {
throw SuperTabFailure(
answer['error'].toString(),
answer['detail'] as String? ?? 'Could not reach this Swarm.',
statusCode: (answer['status'] as num?)?.toInt() ?? 0,
);
}
return answer['value'];
}
/// Asks the account's own computer [machineId] a Swarm question of its own
/// (`super_tabs`), such as preparing a Buddy's folder there
/// (`prepareContribution`, as the desktop's `prepareBuddyMachine` asks it).
/// A refusal throws; so does an account change while it was asked.
Future<Map<String, dynamic>> swarmAskComputer(
String machineId,
Map<String, dynamic> payload,
) async {
final machine = machineStates[machineId];
if (machine == null || machine.needsLink) {
throw const SuperTabFailure(
'MACHINE_UNAVAILABLE',
'This computer is not connected. Open Harness on it, then try again.',
);
}
final revision = _authRevision;
void stillThisAccount() {
if (!_authWorkCurrent(revision)) {
throw const SuperTabFailure(
'ACCOUNT_CHANGED',
'The account changed. Open Swarm again.',
);
}
}
final Map<String, dynamic> answer;
try {
answer = await _conn(machineId).request(
'super_tabs',
payload: payload,
timeout: const Duration(seconds: 30),
);
} on WsRequestFailure catch (failure) {
stillThisAccount();
throw SuperTabFailure(
failure.code,
failure.detail ?? 'Could not reach this computer.',
);
}
stillThisAccount();
return answer;
}
Future<Map<String, dynamic>> connectors(
String machineId,
Map<String, dynamic> payload, {
Duration timeout = const Duration(seconds: 30),
}) async {
final machine = machineStates[machineId];
if (machine == null || machine.needsLink) return {'error': 'UNAVAILABLE'};
try {
return await _conn(machineId)
.request('connectors', payload: payload, timeout: timeout);
} catch (_) {
return {'error': 'UNAVAILABLE'};
}
}
/// Every turn of every session on [machineId], searched by its daemon (`session_search`,
/// cli/src/lib/sessionSearch/) — the desktop's `searchSessions`, unchanged. Null when the machine
/// cannot answer: offline, or a CLI that predates the request, which goes silent rather than
/// refusing it — hence the short timeout.
Future<List<SessionContentHit>?> searchSessions(
String machineId,
String query, {
SearchWhen? when,
int limit = 30,
}) async {
if (!searchableMachineIds.contains(machineId)) return null;
try {
final reply = await _conn(machineId).request(
'session_search',
payload: {
'query': query,
'limit': limit,
if (when != null) ...{
'from': when.from.millisecondsSinceEpoch,
'to': when.to.millisecondsSinceEpoch,
},
},
timeout: const Duration(seconds: 4),
);
if (reply['error'] != null) return null;
return SessionContentHit.listFromReply(machineId, reply);
} catch (_) {
return null;
}
}
Future<Map<String, dynamic>> readAgentGitHistory(
String machineId,
String agentId, {
int offset = 0,
}) async {
final machine = stateOf(machineId), revision = _authRevision;
final agent = machine?.agents.where((a) => a.id == agentId).firstOrNull;
if (machine == null || agent == null) return {'status': 'unavailable'};
try {
final result = await _conn(machineId).request(
'git_pull_request',
payload: {'agentId': agentId, 'history': true, 'offset': offset},
timeout: const Duration(seconds: 45),
);
if (!_machineWorkCurrent(machine, revision) ||
!sameGitConversation(
agent,
machine.agents.where((a) => a.id == agentId).firstOrNull,
)) {
return {'status': 'unavailable'};
}
return result;
} catch (_) {
return {'status': 'unavailable'};
}
}
Future<Map<String, dynamic>> readGitProject(
String machineId,
String path,
) async {
final machine = machineStates[machineId];
if (machine == null) return {'error': 'UNAVAILABLE'};
try {
return await _conn(machineId).request(
'git_project_info',
payload: {'path': path},
timeout: const Duration(seconds: 6),
);
} catch (_) {
return {'error': 'UNAVAILABLE'};
}
}
/// Every Codex profile folder the CLI on [machineId] can offer, merged with [observedPaths]
/// (Codex homes already known from this same machine's other Codex agents). Runs entirely on that
/// machine — this app never touches a filesystem itself, which is what makes it work for a remote
/// machine too. Returns `{profiles: [{path, label}]}` or `{error}`.
Future<Map<String, dynamic>> listCodexProfiles(
String machineId, {
Set<String> observedPaths = const {},
}) async {
final connection = _conn(machineId);
try {
return await connection.request(
'codex_profiles_list',
payload: {'observedPaths': observedPaths.toList()},
timeout: const Duration(seconds: 10),
);
} catch (error) {
return {'error': 'UNREACHABLE'};
}
}
/// Links [path] as a Codex profile on [machineId], persisted there so it survives future
/// requests. Returns `{profile: {path, label}}` or `{error}`.
Future<Map<String, dynamic>> linkCodexProfile(
String machineId,
String path,
) async {
final connection = _conn(machineId);
try {
return await connection.request(
'codex_profile_link',
payload: {'path': path},
timeout: const Duration(seconds: 10),
);
} catch (error) {
return {'error': 'UNREACHABLE'};
}
}
/// Starts an agent, or recovers this form's earlier request after a lost reply.
/// Returns null on success, or an inline message; [attempt] tells the form
/// whether to offer Check status instead of inviting another creation.
/// [projectFolder] asks the MACHINE to produce the folder — a fresh project of its own, or a
/// clone of a repository — instead of being handed one that already exists.
///
/// ⚠️ It replaces [folder] rather than joining it: `cwd` leaves the payload entirely when a
/// request is present. Both answer "which directory", and a machine given a path AND an
/// instruction to make one would have to guess which was meant. `cli/src/lib/projectFolder.ts`
/// reads the pair, and `[folder]` stays required so the ordinary case — a folder the person
/// picked — cannot be forgotten.
///
/// [deskTabId] is the desk tab the agent joins once started — the one Find was narrowed to —
/// instead of the tab the phone is in. [newDeskTab] opens a desk tab of its own for it instead —
/// Find's `+` at the end of the tab chips. See [PhoneDesk.adopt].
Future<String?> createAgent(
String machineId, {
required String engine,
/// Where the harness works. Null only for a terminal (`kTerminalEngine`), which the machine
/// then opens at its home folder, as a terminal app would — the desktop's rule. The CLI refuses
/// every other engine without one (`INVALID_CWD`), so null is never a way to mean "anywhere".
required String? folder,
ProjectFolderRequest? projectFolder,
String? permissionMode,
String? codexHome,
GridModel? model,
String? swarmId,
String? deskTabId,
bool newDeskTab = false,
AgentCreationAttempt? attempt,
String? prompt,
String? name,
/// A Swarm agent's role and skill mode for the machine's Swarm skill
/// (Desktop's `swarmRole`, `swarmSkillMode`): sent for Claude Code and
/// Codex only.
String? swarmRole,
String? swarmSkillMode,
/// The model and effort it starts on, as Desktop's Lead starts (`model`,
/// `effort`). A machine that refuses them before starting anything gets
/// the request again without them ([AgentCreationAttempt.launchModelRefused]).
({String model, String? effort})? launchModel,
}) {
final creation = attempt ?? AgentCreationAttempt();
final task = prompt?.trim();
final choices = <String, dynamic>{
'engine': engine,
// The harness's first task — the machine types it into the agent once it is up. Only the
// engines in `kFirstTaskEngines` take one; an empty one is left out.
if (task != null && task.isNotEmpty) 'prompt': task,
// What the agent is called until its engine titles the session. Absent, the machine names it
// after the engine and the time ("Codex harness 9-17 15:26").
if (name != null && name.trim().isNotEmpty) 'name': name.trim(),
// ⚠️ Left out, not sent empty, when there is no folder: the CLI opens a terminal at home only
// when `cwd` is ABSENT (`launches.ts`), and refuses an empty one as INVALID_CWD.
if (projectFolder == null && folder != null) 'cwd': folder,
...?projectFolder?.payload,
'permissionMode': ?permissionMode,
// ⚠️ **Both keys, and the older one is not redundant.** `permissionMode`
// is the whole menu (`core/permission_modes.dart`); `bypassPermission` is
// the yes/no a daemon from before that menu understands, and it is all
// such a machine reads. Sent alone, "Plan first" on an old machine would
// launch as "approve everything" — so the boolean is derived from the
// mode rather than asked for separately. See [permissionModeApproves].
'bypassPermission': permissionMode == null
? false
: permissionModeApproves(permissionMode),
'codexHome': ?codexHome,
'gridModel': ?model?.id,
'gridName': ?model?.grid,
if (engine == 'claude' || engine == 'codex') ...{
'swarmRole': ?swarmRole,
'swarmSkillMode': ?swarmSkillMode,
},
'model': ?launchModel?.model,
'effort': ?launchModel?.effort,
};
Future<String?> ask() => _create(
machineId,
choices,
swarmId: swarmId,
deskTabId: deskTabId,
newDeskTab: newDeskTab,
attempt: creation,
);
final created = launchModel == null
? ask()
: ask().then<String?>((error) {
if (error == null ||
!_launchModelRefusals.contains(creation._refusal)) {
return error;
}
// Refused before anything launched: the same request without them,
// so the agent starts on its engine's own model rather than not at
// all (Desktop's createAgent).
choices
..remove('model')
..remove('effort');
creation._retryWithoutLaunchModel(launchModel);
return ask();
});
if (task == null || task.isEmpty) return created;
// A task typed into New Harness is a message sent to a session too: the onboarding's first
// message, if it is still waiting for one (`terminal_page.dart` counts every other send).
return created.then((error) {
if (error == null) {
onboardingMeasurement.end(ProductFlow.firstMessage, ProductOutcome.ok);
}
return error;
});
}
/// Clones on their way or still to be confirmed, by machine and source agent — see [cloneAgent].
final Map<(String, String), AgentCreationAttempt> _agentClones = {};
/// Whether a Clone of this agent is on its way: the menu's row says so and takes no tap.
bool agentCloning(String machineId, String agentId) =>
_agentClones[(machineId, agentId)]?._inFlight != null;
/// Clone: another agent of the same kind as [agentId], with a fresh conversation — fork minus the
/// context. The desktop's `cloneAgent` (⌘⇧N): same machine, same project folder, same engine or
/// harness, Codex profile, named agent and permission mode, every one read off the agent's own
/// frame. Nothing of the source is touched, so a clone works while the source is busy or has no
/// conversation yet, where a fork would wait or refuse.
///
/// A machine from before the frame carried the launch choices reports them null; the clone then
/// opens the way New Harness would by default. A terminal clones to a terminal in the same
/// folder, which the machine names itself.
///
/// Null once the clone exists — its id is on [cloneAttempt] — else the sentence to show.
///
/// ⚠️ **A lost reply is kept, receipt and all.** The machine may have started the clone, so the
/// next Clone of the same agent asks `agent_create_status` about the same receipt instead of
/// starting a second one; only a confirmed outcome lets it go.
Future<String?> cloneAgent(String machineId, String agentId) {
final key = (machineId, agentId);
final held = _agentClones[key];
if (held != null) {
if (held._inFlight case final inFlight?) return inFlight;
if (held.awaitingConfirmation) {
return _settleClone(key, checkAgentCreation(held), held);
}
_agentClones.remove(key);
}
final machine = machineStates[machineId];
if (machine == null) return Future.value('Machine not found');
final source = machine.agents
.where((agent) => agent.id == agentId)
.firstOrNull;
if (source == null) {
return Future.value('The source harness is no longer available.');
}
final engine = source.engine;
if (engine == null) {
return Future.value('${source.displayName} has no engine to clone.');
}
if (!source.canClone) {
return Future.value(
'${source.displayName} runs on a grid; cloning a grid harness is not supported.',
);
}
final terminal = engine == 'terminal';
final cwd = source.project?.cwd;
if ((cwd == null || cwd.isEmpty) && !terminal) {
return Future.value(
'${source.displayName} has no project folder to clone into.',
);
}
final attempt = AgentCreationAttempt()
.._codexHomeTrusted = source.codexHome != null;
final work = _create(machineId, {
'engine': engine,
if (cwd != null && cwd.isNotEmpty) 'cwd': cwd,
'dsh': ?source.dsh,
if (engine == 'codex') 'codexHome': ?source.codexHome,
'agent': ?source.namedAgent,
'permissionMode': ?source.permissionMode,
// Unrecorded is not "off": an older machine's agent clones the way a new one would open. A
// terminal has no permissions to bypass. The desktop's rule.
'bypassPermission': source.bypassPermission ?? !terminal,
// A terminal is named by the machine, as the desktop's ⌘⇧T is.
if (!terminal) 'name': cloneNameFor(source.displayName),
}, attempt: attempt);
_agentClones[key] = attempt;
return _settleClone(key, work, attempt);
}
/// The attempt behind the last Clone of [agentId], for the page to open what it started.
AgentCreationAttempt? cloneAttempt(String machineId, String agentId) =>
_agentClones[(machineId, agentId)];
/// Lets a clone's attempt go once its outcome is known — kept only while it is still to be
/// confirmed — and tells the menu it is no longer on its way.
Future<String?> _settleClone(
(String, String) key,
Future<String?> work,
AgentCreationAttempt attempt,
) {
notifyListeners();
return work
.then(
// The New form's "Check status" is a button this menu does not have: here it is Clone
// again, which asks about the same receipt.
(error) => error != null && attempt.awaitingConfirmation
? 'The clone is not confirmed yet. Tap Clone again to check '
'before starting another.'
: error,
)
.whenComplete(() {
if (identical(_agentClones[key], attempt) &&
!attempt.awaitingConfirmation &&
attempt._inFlight == null &&
attempt.agentId == null) {
_agentClones.remove(key);
}
if (!_disposed) notifyListeners();
});
}
/// The name a clone is offered: the source's, marked as a clone — the desktop's `cloneNameFor`.
static String cloneNameFor(String name) =>
'${name.trim().isEmpty ? 'Harness' : name.trim()} - clone';
/// A Claude Code or Codex conversation Harness did not start, opened as a harness that resumes
/// it, in its own folder (Find's "not in Harness" rows, `ExternalSessionRef`) — the desktop's
/// `resumeConversation`. The machine refuses one open elsewhere, already a harness, or whose
/// folder is gone, and says why. Null when it started; otherwise what to tell the person. The
/// new harness's id is on [attempt] once it has.
Future<String?> resumeConversation(
String machineId, {
required String engine,
required String folder,
required String sessionId,
String? name,
AgentCreationAttempt? attempt,
}) => _create(machineId, {
'engine': engine,
'cwd': folder,
'bypassPermission': true,
'name': ?name,
'resumeSessionId': sessionId,
}, attempt: attempt);
/// Asks what became of [attempt] — `agent_create_status`, under the same `creationId` — with
/// the choices it was first made with. The New form's Check status, the desktop's.
///
/// ⚠️ **Not [createAgent] again with the form's rows as they read now.** An answer that lands
/// after the first press — a Git read, a machine's only Codex profile — changes the request the
/// form would build, and a changed request is refused ("Check the original request…") rather
/// than checked, so the form would be stuck saying so. The attempt holds what was asked; this
/// asks about exactly that.
///
/// Never a creation: an attempt that was not sent has nothing to check, and nothing is sent.
Future<String?> checkAgentCreation(AgentCreationAttempt attempt) {
if (attempt._finished) return Future.value(attempt._outcome);
final machineId = attempt._machineId, choices = attempt._choices;
if (!attempt.awaitingConfirmation || machineId == null || choices == null) {
return Future.value(
'This request was never sent. Start the harness again.',
);
}
return _create(machineId, choices, attempt: attempt);
}
Future<String?> _create(
String machineId,
Map<String, dynamic> choices, {
String? swarmId,
String? deskTabId,
bool newDeskTab = false,
AgentCreationAttempt? attempt,
}) {
final creation = attempt ?? AgentCreationAttempt();
if (creation._choices != null &&
(creation._machineId != machineId ||
!mapEquals(creation._choices, choices))) {
return Future.value(
'Check the original request before changing its choices.',
);
}
if (creation._finished) return Future.value(creation._outcome);
if (creation._inFlight case final inFlight?) return inFlight;
if (creation._choices == null) {
creation._choices = choices;
creation._machineId = machineId;
creation._targetId = swarmId ?? activeSwarmId;
// With the request, not read again on a Check status: the tab picked is the one asked for.
creation._deskTabId = deskTabId;
creation._newDeskTab = newDeskTab;
}
final work = _createAgentWithReceipt(creation);
creation._inFlight = work;
return work.whenComplete(() => creation._inFlight = null);
}
String? _creationPlacementError(String targetId) {
final target = swarms.where((s) => s.id == targetId).firstOrNull;
if (target == null) return 'This swarm was closed';
if (target.panes.length >= maxPanes) {
return 'This swarm is full. Open a new swarm to create a harness.';
}
return null;
}
/// A machine's refusals of a launch model, made before anything launched.
static const _launchModelRefusals = {
'LAUNCH_MODEL_UNSUPPORTED',
'INVALID_LAUNCH_MODEL',
};
String _creationFailureMessage(
String code,
String? detail,
String machine, {
Map<String, dynamic>? choices,
}) => switch (code) {
// A New Folder named after its first task (`projectNameMode:
// suggested`). A current machine numbers that name past a folder that
// exists (`robot-2`), so only one that predates the mode refuses it, and
// its sentence is written for a name somebody typed. The phone has no
// name field to change instead, so it says the way to a fresh folder.
'PROJECT_EXISTS' when choices?['projectNameMode'] == 'suggested' =>
'A folder named after this task already exists on $machine. '
'Choose it from your projects, or update Harness there to make '
'a new one.',
// Making the project folder (a new one, a clone, a worktree or a
// branch) before anything starts in it: `cli/src/lib/projectFolder.ts`
// and `gitProject.ts`. The machine's sentence says what to change: the
// URL, the branch, Worktree.
'INVALID_PROJECT_SOURCE' ||
'INVALID_REPOSITORY' ||
'PROJECT_PREPARATION_FAILED' ||
'PROJECT_EXISTS' ||
'CLONE_FAILED' ||
'CLONE_TIMEOUT' ||
'GIT_PROJECT_UNAVAILABLE' ||
'INVALID_BRANCH' ||
'BRANCH_SWITCH_FAILED' ||
'WORKTREE_FAILED' ||
'GIT_UNAVAILABLE' =>
detail ?? 'Could not prepare the project folder on $machine.',
'CWD_NOT_FOUND' || 'INVALID_CWD' =>
'The project folder is unavailable on $machine. '
'Choose another folder and try again.',
'TMUX_UNAVAILABLE' =>
'Harness needs tmux to start harnesses on $machine. '
'Install tmux there, then try again.',
'PTY_HOST_UNAVAILABLE' =>
'Harness could not open a terminal on $machine. '
'Run harness start on that computer, then try again.',
'ENGINE_LAUNCH_REFUSED' =>
detail != null && detail.isNotEmpty
? detail
: 'This engine cannot start on $machine. Nothing was started.',
// The machine's own sentence names the engine and the flag it lacks.
// Without one, the phone's Approvals names the way out.
'CODEX_CLI_TOO_OLD' =>
detail ??
'The installed Codex CLI on $machine is too old for '
'Auto-approve. Update Codex there, or choose Ask first under '
'Approvals.',
'UNSUPPORTED_ON_REMOTE' || 'UNSUPPORTED' =>
'Update the harness CLI on this machine to create a harness',
'INVALID_DSH' =>
'This harness is not installed on $machine. '
'${detail ?? 'Install it there, then try again.'}',
'PROMPT_UNSUPPORTED' =>
'This engine cannot be opened with a first message on $machine.',
'PROMPT_TOO_LONG' =>
'This first task is too long for $machine. Shorten it and try again.',
'AGENT_UNSUPPORTED' =>
'This engine cannot be opened as a named agent on $machine.',
'INVALID_AGENT' =>
'This engine cannot be opened as that named agent on $machine.',
'INVALID_PERMISSION_MODE' =>
'This engine has no such permission mode on $machine.',
// A daemon older than the engine refuses it by name, with no detail;
// the fix is the update the UNSUPPORTED codes ask for. A detail is a
// reason of its own (the sample runs only Claude Code and Codex).
'INVALID_ENGINE' =>
detail ?? 'Update the harness CLI on $machine to start this agent.',
// Opening a conversation Harness did not start (`resumeSessionId`). The machine says what
// stopped it: open elsewhere, already a harness, gone.
'SESSION_OPEN_ELSEWHERE' ||
'SESSION_IN_HARNESS' ||
'SESSION_NOT_FOUND' ||
'SESSION_FOLDER_GONE' ||
'SESSION_BUSY_IN_TERMINAL' ||
'SESSION_STOP_FAILED' ||
'INVALID_SESSION' =>
detail ?? 'Could not open that conversation on $machine.',
// Not the machine's own sentence: it ends "Moving it here quits it
// there", written for the desktop's take-over button. A phone sends no
// `takeOver` and has no such button, so what it can offer is the way
// that works from here.
'SESSION_OPEN_IN_TERMINAL' =>
'It is open in a terminal on $machine. Close it there, then open '
'it here.',
_ => 'Create harness failed: ${detail ?? code}',
};
/// Calls off a request the machine holds — the New form's Cancel request, the desktop's
/// `cancelAgentCreation`. Null once the machine says it is cancelled; otherwise what to tell the
/// person, with the request still kept to check.
///
/// ⚠️ **Confirmed by the machine's own receipt.** A lost reply here cannot turn the original
/// request into a fresh one: the attempt keeps its receipt, and Check status asks about it.
Future<String?> cancelAgentCreation(AgentCreationAttempt creation) async {
if (!creation.canCancelPending ||
creation._cancelling ||
creation._inFlight != null) {
return 'Check the request status before cancelling.';
}
final machineId = creation._machineId;
if (machineId == null || !machineStates.containsKey(machineId)) {
return 'The original machine is unavailable. The request is still saved.';
}
creation._cancelling = true;
try {
final result = await _conn(machineId).request(
'agent_create_cancel',
payload: {'creationId': creation._id},
timeout: const Duration(seconds: 10),
);
if (result['creationId'] == creation._id &&
result['state'] == 'cancelled') {
creation._complete('Creation cancelled.');
return null;
}
return 'The request may already be starting. Check status before starting another.';
} catch (_) {
return 'Cancellation is not confirmed. Check status before starting another.';
} finally {
creation._cancelling = false;
}
}
Future<String?> _createAgentWithReceipt(AgentCreationAttempt creation) async {
final machineId = creation._machineId!;
final targetId = creation._targetId!;
final choices = creation._choices!;
final machine = machineStates[machineId];
if (machine == null) return 'Machine not found';
final machineName = machine.machine.displayName;
// A status check must remain possible even if the destination closed or a
// capability probe changed while the first create was already in flight.
if (!creation.awaitingConfirmation) {
final placementError = _creationPlacementError(targetId);
if (placementError != null) return placementError;
if (choices['codexHome'] != null) {
if (choices['engine'] != 'codex') {
return 'Choose a Codex profile only for Codex';
}
if (!creation._codexHomeTrusted &&
machine.engines['codex']?.supportsCodexHome != true) {
return 'Update the harness CLI on this machine to choose a Codex profile';
}
}
}
final connection = _conn(machineId);
// Recheck before launch: a selected model may have stopped since the picker
// opened. Status checks never repeat this or send a second creation.
if (!creation.awaitingConfirmation && choices['gridModel'] != null) {
final models = await gridModels(machineId);
if (!models.reachable) {
return creation._complete(
'Could not verify models on $machineName. Refresh models or use your subscription.',
);
}
if (!models.supportsModelLaunch) {
return creation._complete(
'Update Harness CLI on $machineName to choose a model before starting.',
);
}
if (!models.canRunLocally(choices['engine'] as String) ||
!models.sections.any(
(section) =>
section.name == choices['gridName'] &&
section.models.any((model) => model.id == choices['gridModel']),
)) {
return creation._complete(
'The selected model is unavailable. Refresh models or use your subscription.',
);
}
}
final operation = creation.awaitingConfirmation
? 'agent_create_status'
: 'agent_create';
final unconfirmed =
'$machineName has not confirmed the new harness yet. '
'Check status before creating another.';
Map<String, dynamic> result;
creation._awaitingConfirmation = true;
try {
if (operation == 'agent_create_status') {
result = await connection.request(
operation,
payload: {'creationId': creation._id},
timeout: const Duration(seconds: 10),
);
if (result['creationId'] != creation._id) return unconfirmed;
} else {
result = await connection.request(
operation,
payload: {...choices, 'creationId': creation._id},
timeout: const Duration(seconds: 20),
);
}
} on WsRequestFailure catch (failure) {
if (operation == 'agent_create_status') {
if (failure.code == 'UNSUPPORTED' ||
failure.code == 'UNSUPPORTED_ON_REMOTE' ||
failure.code == 'E2EE_REQUIRED') {
return '$machineName cannot check this creation. '
'Use Find a harness to look for it before creating another.';
}
return unconfirmed;
}
// Refusals that happen before a launch are safe to correct. INTERNAL,
// spawn timeouts and connection failures cannot prove nothing started.
//
// A code missing here reads as a lost reply ("has not confirmed the new
// harness yet. Check status before creating another."), which asks for
// a second create of something the machine already turned down. The CLI
// checks every one before any pane exists (`create` in its
// core/agents/launches.ts, and core/agents/create.ts before the spawn).
// The desktop's set is the same list; keep the two in step.
const refusedBeforeLaunch = {
// The project folder as asked for, refused before one is made or
// cloned.
'INVALID_PROJECT_SOURCE',
'INVALID_REPOSITORY',
'PROJECT_EXISTS',
'CWD_NOT_FOUND',
'INVALID_CWD',
'INVALID_ENGINE',
'INVALID_GRID',
'GRID_UNAVAILABLE',
'INVALID_CODEX_HOME',
'INVALID_DSH',
// The first task, a named agent and the approval mode.
'PROMPT_UNSUPPORTED',
'PROMPT_TOO_LONG',
'INVALID_PROMPT',
'AGENT_UNSUPPORTED',
'INVALID_AGENT',
'INVALID_PERMISSION_MODE',
'TMUX_UNAVAILABLE',
'PTY_HOST_UNAVAILABLE',
'ENGINE_LAUNCH_REFUSED',
// An engine too old for the approval mode's flag: refused rather than
// left printing its help in a pane.
'CODEX_CLI_TOO_OLD',
'TMUX_TOO_OLD_FOR_GRID',
'GRID_CONFIG_FAILED',
'UNSUPPORTED_ON_REMOTE',
'UNSUPPORTED',
// A conversation Harness did not start, refused before its pane opens.
'SESSION_OPEN_ELSEWHERE',
'SESSION_IN_HARNESS',
'SESSION_NOT_FOUND',
'SESSION_FOLDER_GONE',
'INVALID_SESSION',
// Open in a terminal on that machine (`adoptableSession` in the CLI's
// cli.ts): refused because this phone did not say how to take it
// over, so nothing started. Missing here, the most common case of all
// — a conversation somebody left running in `claude` — read as a lost
// reply, "has not confirmed the new harness yet".
'SESSION_OPEN_IN_TERMINAL',
'SESSION_BUSY_IN_TERMINAL',
'SESSION_STOP_FAILED',
..._launchModelRefusals,
};
if (refusedBeforeLaunch.contains(failure.code)) {
creation._refusal = failure.code;
return creation._complete(
_creationFailureMessage(
failure.code,
failure.detail,
machineName,
choices: choices,
),
);
}
return unconfirmed;
} catch (_) {
// Includes disconnects, malformed replies and timeouts. A transport error
// is not evidence that the machine did not execute the request.
return unconfirmed;
}
if ((result.containsKey('creationId') || result['state'] != null) &&
result['creationId'] != creation._id) {
return unconfirmed;
}
switch (result['state']) {
case 'missing':
// An old CLI may have created the agent before being updated to a
// receipt-aware version. Missing is not proof that nothing started.
// Check status stays read-only, even across upgrades and reconnects.
return '$machineName has no record of this request. '
'Use Find a harness to look for it before creating another.';
case 'pending':
// Held before anything started — an engine being installed, a model waking — the machine
// says on what, in a sentence of its own, and the request can still be called off.
final held = result['held'];
if (held is Map) {
final detail = held['detail'];
if (detail is String && detail.isNotEmpty) {
creation._holdReason = detail;
return detail;
}
}
creation._holdReason = null;
return '$machineName is still starting your harness. Check again in a moment.';
case 'cancelled':
return creation._complete('Creation cancelled.');
case 'unconfirmed':
return '$machineName could not confirm whether this harness started. '
'Use Open Harness to look for it before creating another.';
case 'unavailable':
return creation._complete(
'This harness was created but is no longer available. '
'You can create a new one.',
);
case 'failed':
final failure = result['failure'];
if (failure is! Map || failure['code'] is! String) return unconfirmed;
creation._refusal = failure['code'] as String;
return creation._complete(
_creationFailureMessage(
failure['code'] as String,
failure['detail'] is String ? failure['detail'] as String : null,
machineName,
choices: choices,
),
);
case 'created':
case null: // A successful first response from a CLI predating receipts.
break;
default:
return unconfirmed;
}
final raw = result['agent'];
if (raw is! Map || raw['id'] is! String || (raw['id'] as String).isEmpty) {
return unconfirmed;
}
final Map<String, dynamic> json;
final Agent agent;
try {
json = Map<String, dynamic>.from(raw);
agent = Agent.fromJson(json);
} catch (_) {
return unconfirmed;
}
creation._agentId = agent.id;
creation._complete(null);
if (_disposed || machineStates[machineId] != machine) return null;
// Into the next launch's list at once — the harness just made is the one most likely to be
// reopened by it. See [_cacheAgentJson].
_upsertAgent(machine, agent, json: json);
// ⚠️ Read from the AGENT the machine answered with, not from what was asked for. "New project"
// and a clone send no `cwd` at all — the folder is whatever the machine made — so taking it
// from the request would record nothing for exactly the two sources that produce a folder
// worth remembering.
final projectPath = agent.project?.cwd ?? choices['cwd'];
if (projectPath is String && projectPath.isNotEmpty) {
unawaited(projectHistory.select(machineId, projectPath));
}
// Apply each creation receipt once, even if its transport result is replayed.
stats.onAgentSpawned();
notifyListeners();
if (_creationPlacementError(targetId) != null) {
_lastError =
'The harness was created, but its original swarm or layout changed. '
'Use Open Harness to find it.';
_lastErrorRetryable = false;
notifyListeners();
return null;
}
// Created HERE, so it joins the tab this phone is in — the way an agent
// created in a window joins that window's tab — or the tab picked for it,
// or a tab of its own. See [PhoneDesk.adopt] for what happens when the
// phone is in no tab.
_desk.adopt(
(machineId: machineId, agentId: agent.id),
name: agent.displayName,
tabId: creation._deskTabId,
newTab: creation._newDeskTab,
);
await assignAgentToPane(null, machineId, agent.id, swarmId: targetId);
return null;
}
/// The longest name the backend keeps for a computer — `renameBody` in
/// `backend/src/routes/machines.ts` refuses anything longer.
static const machineNameMaxLength = 40;
/// Computers this phone just set up (Settings ▸ Set up Intern 3): Computers marks them "new" until
/// one is opened. This run only.
final Set<String> _newMachines = {};
bool isNewMachine(String machineId) => _newMachines.contains(machineId);
void markMachineNew(String machineId) {
if (_newMachines.add(machineId)) notifyListeners();
}
void sawMachine(String machineId) {
if (_newMachines.remove(machineId)) notifyListeners();
}
/// New computers whose Start was pressed and is still bringing up their harness: their row drops
/// "new" and its Start spins.
final Set<String> _startingMachines = {};
bool machineStarting(String machineId) =>
_startingMachines.contains(machineId);
void setMachineStarting(String machineId, bool starting) {
final changed = starting
? _startingMachines.add(machineId)
: _startingMachines.remove(machineId);
if (changed) notifyListeners();
}
/// Renames a machine via `PATCH /api/machines/:machineId` (control-plane REST — the machine's
/// `name` is backend-owned, unlike an agent's, which lives on the harness CLI). Returns null on
/// success, or an error message to show inline in the caller's dialog.
Future<String?> renameMachine(String machineId, String name) async {
final revision = _authRevision;
if (machineStates[machineId] == null) {
return 'This computer is no longer on your account.';
}
final trimmed = name.trim();
if (trimmed.isEmpty) return 'Name cannot be empty';
if (trimmed.length > machineNameMaxLength) {
return 'Use $machineNameMaxLength characters or fewer.';
}
try {
await api.renameMachine(machineId: machineId, name: trimmed);
} catch (error) {
return 'Rename failed: ${describeApiError(error)}';
}
// Signed out, or into another account, while the request was out: nothing here is theirs.
if (!_authWorkCurrent(revision)) return null;
// Looked up again — a refresh may have replaced the state while the request was out.
final state = machineStates[machineId];
if (state == null) return null;
state.machine = state.machine.copyWith(name: trimmed);
final index = machines.indexWhere((m) => m.machineId == machineId);
if (index != -1) machines[index] = state.machine;
// The next launch draws its rows from the cache before `/api/machines` answers: the old name
// there would come back for those seconds.
final cache = _machineCache;
if (cache != null) _writeMachineCache(cache);
notifyListeners();
return null;
}
/// Machines being removed right now ([deleteMachine]). Their rows say so, and a second press joins
/// the first rather than sending a second `DELETE`, which the backend would answer with a 404.
final Map<String, Future<String?>> _machineDeletes = {};
bool machineRemoving(String machineId) =>
_machineDeletes.containsKey(machineId);
/// Permanently takes a machine off the account — not to be confused with [unlinkMachine], which
/// only drops this computer's local E2EE trust pin and leaves the machine itself intact. Two steps,
/// in the order desktop takes them (`MachineDevices.removeComputer`): the computer's key out of the
/// account's device log ([removeDevice]), then its machine record (backend
/// `DELETE /api/machines/:id`). Returns null on success, or an error message to show inline.
///
/// ⚠️ **The record alone does not take it out of Your devices.** The backend's delete pushes
/// `machine_revoked` down to a daemon that is connected (`MachineService.destroy`), which clears
/// its session and stops — one that is off finds out on its next dial — but it never touches the
/// device log: the computer's key stayed in Your devices, and every other device of the account
/// went on trusting it. The confirmation that leads here says both.
///
/// A sign-out that fails stops before the record is touched, so the next press does the whole of
/// it again. A record that fails after the sign-out worked says so, and the next press finds no
/// key left to sign out and deletes only the record. A computer the log has no key for — an
/// account or a computer from before the log, one already signed out, a log this phone could not
/// read — loses its record alone, as before the log existed: removing it is never held up for good.
Future<String?> deleteMachine(String machineId) {
final inFlight = _machineDeletes[machineId];
if (inFlight != null) return inFlight;
if (machineStates[machineId] == null) {
return Future.value('This computer is no longer on your account.');
}
late final Future<String?> run;
run = _performDeleteMachine(machineId).whenComplete(() {
if (identical(_machineDeletes[machineId], run)) {
_machineDeletes.remove(machineId);
}
if (!_disposed) notifyListeners();
});
_machineDeletes[machineId] = run;
notifyListeners();
return run;
}
Future<String?> _performDeleteMachine(String machineId) async {
final revision = _authRevision;
final name =
machineStates[machineId]?.machine.displayName ?? 'This computer';
final device = await _machineDeviceKey(machineId);
// Signed out, or into another account, while the log was read: nothing here is theirs.
if (!_authWorkCurrent(revision)) return null;
if (device != null) {
String? failure;
try {
failure = await removeDevice(device.pub);
} catch (_) {
failure = 'UNREACHABLE';
}
// Signed out meanwhile: a DELETE now would go out under whoever is signed in next, and a
// failure is no longer anyone's to read.
if (!_authWorkCurrent(revision)) return null;
// Gone from the log already — another device signed it out after this phone read the log:
// what this step was for is done.
if (failure == 'NOT_IN_LOG') failure = null;
if (failure != null) {
return 'Couldn’t sign $name out ($failure). Try again.';
}
// The account let it go meanwhile (removed from another device): no record is left to delete.
if (machineStates[machineId] == null) return null;
}
try {
await api.deleteMachine(machineId: machineId);
} catch (error) {
final reason = describeApiError(error);
return device == null
? 'Could not remove it: $reason'
: '$name is signed out, but its machine record could not be deleted: $reason';
}
if (!_authWorkCurrent(revision)) return null;
// Any tile still showing this machine would otherwise sit forever in the "waiting to answer"
// busy state, since the machine can never be found again after this.
for (final pane in panesFor(machineId).toList()) {
for (final swarm in swarms) {
swarm.remove(pane);
}
await _detachSession(pane, sendClose: true);
}
if (!_authWorkCurrent(revision)) return null;
_persistLayout();
// Everything [_refreshMachines] lets go of for a machine that left the account — the SOCKET
// above all, which would otherwise go on dialling a machine nothing refers to any more.
final state = machineStates[machineId];
if (state != null) _clearMachineActivity(state);
_stopOfflineRetry(machineId);
_stopAgentSyncTimer(machineId);
unawaited(_pool?.closeMachine(machineId));
machineStates.remove(machineId);
machines.removeWhere((m) => m.machineId == machineId);
_retuneDeafPoll();
expandedMachines.remove(machineId);
if (selectedMachineId == machineId) selectedMachineId = null;
if (pendingPairing?.machineId == machineId) pendingPairing = null;
// A profile on the computer that just left would show its tabs no longer; back to every one.
if (machineProfile.value == machineId) machineProfile.select(null);
_keepActiveDeskTabShown();
final cache = _machineCache;
if (cache != null) _writeMachineCache(cache);
notifyListeners();
return null;
}
/// How long [_machineDeviceKey] waits on the device log before it goes on with what it has.
static const _machineKeyReadCap = Duration(seconds: 5);
/// [machineId]'s key in the account's device log, when this phone's copy of the log has one — what
/// [deleteMachine] signs out before the record goes. The log holds one key per computer at most
/// (`MACHINE_TAKEN`). Null when there is none to sign out: an account or a computer from before the
/// log, one already signed out, a log this phone could not read, or one that is still the account
/// just left (its keys are not this account's to remove).
///
/// The log is read again first, briefly ([_connectAfterDeviceLog] waits as long): a computer that
/// signed in after the last read would otherwise be missed, and one signed out elsewhere since would
/// be signed out again, for nothing. Never throws — no answer is no key, and the record still goes.
Future<DevLogMember?> _machineDeviceKey(String machineId) async {
final log = _deviceLog;
if (log == null) return null;
await log.refresh().timeout(_machineKeyReadCap, onTimeout: () {});
try {
return await () async {
if (!await log.ownsLog()) return null;
final listing = await deviceListing();
for (final row in listing.members) {
final m = row.member;
if (m.kind == 'machine' && m.machineId == machineId) return m;
}
return null;
}().timeout(_machineKeyReadCap);
} catch (error) {
debugPrint(
'devices: could not read the key of ${_shortId(machineId)}: $error',
);
return null;
}
}
/// Computers being tried again by hand ([retryMachine]) — the row says so while it runs.
final Map<String, Future<String?>> _machineRetries = {};
bool machineRetrying(String machineId) =>
_machineRetries.containsKey(machineId);
/// One computer asked again, by hand — Settings ▸ Computers' "Try again", for a machine that reads
/// asleep or is stuck connecting.
///
/// ⚠️ **Not [retryOfflineMachine].** That one only polls for a machine somebody is waiting on an
/// agent of (`pendingOfflineAgentId`), which on a phone is almost never set — it would do nothing
/// here. Nor [retryMachines], which re-reads the account but never dials a machine the account
/// calls down ([_autoConnectAndLoadMachines]), and that status is exactly what is being doubted.
///
/// So: the account's word on it now, then a dial whatever that word is — the way [reachAllMachines]
/// dials for Find — cutting short any backoff and waking a socket the relay parked as offline
/// ([_redialNow]). A machine waiting on its password is not dialled: that is refused again until
/// one lands.
///
/// Returns null, or why the account could not be read; the dial is made either way, on the list
/// the phone already has.
Future<String?> retryMachine(String machineId) {
final inFlight = _machineRetries[machineId];
if (inFlight != null) return inFlight;
late final Future<String?> run;
run = _performRetryMachine(machineId).whenComplete(() {
if (identical(_machineRetries[machineId], run)) {
_machineRetries.remove(machineId);
}
if (!_disposed) notifyListeners();
});
_machineRetries[machineId] = run;
notifyListeners();
return run;
}
Future<String?> _performRetryMachine(String machineId) async {
final revision = _authRevision;
if (!_authWorkCurrent(revision) || status == AppStatus.unauthenticated) {
return null;
}
String? failure;
try {
await refreshMachines();
} catch (error) {
failure = 'Could not load computers: ${describeApiError(error)}';
}
if (_disposed || !_authWorkCurrent(revision)) return null;
final state = machineStates[machineId];
if (state == null) {
return failure ?? 'This computer is no longer on your account.';
}
if (state.needsLink) return failure;
// No transport — the same guard [reachAllMachines] keeps: [_conn] would build one out of a
// null pool.
if (_pool == null && connectionForTest == null) return failure;
// Before the dial, whose `connecting` may be reported at once: this one is the person's.
productConnections.manual(
machineId,
connected: state.connectionStatus == ConnectionStatus.connected,
);
_connectMachine(state);
_redialNow(machineId);
await _loadMachineData(state, force: true);
return failure;
}
/// Renames an agent via `agent_update`. Returns null on success, or an error message to show
/// inline in the caller's dialog.
Future<String?> renameAgent(
String machineId,
String agentId,
String name,
) async {
final machine = machineStates[machineId];
if (machine == null) return 'Machine not found';
final trimmed = name.trim();
if (trimmed.isEmpty) return 'Name cannot be empty';
Map<String, dynamic> result;
try {
result = await _conn(
machineId,
).request('agent_update', payload: {'agentId': agentId, 'name': trimmed});
} catch (error) {
return 'Rename failed: $error';
}
final error = result['error'];
if (error is String) return 'Rename failed: $error';
_renameAgent(machine, agentId, trimmed);
notifyListeners();
return null;
}
/// Queued Stops on their way to the machine, by machine and agent — what a second press joins.
final Map<(String, String), Future<String?>> _closePlanRequests = {};
/// Whether a Stop after it finishes, or calling one off, is on its way for this agent.
bool agentClosePlanPending(String machineId, String agentId) =>
_closePlanRequests.containsKey((machineId, agentId));
/// Whether this agent can be stopped once it finishes: its machine closes harnesses on request
/// (`agent_close`), and it has a conversation to finish — a shell never reads as idle, so its
/// Stop would wait forever.
static bool canStopAfterTask(Agent agent) =>
agent.closeSupported &&
agent.createdAt != null &&
agent.engine != 'terminal' &&
!agent.isStopped;
/// Stop after it finishes: the machine waits for the agent to be idle, then saves and stops it
/// (`agent_close`, `after_task`) — what the desktop's close does with a session still working.
/// Its conversation is kept, as Stop's is. Null once the machine has queued it, else the
/// sentence to show.
Future<String?> stopAfterTask(String machineId, String agentId) =>
_requestClosePlan(machineId, agentId, 'after_task');
/// Keep running: the queued Stop called off (`agent_close`, `cancel`).
Future<String?> keepRunning(String machineId, String agentId) =>
_requestClosePlan(machineId, agentId, 'cancel');
Future<String?> _requestClosePlan(
String machineId,
String agentId,
String mode,
) {
final key = (machineId, agentId);
if (_closePlanRequests[key] case final pending?) return pending;
final request = _sendClosePlan(machineId, agentId, mode).whenComplete(() {
_closePlanRequests.remove(key);
if (!_disposed) notifyListeners();
});
_closePlanRequests[key] = request;
notifyListeners();
return request;
}
Future<String?> _sendClosePlan(
String machineId,
String agentId,
String mode,
) async {
final machine = machineStates[machineId];
final agent = machine?.agents.where((a) => a.id == agentId).firstOrNull;
if (machine == null || agent == null) {
return 'This harness is no longer available.';
}
if (!canStopAfterTask(agent)) {
return 'Update the Harness CLI on this machine to stop a harness once it finishes.';
}
final revision = _authRevision;
final Map<String, dynamic> result;
try {
result = await _conn(machineId).request(
'agent_close',
payload: {
'agentId': agent.id,
'sessionId': agent.sessionId ?? '',
'createdAt': agent.createdAt!.toUtc().toIso8601String(),
'mode': mode,
},
timeout: const Duration(seconds: 15),
);
} on WsRequestFailure catch (failure) {
if (failure.code == 'AGENT_CHANGED') {
return 'The harness changed. Open its menu again.';
}
final detail = failure.detail;
return detail != null && detail.isNotEmpty
? detail
: mode == 'cancel'
? 'Could not keep it running: ${failure.code}'
: 'Could not queue the stop: ${failure.code}';
} catch (_) {
// A lost reply is not a refusal: the machine may have queued it. Its frame says which once
// the agents are read again, and the row follows that.
unawaited(reloadMachineData(machineId));
return mode == 'cancel'
? 'Could not confirm it keeps running. Check its menu again in a moment.'
: 'Could not confirm the stop is queued. Check its menu again in a moment.';
}
final done = mode == 'cancel'
? result['cancelled'] == true
: result['deferred'] == true || result['closed'] == true;
if (!done) {
final detail = result['detail'];
return detail is String && detail.isNotEmpty
? detail
: 'The machine did not confirm it. Check its menu again in a moment.';
}
// The machine's push says the same in a moment; the menu reads it now.
if (!_disposed && _machineWorkCurrent(machine, revision)) {
final index = machine.agents.indexWhere((a) => a.id == agentId);
if (index != -1 && result['closed'] != true) {
machine.agents = [...machine.agents]
..[index] = mode == 'cancel'
? machine.agents[index].copyWith(clearClosePlan: true)
: machine.agents[index].copyWith(closePlanState: 'waiting');
notifyListeners();
}
}
return null;
}
/// Tells the machine that owns an agent it was just opened here, so it can stamp
/// `lastOpenedAt` and every app — this phone, each desktop — sorts by the same
/// last use. Fire and forget: a daemon too old to keep the stamp answers
/// `MISSING_UPDATE`, and nothing here depends on the answer.
///
/// Coalesced per agent: opening the same one again within [_touchEvery] says
/// nothing new.
void touchAgent(String machineId, String agentId) {
final machine = machineStates[machineId];
if (machine == null || machine.needsLink) return;
final key = '$machineId/$agentId';
final now = DateTime.now();
final last = _touchedAt[key];
// A Stop queued for after it finishes is called off by opening the agent again (CLI
// agents/update.ts), so that open is never coalesced away — the desktop's rule.
final queuedStop = machine.agents.any(
(agent) => agent.id == agentId && agent.closePlanState != null,
);
if (!queuedStop && last != null && now.difference(last) < _touchEvery) {
return;
}
_touchedAt[key] = now;
final revision = _authRevision;
unawaited(() async {
try {
// ⚠️ **After the agent's own terminal, never ahead of it (owner, 2026-10-01).** The machine
// takes a connection's frames one at a time (`enqueueDown` in the CLI's backendSocket.ts),
// and this one costs it a whole agent frame (`toProject`, git context and all). At launch
// it is queued before the socket is up and flushed first, so the `terminal_open` behind it
// waited for that. A recency stamp can wait a second; the screen cannot.
await _yieldToTerminalOpen(_conn(machineId), machineId, agentId);
if (_disposed ||
!_authWorkCurrent(revision) ||
machineStates[machineId]?.needsLink != false) {
return;
}
await _conn(machineId).request(
'agent_update',
payload: {'agentId': agentId, 'opened': true},
);
} catch (_) {
// Recency is a nicety: a machine that cannot hear it keeps its order.
}
}());
}
static const _touchEvery = Duration(seconds: 3);
final _touchedAt = <String, DateTime>{};
/// The longest [touchAgent] holds its stamp for the socket, and then for the terminal.
static const _touchYield = Duration(seconds: 3);
/// Until [agentId]'s terminal on [machineId] is live — see [touchAgent]. The socket first: a frame
/// asked for before it is up is queued, and that queue goes out ahead of the terminal's open
/// (`WsConn._flushQueue` runs before the open's wait for readiness ends).
Future<void> _yieldToTerminalOpen(
WsConn connection,
String machineId,
String agentId,
) async {
// Read as the app shows it too: a machine already `connected` here has nothing to wait for.
if (!connection.isReady &&
machineStates[machineId]?.connectionStatus !=
ConnectionStatus.connected) {
try {
await connection.waitUntilReady(timeout: _touchYield);
} catch (_) {
// Not up in time, or closed: the stamp goes the way it always did.
}
}
if (_disposed) return;
TerminalSession? terminal;
for (final pane in allPanes) {
if (pane.machineId == machineId && pane.agentId == agentId) {
terminal = pane.session;
if (terminal != null) break;
}
}
if (terminal == null) return;
await _untilTerminalLive(terminal, _touchYield);
}
/// Deletes an agent via `agent_delete`. Returns null on success, or an error message to show
/// inline in the caller's dialog.
///
/// A refusal the machine says is worth asking again (`retryable`: `IDENTITY_UNAVAILABLE`, its
/// conversation file changing under the lookup) is asked again after [stopRetryDelays], before it
/// is shown. On 2026-10-19, 3 of the phone's 4 stops were refused as `other`, the kind this code
/// falls under. Any other refusal is shown at once — `STOP_UNCONFIRMED` asks for a look at the
/// harness first, not another stop.
Future<String?> deleteAgent(String machineId, String agentId) async {
final machine = machineStates[machineId];
if (machine == null) return 'Machine not found';
Map<String, dynamic> result;
for (var attempt = 0; ; attempt++) {
try {
result = await _conn(machineId)
.request('agent_delete', payload: {'agentId': agentId});
} catch (error) {
return 'Delete failed: $error';
}
if (result['error'] is! String ||
result['retryable'] != true ||
attempt >= stopRetryDelays.length) {
break;
}
await Future<void>.delayed(stopRetryDelays[attempt]);
if (_disposed || machineStates[machineId] == null) {
return 'Machine not found';
}
}
final error = result['error'];
if (error is String) return 'Delete failed: $error';
await _removeAgent(machine, agentId);
// Gone from the machine, so gone from the desk: a tab left holding it would
// keep a pane no computer can ever attach. See [PhoneDesk.drop].
_desk.drop((machineId: machineId, agentId: agentId));
notifyListeners();
return null;
}
/// How long [deleteAgent] waits before asking again after a refusal the machine marks `retryable`,
/// one entry per retry.
@visibleForTesting
List<Duration> stopRetryDelays = const [
Duration(seconds: 1),
Duration(seconds: 2),
];
/// Deletes on their way, by machine and agent — what a second press joins rather than reviewing
/// the same harness twice.
final Map<(String, String), Future<String?>> _agentPurges = {};
/// Whether a Delete of this agent is on its way: the menu's row says so, as Restart does.
bool agentPurging(String machineId, String agentId) =>
_agentPurges.containsKey((machineId, agentId));
/// Delete Harness — the desktop's `purgeAgent`. Unlike Stop ([deleteAgent]), which keeps the
/// conversation to reopen, this stops a running harness and deletes its saved conversation for
/// good, so it can never be opened again. Project files and worktrees are kept.
///
/// The machine's reviewed deletion (`agent_purge`): `inspect` first, then `delete` under that
/// review's id, both naming the harness exactly — id, conversation and when it was registered —
/// so a delete meant for one that has since been replaced under the same id is refused rather
/// than taking the replacement. Null on success, or the sentence to show.
///
/// ⚠️ **A lost reply is not a failed delete.** The second step may have run; the answer says to
/// check rather than inviting another press that would only find nothing to delete.
Future<String?> purgeAgent(String machineId, String agentId) {
final key = (machineId, agentId);
if (_agentPurges[key] case final pending?) return pending;
final request = _purgeAgent(machineId, agentId).whenComplete(() {
_agentPurges.remove(key);
if (!_disposed) notifyListeners();
});
_agentPurges[key] = request;
notifyListeners();
return request;
}
Future<String?> _purgeAgent(String machineId, String agentId) async {
final machine = machineStates[machineId];
final agent = machine?.agents
.where((agent) => agent.id == agentId)
.firstOrNull;
final createdAt = agent?.createdAt;
if (machine == null || agent == null || createdAt == null) {
return 'This harness is no longer listed. Refresh and try again.';
}
// The desktop's rule: a terminal keeps no conversation, so there is nothing to delete past
// what Stop already does.
if (agent.engine == 'terminal') {
return 'A terminal keeps no conversation. Stop it instead.';
}
final revision = _authRevision;
final sessionId = agent.sessionId;
final target = {
'agentId': agentId,
'sessionId': sessionId == null || sessionId.isEmpty ? null : sessionId,
'createdAt': createdAt.millisecondsSinceEpoch,
};
String refused(Object? code, Object? detail) =>
'Delete failed: ${detail is String && detail.isNotEmpty ? detail : code}';
const unconfirmed =
'Could not confirm the deletion. Refresh harnesses to check.';
var deleting = false;
try {
final review = await _conn(machineId).request(
'agent_purge',
payload: {...target, 'mode': 'inspect'},
timeout: const Duration(seconds: 30),
);
if (review['error'] != null) {
return refused(review['error'], review['detail']);
}
final reviewId = review['reviewId'];
if (reviewId is! String) {
return 'Could not review this harness for deletion.';
}
if (!_machineWorkCurrent(machine, revision)) {
return 'The machine changed before the delete. Try again.';
}
deleting = true;
final result = await _conn(machineId).request(
'agent_purge',
payload: {...target, 'mode': 'delete', 'reviewId': reviewId},
timeout: const Duration(seconds: 60),
);
if (result['error'] != null) {
return refused(result['error'], result['detail']);
}
if (result['deleted'] != true) return unconfirmed;
} on WsRequestFailure catch (failure) {
return refused(failure.code, failure.detail);
} on WsRequestTimeout {
return deleting
? unconfirmed
: 'Could not review this harness for deletion. Try again.';
} catch (_) {
return deleting
? unconfirmed
: 'Could not delete the harness. Try again.';
}
if (_disposed || !_machineWorkCurrent(machine, revision)) return null;
await _removeAgent(machine, agentId);
// Gone from the machine, so gone from the desk — as Stop does ([deleteAgent]).
_desk.drop((machineId: machineId, agentId: agentId));
notifyListeners();
return null;
}
/// Takes a harness off this phone's lists while its computer does not answer, so `agent_delete`
/// cannot reach it: nothing is stopped there. Its desk tab keeps it, and the computer's own list
/// brings it back as soon as it answers again (`_replaceAgents`) if it is still there.
Future<void> forgetUnreachableAgent(String machineId, String agentId) async {
final machine = machineStates[machineId];
if (machine == null) return;
await _removeAgent(machine, agentId);
notifyListeners();
}
/// Bring a stopped agent back, so something can be opened on it.
///
/// The desktop's `resumeAgent`: a thin guard over [restartAgent], which is the
/// same `agent_restart` RPC. Split out because the two have different
/// preconditions — restart is "this agent is misbehaving, relaunch it", resume
/// is "this agent is not running, it should be".
///
/// An agent that already has a terminal succeeds without touching the machine:
/// the caller's job is "make it openable", and it is.
///
/// ⚠️ **`agent_resume`, never `agent_restart`.** The daemon routes the two to different services
/// (`backendSocket.ts`): restart swaps the process inside a LIVE pane and refuses an agent with
/// none (`NO_ACTIVE_PROCESS`, `RESTART_UNSUPPORTED_BACKEND`) — which is every stopped agent — while
/// resume builds a pane and reopens the saved conversation by its session id. This used to send
/// restart, so tapping a Stopped row could only ever fail.
Future<RestartAgentResult> resumeAgent(String machineId, String agentId) {
final machine = stateOf(machineId);
final agent = machine?.agents
.where((agent) => agent.id == agentId)
.firstOrNull;
if (agent?.terminalAvailable == true) {
return Future.value(const RestartAgentResult());
}
if (machine == null || agent == null || !agent.isStopped) {
return Future.value(
const RestartAgentResult(
error: 'That harness is no longer available. Search again.',
),
);
}
// Refused here rather than round-tripped: the machine can only say RESUME_UNAVAILABLE.
if (!agent.canPauseAndResume) {
return Future.value(
const RestartAgentResult(
error: 'This harness has no supported saved conversation to resume.',
),
);
}
return _resumeWithReceipt(machine, agent);
}
/// Resumes whose outcome the machine has not confirmed yet, by agent → the receipt id they were
/// sent with.
///
/// ⚠️ **A lost reply is not a failed resume.** The daemon may be starting the conversation right
/// now, and a second `agent_resume` would start it twice. So the next tap on the same agent asks
/// `agent_create_status` about the SAME id instead, exactly as the desktop's restart attempt does;
/// only a confirmed outcome — started, refused, gone — clears the entry.
final Map<(String, String), String> _agentResumes = {};
Future<RestartAgentResult> _resumeWithReceipt(
MachineState machine,
Agent stopped,
) async {
final key = (machine.machine.machineId, stopped.id);
final checking = _agentResumes[key];
final receipt = checking ?? _newReceiptId();
_agentResumes[key] = receipt;
// Counted from the resume being sent — the desktop's rule — not from a status check on one.
final measured = _turnActivityKey(machine.machine.machineId, stopped.id);
if (checking == null) productResumes.sent(measured);
RestartAgentResult settle(String error, {bool refused = true}) {
_agentResumes.remove(key);
if (refused) productResumes.refused(measured);
return RestartAgentResult(error: error);
}
const unconfirmed = RestartAgentResult(
error: 'The machine has not confirmed the resume yet. Tap the harness again to check.',
);
Future<Map<String, dynamic>> resume() => _conn(machine.machine.machineId)
.request(
'agent_resume',
payload: {'creationId': receipt, 'agentId': stopped.id},
);
// Whether the request whose answer is being read is `agent_resume` itself —
// its refusals are final — rather than a status check.
var resuming = checking == null;
Map<String, dynamic> result;
try {
result = resuming
? await resume()
: await _conn(
machine.machine.machineId,
).request('agent_create_status', payload: {'creationId': receipt});
// ⚠️ **`missing` is the machine never having heard of it — the desktop's
// rule.** The first send can fail before it leaves the phone (a socket
// mid-redial is the usual way), and then every check after it answers
// `missing`, for ever: the agent could not be resumed from this phone
// again until the app restarted. So the SAME intent is sent again. The
// daemon reserves a receipt before it launches anything, so a delayed
// original and this replay cannot both open a terminal.
if (!resuming &&
result['creationId'] == receipt &&
result['state'] == 'missing') {
resuming = true;
result = await resume();
}
} on WsRequestFailure catch (failure) {
// A refusal to a resume happened before anything launched; anything else — a timeout,
// INTERNAL, a status check the machine cannot answer — leaves the outcome unknown.
if (!resuming || failure.code == 'INTERNAL') return unconfirmed;
return settle(_resumeFailure(failure.code, failure.detail));
} catch (_) {
return unconfirmed;
}
if (result['creationId'] != receipt) return unconfirmed;
switch (result['state']) {
case 'created':
break;
case 'pending':
return const RestartAgentResult(
error: 'The machine is still resuming this harness. Tap it again in a moment.',
);
case 'unavailable':
// Gone rather than refused: the desktop leaves its resume open for this one too.
return settle(
'That harness is no longer available. Search again.',
refused: false,
);
case 'failed':
final failure = result['failure'];
if (failure is! Map || failure['code'] is! String) return unconfirmed;
return settle(
_resumeFailure(failure['code'] as String, failure['detail']),
);
default:
return unconfirmed;
}
final raw = result['agent'];
if (raw is! Map || raw['id'] != stopped.id) return unconfirmed;
final Map<String, dynamic> json;
final Agent resumed;
try {
json = Map<String, dynamic>.from(raw);
resumed = Agent.fromJson(json);
} catch (_) {
return unconfirmed;
}
// The desktop's bar for "resumed": the conversation promised ([Agent.resumedAsPromised]),
// started — not one still starting or already failed.
final promised = stopped.resumedAsPromised(
resumed,
reportedResumed: result['resumed'] != false,
);
if (!promised || resumed.launchState != 'ready') {
return unconfirmed;
}
_agentResumes.remove(key);
// A paused harness came back from this phone: a first-egg habit.
daemonHabits.resumed();
if (_disposed || machineStates[machine.machine.machineId] != machine) {
return const RestartAgentResult();
}
_upsertAgent(machine, resumed, json: json);
notifyListeners();
return const RestartAgentResult();
}
/// The desktop's `_restartFailure` wording for a resume the machine refused.
String _resumeFailure(String code, Object? detail) =>
code == 'PTY_HOST_UNAVAILABLE'
? 'Harness could not open a terminal on this machine. Run harness start on it, then try again.'
: detail is String && detail.isNotEmpty
? detail
: switch (code) {
'ENGINE_LAUNCH_REFUSED' =>
'This engine cannot start on this machine. Nothing was started.',
'UNSUPPORTED_ON_REMOTE' || 'UNSUPPORTED' =>
'Update the harness CLI on this machine to open saved harnesses.',
'AGENT_BUSY' => 'Another operation is changing this harness. Wait for it to finish, then retry.',
_ => 'Could not open this harness: $code',
};
/// Restarts on their way, by machine and agent ([restartAgent]) — the Restart row of the
/// terminal's menu says so while one runs ([agentRestarting]).
///
/// ⚠️ **A second `agent_restart` is a second restart, not a duplicate.** The machine works
/// through what one connection sends in order, so a press that came while the first restart
/// ran — the menu opened again because nothing seemed to happen — waited behind it and then
/// replaced the engine that had only just come back, cutting it off as it started. So a restart
/// of an agent that already has one on its way joins that one and sends nothing; Connectors'
/// restart button guards itself the same way (`_restarting` in `connectors_page.dart`), and
/// joins here too.
final Map<(String, String), Future<RestartAgentResult>> _agentRestarts = {};
/// Whether a restart of this agent is on its way — see [_agentRestarts].
bool agentRestarting(String machineId, String agentId) =>
_agentRestarts.containsKey((machineId, agentId));
/// How long a restart's reply is waited for: longer than the machine can take to answer one.
///
/// ⚠️ **Not the 20s every other request waits.** The machine answers once the new engine is up,
/// and getting there can take more than that: up to 5s asking the shell whether the engine is
/// still installed, up to 3s for the old process to go, up to 8s for the new one to show — and,
/// when the resumed one never shows, another 8s for a fresh one (`cli/src/core/agents/restart.ts`,
/// `swap.ts`). At 20s the phone gave up on a restart still running, said it had failed, and
/// offered Restart again — which would have restarted it a second time.
static const _restartReplyWait = Duration(seconds: 45);
/// What the phone says when it cannot know how a restart ended: the desktop's sentence for the
/// same case (`restart_agent_action.dart`), word for word.
///
/// ⚠️ **Not knowing is not failing.** A reply that did not come in time, a socket that dropped
/// under the request, a machine that lost track of its own answer — in all of these the restart
/// may have happened, or may be happening still. "Restart failed" sent people to press Restart
/// again; this sends them to the terminal first, which shows what really happened.
static const _restartUnconfirmed =
'Could not confirm the restart. Check the terminal before restarting again.';
/// Restarts an agent via `agent_restart` — exits its current engine process and relaunches it
/// daemon-side, resuming its session where possible.
///
/// The reply carries the same fresh `Agent` shape `agent_synced` pushes once the new process is
/// confirmed, so this upserts from the reply directly — idempotent on `agent.id`, same as
/// [createAgent], and safe even if the CLI's own `agent_synced` push for the restart arrives
/// separately (fire-and-forget on the CLI side, unordered relative to this reply).
///
/// A restart of an agent that already has one on its way returns that one's future and sends
/// nothing — see [_agentRestarts]. Listeners hear when one starts and when it ends.
///
/// [RestartAgentResult.error] is a sentence to show as it is: why the machine refused, in the
/// desktop's words ([_restartRefused]), or [_restartUnconfirmed] when the outcome is not known.
Future<RestartAgentResult> restartAgent(String machineId, String agentId) {
final key = (machineId, agentId);
final inFlight = _agentRestarts[key];
if (inFlight != null) return inFlight;
// Answered before anything is held, so a machine that is not there never reads as restarting.
if (machineStates[machineId] == null) {
return Future.value(const RestartAgentResult(error: 'Machine not found'));
}
late final Future<RestartAgentResult> run;
run = _performRestartAgent(machineId, agentId).whenComplete(() {
if (identical(_agentRestarts[key], run)) _agentRestarts.remove(key);
if (!_disposed) notifyListeners();
});
_agentRestarts[key] = run;
notifyListeners();
return run;
}
Future<RestartAgentResult> _performRestartAgent(
String machineId,
String agentId,
) async {
final machine = machineStates[machineId];
if (machine == null) {
return const RestartAgentResult(error: 'Machine not found');
}
Map<String, dynamic> result;
try {
result = await _conn(machineId).request(
'agent_restart',
payload: {'agentId': agentId},
timeout: _restartReplyWait,
);
} on WsRequestFailure catch (failure) {
// How a refusal really arrives: the socket throws it rather than handing back the map.
return _restartRefused(failure.code, failure.detail);
} catch (_) {
// A timeout, a socket that dropped or could not send: no answer, so no outcome to report.
return const RestartAgentResult(error: _restartUnconfirmed);
}
final error = result['error'];
if (error is String) return _restartRefused(error, result['detail']);
final raw = result['agent'];
// Not after the app let go of its state: with [_restartReplyWait] a reply can land long after
// the tap, and a disposed notifier cannot notify.
if (raw is Map && !_disposed) {
try {
final json = Map<String, dynamic>.from(raw);
_upsertAgent(machine, Agent.fromJson(json), json: json);
notifyListeners();
} catch (_) {
// Malformed reply agent — harmless, the CLI's own agent_synced push still lands.
}
}
// Absent (older daemon build) reads as true — assume resumed rather than warn about a fresh
// session that may not have happened, since this field is purely additive UI polish.
final resumed = result['resumed'];
return RestartAgentResult(resumed: resumed is bool ? resumed : true);
}
/// A restart the machine answered with an error code, as the desktop reads one
/// (`AppNotifier._runAgentRestart` there).
///
/// ⚠️ **Three of the codes are not refusals.** `RESTART_FAILED` can follow a relaunch that did
/// happen but was not seen in time — the machine itself files it as "unconfirmed" when it keeps a
/// receipt (`cli/src/core/agents/launches.ts`) — and `INTERNAL` and `CREATION_STORAGE_FAILED`
/// say nothing about the pane at all. Telling those as a failure would invite the second restart
/// the terminal may not need; the desktop calls them unconfirmed, and so does this.
RestartAgentResult _restartRefused(String code, Object? detail) =>
const {
'INTERNAL',
'CREATION_STORAGE_FAILED',
'RESTART_FAILED',
}.contains(code)
? const RestartAgentResult(error: _restartUnconfirmed)
: RestartAgentResult(error: _restartFailure(code, detail));
/// The desktop's `_restartFailure` wording for a restart the machine refused: the machine's own
/// [detail] when it sends one — already a sentence (`That harness has already exited.`) — or a
/// sentence for the code.
///
/// Not [_resumeFailure], which words the same codes for opening saved work.
String _restartFailure(String code, Object? detail) =>
detail is String && detail.isNotEmpty
? detail
: switch (code) {
'UNSUPPORTED_ON_REMOTE' || 'UNSUPPORTED' =>
'Update the harness CLI on this machine to restart a harness.',
'AGENT_BUSY' => 'Another operation is changing this harness. Wait for it to finish, then retry.',
'RESUME_UNAVAILABLE' => 'The saved conversation is unavailable. The harness can still be started fresh.',
'RESUME_SESSION_MISMATCH' => 'The harness came back on a different conversation. The saved one is still kept.',
'RESUME_FAILED' => 'The harness did not come back. Its output and conversation are kept.',
_ => 'Restart failed: $code',
};
/// Fork's attempts, by machine and source agent — see [AgentForkAttempt] for why one outlives
/// its form.
final Map<(String, String), AgentForkAttempt> _agentForks = {};
/// Whether a fork of this agent is on its way: the terminal menu's Fork row says so, as Restart
/// does.
bool agentForking(String machineId, String agentId) =>
forkPending(machineId, agentId) != null;
/// The fork of this agent on its way, if one is — what the terminal page waits on once the
/// form closed before it landed.
Future<ForkAgentResult>? forkPending(String machineId, String agentId) =>
_agentForks[(machineId, agentId)]?.pending;
/// Whether the attempt's source is still the agent its machine lists — the same connection, the
/// same id and the same conversation.
bool _forkSourceCurrent(AgentForkAttempt attempt) {
final machine = attempt._machine;
final source = attempt.source;
if (machine == null ||
source == null ||
!_machineWorkCurrent(machine, attempt._authRevision)) {
return false;
}
final current = machine.agents
.where((agent) => agent.id == source.id)
.firstOrNull;
return current != null && current.sessionId == source.sessionId;
}
/// The Fork form's attempt for [agentId]: the one already held while its source is unchanged or
/// its outcome is still to be checked, else a new one starting from [name] and [prompt].
AgentForkAttempt forkAttempt(
String machineId,
String agentId, {
String name = '',
String prompt = '',
}) {
final existing = _agentForks[(machineId, agentId)];
if (existing != null &&
(_forkSourceCurrent(existing) ||
(existing.locked &&
existing._machine != null &&
_machineWorkCurrent(
existing._machine,
existing._authRevision,
)))) {
return existing;
}
final machine = machineStates[machineId];
final source = machine?.agents
.where((agent) => agent.id == agentId)
.firstOrNull;
return _agentForks[(machineId, agentId)] = AgentForkAttempt._(
machine,
source,
_authRevision,
name: name,
prompt: prompt,
);
}
/// Lets an unconfirmed fork go — only the form's explicit Start another fork does this, and
/// never while it is on its way. False when [attempt] is not the one held.
bool discardForkAttempt(
String machineId,
String agentId,
AgentForkAttempt attempt,
) {
if (attempt.busy ||
!identical(_agentForks[(machineId, agentId)], attempt)) {
return false;
}
_agentForks.remove((machineId, agentId));
return true;
}
/// Fork: a NEW harness that starts with everything [agentId]'s conversation has, in the same
/// project folder — the desktop's `forkAgent`. The source is not touched, not even paused, which
/// is why it has to be idle (`cli/src/core/agents/fork.ts`).
///
/// One fork per agent at a time: asking again while one is on its way joins it, and once its
/// outcome is unknown the same attempt checks it (`agent_create_status`) rather than sending a
/// second `agent_fork`.
Future<ForkAgentResult> forkAgent(
String machineId,
String agentId, {
AgentForkAttempt? attempt,
}) {
final operation = attempt ?? forkAttempt(machineId, agentId);
if (operation.result case final result?
when result.error == null && result.agentId != null) {
return Future.value(result);
}
if (operation.pending case final pending?) return pending;
late final Future<ForkAgentResult> request;
request = _runAgentFork(machineId, agentId, operation)
.then((result) {
operation.result = result;
return result;
})
.whenComplete(() {
if (identical(operation._inFlight, request)) {
operation._inFlight = null;
}
if (!_disposed && _authWorkCurrent(operation._authRevision)) {
notifyListeners();
}
});
operation._inFlight = request;
notifyListeners();
return request;
}
/// The steps of [forkAgent], in the desktop's order and words.
Future<ForkAgentResult> _runAgentFork(
String machineId,
String agentId,
AgentForkAttempt attempt,
) async {
final machine = attempt._machine;
if (machine == null) {
return const ForkAgentResult(error: 'Machine not found');
}
if (machine.machine.machineId != machineId ||
attempt.source?.id != agentId) {
return const ForkAgentResult(
error: 'The source harness is no longer available.',
);
}
if (!_machineWorkCurrent(machine, attempt._authRevision)) {
return const ForkAgentResult(
error: 'This fork is no longer active. Reopen Fork Harness.',
);
}
if (!attempt.awaitingConfirmation) {
if (!_forkSourceCurrent(attempt)) {
return const ForkAgentResult(
error: 'The source harness changed. Close this prompt and reopen Fork Harness.',
);
}
if (attempt.source?.canFork != true) {
return const ForkAgentResult(
error: 'This harness does not support forking.',
);
}
if (agentIsProcessing(machineId, agentId)) {
return const ForkAgentResult(
error: 'This harness is working. Wait for its turn to finish, then fork.',
);
}
if (attempt.name.characters.length > 80) {
return const ForkAgentResult(
error: 'Use at most 80 characters for the name.',
);
}
if (attempt.prompt.length > 2000) {
return const ForkAgentResult(
error: 'Use at most 2000 characters for the first task.',
);
}
attempt._id = _newReceiptId();
}
final checking = attempt.awaitingConfirmation;
attempt._awaitingConfirmation = true;
const unknown = ForkAgentResult(
error: 'The fork is not confirmed yet. Check status, or look for it in Find before starting another.',
);
Map<String, dynamic> result;
try {
result = await _conn(machineId).request(
checking ? 'agent_create_status' : 'agent_fork',
payload: {
'creationId': attempt._id,
if (!checking) ...{
'agentId': agentId,
if (attempt.name.trim().isNotEmpty) 'name': attempt.name.trim(),
if (attempt.prompt.trim().isNotEmpty) 'prompt': attempt.prompt,
},
},
timeout: checking
? const Duration(seconds: 10)
: const Duration(seconds: 20),
);
} on WsRequestFailure catch (failure) {
// Refusals before anything started are safe to correct. These cannot prove nothing did, and
// no answer to a status check can.
if (checking ||
const {
'INTERNAL',
'CREATION_STORAGE_FAILED',
'SPAWN_FAILED',
'REGISTRATION_FAILED',
}.contains(failure.code)) {
return unknown;
}
attempt._awaitingConfirmation = false;
return ForkAgentResult(error: _forkFailure(failure.code, failure.detail));
} catch (_) {
// Disconnects, timeouts and malformed replies: not evidence that the machine did nothing.
return unknown;
}
if (_disposed || !_machineWorkCurrent(machine, attempt._authRevision)) {
return const ForkAgentResult(
error: 'The machine changed while forking. Check its harnesses after reconnecting.',
);
}
if ((checking ||
result.containsKey('creationId') ||
result.containsKey('state')) &&
result['creationId'] != attempt._id) {
return unknown;
}
switch (result['state']) {
case 'pending':
return const ForkAgentResult(
error: 'The machine is still starting the fork. Check again in a moment.',
);
case 'missing':
case 'unconfirmed':
return unknown;
case 'unavailable':
attempt._awaitingConfirmation = false;
return const ForkAgentResult(
error: 'The fork was created but is no longer available. You can start another.',
);
case 'failed':
final failure = result['failure'];
if (failure is! Map || failure['code'] is! String) return unknown;
attempt._awaitingConfirmation = false;
return ForkAgentResult(
error: _forkFailure(failure['code'] as String, failure['detail']),
);
case 'created':
case null: // A first answer from a machine predating receipts.
break;
default:
return unknown;
}
final raw = result['agent'];
if (raw is! Map ||
raw['id'] is! String ||
(raw['id'] as String).isEmpty ||
raw['id'] == agentId) {
return unknown;
}
final Map<String, dynamic> json;
final Agent fork;
try {
json = Map<String, dynamic>.from(raw);
fork = Agent.fromJson(json);
} catch (_) {
return unknown;
}
attempt._awaitingConfirmation = false;
if (identical(_agentForks[(machineId, agentId)], attempt)) {
_agentForks.remove((machineId, agentId));
}
_upsertAgent(machine, fork, json: json);
// Into the tab the phone is in — the source's, since Fork is asked from its terminal — the way
// the desktop places a fork beside its source.
_desk.adopt((
machineId: machineId,
agentId: fork.id,
), name: fork.displayName);
notifyListeners();
return ForkAgentResult(
level: result['level'] == 'handoff' ? 'handoff' : 'native',
agentId: fork.id,
);
}
/// The desktop's `_forkFailure`: the machine's own [detail] when it sends one, else a sentence
/// for the code.
String _forkFailure(String code, Object? detail) =>
detail is String && detail.isNotEmpty
? detail
: switch (code) {
'UNSUPPORTED_ON_REMOTE' || 'UNSUPPORTED' =>
'Update the harness CLI on this machine to fork a harness.',
'AGENT_BUSY' =>
'This harness is working. Wait for its turn to finish, then fork.',
_ => 'Fork failed: $code',
};
/// Change agent's switches, by machine and agent — see [_AgentChange] for why one outlives a
/// failed step.
final Map<(String, String), _AgentChange> _agentChanges = {};
/// Whether a switch of this agent is on its way: the terminal menu's Change agent row says so
/// and takes no tap, as Restart does.
bool agentChanging(String machineId, String agentId) =>
_agentChanges[(machineId, agentId)]?.pending != null;
/// Whether Change agent is offered for [agent] — the desktop's pane agent selector.
///
/// ⚠️ **Plain engines only, on the phone.** A domain-specific harness can run only the engines its
/// package lists (`dsh_list`, the desktop's `agentSwitchEngines`), and this app carries no Store
/// catalog to read that from (deliberately off, `agent_model_sections.dart`): offered here, the
/// switch would close the harness and start one the machine then refuses. A terminal is a shell,
/// not an agent to switch (the desktop offers it none either).
static bool canChangeAgent(Agent agent) =>
agent.engine != null && agent.dsh == null && agent.engine != 'terminal';
/// Whether the terminal's menu offers Change agent on [agent] of [machineId]: an agent it can
/// switch ([canChangeAgent]), on this person's own machine while it is online, as the desktop's
/// pane header does. Another account's shared machine answers the handoff for its owner alone
/// (cli superTabs/leadSwitch.ts), so the switch could never go through from here.
bool offersChangeAgent(String machineId, Agent agent) {
final machine = machineStates[machineId];
return canChangeAgent(agent) &&
machine != null &&
!machine.machine.shared &&
machine.nodeOnline != false;
}
/// The engines a harness can be switched to, in the desktop picker's order: OpenCode first, the
/// rest by name. The current one is listed too, as the one it is on.
static List<String> agentChangeEngines() {
final ids = [for (final engine in allEngines) engine.id]
..sort(
(a, b) => a == 'opencode'
? -1
: b == 'opencode'
? 1
: engineIdentity(a).label.compareTo(engineIdentity(b).label),
);
return ids;
}
/// Change agent: the same project, carried on by another engine — the desktop's `changeAgent`.
/// Mostly for a subscription that ran out: Claude Code to Codex, and back.
///
/// The steps, in the desktop's order, each one only if the one before it held:
/// 1. The machine writes a record of the conversation into the project (`agent_handoff_prepare`)
/// and the new agent is told to read it. An older machine answers UNSUPPORTED, and the last
/// requests and answer are handed over instead (`agent_recent`). An engine that takes no first
/// message gets neither: it starts a new conversation in the same folder.
/// 2. The old agent is saved and stopped (`agent_close`, `now`). Never before step 1: a switch
/// that cannot carry the conversation leaves the old agent running.
/// 3. The new agent starts in the same folder, in the same permission mode where it has one.
/// 4. The machine is told which harness took over (`agent_handoff_complete`), best effort.
///
/// Steps 1 to 4 share one id: the handoff's `changeId`, the close's (only once step 1 prepared
/// the handoff), the start's `creationId` and the report's. A Swarm Product Manager's machine
/// stops it only for a close that names the switch it prepared (otherwise LEAD_PROTECTED), and
/// finds its new session by that id (#2493).
///
/// One switch per harness at a time. Choosing the same engine again while one runs joins it;
/// once one fails it is carried on by the same choice, receipt and all, until it is safe to drop
/// — see [_AgentChange].
Future<AgentChangeResult> changeAgent(
String machineId,
String agentId,
String engine,
) {
final machine = machineStates[machineId];
final source = machine?.agents.where((a) => a.id == agentId).firstOrNull;
if (machine == null || source == null) {
return Future.value(
const AgentChangeResult(error: 'This harness is no longer available.'),
);
}
if (source.engine == engine) {
return Future.value(AgentChangeResult(agentId: agentId));
}
if (machine.machine.shared) {
return Future.value(
const AgentChangeResult(
error: 'Only the person whose machine runs this agent can change it.',
),
);
}
if (!canChangeAgent(source) || !allEngines.any((e) => e.id == engine)) {
return Future.value(
const AgentChangeResult(
error: 'This agent is not supported by the installed harness.',
),
);
}
final key = (machineId, agentId);
var change = _agentChanges[key];
if (change?.pending case final pending?) {
return change!.engine == engine
? pending
: Future.value(
const AgentChangeResult(error: 'The agent is already switching.'),
);
}
// Let go of a switch that left nothing to finish: the old agent still running and the handoff
// not held for this engine, or a launch that failed, or a creation refused for good. One whose
// old agent was already stopped is never let go — only finished.
if (change != null &&
((!change.preservingViews &&
(!change.handoffHeld || change.engine != engine)) ||
change.launchFailed ||
(change.creation._finished && change.creation.agentId == null))) {
_agentChanges.remove(key);
change = null;
}
if (change != null && change.engine != engine) {
return Future.value(
AgentChangeResult(
error:
'Check the pending switch to '
'${engineIdentity(change.engine).label} before choosing another agent.',
),
);
}
final operation = change ?? _AgentChange(source, engine, _authRevision);
_agentChanges[key] = operation;
_logChange(
operation,
change == null
? 'switching from ${source.engine} to $engine'
: 'carrying the switch to $engine on',
);
late final Future<AgentChangeResult> run;
run = _changeAgent(machineId, operation)
.then((result) {
_logChange(
operation,
result.error == null
? 'switched; ${result.agentId} opens'
: 'stopped: ${result.error}',
);
return result;
})
.whenComplete(() {
if (identical(operation.pending, run)) operation.pending = null;
if (!_disposed) notifyListeners();
});
operation.pending = run;
notifyListeners();
return run;
}
/// The steps of [changeAgent], for the switch [change] holds.
Future<AgentChangeResult> _changeAgent(
String machineId,
_AgentChange change,
) async {
final machine = machineStates[machineId];
final source = change.source;
const inactive = AgentChangeResult(
error: 'This switch is no longer active.',
);
const changed = AgentChangeResult(
error: 'The conversation changed. Reopen Change agent.',
);
bool live() =>
machine != null &&
machineStates[machineId] == machine &&
_machineWorkCurrent(machine, change.revision);
// The harness as the machine lists it now, if it is still the one chosen.
Agent? same() {
final now = machine?.agents.where((a) => a.id == source.id).firstOrNull;
return now != null &&
now.createdAt == source.createdAt &&
now.sessionId == source.sessionId
? now
: null;
}
if (!live()) return inactive;
final current = same();
if (current == null) {
change.handoffHeld = false;
return changed;
}
final folder = source.project?.cwd;
if (folder == null || folder.isEmpty) {
return const AgentChangeResult(
error: 'This harness has no project folder to open with another agent.',
);
}
// Asked before anything is written on the machine: one that cannot save and stop the old agent
// safely cannot finish the switch, and a handoff file left behind for nothing helps nobody.
if (!current.isStopped &&
!change.closed &&
(current.createdAt == null || !current.closeSupported)) {
return const AgentChangeResult(
error: 'Update the Harness CLI on this machine to close saved sessions safely.',
);
}
if (supportsAgentHandoff(change.engine) && !change.contextLoaded) {
final error = await _loadSwitchHandoff(machineId, change, folder);
if (error != null) return AgentChangeResult(error: error);
if (!live()) return inactive;
}
// The handoff can outlive a binding, an engine or a project change: close only the same one.
final latest = same();
if (latest == null ||
latest.engine != source.engine ||
latest.project?.cwd != folder) {
return changed;
}
change.preservingViews = true;
if (!latest.isStopped && !change.closed) {
_logChange(change, 'saving and stopping the old agent');
// Named only after its handoff was prepared under this id: a Swarm Product Manager's machine
// checks the two belong to one switch, and refuses its close otherwise (LEAD_PROTECTED).
final refused = await _closeAgentNow(
machineId,
latest,
changeId: change.handoffPrepared ? change.creation._id : null,
);
if (refused != null) {
change.preservingViews = false;
return AgentChangeResult(error: refused);
}
change.closed = true;
_logChange(change, 'the old agent is saved and stopped');
if (!live()) return inactive;
}
// The old agent's mode where the new engine has it; otherwise asking first, never more freedom
// than it had. An engine with no modes is sent none (the CLI refuses a mode an engine lacks).
final modes = permissionModesOf(change.engine);
final mode = modes.isEmpty
? null
: modes.any((m) => m.id == source.permissionMode)
? source.permissionMode
: 'ask';
_logChange(
change,
'starting ${change.engine} in the same folder '
'(${change.handoff == null ? 'no first message' : 'with the handoff'})',
);
final error = await createAgent(
machineId,
engine: change.engine,
folder: folder,
permissionMode: mode,
name: source.displayName,
prompt: change.handoff,
attempt: change.creation,
);
if (error != null) return AgentChangeResult(error: error);
final nextId = change.creation.agentId;
if (nextId == null) {
return const AgentChangeResult(
error: 'The new agent has not confirmed its start yet. Choose it again to check.',
);
}
if (!live()) return inactive;
final target = machine!.agents.where((a) => a.id == nextId).firstOrNull;
if (target?.launchState == 'failed') {
change.launchFailed = true;
return AgentChangeResult(
error: target!.launchDetail ?? 'The new agent could not start.',
);
}
// Before the switch is let go: while it is reported, choosing an agent again joins this one
// rather than starting a second harness off the stopped one. Unreported, a Swarm Product
// Manager's machine never takes the new session in and closes it once its time is up (cli
// superTabs/host.ts, SWITCH_ADOPT_MS), so the switch is not done until it is: choosing again
// reports it, as the desktop does.
if (!change.replacementReported) {
if (!await _reportReplacement(machineId, change, nextId)) {
return const AgentChangeResult(
error: 'The new agent started. Choose it again to finish the switch.',
);
}
change.replacementReported = true;
if (!live()) return inactive;
}
_agentChanges.remove((machineId, source.id));
unawaited(agentPreference.select(change.engine));
String? notice;
if (change.handoffEmpty) {
final from = engineIdentity(source.engine).label;
final to = engineIdentity(change.engine).label;
notice = change.handoffFailed
? agentSwitchHandoffFailedHint(from, to)
: agentSwitchNoHistoryHint(from, to);
}
return AgentChangeResult(agentId: nextId, notice: notice);
}
/// Tells the machine which harness took over (`agent_handoff_complete`), the desktop's
/// replacement report, so a Swarm keeps the same agent on the new session (`agent.rebind`).
/// Whether it is done: recorded, or a machine too old to take one (`UNSUPPORTED`), as the
/// desktop counts it. A refusal or no answer in time is logged, and the switch waits for it.
Future<bool> _reportReplacement(
String machineId,
_AgentChange change,
String replacementId,
) async {
try {
final reply = await _conn(machineId).request(
'agent_handoff_complete',
payload: {
'agentId': change.source.id,
'replacementId': replacementId,
'changeId': change.creation._id,
'targetEngine': change.engine,
},
timeout: const Duration(seconds: 5),
);
final recorded = reply['ok'] == true;
_logChange(
change,
recorded
? 'the machine recorded the replacement'
: 'the replacement report was not confirmed',
);
return recorded;
} on WsRequestFailure catch (failure) {
if (failure.code == 'UNSUPPORTED') {
_logChange(change, 'the machine takes no replacement report');
return true;
}
_logChange(
change,
'the replacement report was refused (${failure.code})',
);
return false;
} catch (error) {
_logChange(change, 'the replacement report was not answered ($error)');
return false;
}
}
/// Fills [change]'s handoff for the new agent, or says why the switch must not go on — the
/// desktop's `_loadSwitchHandoff`. Both reads happen BEFORE the old agent is closed.
///
/// First choice: the machine writes the whole conversation into the project and the new agent is
/// told to read it. A reply that does not hold up ([acceptAgentHandoffReply]) holds the switch with
/// the old agent still running. Only an explicit UNSUPPORTED — a machine older than the request —
/// falls back to the last requests and answer.
Future<String?> _loadSwitchHandoff(
String machineId,
_AgentChange change,
String folder,
) async {
const waiting =
'Waiting for the conversation handoff. Try switching again.';
const unreadable =
'Could not read the conversation for the handoff. Try switching again.';
final source = change.source;
change.handoffHeld = true;
try {
final reply = await _conn(machineId).request(
'agent_handoff_prepare',
payload: {
'agentId': source.id,
'changeId': change.creation._id,
'targetEngine': change.engine,
},
timeout: const Duration(seconds: 6),
);
final accepted = acceptAgentHandoffReply(
reply,
agentId: source.id,
changeId: change.creation._id,
folder: folder,
sourceLabel: engineIdentity(source.engine).label,
);
if (!accepted.accepted) {
_logChange(
change,
'handoff reply did not hold up; the old agent keeps running',
);
return waiting;
}
_logChange(
change,
accepted.prompt == null
? 'handoff: nothing to hand over'
: 'handoff: the machine wrote the record',
);
change
..handoff = accepted.prompt
..handoffEmpty = accepted.prompt == null
..handoffFailed = false
..contextLoaded = true
..handoffPrepared = true
..handoffHeld = false;
return null;
} on WsRequestFailure catch (failure) {
if (failure.code == 'CHANGE_CONFLICT') {
change.handoffHeld = false;
_logChange(change, 'handoff: the conversation changed');
return 'The conversation changed. Choose the agent again to start a new switch.';
}
if (failure.code != 'UNSUPPORTED') {
_logChange(
change,
'handoff refused (${failure.code}); the old agent keeps running',
);
return agentHandoffHeldMessage(
failure.code,
failure.hold,
engineIdentity(source.engine).label,
);
}
_logChange(
change,
'handoff: an older machine; reading the last requests instead',
);
} catch (error) {
_logChange(
change,
'handoff unanswered ($error); the old agent keeps running',
);
return waiting;
}
try {
final recent = await _conn(machineId).request(
'agent_recent',
payload: {'agentId': source.id, 'n': 5},
timeout: const Duration(seconds: 4),
);
if (recent['agentId'] != null && recent['agentId'] != source.id) {
return unreadable;
}
final handoff = agentSwitchHandoff(
source.engine ?? 'the previous agent',
recent,
);
_logChange(
change,
handoff == null
? 'handoff: no excerpt to hand over'
: 'handoff: excerpt read',
);
change
..handoff = handoff
..handoffEmpty = handoff == null
..handoffFailed = handoff == null
..contextLoaded = true
..handoffHeld = false;
return null;
} catch (error) {
_logChange(
change,
'excerpt unreadable ($error); the old agent keeps running',
);
return unreadable;
}
}
/// One line of a switch's progress in the app log: which harness, and what just happened. Never
/// the conversation itself — no prompt, no excerpt, no path — only the steps, so a switch that
/// stopped somewhere can be followed afterwards (the first one on a phone stopped on a close that
/// never came back, and nothing said where).
void _logChange(_AgentChange change, String step) => appLog.info(
'agents',
'change agent ${_shortId(change.source.id)}: $step',
);
/// Saves and stops [agent] at once (`agent_close`, `now`) — the desktop's session close, for
/// Change agent. Null once the machine says it closed; otherwise what to tell the person.
///
/// ⚠️ **A lost reply never sends a second Stop.** The machine's own list is read instead, and only
/// a harness it lists as stopped, the same one, counts as closed.
///
/// [changeId]: the switch whose handoff the machine prepared — see
/// [_AgentChange.handoffPrepared].
Future<String?> _closeAgentNow(
String machineId,
Agent agent, {
String? changeId,
}) async {
final machine = machineStates[machineId];
final revision = _authRevision;
try {
final result = await _conn(machineId).request(
'agent_close',
payload: {
'agentId': agent.id,
'sessionId': agent.sessionId ?? '',
'createdAt': agent.createdAt!.toUtc().toIso8601String(),
'mode': 'now',
'changeId': ?changeId,
},
// Saving the conversation and letting the engine exit can take seconds on the machine.
timeout: const Duration(seconds: 30),
);
if (result['closed'] == true) return null;
return closeRefusalMessage(result['error'], result['detail']);
} on WsRequestFailure catch (failure) {
appLog.info(
'agents',
'change agent ${_shortId(agent.id)}: close refused (${failure.code})',
);
if (failure.code == 'AGENT_CHANGED') {
return 'The conversation changed. Reopen Change agent.';
}
return closeRefusalMessage(failure.code, failure.detail);
} catch (error) {
appLog.warn(
'agents',
'change agent ${_shortId(agent.id)}: close reply lost ($error); '
'asking the machine whether it stopped',
);
if (machine == null) return _closeUnconfirmed;
final stopped = await _stoppedAfterLostClose(machine, agent, revision);
final now = switch (stopped) {
true => 'stopped',
false => 'still running',
null => 'unknown',
};
appLog.info(
'agents',
'change agent ${_shortId(agent.id)}: after the lost reply the old '
'agent is $now',
);
return switch (stopped) {
true => null,
false =>
'The computer did not confirm the close, and the old agent is still '
'running. Try switching again.',
null => _closeUnconfirmed,
};
}
}
static const _closeUnconfirmed =
'Could not confirm the close. Check the machine connection and try again.';
/// What Change agent says when the machine will not save and stop the old agent: the machine's
/// own [detail] when it sends one, as the desktop does; otherwise the CLI's sentence for [code]
/// (lib/closeAgentService.ts), never the bare code. A Swarm Product Manager's machine refuses
/// any close but its prepared switch's (LEAD_PROTECTED), and a second switch while one runs
/// (LEAD_SWITCHING).
@visibleForTesting
static String closeRefusalMessage(Object? code, Object? detail) =>
detail is String && detail.isNotEmpty
? detail
: switch (code) {
'LEAD_PROTECTED' =>
'This harness is the Product Manager of a Swarm project. '
'Delete its project first to stop it.',
'LEAD_SWITCHING' =>
'This Product Manager is already switching its agent. '
'Wait for it to finish.',
_ =>
'Could not save and stop this conversation. '
'Its agent has not been changed.',
};
/// How long a lost close waits for its socket to come back before it reads the machine's list.
static const _closeRecheckReady = Duration(seconds: 15);
/// How long between the reads of the machine's list after a lost close. A field only so a test
/// need not wait it out, as [resumeRedialAfter] is.
@visibleForTesting
Duration closeRecheckEvery = const Duration(seconds: 3);
/// After an `agent_close` whose reply never came: whether the machine stopped [agent], read from
/// its own list once the socket is back. True stopped, false still running, null not known (no
/// socket, a harness gone or replaced, the account changed).
///
/// ⚠️ **Why the switch asks rather than giving up.** The first switch tried on a phone sent its
/// close and heard nothing for 28s, until the relay dropped the socket (2026-10-16, a Codex
/// harness). Whether the close ran at all could not be told from the phone, and "could not
/// confirm" left the person with nothing to go on. The machine's list says it: stopped, and the
/// switch carries on as if the reply had come; still running, and it says so, with the old agent
/// untouched. Read three times, [closeRecheckEvery] apart, because saving a conversation can
/// still be finishing when the socket comes back. Read straight from the machine rather than from
/// this phone's list, which the reconnect may still be refreshing.
Future<bool?> _stoppedAfterLostClose(
MachineState machine,
Agent agent,
int revision,
) async {
final connection = _conn(machine.machine.machineId);
try {
await connection.waitUntilReady(timeout: _closeRecheckReady);
} catch (_) {
return null;
}
bool? stopped;
for (var read = 0; read < 3; read++) {
if (read > 0) await Future<void>.delayed(closeRecheckEvery);
if (!_machineWorkCurrent(machine, revision)) return null;
try {
final listed = await connection.request(
'agents_list',
payload: kAgentsListPayload,
timeout: const Duration(seconds: 10),
);
final raw = (listed['agents'] as List?)
?.whereType<Map>()
.map((m) => Map<String, dynamic>.from(m))
.where((m) => m['id'] == agent.id)
.firstOrNull;
final observed = raw == null ? null : Agent.fromJson(raw);
// Gone, or another harness under the id now: not this close's to call either way.
if (observed == null || !observed.continuesSession(agent)) return null;
if (observed.isStopped) {
if (_machineWorkCurrent(machine, revision)) {
_upsertAgent(machine, observed, json: raw);
notifyListeners();
}
return true;
}
stopped = false;
} catch (_) {
// No answer this time: the next read may get one.
}
}
return stopped;
}
/// Live models on every harness grid this machine is signed into, for the
/// model sheet.
///
/// Asked of the machine the agent runs on rather than kept in app state: the
/// answer is whatever that machine's `grid` reports at this moment (an engine
/// can join or leave between two opens), and a cached list would offer a
/// model nobody is serving any more.
///
/// Never throws — a machine whose daemon is too old to know the RPC, one with
/// no grid, and one that timed out are all "nothing to offer", which is what
/// the sheet shows.
///
/// [userAction] marks the read as a person opening a model sheet: the only
/// read the model list's reach counts (`model_list_user_*`).
Future<GridModels> gridModels(
String machineId, {
bool userAction = false,
}) async {
try {
final response = await _conn(machineId).request(
'grid_models_list',
payload: userAction ? const {'userAction': true} : const {},
timeout: const Duration(seconds: 12),
);
List<GridModel> parseModels(Object? raw, {String? grid}) =>
(raw as List<dynamic>? ?? [])
.whereType<Map<String, dynamic>>()
.map(
(m) => GridModel(
id: (m['id'] as String?) ?? '',
node: (m['node'] as String?) ?? '',
grid: grid,
),
)
.where((m) => m.id.isNotEmpty)
.toList();
final capable = response['localModelEngines'];
return GridModels(
supportsModelLaunch: response['supportsModelLaunch'] == true,
gridName: response['gridName'] as String?,
// The own grid's list, which an older daemon sends on its own.
models: parseModels(response['models']),
grids: (response['grids'] as List<dynamic>? ?? [])
.whereType<Map<String, dynamic>>()
.where((g) => (g['name'] as String?)?.isNotEmpty == true)
.map(
(g) => GridSection(
name: g['name'] as String,
own: g['own'] == true,
models: parseModels(g['models'], grid: g['name'] as String),
),
)
.toList(),
localModelEngines: capable is List
? capable.whereType<String>().map((e) => e.toLowerCase()).toSet()
: null,
gridCli: GridCli.parse(response['gridCli']),
);
} catch (_) {
// NOT `gridName: null` with an empty list — that is the shape of "this
// account has no grid", and a caller cannot tell it from "the machine did
// not answer". A signed-in user whose daemon was offline would be told to
// sign in again, which is both wrong and unactionable.
return const GridModels.unreachable();
}
}
/// Point one agent at a model on a harness grid. Returns null on success, or
/// the one sentence to show — the phone has no error rail, so the caller
/// snackbars it (see [retargetRefusalMessage]).
///
/// Sends the model id and nothing else: the daemon on that machine resolves
/// the endpoint and the credential from its own signed-in `grid`, so neither
/// travels over the relay and the phone never holds a grid key. Moving an
/// agent re-execs its pane, which is why this is an explicit choice in a
/// sheet rather than something a swipe can do.
///
/// [gridName] is the grid the model was picked from — a shared grid's section
/// in the sheet. Absent, the daemon uses the account's own grid.
Future<String?> retargetAgentToGridModel(
String machineId,
String agentId,
String modelId, {
String? gridName,
}) => _retarget(machineId, agentId, {
'agentId': agentId,
'gridModel': modelId,
'gridName': ?gridName,
});
/// Put the agent back on its engine's own vendor login.
Future<String?> clearAgentGrid(String machineId, String agentId) =>
_retarget(machineId, agentId, {'agentId': agentId, 'clearGrid': true});
/// The one `agent_retarget` call both doors take.
///
/// A refusal happens BEFORE the daemon touches the pane — an engine with no
/// way onto a Local model, a busy agent, a machine that cannot resolve its
/// models — so nothing in the terminal ever says why, and without this the
/// tap simply does nothing. One sentence, in the app's own words; the
/// daemon's own `detail` is written for its log and names the grid.
///
/// A transport failure is NOT a refusal: the daemon may well have done the
/// move, and the agent frame that follows is the truth. Nothing is said
/// rather than a story the terminal is about to contradict.
Future<String?> _retarget(
String machineId,
String agentId,
Map<String, dynamic> payload,
) async {
try {
await _conn(machineId).request(
'agent_retarget',
payload: payload,
timeout: const Duration(seconds: 30),
);
return null;
} on WsRequestFailure catch (failure) {
return _retargetRefusal(machineId, agentId, failure.code, failure.detail);
} catch (_) {
return null;
}
}
String _retargetRefusal(
String machineId,
String agentId,
String code,
String? detail,
) {
final agent = machineStates[machineId]?.agents
.where((a) => a.id == agentId)
.firstOrNull;
return retargetRefusalMessage(
code,
engineLabel: engineIdentity(agent?.engine).label,
detail: detail,
);
}
/// Every tile on the machine, not just the focused one: the machine is what
/// went away, so a tile of the same machine sitting in another corner of the
/// grid is just as dead and must say so rather than keep showing a terminal
/// that can no longer receive anything. Records what was open so the next
/// `connected` can put it back (`_recoverPendingAgent`).
void _markSessionsUnreachable(MachineState machine, String message) {
// The tile being looked at first. `pendingOfflineAgentId` is ONE slot, filled by the first tile
// that qualifies, and `_recoverPendingAgent` SELECTS what is in it — focus, `activeAgentId`
// and the right to take the terminal back all go with that. A phone holds several tiles per
// machine now (the pager's neighbours, see [warmAgentPane]), and list order says nothing
// about which of them a person is reading.
final focused = focusedPane;
final tiles = panesFor(machine.machine.machineId).toList();
if (focused != null && tiles.remove(focused)) tiles.insert(0, focused);
for (final pane in tiles) {
final session = pane.session;
if (session == null) continue;
machine.activeAgentId ??= session.agentId;
// A pane someone else already took over must stay frozen until the user retries it
// themselves (see `_paneNeedsAttach`) — recording it here would have `_recoverPendingAgent`
// call `selectAgent` on reconnect and silently win it back the moment the connection
// returns, fighting whichever machine holds it now.
//
// Nor a warm tile, for the same reason one step removed: nobody ever looked at it, and
// selecting it is what would let it take a terminal another app picked up meanwhile. It
// comes back with the rest, through `_attachPendingPanes`, as politely as it first opened.
if (session.status != TerminalSessionStatus.takenOver && !pane.warm) {
machine.pendingOfflineAgentId ??= session.agentId;
}
// Do not send terminal_close: the adapter is already gone and the
// next client attachment should be the only stream that owns the pane.
session.transportLost(message);
}
}
Future<void> _applyNodeStatus(MachineState machine, bool online) async {
if (_disposed) return;
final machineId = machine.machine.machineId;
final wasOnline = machine.nodeOnline;
machine.nodeOnline = online;
// Asleep or awake decides how often a phone with nothing connected reads the list again.
if (wasOnline != online) _retuneDeafPoll();
if (!online) {
_markSessionsUnreachable(
machine,
'Harness is offline. Run harness start on that machine to reconnect.',
);
_startOfflineRetry(machine);
} else {
_stopOfflineRetry(machineId);
// A socket waiting for this machine to come back need wait no longer ([_parkUntilOnline]).
_pool?[machineId]?.wake('reported online');
if (wasOnline == false) {
for (final pane in panesFor(machineId)) {
pane.session?.transportLost(
'Harness reconnected; restoring terminal…',
);
}
}
final pending = machine.pendingOfflineAgentId;
if (pending != null) {
// Back from off, the list held is from before its Harness went away; otherwise only a
// socket dropped, and the list held still stands.
unawaited(
_recoverPendingAgent(
machine,
pending,
listStands: wasOnline != false,
),
);
} else if (_connectionReady(machineId) &&
(wasOnline == false || panesFor(machineId).any(_paneNeedsAttach))) {
// ⚠️ **A machine that was OFF and is back owes a fresh list, whether or
// not anything here was waiting on it.** This arrives as a `node_status`
// push over a socket that never closed, so `_onConnectionStatus` — which
// is what reloads after every real reconnect — does not run, and the
// list this app holds is from before that machine's Harness restarted.
// Nothing corrects it: the pushes that would have go to a session the
// restart dropped. A phone therefore kept showing a machine's agents
// from minutes earlier, every agent made since invisible, and a desk tab
// holding those agents (`deskGroups`) read as an empty tab.
//
// A tile restored from the saved layout is the other half, and has no
// pendingOfflineAgentId — nothing of its was interrupted, it simply
// arrived before its machine did. Without this it would sit on
// "Attaching…" forever on a machine that has since come back, because
// every other route to _attachSession runs off a load that nothing here
// would trigger.
//
// ⚠️ **Only once the socket is actually up.** `/api/machines` reports a
// machine as running well before this app has finished dialling it, and
// this branch fires off that REST answer — so on a cold launch it asked
// for the agent list against a socket that was still handshaking. The
// request then spent the whole ten-second inventory budget WAITING for
// that handshake, timed out, and the timeout handler read it as the node
// having gone offline and called `forceReconnect()`, which threw away
// the socket that was seconds from being ready and dialled again. That
// is the twelve-second `Attaching → Disconnected → Attaching → Live` a
// launch showed.
//
// Nothing is lost by waiting: `_onConnectionStatus` runs this same load
// with `force: true` the moment the handshake completes, and it is what
// attaches the restored tile in every other case already.
unawaited(_loadMachineData(machine, force: true));
}
}
notifyListeners();
}
/// The relay said [machine] is offline: a socket of the app's that never reached it waits for
/// it to come back instead of redialling on its backoff ([WsConn.parkUntilOnline]). It is woken
/// by any word that the machine is back — `machines_status` down any socket
/// ([_wakeMachinesBackOnline]), its own `node_status`, `/api/machines` ([_applyNodeStatus]) — and
/// by a person opening one of its agents ([_redialNow] → [WsConn.reconnectNow] once the parked
/// socket is gone, or the parked socket itself answering).
///
/// Nothing for a socket that is up: a live session's machine going away is [_applyNodeStatus]'s.
void _parkUntilOnline(MachineState machine) {
final machineId = machine.machine.machineId;
final connection = _pool?[machineId];
if (connection == null || connection.isReady) return;
connection.parkUntilOnline();
// Waiting on a machine that is off is no reason to keep the next one from dialling.
if (connection.isParked) _endReleaseTurn(machineId, 'parked: offline');
}
/// `machines_status` — the relay's word on every machine of the account, sent down every socket
/// as it changes. Read for one thing: a machine reported online whose socket is parked waiting
/// for it ([_parkUntilOnline]) dials now.
///
/// ⚠️ **Not applied as each machine's status.** That stays with `/api/machines` and each
/// socket's own `node_status`, as it was; this frame was ignored before, and taking it up for
/// everything would change what every machine's row says on a feed nothing here was built on.
void _wakeMachinesBackOnline(Object? statuses) {
if (statuses is! List) return;
final now = DateTime.now();
for (final status in statuses) {
if (status is! Map) continue;
final machineId = status['machineId'];
if (machineId is! String || machineId.isEmpty) continue;
final online = status['online'] == true;
_relaySaid[machineId] = (online: online, at: now);
if (online) _pool?[machineId]?.wake('the relay says it is online');
}
}
/// What `machines_status` last said of each machine, and when — read by [reachAllMachines], and
/// by nothing else (see [_wakeMachinesBackOnline] for why it is not the machine's status).
final Map<String, ({bool online, DateTime at})> _relaySaid = {};
/// How long the relay's "offline" stands for [reachAllMachines]. It says so again as it changes,
/// so this is only the bound on trusting a word that may have gone unrepeated.
static const _relayOfflineStands = Duration(minutes: 2);
/// Whether the relay said, a moment ago, that [machineId] is off — so there is nothing to dial.
bool _relaySaysOffline(String machineId, DateTime now) {
final said = _relaySaid[machineId];
return said != null &&
!said.online &&
now.difference(said.at) < _relayOfflineStands;
}
/// Machines whose [_recoverPendingAgent] began on a machine that had been away — see
/// [_reopenFromHeldList], which a later call must not run for them.
final Set<String> _recoveringAfterAway = {};
/// Bring the agent a lost socket was showing back on screen, once [machine] can be asked again.
///
/// [listStands] says the machine itself never went away — only this phone's socket to it — so
/// the list read before the drop still names its agents ([_reopenFromHeldList]).
Future<void> _recoverPendingAgent(
MachineState machine,
String agentId, {
bool listStands = false,
}) async {
final machineId = machine.machine.machineId;
// ⚠️ **Before the in-flight check, and without a single await before it.** A return to the
// app usually starts a recovery from `/api/machines` while the socket is still dialling, and
// that one polls every 250ms — so when the socket came up, this call returned as a duplicate,
// the reconnect sent its `agents_list`, and the poll's reopen went out 40ms behind it, to wait
// out the whole list on the machine's queue all the same (measured on a phone, 254 agents,
// 2026-10-08). Run here, the reopen leaves inside `_onConnectionStatus`, before the list it
// starts, and the list then waits for it ([_yieldToFocusedTerminal]).
if (listStands &&
!_recoveringAfterAway.contains(machineId) &&
_reopenFromHeldList(machine, agentId)) {
return;
}
// Marked even when one is already running: that one asks the machine, and none after it may
// reopen from the held list while it does.
if (!listStands) _recoveringAfterAway.add(machineId);
if (!_offlineRecoveryInFlight.add(machineId)) return;
try {
// E2EE and agents_list can become ready in separate frames after a
// node restart. Poll briefly instead of racing a single request.
for (var attempt = 0; attempt < 40; attempt++) {
if (_disposed ||
machine.nodeOnline != true ||
machine.pendingOfflineAgentId != agentId) {
return;
}
// ⚠️ Poll past a socket that is not up yet rather than asking through
// it. `_loadMachineData` would spend its whole ten-second inventory
// budget waiting for the handshake and then report the machine offline —
// on the very path that exists to recover a machine coming back. The
// delay at the foot of this loop is the poll; this just skips the turn.
if (!_connectionReady(machineId)) {
await Future<void>.delayed(const Duration(milliseconds: 250));
continue;
}
await _loadMachineData(machine, force: true);
final agent = machine.agents.cast<Agent?>().firstWhere(
(candidate) => candidate?.id == agentId,
orElse: () => null,
);
if (agent != null &&
agent.terminalAvailable &&
machine.terminalCapabilityAvailable) {
machine.pendingOfflineAgentId = null;
// Only reattach the terminal if the user is still on THIS machine — recovery can finish
// well after the user has moved on to a different machine/agent, and forcing selectAgent
// here would yank their focus back to what they were looking at before, mid-navigation.
// The recovered agent still shows normally in the rail; they can click it themselves.
if (selectedMachineId == machineId) {
// A machine coming back is not somebody picking the phone up: the
// agent shows again, its terminal stays with whoever holds it.
await selectAgent(
machineId,
agentId,
intent: AttachIntent.automatic,
);
} else {
notifyListeners();
}
return;
}
await Future<void>.delayed(const Duration(milliseconds: 250));
}
} finally {
_offlineRecoveryInFlight.remove(machineId);
_recoveringAfterAway.remove(machineId);
}
}
/// [_recoverPendingAgent]'s first move on a socket that only dropped: the agent reopened from the
/// list read before the drop, now, rather than after the machine has listed every agent again.
/// False — nothing done — unless the socket is up, that list stands ([_listHeldThroughDrop]) and
/// it names the agent with a terminal to open; the caller then asks the machine, as it always did.
///
/// Synchronous to the reopen: [selectAgent] moves the terminal to `opening` before its first
/// await, which is what the list's wait for it reads.
bool _reopenFromHeldList(MachineState machine, String agentId) {
final machineId = machine.machine.machineId;
if (_disposed ||
machine.nodeOnline != true ||
machine.pendingOfflineAgentId != agentId ||
!_connectionReady(machineId) ||
!_listHeldThroughDrop(machine) ||
!machine.terminalCapabilityAvailable) {
return false;
}
final agent = machine.agents.where((a) => a.id == agentId).firstOrNull;
if (agent == null || !agent.terminalAvailable) return false;
machine.pendingOfflineAgentId = null;
// The same two roads as the loop in [_recoverPendingAgent]: focus is not taken back from
// somebody who has moved to another machine meanwhile.
if (selectedMachineId == machineId) {
unawaited(
selectAgent(machineId, agentId, intent: AttachIntent.automatic),
);
} else {
notifyListeners();
}
return true;
}
/// Enable-time fallback: preserve the user's current choice and acknowledge it.
/// Selection records focus before waiting for terminal attachment, so a later
/// user click is never overwritten by completion of an asynchronous open.
Future<void> ensureDeviceFocus(Map<String, dynamic> payload) async {
final expiresAt = payload['expiresAt'];
final machineId = payload['machineId'];
final agentId = payload['agentId'];
final focusRevision = payload['focusRevision'];
if (expiresAt is! num ||
expiresAt <= DateTime.now().millisecondsSinceEpoch ||
machineId is! String ||
agentId is! String ||
agentId.isEmpty ||
focusRevision is! String ||
focusRevision.isEmpty) {
return;
}
if (focusedPane?.agentId != null) return;
// The WiFi device asked, not a hand on this phone — see [AttachIntent].
await _showAgentFromDevice(machineId, agentId);
}
/// The dial turned to an agent. Ordinary selection, the same path a click on the rail takes.
///
/// It used to take a `DeskEdge` and, for an agent with no tile, replace the pane at that end — the
/// dial's carousel could walk past the end of the desk onto an unopened agent, and the edge said
/// which tile it had walked off. The carousel walks only open panes now, so there is no off-desk
/// landing left to place and nothing to replace.
Future<void> selectAgentFromDial(String machineId, String agentId) async {
// ⚠️ Not `selectAgent`: arriving is a claim, and the dial turning is
// not a person arriving at THIS phone. The agent comes on screen; its
// terminal stays with whoever types in it, and the band offers it back.
await _showAgentFromDevice(machineId, agentId);
}
/// Put an agent on screen because a device asked — the dial, the WiFi
/// device — without taking its terminal. See [AttachIntent].
Future<void> _showAgentFromDevice(String machineId, String agentId) async {
final existing = paneOfAgent(machineId, agentId);
if (existing == null) {
await selectAgent(machineId, agentId, intent: AttachIntent.automatic);
return;
}
selectedMachineId = machineId;
machineStates[machineId]?.activeAgentId = agentId;
focusPane(existing.id);
if (existing.session == null) {
await _attachSession(existing, takeControl: false);
}
}
/// Open [agentId] on this phone, taking its terminal.
///
/// ⚠️ **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.
///
/// The displaced app is told who took it and has the same one press back; on the phone that
/// press is a tap or a scroll on the terminal taken back off it.
///
/// 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, {
/// [AttachIntent.automatic] shows the agent without claiming its
/// terminal — the road `_showAgentFromDevice` and recovery take.
AttachIntent intent = AttachIntent.person,
}) async {
final person = intent == AttachIntent.person;
// ⚠️ **A person arriving does not wait out a reconnect backoff — see [_redialNow].** First,
// before anything below can return early on a machine that is not up.
if (person) _redialNow(machineId);
final existing = paneOfAgent(machineId, agentId);
if (existing != null) {
selectedMachineId = machineId;
machineStates[machineId]?.activeAgentId = agentId;
focusPane(existing.id);
// A tile the pager opened ahead of time is being looked at now, so it
// joins the saved layout like any tile a person chose. Left warm, a
// relaunch would restore the tile before it AND reopen this agent from
// `lastOpenedAgent` — two streams for one screen. See [TerminalPane.warm].
if (existing.warm) {
existing.warm = false;
_persistLayout();
}
final terminal = existing.session;
if (terminal != null) {
// 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 = person;
}
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: person);
} else if (terminal.watching && person) {
// ⚠️ **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. 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 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 &&
terminal.status != TerminalSessionStatus.resyncing) {
if (!_canAttachPane(existing)) return;
// Retry the dead stream in place so its output and view context remain
// available until the next keyframe. Healthy panes stay focus-only.
await terminal.reopen();
}
return;
}
await addAgentToSwarm(machineId, agentId, takeControl: person);
}
/// Dial [machineId] now if its socket is down and sitting out a reconnect backoff — somebody has
/// just arrived on one of its agents ([selectAgent]).
///
/// ⚠️ **Why (owner, 2026-09-30).** A socket that fails several dials in a row waits longer before
/// each next one — 1, 2, 4, 8, 16, then 30 seconds (`WsConn._scheduleReconnect`) — and the only
/// thing that cut that short was the app coming back to the foreground ([handleAppResumed]).
/// Picking an agent in Find, swiping onto one, or tapping its terminal all waited it out: the
/// terminal sat on "Reconnecting…" for up to half a minute, for a machine that would have
/// answered the moment anything dialled it. A person looking at the agent is exactly who that
/// backoff was never meant to keep waiting.
///
/// [WsConn.reconnectNow] decides whether there is anything to do — nothing for a socket that is
/// open or already dialling, nothing for one closed on purpose — so a healthy machine costs
/// nothing, and one that is still down costs one dial per arrival, which a person sets the pace
/// of. The connection is only ever the one the app already holds: building one here would dial
/// a machine the launch deliberately left alone (see [_autoConnectAndLoadMachines]).
///
/// Not for a machine waiting on its link: that one comes back with a password, not a redial.
void _redialNow(String machineId) {
if (machineStates[machineId]?.needsLink == true) return;
_pool?[machineId]?.reconnectNow();
}
/// Opens [agentId]'s stream for a tile nobody is looking at yet — the phone's
/// pager attaching the agents either side of the one on screen, so the next
/// swipe lands on output instead of on "Attaching…".
///
/// Everything [selectAgent] does BESIDES attaching is deliberately left out:
/// no focus, no `selectedMachineId`, no `activeAgentId`, no announcement to
/// the daemon, no layout write. The tile is a guess about where the thumb
/// goes next, and none of those should move for a guess. [TerminalPane.warm]
/// is the one thing that marks it, and [selectAgent] is what happens when the
/// guess comes true.
///
/// A tile already there is left alone — except a warm one holding a dead
/// stream, which is reopened the way `_attachPendingPanes` would. A stream
/// someone else took over is NOT reopened from here: that is the tug-of-war
/// `_paneNeedsAttach` exists to avoid, and a page nobody is looking at has no
/// business starting it.
///
/// ⚠️ **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 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;
final existing = paneOfAgent(machineId, agentId);
if (existing != null) {
// Only a tile that is still warm, whose session asks politely. One a
// person has looked at reopens WITH a takeover, and that is for the
// recovery every tile shares (`_attachPendingPanes`) to decide, never
// for a guess about the next swipe.
if (existing.warm && _paneNeedsAttach(existing)) {
// ⚠️ Automatic, spelled out: [_reattachPane] defaults to a PERSON,
// which raises the session's takeover — and a guess reopened that way
// took the terminal off the desktop with nobody on the page.
await _reattachPane(existing, intent: AttachIntent.automatic);
}
return;
}
if (!canAddPane || !_canAttachAgent(machineId, agentId)) return;
final pane = TerminalPane(
id: _nextPaneId++,
machineId: machineId,
agentId: agentId,
)..warm = true;
panes.add(pane);
// 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, takeControl: false);
}
/// Show a MACHINE in the grid, for the states that belong to the machine
/// rather than to any agent on it.
///
/// It has to be a tile like any other — the alternative of letting a machine
/// take over the whole content area would blank three working terminals
/// belonging to two other machines. The one exception is a machine that
/// already needs linking: that state now surfaces as a blocking popup
/// (the desktop's `HomeScreen._maybeShowLinkDialog`) rather
/// than a tile, so opening one here too would just be a redundant "not
/// linked" pane sitting behind it. Selecting is still worth doing — it's
/// what makes the popup's gate notice this machine — the tile is not.
void showMachinePane(String machineId) {
final machine = machineStates[machineId];
if (machine == null) return;
_dismissedLinkPrompts.remove(machineId);
selectedMachineId = machineId;
if (machine.isRemote && machine.needsLink) {
notifyListeners();
return;
}
final existing = panes
.where((pane) => pane.machineId == machineId && pane.agentId == null)
.firstOrNull;
if (existing != null) {
focusPane(existing.id);
notifyListeners();
return;
}
final target = focusedPane;
if (target != null && target.agentId == null) {
target.machineId = machineId;
focusPane(target.id);
notifyListeners();
return;
}
if (!canAddPane) return;
final pane = TerminalPane(id: _nextPaneId++, machineId: machineId);
panes.add(pane);
focusPane(pane.id);
notifyListeners();
}
/// Put an agent into a specific tile, or into a NEW tile when [paneId] is
/// null — which is what a drop on the empty slot means.
Future<void> assignAgentToPane(
int? paneId,
String machineId,
String agentId, {
String? swarmId,
bool takeControl = false,
}) async {
final target = swarms
.where((s) => s.id == (swarmId ?? activeSwarmId))
.firstOrNull;
if (target == null || _disposed) return;
final targetPanes = target.panes;
final machine = machineStates[machineId];
if (machine == null) return;
Agent? agent;
for (final candidate in machine.agents) {
if (candidate.id == agentId) {
agent = candidate;
break;
}
}
if (agent == null) return;
final shared = allPanes
.where((p) => p.machineId == machineId && p.agentId == agentId)
.firstOrNull;
final existing = targetPanes
.where((p) => p.machineId == machineId && p.agentId == agentId)
.firstOrNull;
if (paneId == null && existing != null) {
if (target == activeSwarm) focusPane(existing.id);
return;
}
final replaced = targetPanes.where((p) => p.id == paneId).firstOrNull;
if (replaced == shared && shared != null) {
if (target == activeSwarm) focusPane(shared.id);
return;
}
if (replaced == null &&
existing == null &&
targetPanes.length >= maxPanes) {
_lastError =
'This swarm holds $maxPanes harnesses. Open another swarm to add more.';
_lastErrorRetryable = false;
notifyListeners();
return;
}
final insertion = replaced == null
? targetPanes.length
: targetPanes.indexOf(replaced);
if (existing != null) target.remove(existing);
if (replaced != null) target.remove(replaced);
final pane =
shared ??
TerminalPane(id: _nextPaneId++, machineId: machineId, agentId: agentId);
final firstAgent = targetPanes.every((pane) => pane.agentId == null);
targetPanes.insert(insertion.clamp(0, targetPanes.length), pane);
if (firstAgent && target.name == Swarm.defaultName) {
final name = agent.name.trim();
if (name.isNotEmpty) {
target.name = name.length > 80 ? name.substring(0, 80) : name;
}
}
if (replaced != null && !allPanes.contains(replaced)) {
// Release just the desktop stream. The CLI agent process keeps running.
unawaited(_detachSession(replaced, sendClose: true));
}
target.focusedPaneId = pane.id;
target.zoomedPaneId = null;
if (target == activeSwarm) selectedMachineId = machineId;
_dismissedLinkPrompts.remove(machineId);
machine.activeAgentId = agentId;
_persistLayout();
if (machine.nodeOnline == false) {
machine.pendingOfflineAgentId = agentId;
_startOfflineRetry(machine);
notifyListeners();
return;
}
if (!machine.terminalCapabilityAvailable) {
notifyListeners();
return;
}
machine.pendingOfflineAgentId = null;
_stopOfflineRetry(machineId);
notifyListeners();
if (target == activeSwarm || pane.session != null) {
await _attachSession(pane, takeControl: takeControl);
}
}
/// How this phone introduces itself on `terminal_open`, so a desktop it
/// displaces can say "(this phone) took control": the name given it in
/// Settings, else the OS's, else its model — `core/device_name.dart` has the
/// order and why `Platform.localHostname` ("localhost" on iOS) is not it.
TerminalClientDescriptor phoneClientDescriptor() {
return TerminalClientDescriptor(
kind: 'phone',
name: composePhoneName(
override: phoneNameStore.value,
device: NativeDeviceInfo.cached,
userName: currentUser?.name,
),
);
}
/// Open the stream for a tile that already knows what it wants.
///
/// Separate from [assignAgentToPane] because a restored tile takes this path
/// on its own, later, when its machine finally answers — the intent was
/// settled at launch, and nothing about the selection should move again then.
/// ⚠️ **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 = true,
}) async {
if (_disposed || !allPanes.contains(pane) || pane.session != null) return;
final wantedAgentId = pane.agentId;
if (wantedAgentId == null) return;
if (kTypingTrace) typingEvent('switch: attaching a session to the pane');
final machine = machineStates[pane.machineId];
if (machine == null) return;
if (machine.nodeOnline == false) return;
if (!machine.terminalCapabilityAvailable) return;
Agent? agent;
for (final candidate in machine.agents) {
if (candidate.id == wantedAgentId) {
agent = candidate;
break;
}
}
if (agent == null || !agent.terminalAvailable) return;
final terminal = TerminalSession(
machineId: pane.machineId,
agentId: agent.id,
agentName: agent.name,
engineId: agent.engine,
scrollMemory: _scrollMemoryFor('${pane.machineId}/${agent.id}'),
client: phoneClientDescriptor(),
send: (type, payload) =>
_sendTerminalFrame(pane.machineId, type, payload),
sendBinary: (frame) => _sendTerminalBinary(pane.machineId, frame),
// What tells the open watchdog a SLOW machine from a gone one — see
// [TerminalSession.lastHeardFromMachine]. Read off the connection the pane
// already has, never one built for the asking.
lastHeardFromMachine: () =>
_heldConnection(pane.machineId)?.lastHeardFromMachineAt,
// ⚠️ **A socket that has not finished its handshake is not a stalled one,
// and forcing a reconnect on it destroys the dial that was about to
// succeed.** `terminal_open` can now be sent very early — the agent and
// the machine's capabilities both come from the cache, so a terminal is
// built while the relay handshake is still in flight. That open gets no
// `terminal_ready`, which looks exactly like a stalled stream, and the
// recovery for a stalled stream is `forceReconnect()`: it tore down the
// in-progress dial, the redial started over, and the launch spent an extra
// two seconds showing `Attaching → Disconnected → Attaching → Live`.
//
// Reconnecting is right for a session that stalled on a connection that IS
// up — the relay's cached upstream session going stale, which is what this
// hook was written for. It is wrong before readiness, where there is
// nothing to recover and the thing to do is wait: `_onConnectionStatus`
// reattaches every pane the moment the handshake lands.
onOpenStalled: () async {
final connection = _conn(pane.machineId);
if (!connection.isReady) return false;
await connection.forceReconnect();
return true;
},
// A live stream gone quiet on a socket that heard nothing from the machine either — see
// [TerminalSession.onTransportSilent]. The socket held now, never one built for the asking:
// a pane whose machine has no socket has nothing to redial.
onTransportSilent: () {
final machine = machineStates[pane.machineId];
final connection = _heldConnection(pane.machineId);
if (machine == null || connection == null) return false;
return _redialStaleTransport(
machine,
connection,
why: 'a terminal stream and its socket went quiet',
);
},
// ⚠️ **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;
// Back to an agent read a moment ago: its last screen, at once, until the stream's arrives.
final keptKey = '${pane.machineId}/${agent.id}';
final kept = _keptScreens.remove(keptKey);
if (kept != null) {
terminal.seedScreen(kept);
} else {
// Or its visible screen, kept when this run last left it — see [_keptScreenStore]. Nothing
// from an earlier run: a launch's agent is the skeleton until its keyframe lands.
final saved = _keptScreenStore?.read(keptKey);
if (saved != null) terminal.seedSnapshot(saved);
}
terminal.addListener(notifyListeners);
// The launch's held machines go once a terminal is live — see [_launchMachineId].
if (_launchMachineId != null) _releaseOnFirstFrame(terminal);
notifyListeners();
// Wait for the pane's actual measured viewport before asking the daemon to open anything.
// Sending the 80x24 fallback here used to make the daemon spawn the remote TTY (and render its
// first keyframe) at that wrong size, which then had to be corrected by a resize round trip —
// visible as the terminal's content briefly rendering narrow before snapping to full width. The
// blank "Attaching…" placeholder already covers this measurement, which lands within a frame or
// two of the panel mounting; `waitForViewportSize`'s own 2s timeout falls back to 80x24 only if
// the pane genuinely never gets laid out.
await terminal.open(waitForViewportSize: true);
}
Future<void> _detachSession(
TerminalPane pane, {
required bool sendClose,
/// False where the screen must not outlive the stream: a sign-out, a reset, a deleted agent.
bool keepScreen = true,
}) async {
final terminal = pane.session;
pane.session = null;
if (terminal == null) return;
terminal.removeListener(notifyListeners);
// The screen as the reader left it, for the next time this agent opens in this run — see
// [_keptScreens], and [_keptScreenStore] for one opened again after those three have moved on.
final agentId = pane.agentId;
if (keepScreen && agentId != null && terminal.hasRenderedFrame) {
final key = '${pane.machineId}/$agentId';
_keptScreens.remove(key);
_keptScreens[key] = terminal.terminal;
while (_keptScreens.length > _keptScreenLimit) {
_keptScreens.remove(_keptScreens.keys.first);
}
_keepScreen(key, terminal);
}
if (sendClose) await terminal.close();
terminal.dispose();
}
/// ⌘; — the pane focused before this one.
///
/// tmux spells it the same way, and the reason it earns a key is that two
/// agents at a time is the shape most work actually has: a thing being built
/// and a thing being watched. Walking a list to get back to the other one is
/// the wrong motion, and it gets longer as the grid fills.
set _previousPaneId(int? value) => activeSwarm.previousPaneId = value;
/// ⌘⏎ — one pane filling the grid, and back.
///
/// The id is held rather than a flag, so a zoom SURVIVES the thing that
/// usually breaks this: focus moving. Zoomed on tile 3 and then jumping to
/// tile 5 shows tile 5 zoomed, which is what tmux does and what the eye
/// expects; a boolean would have shown tile 3 while the focus was elsewhere.
int? get zoomedPaneId => activeSwarm.zoomedPaneId;
set zoomedPaneId(int? value) => activeSwarm.zoomedPaneId = value;
/// Put pinned tiles back in their slots after the list moved under them.
///
/// Lifted rather than swapped: after a close everyone has slid up one, and
/// lifting the pinned tile back into its slot leaves that slide intact for
/// every other tile. A swap would instead fling whichever tile inherited the
/// slot to the far end of the grid — one close, two tiles moved, and only one
/// of them explicable.
///
/// A pin past the end of a shrunken grid is HELD, not dropped: the tiles that
/// closed can come back, and forgetting the pin the moment the grid got small
/// would quietly undo a choice the user never revisited.
void _settlePins() {
final pinned = panes.where((pane) => pane.pinnedSlot != null).toList()
..sort((a, b) => a.pinnedSlot!.compareTo(b.pinnedSlot!));
for (final pane in pinned) {
final want = pane.pinnedSlot!;
if (want >= panes.length) continue;
final at = panes.indexOf(pane);
if (at == want) continue;
panes.removeAt(at);
panes.insert(want, pane);
}
}
Future<void> closePane(int paneId, {bool persist = true}) async {
final pane = panes.where((p) => p.id == paneId).firstOrNull;
if (pane == null) return;
// A warm tile was never something the person had open — see
// [TerminalPane.warm] — so closing it is not something to offer undoing.
if (pane.agentId != null && !pane.warm) {
final machine = stateOf(pane.machineId);
final agent = machine?.agents
.where((a) => a.id == pane.agentId)
.firstOrNull;
_rememberClosed(
ClosedAgent(
pane,
activeSwarm,
historyId: 'closed-${_nextClosedHistoryId++}',
name: agent?.name ?? pane.session?.agentName ?? pane.agentId!,
machineName: machine?.machine.displayName ?? pane.machineId,
engine: agent?.engine ?? pane.session?.engineId,
),
);
}
activeSwarm.remove(pane);
_settlePins();
if (persist) _persistLayout();
selectedMachineId = focusedPane?.machineId;
notifyListeners();
if (!allPanes.contains(pane)) await _detachSession(pane, sendClose: true);
}
/// The last screens of agents this phone closed, oldest first — shown the instant one is opened
/// again, while its live stream attaches ([TerminalSession.seedScreen]). A few, not all: each holds
/// its scrollback, up to 10,000 lines.
final _keptScreens = <String, Terminal>{};
static const _keptScreenLimit = 3;
/// What the terminal view's scroll mirror knew of each agent opened most
/// recently in this run — its rows, which of them scroll — so that a reopen,
/// or a keyframe, does not fetch them again ([RemoteScrollMemory]). In memory
/// only, as [_keptScreens] are, and cleared with them.
final _scrollMemories = <String, RemoteScrollMemory>{};
/// A few, not all — each holds up to two grids of 1,500 rows, about a
/// kilobyte a row. Eight: the pager attaches the agents either side of the
/// one on screen, and at four, going back to an agent a few swipes away
/// found its rows already let go.
static const _scrollMemoryLimit = 8;
/// Every agent's scroll memory forgotten — this account's terminals' rows.
void _forgetScrollMemories() {
for (final memory in _scrollMemories.values) {
memory.clear();
}
_scrollMemories.clear();
}
/// [key]'s scroll memory — `machineId/agentId` — made the most recent.
RemoteScrollMemory _scrollMemoryFor(String key) {
final memory = _scrollMemories.remove(key) ?? RemoteScrollMemory();
_scrollMemories[key] = memory;
while (_scrollMemories.length > _scrollMemoryLimit) {
_scrollMemories.remove(_scrollMemories.keys.first)?.clear();
}
return memory;
}
/// The visible screens of the agents opened most recently in this run, in memory only — see
/// [KeptScreenStore]. Where [_keptScreens] has no exact terminal for an agent (it holds three),
/// this has the screen it showed. Null in tests that do not hand one over.
final KeptScreenStore? _keptScreenStore;
/// [terminal]'s screen into [_keptScreenStore] under [key], when it has a live one to keep.
void _keepScreen(String key, TerminalSession terminal) {
final store = _keptScreenStore;
if (store == null) return;
final snapshot = terminal.snapshotForKeeping();
if (snapshot != null) store.put(key, snapshot);
}
/// [json] — one agent as the daemon sent it — into the machine cache's copy of [machine]'s list,
/// for the next launch to draw from ([MachineCache.rememberAgent]). A harness NEW to that list is
/// written out in a moment ([_saveMachineCacheSoon]); any other change waits for the app to leave
/// the screen ([_keepMachineCache]).
void _cacheAgentJson(MachineState machine, Map<String, dynamic> json) {
final cache = _machineCache;
if (cache == null) return;
if (cache.rememberAgent(machine.machine.machineId, json)) {
_saveMachineCacheSoon();
}
}
/// When the machine cache goes out after a harness was added to or removed from it — see
/// [_saveMachineCacheSoon].
Timer? _machineCacheSaveTimer;
static const _machineCacheSaveDelay = Duration(seconds: 3);
/// Write the machine cache in [_machineCacheSaveDelay], not only when the app leaves the screen.
///
/// ⚠️ **For a harness made or deleted — not for every push.** The background write
/// ([_keepMachineCache]) is the one that matters, and it is enough for everything else: a status, a
/// title, a branch drawn a run late costs nothing, the machine's list replaces it a second in.
/// A harness missing from the list costs the launch that reopens it its whole head start (the
/// terminal waits for that list — see [MachineCache.rememberAgent]), and an app closed without
/// passing through the background — killed from a debugger, or crashed — would lose it. Made
/// rarely and by hand, so writing for each is a few writes an hour; the delay lets the pushes
/// that follow a creation (its name, its terminal coming up) land in the same write. Not
/// re-armed by them: the first change starts the clock.
void _saveMachineCacheSoon() {
if (_machineCacheSaveTimer != null || _disposed) return;
_machineCacheSaveTimer = Timer(_machineCacheSaveDelay, _keepMachineCache);
}
/// The machine cache written out if anything in it changed since it last was — the agents this
/// run learned one at a time, between lists ([MachineCache.hasUnsaved]). Called as the app leaves
/// the screen ([handleAppPaused], [handleAppInactive]) and by [_saveMachineCacheSoon]. Never
/// awaited, and nothing when nothing changed: an idle run writes nothing.
void _keepMachineCache() {
_machineCacheSaveTimer?.cancel();
_machineCacheSaveTimer = null;
final cache = _machineCache;
if (cache == null || _disposed) return;
// Nothing learned, and the launch record already names the machine the next launch reopens:
// nothing to write. A person who moved to another machine's agent since is a launch record
// to rewrite, even with every list unchanged.
if (!cache.hasUnsaved &&
!cache.launchRecordStale(lastOpenedAgent.current?.machineId)) {
return;
}
// Signed out, or not yet signed in: the file is the account's, and [logout] clears it.
if (status != AppStatus.authenticated) return;
// A list not there to write would write the cache EMPTY — every machine gone from the next
// launch's warm start. The fetch that fills it saves on landing anyway.
if (machines.isEmpty) return;
_writeMachineCache(cache);
}
Future<void> _closeAllPanes({bool persist = true}) async {
// Everything closing at once is a sign-out or a reset: nothing of it is kept
// ([_detachSession]'s `keepScreen`).
_keptScreens.clear();
_forgetScrollMemories();
final open = allPanes.toList();
for (final swarm in swarms) {
swarm.panes.clear();
swarm.focusedPaneId = null;
swarm.zoomedPaneId = null;
}
for (final pane in open) {
await _detachSession(pane, sendClose: true, keepScreen: false);
}
if (persist) _persistLayout();
}
int _layoutRevision = 0;
Future<void> flushPaneLayout() =>
_paneLayout?.flushSwarms() ?? Future<void>.value();
void _persistLayout() {
_draftSwarmReturns.removeWhere((id, _) {
final swarm = swarms.where((swarm) => swarm.id == id).firstOrNull;
return swarm == null ||
swarm.panes.isNotEmpty ||
swarm.name != Swarm.defaultName;
});
_layoutRevision++;
final saved = swarms.where((swarm) => !isDraftSwarm(swarm.id)).toList();
if (saved.isEmpty) return;
final savedActive = isDraftSwarm(activeSwarmId)
? _draftSwarmReturns[activeSwarmId]
: activeSwarmId;
unawaited(
_paneLayout?.saveSwarms(
saved,
saved.any((swarm) => swarm.id == savedActive)
? savedActive!
: saved.last.id,
),
);
}
/// Rebuild the grid from disk as INTENT only — the tiles appear immediately,
/// each saying which machine it is waiting for, and attach themselves as
/// their machines answer.
///
/// The tiles cannot wait for the machines: machines answer in an order this
/// side does not decide, a restored grid commonly spans two of them, and one
/// being slow or offline must not hold the others blank.
Future<void> _restorePaneLayout() async {
final store = _paneLayout;
if (store == null) return;
final initialSwarm = activeSwarm;
final revision = _layoutRevision;
final saved = await store.loadSwarms();
if (_disposed || revision != _layoutRevision) return;
if (saved != null &&
allPanes.isEmpty &&
swarms.length == 1 &&
activeSwarm == initialSwarm) {
final restored = <Swarm>[];
final pool = <String, TerminalPane>{};
for (final raw in (saved['swarms'] as List).take(maxSwarms)) {
if (raw is! Map || raw['id'] is! String || raw['panes'] is! List) {
continue;
}
final id = raw['id'] as String;
if (id.isEmpty || restored.any((s) => s.id == id)) continue;
final swarm = Swarm(
id: id,
name:
raw['name'] is String && (raw['name'] as String).trim().isNotEmpty
? (raw['name'] as String).substring(
0,
(raw['name'] as String).length.clamp(0, 80),
)
: Swarm.defaultName,
);
for (final item in (raw['panes'] as List).take(maxPanes)) {
final entry = PaneLayoutEntry.fromJson(item);
if (entry == null) continue;
final key = '${entry.machineId}\u0000${entry.agentId}';
final pane = pool.putIfAbsent(
key,
() => TerminalPane(
id: _nextPaneId++,
machineId: entry.machineId,
agentId: entry.agentId,
)..pinnedSlot = entry.pinnedSlot,
);
if (!swarm.panes.contains(pane)) {
swarm.panes.add(pane);
if (entry.pinnedSlot != null) {
swarm.pinnedSlots[pane.id] = entry.pinnedSlot!;
}
}
}
int? paneAt(Object? index) =>
index is int && index >= 0 && index < swarm.panes.length
? swarm.panes[index].id
: null;
swarm.focusedPaneId =
paneAt(raw['focus']) ?? swarm.panes.firstOrNull?.id;
swarm.zoomedPaneId = paneAt(raw['zoom']);
swarm.previousPaneId = paneAt(raw['previousFocus']);
restored.add(swarm);
}
if (restored.isNotEmpty) {
// Older builds saved multiple unused start pages. Retain the selected
// one when possible; custom names and real work stay intact.
final starters = restored.where((swarm) => swarm.isEmptyStarter);
final starter =
starters
.where((swarm) => swarm.id == saved['activeId'])
.firstOrNull ??
starters.firstOrNull;
final hadDuplicateStarters = starters.length > 1;
if (hadDuplicateStarters) {
restored.removeWhere(
(swarm) => swarm.isEmptyStarter && swarm != starter,
);
}
swarms
..clear()
..addAll(restored);
_activeSwarmId = restored.any((s) => s.id == saved['activeId'])
? saved['activeId'] as String
: restored.first.id;
while (swarms.any((s) => s.id == 'swarm-$_nextSwarmId')) {
_nextSwarmId++;
}
_autoPickedAgent = true;
if (hadDuplicateStarters) _persistLayout();
notifyListeners();
return;
}
}
if (allPanes.isNotEmpty ||
swarms.length != 1 ||
activeSwarm != initialSwarm) {
return;
}
final entries = await store.load();
if (_disposed || revision != _layoutRevision) return;
if (entries.isEmpty) return;
for (final entry in entries) {
panes.add(
TerminalPane(
id: _nextPaneId++,
machineId: entry.machineId,
agentId: entry.agentId,
)..pinnedSlot = entry.pinnedSlot,
);
}
// The saved order already puts everything where it was left, so this is
// only a repair: a layout whose file was hand-edited, or trimmed by the
// pane ceiling on the way in, can arrive with a pinned tile off its slot.
_settlePins();
focusedPaneId = panes.first.id;
// A restored grid IS the choice of what to open, so the first-run
// convenience must not also fire and add a fifth agent nobody asked for.
_autoPickedAgent = true;
notifyListeners();
}
/// Attach any tile of this machine that is still waiting.
///
/// Called after every load rather than once, because the three things
/// [_attachSession] insists on — the agent exists, it has a tmux terminal,
/// and the machine's terminal protocol has been negotiated — become true at
/// different moments, and a machine that goes away and returns has to be able
/// to re-arrive at them.
void _attachPendingPanes(
MachineState machine, {
bool retryExisting = true,
required AttachIntent intent,
}) {
// Nobody asked on this phone, and this machine's CLI cannot open a terminal
// without taking it from whoever has it — so it opens nothing.
if (intent == AttachIntent.automatic &&
!machine.terminalNoTakeoverAvailable) {
return;
}
final machineId = machine.machine.machineId;
for (final pane in allPanes.toList()) {
if (!panes.contains(pane) && pane.session == null) continue;
if (pane.machineId != machineId) continue;
// Navigation may mount a new view; it must never retry a retained stream
// or discard its output while the machine is unavailable.
if (!retryExisting && pane.session != null) continue;
if (!_paneNeedsAttach(pane)) continue;
// Covers a tile that never attached AND one holding a stream the machine
// lost. Only the first used to be covered, and the second is why a
// reconnect left every tile but one frozen on "restoring terminal…":
// recovery ran off pendingOfflineAgentId, which is a single slot, so it
// could only ever promise restoration to one of them.
unawaited(_reattachPane(pane, intent: intent));
}
}
/// Whether this tile is showing something that is not a working terminal.
///
/// `takenOver` is deliberately absent. A stream someone else claimed is only
/// reopened when a person asks for it — see [selectAgent], which is reached
/// from the tile's own retry button. Doing it automatically would have two
/// windows trading one terminal back and forth for as long as both stayed
/// open.
bool _paneNeedsAttach(TerminalPane pane) {
if (pane.agentId == null) return false;
final session = pane.session;
if (session == null) return true;
return switch (session.status) {
TerminalSessionStatus.error || TerminalSessionStatus.closed => true,
_ => false,
};
}
/// Reopen a dead stream in its existing session, keeping its rendered output.
/// An already-lost stream needs no close addressed to its previous owner.
Future<void> _reattachPane(
TerminalPane pane, {
AttachIntent intent = AttachIntent.person,
}) async {
if (!_canAttachPane(pane)) return;
final session = pane.session;
if (session == null) {
await _attachSession(pane, takeControl: intent == AttachIntent.person);
} else {
if (intent == AttachIntent.person) session.takeover = true;
await session.reopen();
}
}
bool _canAttachPane(TerminalPane pane) =>
!_disposed &&
allPanes.contains(pane) &&
_canAttachAgent(pane.machineId, pane.agentId);
/// Whether a terminal for this agent could be opened right now, whether or not a pane holds it.
bool _canAttachAgent(String machineId, String? agentId) {
final machine = machineStates[machineId];
return machine != null &&
machine.nodeOnline != false &&
machine.terminalCapabilityAvailable &&
!(machine.isRemote && machine.needsLink) &&
machine.agents.any((a) => a.id == agentId && a.terminalAvailable);
}
/// Resolve a dial agent to the machine that owns it.
///
/// New CLIs state the machine explicitly. Older CLIs only sent an agent id;
/// that is safe to retain only when the current snapshots contain exactly
/// one matching machine. The websocket carrying the event is always the
/// local daemon and is therefore not evidence that the agent is local.
String? _dialFocusMachine(Map<String, dynamic> payload, String agentId) {
final explicitMachineId = payload['machineId'];
if (explicitMachineId is String && explicitMachineId.isNotEmpty) {
final state = machineStates[explicitMachineId];
if (state == null ||
!state.agents.any((candidate) => candidate.id == agentId)) {
return null;
}
return explicitMachineId;
}
String? match;
for (final entry in machineStates.entries) {
if (!entry.value.agents.any((candidate) => candidate.id == agentId)) {
continue;
}
if (match != null) return null; // Ambiguous legacy event: do not guess.
match = entry.key;
}
return match;
}
Future<void> _handleEvent(
String machineId,
Map<String, dynamic> event,
) async {
final machine = machineStates[machineId];
if (machine == null) return;
final type = event['type'] as String? ?? '';
final payload = (event['payload'] as Map<String, dynamic>?) ?? {};
// Only terminal protocol frames visit the session pool. Heartbeats, dial
// scroll and discovery events must not await every retained terminal.
// Each session still sees terminal frames: ready replies match their own
// request/agent, while transport errors must reach the whole machine.
if (type.startsWith('terminal_')) {
for (final pane in panesFor(machineId).toList()) {
await pane.session?.handleFrame(type, payload);
}
return;
}
if (SessionPreviewStore.eventTypes.contains(type)) {
_ingestPreview(machine, event, type, payload);
// Content belongs to the preview's notifier. It must not invalidate the
// whole app for every token or tool event.
if (type != 'turn_started' && type != 'turn_ended') return;
}
switch (type) {
// ── the dial, over the cable, forwarded by the local daemon ──────────────────────────────────
// Local-only frames (backend.sendLocal in the harness CLI): they describe a hand at THIS desk, so
// they never reach the cloud web audience, who may be sitting at another computer entirely.
case 'dial_status':
// The dial came, went, or started taking an update. Its own notifier —
// see [dial] — so nothing else in the window rebuilds for it.
dial.apply(DialStatus.fromJson(payload));
return;
case 'dial_scroll':
// Straight through, including the reports carrying no travel — the ends of a stroke are the point
// of the message. The window does no arithmetic here; the terminal that owns the scrollback does.
final phase = switch (payload['phase']) {
'down' => 0,
'up' => 2,
_ => 1,
};
activeTerminal?.scroll(
phase,
(payload['dy'] as num?)?.round() ?? 0,
(payload['velocity'] as num?)?.round() ?? 0,
);
return;
case 'device_focus':
unawaited(ensureDeviceFocus(payload));
break;
case 'dial_focus':
// Turning the dial to an agent brings that agent's terminal up here — the ordinary selection
// path, the same one a click on the rail takes, failing the same way for a missing terminal,
// an offline machine or an unknown id.
//
// It used to carry an `edge` for an agent with no tile, naming which end of the desk the
// carousel had walked off so a tile could be replaced there. The carousel walks only open
// panes now, so every focus it sends is about a pane that already exists.
final agentId = payload['agentId'];
if (agentId is String && agentId.isNotEmpty) {
final targetMachineId = _dialFocusMachine(payload, agentId);
if (targetMachineId != null) {
unawaited(selectAgentFromDial(targetMachineId, agentId));
}
}
break;
case 'dial_swarm':
// The dial picked a swarm from its own list. The ordinary switch, exactly as ⌘] or a click on
// the tab: the desk changes, `_persistLayout` re-describes it, and the dial's ring and swarm
// line follow from that — nothing is answered to the dial directly.
final swarmId = payload['swarmId'];
if (swarmId is String && swarmId.isNotEmpty) selectSwarm(swarmId);
break;
case 'device_keys_changed':
// The account's device key log grew: read and verify it from this phone's head.
// Arrives once per machine socket, like desk_changed; concurrent reads share one.
unawaited(_deviceLog?.refresh());
return;
case 'machines_changed':
// The account's machine list changed somewhere: a machine created, renamed or deleted. The
// payload is only a reason; the list itself is read again (once per machine socket it
// arrives on: concurrent reads share one).
_rereadMachines();
return;
case 'desk_changed':
// The account's tabs changed — in a window on some computer, or on
// another phone. The frame carries only the revision; the document
// itself is fetched, so a burst of edits collapses into one read.
//
// ⚠️ It arrives once per MACHINE this phone is connected to (the backend
// has no per-phone socket to send it on, so it rides each machine's —
// `lib/webWs.ts`). [PhoneDesk.noticeRevision] is what makes four
// machines mean one GET.
_desk.noticeRevision(payload['revision']);
return;
case 'zoo_changed':
// The account's daemons and eggs changed — an egg earned on a computer,
// a hatch or a pair switch on another client. Once per machine, like
// `desk_changed`; [ZooClient.noticeRevision] makes that one GET.
zoo.noticeRevision(payload['revision']);
return;
case 'node_status':
final online = payload['online'] == true;
if (!online) _parkUntilOnline(machine);
await _applyNodeStatus(machine, online);
break;
case 'machines_status':
// Read only to wake a parked socket, and nothing else changed here: no redraw.
_wakeMachinesBackOnline(payload['statuses']);
return;
case 'machine_select_error':
if (payload['error'] == 'NOT_YOUR_MACHINE') {
// Removed from the account, or no longer shared with it: no redial brings it back, and
// its socket has stopped (WsConn._selectRefused). The account's list is read again so the
// machine leaves the list, its tabs and the cache it came from. Prod, 2026-10-28: a laptop
// removed in September was still selected every ~7 s.
_lastError =
'${machine.machine.displayName} is no longer on your account.';
_lastErrorRetryable = false;
unawaited(refreshMachines());
} else {
_lastError =
'Machine selection failed: ${payload['error'] ?? 'unknown error'}';
_lastErrorRetryable = true;
}
machine.connectionStatus = ConnectionStatus.disconnected;
break;
case 'agent_synced':
final raw = payload['agent'];
if (raw is Map) {
try {
final json = Map<String, dynamic>.from(raw);
final agent = Agent.fromJson(json);
final changed = _upsertAgent(machine, agent, json: json);
if (agent.terminalAvailable) {
// A pane created before this agent's terminal was verified is still sitting on
// "Attaching…" with no session — nothing else re-checks it once agentLoadStatus is
// already `loaded`, so this push is the only signal that it can attach now.
// A push about an agent synced elsewhere.
_attachPendingPanes(machine, intent: AttachIntent.automatic);
// ⚠️ **No redraw for a push that changed nothing**, which is most of them: the
// machine re-sends every agent it has every five minutes (its reconcile), and a
// fleet of eighty was eighty redraws of every screen in two seconds — under
// somebody typing. An attach started above redraws for itself when it lands.
if (!changed) return;
} else {
// ⚠️ **Kept, not removed — the desktop's rule.** This is how a STOP arrives
// (`publishStoppedAgent` pushes the agent with `status: 'stopped'`), and also how an
// agent looks for a moment while its pane is re-verified. Removing it here made
// stopped work vanish from the phone until the next full reload, so there was no row
// left to resume. `agent_deleted` is what removes an agent; this only lets go of the
// streams, which have no terminal behind them any more.
var detached = false;
for (final pane in panesFor(machine.machine.machineId).toList()) {
if (pane.agentId != agent.id) continue;
// `_detachSession` redraws nothing itself — the redraw below is this one's.
if (pane.session != null) detached = true;
await _detachSession(pane, sendClose: false);
}
if (!changed && !detached) return;
}
} catch (_) {
unawaited(_loadMachineData(machine, force: true));
}
} else {
unawaited(_loadMachineData(machine, force: true));
}
break;
case 'agent_created':
final raw = payload['agent'];
if (raw is Map && raw['terminal'] is Map) {
try {
final json = Map<String, dynamic>.from(raw);
final agent = Agent.fromJson(json);
_upsertAgent(machine, agent, json: json);
// Same reattach as `agent_synced` above — a pane can be waiting on this exact agent
// (e.g. one this window's own New Agent dialog just opened) with no session yet.
// A push about an agent created elsewhere.
_attachPendingPanes(machine, intent: AttachIntent.automatic);
} catch (_) {
unawaited(_loadMachineData(machine, force: true));
}
} else {
unawaited(_loadMachineData(machine, force: true));
}
break;
case 'agent_renamed':
final agentId = _eventAgentId(machine, event, payload);
final name = payload['name'];
if (agentId != null && name is String) {
// ⚠️ **No redraw for a name it already has.** A machine coming back online re-sends
// `agent_renamed` for every agent it holds — eighty in one second, measured — and each
// one redrew every screen.
if (!_renameAgent(machine, agentId, name)) return;
} else {
unawaited(_loadMachineData(machine, force: true));
}
break;
case 'agent_deleted':
final agentId = _eventAgentId(machine, event, payload);
if (agentId != null) await _removeAgent(machine, agentId);
// ⚠️ **`retained` is a stop, not a deletion — the desktop's rule.** The
// daemon's `forgetSession` ends the live agent and keeps its work as a
// stopped harness in the same breath, and says only this; the stopped
// row is in the next `agents_list` (`includeStopped`), never in a push.
// Without the read the harness vanished from the phone until the
// next sync tick — the one row somebody opens to resume it.
if (agentId == null || payload['retained'] == true) {
unawaited(_loadMachineData(machine, force: true));
}
break;
// An agent stopped and is waiting on the person. Over the relay since
// 2026-10-21 (cli core/questions.ts `sendRemote`); a daemon from before
// shaped it for the dial and its own computer only, so it never came
// down this wire.
case 'commander_question':
final agentId = _eventAgentId(machine, event, payload);
if (agentId != null) {
final asked = PendingQuestion.fromPayload(
machineId: machineId,
agentId: agentId,
payload: payload,
now: DateTime.now(),
);
if (asked != null) {
// The daemon re-announces an open question after a reconnect, and
// on attaching to a turn that was already mid-dialog. Keep the
// original clock in that case: this is the same wait continuing,
// and restarting it would make a long block look new.
final known = machine.blockedAgents[agentId];
machine.blockedAgents[agentId] =
known != null && known.sameAs(asked)
? asked.withSince(known.since)
: asked;
// Whether it is NEWS is the announcer's to say, not [known]'s:
// `blockedAgents` is emptied on every dropped socket, and the
// re-announce that follows is the same question — see
// `notify/question_notice.dart`.
_announceQuestion(machine, asked);
}
}
break;
// It stopped being on screen — answered here, in the pane by hand, on
// another window, or on the dial. Whoever got there first, everyone else
// is told to stop drawing it.
case 'commander_question_close':
final agentId = _eventAgentId(machine, event, payload);
final requestId = payload['requestId'];
if (agentId != null) {
final open = machine.blockedAgents[agentId];
// Only if it is the one being closed: a stale close must not wipe the
// question that replaced it when a dialog advanced to its next page.
if (open != null &&
(requestId is! String ||
requestId.isEmpty ||
open.requestId == requestId)) {
machine.blockedAgents.remove(agentId);
}
agentNotices.questionClosed((
machineId: machine.machine.machineId,
agentId: agentId,
), requestId: requestId is String ? requestId : null);
}
break;
// Which questions the machine has open at all, said as an app connects,
// after each one still open (cli core/questions.ts `reannounceRemote`).
// One held here and not among them was answered while the phone was away.
case 'commander_questions_open':
final requestIds = payload['requestIds'];
if (requestIds is! List) return;
final open = requestIds.whereType<String>().toSet();
machine.blockedAgents.removeWhere(
(_, asked) => !open.contains(asked.requestId),
);
agentNotices.questionsOpen(machine.machine.machineId, open);
break;
case 'turn_started':
case 'turn_heartbeat':
var changed = false;
final agentId = _eventAgentId(machine, event, payload);
if (agentId != null) {
machine.agentActivityAt[agentId] = DateTime.now();
changed = _markAgentProcessing(machine, agentId);
// Only a START opens a stats turn, for the reason above: a heartbeat
// is a turn already under way, and counting one would report an agent
// this app merely reconnected to as work somebody just asked for.
if (type == 'turn_started') {
stats.onTurnStarted(
_turnActivityKey(machine.machine.machineId, agentId),
);
// Live work, not a reconnect's replay: a harness resumed from here is back.
if (event['replay'] != true) {
productResumes.worked(
_turnActivityKey(machine.machine.machineId, agentId),
);
}
}
} else {
final sessionId = _eventSessionId(event, payload);
if (sessionId != null) {
changed = machine.pendingProcessingSessions.add(sessionId);
}
}
// Renew the watchdog on every heartbeat, but redraw only when the
// agent first becomes busy. Expiry and turn end publish separately.
if (!changed) return;
break;
case 'turn_ended':
final agentId = _eventAgentId(machine, event, payload);
if (agentId != null) {
// The answer just landed — the moment a recency sort should follow.
machine.agentActivityAt[agentId] = DateTime.now();
_cancelTurnActivity(machine.machine.machineId, agentId);
_announceTurnEnd(machine, agentId, event, payload);
} else {
final sessionId = _eventSessionId(event, payload);
if (sessionId != null) {
machine.pendingProcessingSessions.remove(sessionId);
}
}
break;
// The recap that follows a turn's end. Nothing here draws it: it says
// how loudly that end tells.
case 'turn_summary':
_announceTurnTier(machine, event, payload);
return;
// A program in a harness's pane opened a page (Claude Code's `/login`) while this phone was the one
// typing there (cli core/terminals/browser.ts): it opens on this phone. Nothing here to redraw.
case 'browser_open':
final url = payload['url'];
if (url is String && url.isNotEmpty) {
onBrowserOpen?.call(
machineId,
payload['agentId'] as String? ?? '',
url,
);
}
return;
// ⚠️ Everything else changed nothing here, so it must not redraw. The machine streams every
// agent's live chat — `text_delta`, `tool_start`, … — down this socket, several per second
// per agent, and each one used to rebuild every screen listening to this notifier.
default:
return;
}
notifyListeners();
}
/// Feed one machine event straight into the dispatcher.
///
/// The frames worth testing here have no terminal to route through and no
/// socket to arrive on — what they exercise is the bookkeeping either side of
/// that, which is exactly what a live socket makes hard to reach.
@visibleForTesting
Future<void> restorePaneLayoutForTest() => _restorePaneLayout();
@visibleForTesting
Future<void> handleMachineEventForTest(
String machineId,
Map<String, dynamic> event,
) => _handleEvent(machineId, event);
@visibleForTesting
Future<void> handleTerminalBinaryForTest(String machineId, Uint8List frame) =>
_handleTerminalBinary(machineId, frame);
/// Put an already-built session on the grid.
///
/// The seam tests used to get from assigning `activeTerminal` directly, which
/// a grid cannot offer: a session on screen is a session in a TILE, and the
/// tile is what every lifecycle path — a machine going offline, an agent
/// being deleted, a frame arriving — actually looks for.
@visibleForTesting
TerminalPane adoptSessionForTest(TerminalSession session) {
final pane = TerminalPane(
id: _nextPaneId++,
machineId: session.machineId,
agentId: session.agentId,
)..session = session;
panes.add(pane);
focusedPaneId = pane.id;
session.addListener(notifyListeners);
return pane;
}
@visibleForTesting
Future<void> handleEventForTest(
String machineId,
Map<String, dynamic> event,
) => _handleEvent(machineId, event);
/// The agent on screen, when the app is in front of anybody.
AgentRef? get _watchedAgent {
if (!agentNotices.inFront) return null;
final pane = focusedPane;
final agentId = pane?.agentId;
if (pane == null || agentId == null) return null;
return (machineId: pane.machineId, agentId: agentId);
}
void _seeWatchedAgent() {
final watched = _watchedAgent;
if (watched != null) agentNotices.seen(watched);
}
/// Every change the screens hear about is also a chance that the agent on
/// screen is a different one — and going to an agent is what reads its news.
///
/// ⚠️ **Here, and not in the `focusedPaneId` setter where it first went.**
/// Half the roads onto an agent never touch that setter: a NEW pane — a row
/// tapped, a notice tapped — is focused on its swarm directly, and so are a
/// restored layout and a swarm switched to. Hooked there, the mark outlived
/// the person opening the very agent it pointed at. Every one of those roads
/// ends by notifying, so this is the one place none of them can miss. It
/// costs a lookup: [AgentAnnouncer.seen] is silent for an agent with no mark.
@override
void notifyListeners() {
_seeWatchedAgent();
if (!kTypingTrace) {
super.notifyListeners();
return;
}
typingCount('app.notify');
// What every listener does with the tick, right here on this thread — the builds come later,
// in the frame (`frame SLOW`).
final listening = Stopwatch()..start();
super.notifyListeners();
final took = listening.elapsedMicroseconds / 1000;
if (took >= 4) {
typingEvent('notify: listeners took ${took.toStringAsFixed(1)}ms');
}
}
/// [agent] on [machine], as a notice names it.
NoticeAgent _noticeAgent(MachineState machine, Agent agent) => (
ref: (machineId: machine.machine.machineId, agentId: agent.id),
name: agent.displayName,
machine: machine.machine.displayName,
);
/// An agent this phone has not been told about is never announced: a notice
/// about it could not open anything.
Agent? _knownAgent(MachineState machine, String agentId) =>
machine.agents.where((a) => a.id == agentId).firstOrNull;
/// One agent's turn ended: tell the person as the dial would — see
/// `notify/done_notice.dart` for when that is a tap, a mark or a notice —
/// once the daemon's `turn_summary` says how loudly ([_announceTurnTier]).
void _announceTurnEnd(
MachineState machine,
String agentId,
Map<String, dynamic> event,
Map<String, dynamic> payload,
) {
final agent = _knownAgent(machine, agentId);
if (agent == null) return;
final who = _noticeAgent(machine, agent);
agentNotices.turnEndedAwaitingTier(
who,
turnEndFrom(
event,
payload,
reply: sessionPreviews
.read(previewKey(who.ref.machineId, agent))
?.turnReply,
),
watching: () => _watchedAgent == who.ref,
);
}
/// The recap after a turn's end, with how loudly the daemon says it tells
/// (`tier`, cli `services/recaps.ts`): the turn waiting for it is announced
/// now. A daemon that decides none sends its recap without one, and the old
/// rule goes at once.
void _announceTurnTier(
MachineState machine,
Map<String, dynamic> event,
Map<String, dynamic> payload,
) {
final agentId = _eventAgentId(machine, event, payload);
if (agentId == null) return;
agentNotices.tierDecided((
machineId: machine.machine.machineId,
agentId: agentId,
), noticeTierFrom(payload['tier']));
}
/// An agent stopped to ask the person something — see
/// `notify/question_notice.dart`.
void _announceQuestion(MachineState machine, PendingQuestion asked) {
final agent = _knownAgent(machine, asked.agentId);
if (agent == null) return;
final who = _noticeAgent(machine, agent);
agentNotices.questionAsked(
who,
requestId: asked.requestId,
prompt: asked.prompt,
watching: () => _watchedAgent == who.ref,
);
}
/// The app is back in front of somebody: every machine socket the phone lost while it was away
/// dials again now instead of waiting out a backoff nobody is watching.
///
/// ⚠️ The phone loses these sockets by being BACKGROUNDED — the OS stops the process, and it is
/// not obliged to say so. Nothing here detects that at the time, and nothing can: a suspended
/// process runs no code to notice with. Resuming is the first moment the app is able to look, so
/// it is the moment it must.
///
/// Safe to call on every resume. [WsPool.reconnectAll] skips connections that are already open
/// and connections somebody closed on purpose, so a tab switch that cost nothing costs nothing.
///
/// An open socket is not always a live one, though: after [resumeRedialAfter] away, one that
/// heard nothing from its machine meanwhile is dialled again too — see [_redialSocketsSilentSince].
void handleAppResumed() {
if (kTypingTrace) {
final pane = focusedPane;
typingEvent(
'resume: app back in front, on'
' ${pane == null ? '-' : '${_shortId(pane.machineId)}/${_shortId(pane.agentId ?? '-')}'}',
);
}
final pausedAt = _pausedAt;
_pausedAt = null;
_pool?.reconnectAll();
// After reconnectAll, not before: a socket it has just started dialling is not ready, and is
// left to that dial.
if (pausedAt != null &&
DateTime.now().difference(pausedAt) >= resumeRedialAfter) {
_redialSocketsSilentSince(pausedAt);
}
// Back in front of the agent that was on screen: whatever it finished
// while the phone was in a pocket has now been seen.
_seeWatchedAgent();
// ⚠️ **The desk is re-read here and not only on a push.** A backgrounded
// phone runs no code, so every `desk_changed` sent while it was away
// reached a socket nobody was listening on: without this the tabs would be
// whatever they were when the phone went into a pocket, until something
// else happened to change them.
unawaited(_desk.refresh());
if (status == AppStatus.authenticated) {
// The device key log too: a `device_keys_changed` sent while the phone was away reached nobody
// — and this phone's key goes into it if the boot could not put it there.
unawaited(_deviceLog?.ensureRegistered());
// And the machine list, when no machine is connected to push one: the person most likely just
// went to their computer to sign it in.
_rereadMachinesWhileDeaf();
_startDeafPoll();
if (currentUser == null) unawaited(_loadProfile());
}
// The zoo too, for the same reason: a `zoo_changed` sent while the phone
// was in a pocket reached nobody.
if (status == AppStatus.authenticated) unawaited(zoo.refresh());
// Only back from a pocket: a moment on the app switcher (`inactive`) stopped nothing.
if (pausedAt != null && status == AppStatus.authenticated) {
_resumeBackgroundPolls();
}
}
/// Back from a pocket: the periodic reads [handleAppPaused] stopped start again, each with one
/// read now — and never a second beside a read this return already makes.
///
/// - **Agent lists**, per connected machine: the safety net's tick, at once. It reads now a list
/// older than its interval and waits for a fresher one to come due ([_agentSyncTick]) — a list
/// costs the machine a second or two of the queue its keystrokes wait in. A socket lost while
/// away is not connected yet, and reads its whole list when it is ([_onConnectionStatus]).
/// - **An offline machine something waits on**: its poll, unless the machine list is being read
/// again already ([_rereadMachinesWhileDeaf], above), which answers the same question.
/// - **The key watch**: only started again — the device log was just read ([handleAppResumed]'s
/// `ensureRegistered`).
void _resumeBackgroundPolls() {
final now = DateTime.now();
for (final machine in machineStates.values.toList()) {
final machineId = machine.machine.machineId;
if (machine.connectionStatus == ConnectionStatus.connected) {
_startAgentSyncTimer(machineId);
_agentSyncTick(machineId, now);
}
if (machine.nodeOnline == false &&
machine.pendingOfflineAgentId != null &&
!_offlineRetryTimers.containsKey(machineId)) {
_startOfflineRetry(machine);
if (_machineReread == null) unawaited(_pollOfflineMachine(machineId));
}
}
if (machineStates.values.any((m) => m.keyAwaitedSince != null)) {
_armKeyWatch();
}
}
/// The app went into a pocket: stop the reads that only make sense in front
/// of somebody. The sockets are left to the OS, which suspends them anyway —
/// [handleAppResumed] is what puts both back.
///
/// And write the machine cache now ([_keepMachineCache]): this is the last moment the app is sure
/// to run, since closing it from the app switcher starts by sending it here.
///
/// What the phone was still waiting on has no one to wait for it now, and ends before the counts are
/// sent ([_endOpenMeasurementsForBackground]): an app the OS suspends in its first seconds away never
/// hears the socket's answer, and the dial or launch would stay without an outcome.
void handleAppPaused() {
// The first pause of this time away: a second without a resume between (the OS repeating
// itself) does not move the moment the phone actually left.
_pausedAt ??= DateTime.now();
_desk.pause();
_stopDeafPoll();
// And every other read on a timer: Android keeps an app in a pocket running, and it would go on
// asking — the agent lists, an offline machine, the device log while a key is awaited. A read
// already under way still lands. [handleAppResumed] starts them again ([_resumeBackgroundPolls]).
_pauseBackgroundPolls();
// A socket waiting on a machine that is off stops dialling it while nobody is looking;
// [handleAppResumed]'s reconnectAll asks again the moment the phone is back
// ([WsConn.pauseParkedRecheck]).
for (final machine in machines) {
_heldConnection(machine.machineId)?.pauseParkedRecheck();
}
// The agents this run learned between lists, for the next launch — see [_keepMachineCache].
_keepMachineCache();
_endOpenMeasurementsForBackground();
_sendMeasurementBeforeBackground();
}
/// When the app last went into the background ([handleAppPaused]); null while it is in front.
DateTime? _pausedAt;
/// [handleAppPaused]'s half of [_resumeBackgroundPolls]: the timers go, what they counted stays
/// (timeouts, a poll in flight) — a pocket is not the machine going.
void _pauseBackgroundPolls() {
for (final timer in _agentSyncTimers.values) {
timer.cancel();
}
_agentSyncTimers.clear();
for (final hold in _agentSyncHolds.values) {
hold.cancel();
}
_agentSyncHolds.clear();
for (final timer in _offlineRetryTimers.values) {
timer.cancel();
}
_offlineRetryTimers.clear();
_keyWatch?.cancel();
_keyWatch = null;
}
/// How long the app has to have been away before [handleAppResumed] stops trusting an open
/// socket that heard nothing from its machine in that time.
///
/// ⚠️ **Thirty seconds, the daemon's terminal lease** (`HEARTBEAT_TIMEOUT_MS`,
/// `cli/src/lib/terminalStreamManager.ts`). A phone the OS suspended sends no `terminal_alive`, so
/// past this the daemon has closed this phone's terminal streams anyway, and they have to be
/// opened again whatever the socket: a fresh socket costs nothing they were not going to cost.
/// Shorter, a glance at another app would redial a socket that was fine and reopen terminals
/// that were still live — the "every tab switch costs a handshake" [WsConn.reconnectNow] warns
/// about.
///
/// A field rather than a constant only so a test can stand in for half a minute in a pocket, as
/// [trustSettleRound] does for its wait.
@visibleForTesting
Duration resumeRedialAfter = const Duration(seconds: 30);
/// Back after [resumeRedialAfter] away: dial again every socket that still calls itself open
/// but heard nothing from its machine since [since], the moment the app left.
///
/// ⚠️ **Why an open socket is not taken at its word.** The phone's line to the relay is lost by
/// being backgrounded, and above all by the network changing under it — Wi-Fi giving way to 4G
/// in a pocket — and the OS does not always say so: the old socket stays "open", bound to a
/// network that is gone, and takes every send while nothing comes back. Waited out, that was the
/// terminal's 15s watchdog plus its repairs, about twenty seconds of a screen that looked live
/// and took no keys; dialled now, the terminal is back in a couple of seconds.
///
/// ⚠️ **Nothing heard while away is the test, not the time away alone.** A phone whose OS let it
/// run in the background (Android often does, for a while) kept its streams alive and heard
/// their sync frames: that socket is proved alive and left alone, terminals and all.
///
/// Only a machine with a terminal attached: this exists to bring terminals back, and a machine
/// with none has nothing on screen waiting — its socket keeps its own repairs, as it did.
void _redialSocketsSilentSince(DateTime since) {
if (status != AppStatus.authenticated) return;
final away = DateTime.now().difference(since).inSeconds;
for (final machine in machineStates.values.toList()) {
final machineId = machine.machine.machineId;
if (!panesFor(machineId).any((pane) => pane.session != null)) continue;
final connection = _heldConnection(machineId);
if (connection == null) continue;
final heard = connection.lastHeardFromMachineAt;
if (heard != null && heard.isAfter(since)) continue;
_redialStaleTransport(
machine,
connection,
why: 'back after ${away}s away with nothing heard from it',
);
}
}
/// The app lost the foreground for a moment — the app switcher, a system sheet. Nothing stops;
/// only the machine cache is written ([_keepMachineCache]), because the switcher is where an app
/// is closed, and closing it there need not pass through [handleAppPaused] first. The queued
/// counts go now too, for the same reason ([_sendMeasurementBeforeBackground]).
void handleAppInactive() {
_keepMachineCache();
_sendMeasurementBeforeBackground();
}
/// Whether leaving the screen sends the queued product counts ([ProductMeasurement
/// .sendBeforeBackground]). Off under test, where a report would go to the network; a test that
/// passes its own measurement turns it on.
@visibleForTesting
bool sendMeasurementBeforeBackground = !kUnderTest;
/// Counts kept in RAM are lost when iOS ends a suspended app; the minute's report may never come.
/// Never awaited: leaving the screen waits for nothing.
void _sendMeasurementBeforeBackground() {
if (!sendMeasurementBeforeBackground) return;
unawaited(productMeasurement.sendBeforeBackground());
}
/// How often a phone with no machine connected reads the machine list again. Every push
/// (`machines_changed`, `device_keys_changed`) reaches the phone over a machine's socket; with none
/// connected — the person signed in on the phone first and is now running `harness login` on their
/// computer — nothing tells it that computer joined.
@visibleForTesting
Duration deafMachineListInterval = const Duration(seconds: 20);
/// The same read, when the account's ONLY machine is asleep. Switched on, it shows up here on its
/// own within this — the computer the person is standing at, waiting to see it come back.
@visibleForTesting
Duration asleepMachineListInterval = const Duration(seconds: 4);
/// The same read, when every one of SEVERAL machines is asleep.
@visibleForTesting
Duration asleepMachinesListInterval = const Duration(seconds: 8);
Timer? _deafMachineListTimer;
Future<void>? _machineReread;
/// The interval [_deafMachineListTimer] was set to, and the time since — so [_retuneDeafPoll] can
/// tell when that interval no longer fits, and how much of it has already gone.
Duration? _deafPollInterval;
final Stopwatch _deafPollSince = Stopwatch();
/// How long the deaf poll waits between two reads: [asleepMachineListInterval] when the account's
/// one machine is asleep, [asleepMachinesListInterval] when every one of several is, and
/// [deafMachineListInterval] otherwise — no machine at all, or one that is on but not connected
/// (still connecting, or waiting for its password).
///
/// "Asleep" is what its row on the Computers screen says (`phoneMachineStatusOf`): the machine
/// reported off. A machine with no state yet counts as not asleep — the slower, safer interval.
Duration _deafPollIntervalNow() {
if (machines.isEmpty) return deafMachineListInterval;
for (final machine in machines) {
if (machineStates[machine.machineId]?.nodeOnline != false) {
return deafMachineListInterval;
}
}
return machines.length == 1
? asleepMachineListInterval
: asleepMachinesListInterval;
}
void _startDeafPoll() {
if (_disposed || status != AppStatus.authenticated) return;
if (_deafMachineListTimer != null) return;
final interval = _deafPollIntervalNow();
_setDeafPoll(interval, firstIn: interval);
}
/// One read [firstIn] from now, then one every interval the machines call for at the time of each
/// — see [_deafPollIntervalNow]. A timer set again after every read rather than a periodic one,
/// because the interval follows the machines.
void _setDeafPoll(Duration interval, {required Duration firstIn}) {
_deafMachineListTimer?.cancel();
_deafPollInterval = interval;
_deafPollSince
..reset()
..start();
late final Timer timer;
timer = Timer(firstIn < Duration.zero ? Duration.zero : firstIn, () {
_rereadMachinesWhileDeaf();
// Stopped meanwhile — paused, signed out, disposed — or set again already: nothing to do.
if (_disposed || !identical(_deafMachineListTimer, timer)) return;
final next = _deafPollIntervalNow();
_setDeafPoll(next, firstIn: next);
});
_deafMachineListTimer = timer;
}
/// The machines changed (one went to sleep or woke, or the list itself changed): a poll running at
/// an interval that no longer fits is set to the one that does, counting the wait already spent.
///
/// ⚠️ Without this the new interval would only take over after the old one ran out: on launch the
/// poll can start before the machine list has landed — so at [deafMachineListInterval] — and a
/// computer asleep from the start would be read again only after those 20 seconds.
void _retuneDeafPoll() {
final current = _deafPollInterval;
if (_disposed || _deafMachineListTimer == null || current == null) return;
final interval = _deafPollIntervalNow();
if (interval == current) return;
_setDeafPoll(interval, firstIn: interval - _deafPollSince.elapsed);
}
void _stopDeafPoll() {
_deafMachineListTimer?.cancel();
_deafMachineListTimer = null;
_deafPollInterval = null;
_deafPollSince
..stop()
..reset();
}
/// A phone that hears nothing reads the machine list again: the computer the person is signing in on
/// right now appears, and the dial that follows reads the device log for its key first.
void _rereadMachinesWhileDeaf() {
if (_disposed || status != AppStatus.authenticated) return;
if (machineStates.values.any(
(m) => m.connectionStatus == ConnectionStatus.connected,
)) {
return;
}
_rereadMachines();
}
/// Read the machine list again because something other than the person asked; reads under way are
/// shared, and a failure is left to the next one.
///
/// [rereadMachines] is the same read, for a screen that watches the list.
void _rereadMachines() {
_machineReread ??= refreshMachines()
.catchError((Object _) {})
.whenComplete(() => _machineReread = null);
}
/// The machine list read again, joining a read already under way — for a screen waiting on a
/// computer to join, back in front, beside [handleAppResumed]'s own read (`ComputerWatch`).
void rereadMachines() => _rereadMachines();
/// What the local CLI closing this machine's socket with [code] does to the
/// model — the `WsPool.onLocalFailure` path, without a socket.
@visibleForTesting
void localFailureForTest(String machineId, int code, String reason) =>
_onLocalFailure(machineId, code, reason);
/// What a socket finding the session gone for good does to the model — the
/// `WsPool.onAuthFailure` path ([WsCredentialRevoked]), without a socket.
@visibleForTesting
void authFailureForTest(String message) => _signedOutAtRuntime(message);
@override
void dispose() {
_profileAgain?.cancel();
launchMeasurement?.dispose();
productConnections.dispose();
productResumes.dispose();
onboardingMeasurement.dispose();
productMeasurement.dispose();
_measurementConnections.clear();
_disposed = true;
// A sign-in page still up has nobody left to come back to: its listener goes.
if (signInProvider != null) viewer.login.cancel();
_closedHistory.clear();
_stopAccountTimers();
_stopAllOfflineRetries();
_stopAllAgentSyncTimers();
_forgetLaunchHold();
_machineCacheSaveTimer?.cancel();
_machineCacheSaveTimer = null;
_clearAllTurnActivity();
for (final pane in allPanes) {
pane.session?.removeListener(notifyListeners);
pane.session?.dispose();
}
for (final swarm in swarms) {
swarm.panes.clear();
}
sessionPreviews.dispose();
_pushLifecycle?.dispose();
_push?.channel.close();
agentNotices.dispose();
_desk.dispose();
daemonHabits.dispose();
individualArt.dispose();
zoo.dispose();
super.dispose();
}
}
final appStateProvider = Provider<AppNotifier>((ref) {
final app = AppNotifier(
config: AppConfig.dev,
authSession: AuthSession(),
configStore: ConfigStore(),
paneLayoutStore: PaneLayoutStore(),
);
// The app icon's Swarm count: a launch that starts signed out has no
// Swarm session to take the last account's number off.
if (app.agentNotices.system case final SwarmNotices notices) {
swarmBadgeOffWhileSignedOut(
app,
signedOut: () => app.status == AppStatus.unauthenticated,
notices: notices,
);
}
app.bootstrap();
return app;
});