Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

perf(mobile): cut launch-to-terminal from 13.5s to 2.8s

tony1e73bacf3825
diff --git a/mobile/lib/app_shell.dart b/mobile/lib/app_shell.dart
index 7546dc201..74284b111 100644
--- a/mobile/lib/app_shell.dart
+++ b/mobile/lib/app_shell.dart
@@ -22,6 +22,7 @@ import 'widgets/flash_firmware_dialog.dart';
import 'core/startup.dart';
import 'logging/app_log.dart';
import 'logging/install.dart';
+import 'logging/startup_trace.dart';
import 'shortcuts/app_keymap.dart';
import 'widgets/shortcuts_sheet.dart';
import 'widgets/update_notice.dart';
@@ -53,10 +54,22 @@ Future<void> startHarness({
installFileLogs();
CrashLog.install();
appLog.info('app', 'launched');
+ // Reads the clock, which starts it — from here every `startup` line in the log
+ // is an offset into THIS launch. Touched before any awaited work so the origin
+ // is the entrypoint rather than whatever step happens to mark itself first.
+ StartupTrace.mark('startHarness');
final keymap = AppKeymap(store: AppKeymap.fileStore());
// Keyboard configuration has its own file and watchers. It can load beside
// the appearance, but both must be ready before the window becomes usable.
- await Future.wait([loadPersistedSettings(), keymap.start()]);
+ //
+ // Timed apart rather than as one `Future.wait`: they finish together by
+ // construction, so a single number around the pair would only ever report the
+ // slower one and never say WHICH. On a phone that distinction is the whole
+ // question — the keymap reads a file nobody on a touchscreen can have edited.
+ await Future.wait([
+ StartupTrace.time('settings.load', loadPersistedSettings),
+ StartupTrace.time('keymap.start', keymap.start),
+ ]);
runApp(
ProviderScope(
child: HarnessApp(
@@ -65,6 +78,14 @@ Future<void> startHarness({
),
),
);
+ StartupTrace.mark('runApp');
+ // The frame itself, not the call that scheduled it: `runApp` returns before
+ // anything is rasterised, so the gap between these two marks is the build and
+ // paint of the first screen — the part a person actually waits through while
+ // looking at a blank window.
+ WidgetsBinding.instance.addPostFrameCallback(
+ (_) => StartupTrace.mark('firstFrame'),
+ );
}
class HarnessApp extends StatelessWidget {
diff --git a/mobile/lib/auth/auth_session.dart b/mobile/lib/auth/auth_session.dart
index a0d10af05..8c379b3d2 100644
--- a/mobile/lib/auth/auth_session.dart
+++ b/mobile/lib/auth/auth_session.dart
@@ -49,8 +49,29 @@ class AuthSession {
Future<String?> accessToken() => _storage.read(_access);
Future<String?> refreshToken() => _storage.read(_refresh);
Future<String> autonomousEnv() async => (await _storage.read(_env)) ?? 'prod';
- Future<DateTime?> accessTokenExpiresAt() async {
- final raw = await _storage.read(_expiresAt);
+ Future<DateTime?> accessTokenExpiresAt() async =>
+ _expiryFrom(await _storage.read(_expiresAt));
+
+ /// The token and its expiry as ONE read.
+ ///
+ /// The launch asks both questions back to back — is there a session, and is it
+ /// still good — and asking them separately costs two exclusive locks on
+ /// `state.json` and two full parses of it (see [HarnessFileStore]), in series,
+ /// before the app can so much as decide which screen to show.
+ ///
+ /// Reading them together also makes the pair coherent: taken separately, a
+ /// refresh landing between the two reads returns the OLD token with the NEW
+ /// expiry — a token that then looks fresh and is not, which is a sign-in
+ /// failure several round-trips later rather than a refresh here.
+ Future<({String? token, DateTime? expiresAt})> accessTokenWithExpiry() async {
+ final saved = await _storage.readMany([_access, _expiresAt]);
+ return (
+ token: saved[_access],
+ expiresAt: _expiryFrom(saved[_expiresAt]),
+ );
+ }
+
+ static DateTime? _expiryFrom(String? raw) {
final milliseconds = int.tryParse(raw ?? '');
return milliseconds == null
? null
diff --git a/mobile/lib/core/harness_file_store.dart b/mobile/lib/core/harness_file_store.dart
index ced3f888d..63feec6d3 100644
--- a/mobile/lib/core/harness_file_store.dart
+++ b/mobile/lib/core/harness_file_store.dart
@@ -31,8 +31,36 @@ class HarnessFileStore implements BatchLocalKeyValueStore {
final Directory directory;
+ /// The parsed document, held between operations — **only where this app is the
+ /// only writer.**
+ ///
+ /// ⚠️ **On a phone, and only on a phone.** Every read here costs a directory
+ /// create, a lock file open, an exclusive `flock`, a full re-read and re-parse,
+ /// an unlock and a close — and they are queued process-wide, so a launch that
+ /// touches a dozen keys pays that toll a dozen times in series. Measured on a
+ /// simulator, loading three config keys this way took 196ms for a 3 KB file.
+ ///
+ /// Sound because a viewer's state file has exactly one writer: the app itself,
+ /// in its own sandbox, where no `harness` CLI exists and no second process can
+ /// reach the container. On a DESKTOP the CLI writes this same file — the whole
+ /// reason for the lock — so the cache stays off there and every read goes to
+ /// disk exactly as before.
+ ///
+ /// It is a cache of the LAST READ DOCUMENT, refreshed by every write this
+ /// store makes, so it cannot serve values older than this process's own last
+ /// change. [_invalidate] drops it when a write fails and the file's true
+ /// contents are no longer known.
+ Map<String, String>? _cached;
+
+ /// Whether this store may hold [_cached] at all. See its doc comment.
+ final bool _cacheable;
+
HarnessFileStore({Directory? directory})
- : directory = directory ?? Directory(defaultDirectoryPath());
+ : directory = directory ?? Directory(defaultDirectoryPath()),
+ // Only the shared, default-location store on a phone: a store pointed at a
+ // directory a caller chose is a test's, or a second copy of the same file,
+ // and neither may assume it is the only writer.
+ _cacheable = isMobileHost && directory == null;
/// [name] names the sibling under `~/.harness`; it defaults to this store's own.
static String defaultDirectoryPath({
@@ -60,8 +88,16 @@ class HarnessFileStore implements BatchLocalKeyValueStore {
File get _lockFile => File(_join(directory.path, lockFileName));
@override
- Future<String?> read(String key) =>
- _serialized(() async => (await _readDocument())[key]);
+ Future<String?> read(String key) {
+ final cached = _cached;
+ // Answered without touching the filesystem, and without joining the queue:
+ // where this store is the only writer, the held document IS the file. A
+ // `SynchronousFuture` would let this resolve inside the caller's own
+ // microtask, but an ordinary one keeps every caller's ordering identical to
+ // the uncached path, which is worth more than the hop it saves.
+ if (cached != null) return Future.value(cached[key]);
+ return _serialized(() async => (await _readDocument())[key]);
+ }
/// One lock and document read for related preferences. The snapshot is scoped
/// to this call: later reads still observe intervening writes, including
@@ -71,6 +107,10 @@ class HarnessFileStore implements BatchLocalKeyValueStore {
Future<Map<String, String?>> readMany(Iterable<String> keys) {
final requested = keys.toSet();
if (requested.isEmpty) return Future.value(const <String, String?>{});
+ final cached = _cached;
+ if (cached != null) {
+ return Future.value({for (final key in requested) key: cached[key]});
+ }
return _serialized(() async {
final values = await _readDocument();
return {for (final key in requested) key: values[key]};
@@ -128,9 +168,16 @@ class HarnessFileStore implements BatchLocalKeyValueStore {
}
}
+ /// The document on disk, and — where [_cacheable] — what [_cached] becomes.
+ ///
+ /// ⚠️ **Always returns a map the caller may mutate.** `write` and `delete`
+ /// edit what this returns and hand it to [_writeDocument], so handing back
+ /// `_cached` itself would let a write that later fails leave its change in the
+ /// cache, where it would be served as though it had been persisted. Every exit
+ /// below builds a fresh map, and [_remember] copies rather than aliases.
Future<Map<String, String>> _readDocument() async {
final file = stateFile;
- if (!await file.exists()) return <String, String>{};
+ if (!await file.exists()) return _remember(<String, String>{});
try {
final decoded = jsonDecode(await file.readAsString());
if (decoded is! Map<String, dynamic>) {
@@ -150,18 +197,42 @@ class HarnessFileStore implements BatchLocalKeyValueStore {
}
values[entry.key as String] = entry.value as String;
}
- return values;
+ return _remember(values);
} on UnsupportedStateVersionException {
+ // NOT remembered: this one leaves the file untouched and intact, so the
+ // next read must go and look again rather than answer from a document
+ // this store never managed to understand.
rethrow;
} on Object {
+ // The corrupt file has been moved aside, so an empty document is now the
+ // truth on disk and is safe to hold.
await _quarantineCorruptState(file);
- return <String, String>{};
+ return _remember(<String, String>{});
}
}
+ /// Hold [values] as the known contents, and return it for the caller to use.
+ ///
+ /// The COPY is the one kept: callers mutate what they are given (see
+ /// [_readDocument]), and a cache aliased to that map would follow their edits
+ /// before those edits reached the disk.
+ Map<String, String> _remember(Map<String, String> values) {
+ if (_cacheable) _cached = Map<String, String>.from(values);
+ return values;
+ }
+
+ /// Forget the held document: the file's contents are no longer known.
+ void _invalidate() => _cached = null;
+
Future<void> _writeDocument(Map<String, String> values) async {
final suffix = '${pid}_${DateTime.now().microsecondsSinceEpoch}';
final temporary = File(_join(directory.path, '.$fileName.$suffix.tmp'));
+ // ⚠️ Dropped BEFORE the write and only restored once the rename lands. A
+ // write that throws halfway leaves a file this store can no longer describe,
+ // and serving the pre-write document from memory would be a lie that
+ // outlives the process's next read. Cleared first, the next read goes to
+ // disk and finds out.
+ _invalidate();
try {
await temporary.writeAsString(
'${const JsonEncoder.withIndent(' ').convert({'version': schemaVersion, 'values': values})}\n',
@@ -170,6 +241,8 @@ class HarnessFileStore implements BatchLocalKeyValueStore {
await _makePrivateFile(temporary);
await temporary.rename(stateFile.path);
await _makePrivateFile(stateFile);
+ // The rename is the commit: past it, `values` is exactly what is on disk.
+ _remember(values);
} finally {
if (await temporary.exists()) await temporary.delete();
}
diff --git a/mobile/lib/core/last_opened_agent.dart b/mobile/lib/core/last_opened_agent.dart
index c5c4951b1..0a3b7cce8 100644
--- a/mobile/lib/core/last_opened_agent.dart
+++ b/mobile/lib/core/last_opened_agent.dart
@@ -23,10 +23,38 @@ class LastOpenedAgent {
AgentRef? _value;
Future<void> _writes = Future.value();
+ Future<AgentRef?>? _read;
+
+ /// Start reading now, so the home screen does not have to start it later.
+ ///
+ /// ⚠️ **This read is on the phone's critical path, and it used to begin at the
+ /// worst possible moment.** `AgentHome` starts it from `initState` and holds
+ /// the whole screen on "Getting things ready…" until it lands — but `initState`
+ /// only runs once the app is already `authenticated`, so the read joined the
+ /// back of a queue of state-file operations the launch had just made, behind
+ /// an exclusive lock it now had to wait its turn for.
+ ///
+ /// Called from `bootstrap`, the same read instead overlaps the sign-in check
+ /// and the machine fetch, and [read] finds the answer waiting. Idempotent, so
+ /// the prefetch and the screen share one read rather than racing for the lock.
+ void prefetch() => _read ??= _load();
/// What the previous run left, or null. Anything malformed reads as nothing — a missing
/// preference must never hold the app on its launch screen.
- Future<AgentRef?> read() async {
+ ///
+ /// Served from the in-flight or completed [prefetch] when there is one. Not
+ /// cached beyond that: [remember] writes through `_value`, and a stale read is
+ /// how a relaunch reopens the agent before last.
+ Future<AgentRef?> read() {
+ final pending = _read;
+ if (pending == null) return _load();
+ // One-shot: the next caller wants what is on disk now, not what was there
+ // when the launch began.
+ _read = null;
+ return pending;
+ }
+
+ Future<AgentRef?> _load() async {
try {
final raw = await _storage?.read(_key);
if (raw == null) return null;
diff --git a/mobile/lib/core/machine_cache.dart b/mobile/lib/core/machine_cache.dart
new file mode 100644
index 000000000..75da3b0a6
--- /dev/null
+++ b/mobile/lib/core/machine_cache.dart
@@ -0,0 +1,222 @@
+import 'dart:convert';
+
+import 'models.dart';
+import 'snapshot_store.dart';
+
+/// The machines this account had at the end of the last run, so the next launch
+/// can start dialling before `/api/machines` answers.
+///
+/// ⚠️ **A hint, never a source of truth.** The real list always arrives and
+/// always wins: this exists only to fill the ~700ms round-trip during which the
+/// app used to know nothing at all and could therefore do nothing at all. A
+/// machine in here that the account no longer has is dropped the moment the
+/// fetch lands, and one that was added on another device appears then too.
+///
+/// Only machines the account reported as UP are kept. A machine that was off
+/// last time is the one case where acting on stale information costs something
+/// real — a dial that opens a relay socket and then waits out its timeout
+/// against a computer that is not there — and it is also the case the cache can
+/// be most wrong about, because a machine's power state is exactly what changes
+/// between two launches. Writing only the live ones means a wrong guess is the
+/// cheap direction: at worst the phone waits for the fetch, which is what it did
+/// before this existed.
+///
+/// It also remembers each machine's AGENTS, so the phone can draw its terminal —
+/// with the right agent's name on it — while `agents_list` is still in flight.
+/// The agents are kept exactly as the daemon sent them, so [Agent.fromJson] is
+/// the only thing that ever parses that shape; a hand-written mirror of it would
+/// drift the first time a field moved.
+///
+/// Stored beside the state file rather than in it ([SnapshotStore]): this is a
+/// disposable cache with no secrets in it, and it must never take a turn in the
+/// lock queue that the session token and the E2EE keys are waiting in.
+class CachedMachine {
+ const CachedMachine({
+ required this.machine,
+ required this.agents,
+ required this.capabilities,
+ });
+
+ final Machine machine;
+
+ /// What this machine last listed. Empty where the last run never got that far,
+ /// which is simply a machine whose agents this launch waits for as before.
+ final List<Agent> agents;
+
+ /// The machine's last `terminal_capabilities` reply, or null where the last
+ /// run never got one — see [MachineCache.rememberCapabilities].
+ final Map<String, dynamic>? capabilities;
+}
+
+class MachineCache {
+ MachineCache({SnapshotStore? store})
+ : _store = store ?? FileSnapshotStore('machines-cache');
+
+ final SnapshotStore _store;
+
+ /// The last agent list seen for each machine, as the daemon sent it, awaiting
+ /// the next [save].
+ ///
+ /// Held in memory rather than written on the spot: agent lists arrive one
+ /// machine at a time, seconds apart, and a write per arrival would be several
+ /// launches' worth of disk churn for a file only the NEXT launch reads. They
+ /// go out with the machine list, which is written once per refresh.
+ final Map<String, List<Map<String, dynamic>>> _agents = {};
+
+ /// Writes run one at a time, in the order they were asked for.
+ ///
+ /// ⚠️ **[save] and [clear] race otherwise, and the loser is the file.** Both
+ /// are started with `unawaited` — neither is worth making a person wait on —
+ /// so a sign-out issued while a refresh's save is still in flight could leave
+ /// that save landing AFTER the clear, and the next launch would warm-start
+ /// into the machines of the account that just signed out. Queued, the last
+ /// call asked for is the last one written.
+ Future<void> _writes = Future.value();
+
+ /// Bumped when the shape below changes. An older or newer document reads as no
+ /// cache at all, which is always safe — the fetch fills it in.
+ static const _version = 1;
+
+ /// What the last run saw, or empty when there is nothing usable.
+ ///
+ /// Never throws: a cache that cannot be read is a cache that is not there.
+ Future<List<CachedMachine>> read() async {
+ try {
+ final raw = await _store.read();
+ if (raw == null || raw.isEmpty) return const [];
+ final decoded = jsonDecode(raw);
+ if (decoded is! Map<String, dynamic>) return const [];
+ if (decoded['version'] != _version) return const [];
+ final machines = decoded['machines'];
+ if (machines is! List) return const [];
+ final parsed = <CachedMachine>[];
+ for (final item in machines) {
+ if (item is! Map<String, dynamic>) continue;
+ try {
+ final machine = Machine.fromJson(item);
+ final rawAgents = item['agents'];
+ final agents = <Agent>[];
+ if (rawAgents is List) {
+ for (final entry in rawAgents) {
+ if (entry is! Map<String, dynamic>) continue;
+ try {
+ agents.add(Agent.fromJson(entry));
+ } on Object {
+ // One unreadable agent is one agent this launch draws a second
+ // later than it might have. Its machine still opens.
+ continue;
+ }
+ }
+ }
+ final rawCaps = item['capabilities'];
+ final capabilities = rawCaps is Map<String, dynamic> ? rawCaps : null;
+ parsed.add(
+ CachedMachine(
+ machine: machine,
+ agents: agents,
+ capabilities: capabilities,
+ ),
+ );
+ _agents[machine.machineId] = [
+ for (final entry in (rawAgents is List ? rawAgents : const []))
+ if (entry is Map<String, dynamic>) entry,
+ ];
+ // Carried forward so a launch that reads the cache and is closed
+ // before any machine answers still writes back what it knew.
+ if (capabilities != null) {
+ _capabilities[machine.machineId] = capabilities;
+ }
+ } on Object {
+ // One malformed entry does not discard the rest; the fetch will
+ // correct whatever this cache got wrong either way.
+ continue;
+ }
+ }
+ return parsed;
+ } on Object {
+ return const [];
+ }
+ }
+
+ /// Remember [agents] — the daemon's own JSON — as this machine's list.
+ ///
+ /// Kept until the next [save] writes it out. Passing an empty list is
+ /// meaningful and is kept: a machine whose agents were all deleted should come
+ /// back empty next launch, not with the ones it had before.
+ void rememberAgents(String machineId, List<Map<String, dynamic>> agents) =>
+ _agents[machineId] = agents;
+
+ /// Remember a machine's `terminal_capabilities` reply, as the daemon sent it.
+ ///
+ /// ⚠️ **Only ever called with a reply that said the terminal IS available.**
+ /// The point of keeping this is to let the next launch attach a terminal
+ /// before the negotiation round-trip returns, and a remembered "unavailable"
+ /// would instead make the next launch refuse to attach to a machine that may
+ /// well be fine by then — a cache that can only do harm. A machine whose tmux
+ /// really has gone simply negotiates as it always did, one round-trip in.
+ void rememberCapabilities(String machineId, Map<String, dynamic> reply) =>
+ _capabilities[machineId] = reply;
+
+ /// See [rememberCapabilities]. Same lifetime as [_agents].
+ final Map<String, Map<String, dynamic>> _capabilities = {};
+
+ /// Replace the cache with the machines from a fetch that has just landed.
+ ///
+ /// Never throws and is never worth awaiting on a path a person is waiting on:
+ /// a cache that failed to save costs the NEXT launch a few hundred
+ /// milliseconds and costs this one nothing.
+ Future<void> save(
+ Iterable<Machine> machines, {
+ required bool Function(Machine) isOnline,
+ }) {
+ // Encoded now, on the caller's turn, so the document written is the machine
+ // list as it was when the save was ASKED for rather than whatever the list
+ // has become by the time the queue reaches it.
+ final payload = jsonEncode({
+ 'version': _version,
+ 'machines': [
+ for (final machine in machines.where(isOnline))
+ {
+ 'machineId': machine.machineId,
+ 'computerId': machine.computerId,
+ 'authMode': machine.authMode.name,
+ 'engine': machine.engine,
+ 'name': machine.name,
+ 'hostname': machine.hostname,
+ // Written as the status that got it in here. The reader treats
+ // every cached machine as a candidate to dial, and the fetch
+ // replaces this with the truth within the second.
+ 'status': machine.status,
+ // The daemon's own agent JSON, verbatim — see the class comment.
+ // Absent where this run never listed that machine's agents, which
+ // reads back as a machine with no cached agents.
+ 'agents': ?_agents[machine.machineId],
+ 'capabilities': ?_capabilities[machine.machineId],
+ },
+ ],
+ });
+ return _queue(() => _store.write(payload));
+ }
+
+ /// Forget everything — what signing out does, so the next account does not
+ /// start by dialling the previous one's machines.
+ Future<void> clear() {
+ _agents.clear();
+ _capabilities.clear();
+ return _queue(_store.clear);
+ }
+
+ /// Run [write] after every write already asked for, swallowing its failure.
+ Future<void> _queue(Future<void> Function() write) {
+ final queued = _writes.then((_) async {
+ try {
+ await write();
+ } on Object {
+ // Best effort, exactly like the snapshot store's own contract: a cache
+ // that failed to save costs the next launch a few hundred milliseconds.
+ }
+ });
+ _writes = queued;
+ return queued;
+ }
+}
diff --git a/mobile/lib/core/startup.dart b/mobile/lib/core/startup.dart
index 9962d3d94..bf15b4b37 100644
--- a/mobile/lib/core/startup.dart
+++ b/mobile/lib/core/startup.dart
@@ -1,3 +1,4 @@
+import '../logging/startup_trace.dart';
import '../phone/voice_language_store.dart';
import '../shared/theme/appearance_prefs_store.dart';
import '../stats/harness_stats.dart';
@@ -26,20 +27,41 @@ Future<void> loadPersistedSettings({
// Independent stores may load together, but all must finish before runApp.
// Font and appearance share a serialized file store; each reads its related
// preferences as one snapshot. Stats uses a separate file and can overlap.
+ //
+ // ⚠️ **"Together" is the intent, not the outcome, for four of these five.**
+ // Every store but `stats` is backed by [HarnessFileStore], which serializes
+ // ALL of its operations behind one process-wide queue and one exclusive file
+ // lock (`core/harness_file_store.dart`) — so this `Future.wait` starts four
+ // reads that then stand in a line, each taking the lock and re-parsing the
+ // whole of `state.json`. Timing them individually is what makes that visible
+ // in the log: four spans that start together and end one after another are a
+ // queue, not parallelism.
await Future.wait([
- (terminalFont ?? terminalFontStore).load(),
+ StartupTrace.time(
+ 'prefs.terminalFont',
+ (terminalFont ?? terminalFontStore).load,
+ ),
// Beside the font, and for the same reason: loading the scheme after the
// first frame paints every pane on the default ground and then snaps it to
// the saved one, which reads as a flash of the wrong colour at every launch.
- (terminalTheme ?? terminalThemeStore).load(),
+ StartupTrace.time(
+ 'prefs.terminalTheme',
+ (terminalTheme ?? terminalThemeStore).load,
+ ),
// Every control box uses these values. A late load would move the whole
// window's geometry after its first frame, as well as changing its palette.
- (appearance ?? appearancePrefsStore).load(),
+ StartupTrace.time(
+ 'prefs.appearance',
+ (appearance ?? appearancePrefsStore).load,
+ ),
// Counters begin moving with the first agent event. Loading them later
// could overwrite a new event with the old count from disk.
- (stats ?? harnessStats).load(),
+ StartupTrace.time('prefs.stats', (stats ?? harnessStats).load),
// The language the mic transcribes in. Read late, a first take could be sent to the backend
// in the phone's language by somebody who chose another.
- (voiceLanguage ?? voiceLanguageStore).load(),
+ StartupTrace.time(
+ 'prefs.voiceLanguage',
+ (voiceLanguage ?? voiceLanguageStore).load,
+ ),
]);
}
diff --git a/mobile/lib/logging/startup_trace.dart b/mobile/lib/logging/startup_trace.dart
new file mode 100644
index 000000000..7b54894e0
--- /dev/null
+++ b/mobile/lib/logging/startup_trace.dart
@@ -0,0 +1,87 @@
+import 'app_log.dart';
+
+/// Where the launch actually spends its time, as a timeline a shipped build can
+/// be asked about after the fact.
+///
+/// The phone's launch is a long chain of awaits — preferences off disk, the SSO
+/// session, `/api/machines`, a relay dial per machine, the E2EE handshake on top
+/// of it, and only then the agent list. Every one of those is a plausible
+/// suspect for a slow start, and until each is timed separately the only honest
+/// answer to "why is it slow" is a guess. The screen says
+/// "Connecting to your machine…" for all of them at once (see
+/// `phone/phone_status.dart`), so the UI cannot be read as a progress bar
+/// either.
+///
+/// Two shapes, because the launch has two:
+/// - [mark] for a moment on one timeline — how far into the launch it happened.
+/// - [time]/[timeSync] for a span, which is what a suspect actually needs: the
+/// span's own cost, not its position.
+///
+/// ⚠️ **Both write through [appLog], which is a SYNCHRONOUS, FLUSHED file write
+/// on the UI isolate** (see `logging/log_file.dart`). That is fine for the tens
+/// of events a launch produces and is emphatically not fine per frame or per
+/// terminal chunk: instrument phases here, never hot paths.
+///
+/// Timings are always on, in release too. A launch that is slow on a tester's
+/// phone and fast on a developer's is exactly the launch worth measuring, and
+/// `~/.harness/logs/app-YYYYMMDD.log` is where that evidence already lives —
+/// the same reasoning that keeps the file sink itself unconditional
+/// (`logging/debug_surface.dart`).
+abstract final class StartupTrace {
+ /// Started when the process reaches `startHarness`, so every [mark] shares one
+ /// origin. Not `DateTime`: a clock the user or the network can move backwards
+ /// mid-launch would report negative elapsed time.
+ static final Stopwatch _sinceLaunch = Stopwatch()..start();
+
+ /// How long since the app entered `startHarness`.
+ static Duration get sinceLaunch => _sinceLaunch.elapsed;
+
+ /// One moment on the launch timeline, stamped with its offset from launch.
+ ///
+ /// For things that have no duration of their own — the first frame, the point
+ /// bootstrap decided the user was signed in. A span belongs in [time].
+ static void mark(String event) =>
+ appLog.info('startup', '$event @${_ms(_sinceLaunch.elapsed)}');
+
+ /// Run [body], then log what it cost and where it fell in the launch.
+ ///
+ /// The offset is carried alongside the duration because a 300ms step means
+ /// something different at 200ms into the launch than at 4s: the first is the
+ /// launch, the second is a step waiting on something that came before it.
+ ///
+ /// A throwing [body] is timed and logged too, then rethrown — a step that
+ /// failed after 15 seconds is the single most useful line in the file, and it
+ /// is exactly the one a `finally`-less version would drop.
+ static Future<T> time<T>(String step, Future<T> Function() body) async {
+ final started = _sinceLaunch.elapsed;
+ try {
+ return await body();
+ } finally {
+ _record(step, started);
+ }
+ }
+
+ /// [time] for work that is not asynchronous.
+ static T timeSync<T>(String step, T Function() body) {
+ final started = _sinceLaunch.elapsed;
+ try {
+ return body();
+ } finally {
+ _record(step, started);
+ }
+ }
+
+ static void _record(String step, Duration started) {
+ final elapsed = _sinceLaunch.elapsed - started;
+ appLog.info(
+ 'startup',
+ '$step took ${_ms(elapsed)} (at ${_ms(started)})',
+ );
+ }
+
+ /// Milliseconds, the unit a launch is argued about in.
+ ///
+ /// Deliberately not `logDuration` from `log_file.dart`: that one floors to
+ /// whole seconds, which renders every interesting step of a launch as `0s`.
+ static String _ms(Duration d) => '${d.inMilliseconds}ms';
+}
diff --git a/mobile/lib/phone/agent_home.dart b/mobile/lib/phone/agent_home.dart
index 80c1cac73..6892c49ae 100644
--- a/mobile/lib/phone/agent_home.dart
+++ b/mobile/lib/phone/agent_home.dart
@@ -4,6 +4,7 @@ import 'package:flutter/foundation.dart' show ValueListenable;
import 'package:flutter/material.dart';
import 'package:lucide_icons_flutter/lucide_icons.dart';
+import 'package:harness_mobile/logging/startup_trace.dart';
import 'package:harness_mobile/shared/theme/app_theme.dart';
import 'package:harness_mobile/shared/widgets/empty_state.dart';
import 'package:harness_mobile/state/app_state.dart';
@@ -202,7 +203,10 @@ class _AgentHomeState extends State<AgentHome> {
}
Future<void> _readLast() async {
- final last = await widget.notifier.lastOpenedAgent.read();
+ final last = await StartupTrace.time(
+ 'home.readLastAgent',
+ widget.notifier.lastOpenedAgent.read,
+ );
if (!mounted) return;
// The deadline has done its job either way once this lands, and a timer left running would fire
// into a screen that is no longer waiting.
@@ -352,6 +356,41 @@ class _AgentHomeState extends State<AgentHome> {
/// The message names the step actually in progress rather than saying "Loading…" throughout. On a
/// cold launch these run several seconds each, and a line that changes is how somebody can tell a
/// slow connection from a stuck one.
+
+ /// The last line [_traceLoading] wrote, so a wait is logged as a step rather
+ /// than as one line per frame.
+ String? _tracedLoading;
+ bool _tracedReady = false;
+
+ /// Record each step of the wait as the screen enters it.
+ ///
+ /// This is the wait as the PERSON experiences it, which is the only timeline
+ /// that settles whether a launch is slow: everything else in the log measures
+ /// one operation, while this measures how long the phone showed a given
+ /// sentence. "Connecting to your machine…" covers a dial, an E2EE handshake
+ /// and an agent list (see `phone_status.dart`), so the gap between this line
+ /// and the next is the only place that stretch appears as a number at all.
+ ///
+ /// ⚠️ Called from `build`, so it must write only on a CHANGE. [appLog] is a
+ /// synchronous flushed file write (`logging/log_file.dart`); at 60fps an
+ /// unguarded call here would fsync a line per frame and slow down the very
+ /// wait it claims to be measuring.
+ void _traceLoading(String? message) {
+ if (message == null) {
+ // The first screen with real content on it ends the launch — and only the
+ // first: a later empty state is not a launch, and re-arming this would
+ // report the wait as starting over.
+ if (_tracedReady) return;
+ _tracedReady = true;
+ _tracedLoading = null;
+ StartupTrace.mark('home.ready');
+ return;
+ }
+ if (message == _tracedLoading) return;
+ _tracedLoading = message;
+ StartupTrace.mark('home.waiting: $message');
+ }
+
String? _loadingMessage() {
// Waited long enough — see [_loadingTimeout]. ⚠️ Checked before [_readingLast] and not after:
// the local read is the one step that cannot be retried from the empty state, so if even that
@@ -366,6 +405,23 @@ class _AgentHomeState extends State<AgentHome> {
return notifier.machinesLoading ? 'Looking for your machines…' : null;
}
final machines = filterableMachines(notifier);
+ // ⚠️ **The first machine to answer ends the wait; the others catch up behind
+ // a screen that is already usable.** Both tests below ask whether ANY
+ // machine is still coming, which made a launch as slow as the SLOWEST
+ // machine on the account: one box still dialling held a full-screen spinner
+ // over agents that another machine had already listed and was ready to open.
+ //
+ // Once a machine has delivered its agents there is nothing left to wait for.
+ // The caller opens one, and a machine that answers a second later simply
+ // adds its agents to a list that is already on screen — which is what
+ // `phoneMachineListsAgents` and the pager have always done for a machine
+ // that reconnects.
+ //
+ // The remembered agent keeps its head start regardless: this runs only when
+ // [_target] found nothing to show, and [_target]'s own `_waitingForRestore`
+ // (checked by the caller) still holds the screen while the machine holding
+ // that agent is genuinely on its way.
+ if (machines.any(phoneMachineListsAgents)) return null;
// Then each machine's own socket. `connecting` covers both the dial and the handshake after it.
if (machines.any(
(machine) =>
@@ -430,6 +486,7 @@ class _AgentHomeState extends State<AgentHome> {
// Every other machine may be up and loaded while the one holding the remembered agent
// is still dialling — without this the wait would draw as "No agents yet".
(_waitingForRestore ? 'Connecting to your machine…' : null);
+ _traceLoading(loading);
if (loading != null) return _AgentHomeLoading(message: loading);
// ⚠️ **No machine is open → this is a MACHINE problem, so the machine screen is what the
// person gets.** An "Agents" header over "No machines are open yet" named the thing that is
diff --git a/mobile/lib/phone/phone_status.dart b/mobile/lib/phone/phone_status.dart
index a41f2b669..b56620842 100644
--- a/mobile/lib/phone/phone_status.dart
+++ b/mobile/lib/phone/phone_status.dart
@@ -47,11 +47,24 @@ PhoneMachineStatus phoneMachineStatusOf(MachineState machine) {
/// agents out of the list for the length of the redial — the pager, whose pages ARE that list, was
/// thrown away and the screen fell back to "Connecting to your machine…" on every return to the app.
/// A first connect has no list yet, so it still waits like one.
+/// ⚠️ **Agents restored from the last run count too, and that is the whole
+/// point of restoring them.** A warm-started machine is `connecting` (its socket
+/// is genuinely still coming up) and `loading` (it genuinely still owes a list),
+/// so the `loaded` test below hid exactly the agents the cache exists to show —
+/// the phone read nine of them off disk at 520ms and still sat on "Connecting to
+/// your machine…" until the handshake finished two seconds later.
+///
+/// Showing them is safe for the same reason showing a RECONNECTING machine's
+/// agents is safe, which is what the paragraph above describes: the names are
+/// last known good, the real list replaces them the moment it lands, and
+/// `_replaceAgents` retires anything that has gone. The difference is only how
+/// long ago "last known" was.
bool phoneMachineListsAgents(MachineState machine) =>
switch (phoneMachineStatusOf(machine)) {
PhoneMachineStatus.ready => true,
PhoneMachineStatus.connecting =>
- machine.agentLoadStatus == AgentLoadStatus.loaded,
+ machine.agentLoadStatus == AgentLoadStatus.loaded ||
+ machine.agentsFromCache,
PhoneMachineStatus.needsPassword || PhoneMachineStatus.offline => false,
};
diff --git a/mobile/lib/phone/terminal_page.dart b/mobile/lib/phone/terminal_page.dart
index 2e434697e..1e51f4abb 100644
--- a/mobile/lib/phone/terminal_page.dart
+++ b/mobile/lib/phone/terminal_page.dart
@@ -10,8 +10,13 @@ import 'package:lucide_icons_flutter/lucide_icons.dart';
import 'package:harness_mobile/core/models.dart' show Agent;
import 'package:harness_mobile/shared/theme/app_theme.dart';
import 'package:harness_mobile/shared/widgets/app_icon_button.dart';
+import 'package:harness_mobile/shared/widgets/pulse.dart';
+import 'package:harness_mobile/shared/widgets/skeleton.dart';
import 'package:harness_mobile/state/app_state.dart';
import 'package:harness_mobile/terminal/image_transcode.dart';
+import 'package:harness_mobile/terminal/terminal_font_store.dart';
+import 'package:harness_mobile/terminal/terminal_theme.dart';
+import 'package:harness_mobile/terminal/terminal_theme_store.dart';
import 'package:harness_mobile/terminal/terminal_session.dart';
import 'package:harness_mobile/widgets/rename_agent_dialog.dart';
import 'package:harness_mobile/widgets/terminal_panel.dart';
@@ -148,6 +153,13 @@ class _TerminalPageState extends State<TerminalPage>
/// TerminalPage still sitting in the Agents tab's stack.
bool _hadPane = false;
+ /// The agent's name as the last list to carry it knew it.
+ ///
+ /// Held because the sentence [_AgentGone] shows is about an agent that is, by
+ /// then, in no list at all — the name has to be captured while it is still
+ /// there or the screen can only say "that agent".
+ String? _cachedAgentName;
+
/// Whether a tap on the terminal has asked for the keyboard, and it has not
/// risen yet.
///
@@ -648,6 +660,30 @@ class _TerminalPageState extends State<TerminalPage>
final agent = machine?.agents
.where((a) => a.id == widget.agentId)
.firstOrNull;
+ // ⚠️ **The agent this page opened on is not in the machine's own list.**
+ // Only ever true of a page opened from the cache (see [_AgentGone]): the
+ // list is the machine's — `agentsFromCache` is false, so a real
+ // `agents_list` has landed — it has been LOADED rather than merely
+ // attempted, and the agent it named is not in it.
+ //
+ // Every one of those conditions matters. Without `loaded` this would
+ // fire during the window the cache exists to cover; without
+ // `!agentsFromCache` it would fire against the cached list itself, which
+ // is where the agent came from; and a machine that errored or went
+ // offline has not disowned anything — it simply has not answered, and
+ // its pane keeps the terminal's own reconnect behaviour.
+ //
+ // Note this deliberately ignores `_hadPane`/`_leave` above: that path
+ // handles a pane REMOVED while the page was live. This one is about a
+ // page that should never have been built, answered before its pane
+ // could be.
+ final agentGone =
+ agent == null &&
+ machine != null &&
+ !machine.agentsFromCache &&
+ machine.agentLoadStatus == AgentLoadStatus.loaded;
+ // Captured while the agent is still listed, for the sentence above.
+ if (agent != null) _cachedAgentName = agent.name;
final reclaim = phoneReclaimAction(session);
// The header's trailing controls, counted before they are built: the
// slot they share with Cancel is sized from this, and the search field
@@ -711,7 +747,12 @@ class _TerminalPageState extends State<TerminalPage>
// the panel no knowledge of the page's chrome.
child: NotificationListener<ScrollNotification>(
onNotification: _chrome.onNotification,
- child: pane == null || session == null
+ child: agentGone
+ ? _AgentGone(
+ name: _cachedAgentName,
+ onPickAnother: _pickAnotherAgent,
+ )
+ : pane == null || session == null
? const _Attaching()
: TerminalPanel(
key: ValueKey(pane.id),
@@ -768,6 +809,30 @@ class _TerminalPageState extends State<TerminalPage>
),
),
),
+ // ⚠️ **The skeleton is laid OVER the live panel, not
+ // swapped in for it, and that is not a stylistic
+ // choice.** [TerminalPanel.initState] calls
+ // `session.attachViewport`, which is how the machine
+ // learns how many rows and columns to draw; a page
+ // that showed a skeleton INSTEAD would leave the
+ // session with no viewport, and the first keyframe
+ // would arrive sized for nothing.
+ //
+ // So the panel mounts, measures and resizes as always,
+ // and this covers the empty emulator buffer it paints
+ // meanwhile. `session == null` upstream keeps its own
+ // branch for the frames before a session exists at all.
+ //
+ // ⚠️ **This is also the bug that made the skeleton
+ // invisible.** The only gate used to be `session ==
+ // null`, and `selectAgent` creates the pane and the
+ // session in one frame — so the branch above was
+ // essentially never taken, and what a person actually
+ // waited in front of was a mounted terminal with an
+ // empty buffer: a black rectangle, for as long as the
+ // keyframe took.
+ if (session != null && !session.hasRenderedFrame)
+ const Positioned.fill(child: _Attaching()),
// The mic — the one voice control the page has,
// floating over the terminal's bottom right corner
// rather than sitting in a row of its own.
@@ -1076,6 +1141,18 @@ class _TerminalPageState extends State<TerminalPage>
/// the same agent list: the agent leaves it, the home screen's target stops matching, and it
/// rebuilds onto another agent or onto its empty state. Leaving the route was never what fixed
/// this case; it only uncovered the list that did.
+ /// Leave the agent that is no longer there, and let the home screen choose.
+ ///
+ /// It pops rather than picking a replacement itself: `AgentHome` already
+ /// decides what to open — the remembered agent, then the first openable one —
+ /// and it re-runs that the moment this page is out of the way. Choosing here
+ /// would be a second, competing copy of that rule.
+ ///
+ /// The stale record is not cleared: it names an agent no list contains, so it
+ /// matches nothing and the home screen falls through to the first agent it can
+ /// reach. Whatever it opens overwrites the record itself.
+ void _pickAnotherAgent() => _leave();
+
void _leave() {
WidgetsBinding.instance.addPostFrameCallback((_) {
if (!mounted) return;
@@ -1224,31 +1301,546 @@ class _ReclaimButton extends StatelessWidget {
}
}
-class _Attaching extends StatelessWidget {
- const _Attaching();
+/// What the terminal shows when the agent it opened on is not there any more.
+///
+/// ⚠️ **This is the cost of opening from the cache, and the whole of it.** The
+/// phone draws its terminal from last run's agent list so the screen is usable
+/// in half a second (`MachineCache`), and the machine's real list lands a moment
+/// later. Almost always they agree. When they do not — the agent was deleted
+/// from another device since this phone last looked — the terminal is already on
+/// screen with a name on it, and this is what replaces its body.
+///
+/// Worded as a fact about the agent, not as a failure of the app: nothing went
+/// wrong here, something simply changed elsewhere. The button is the way out,
+/// because a dead end on the phone's home screen leaves nothing to tap at all.
+class _AgentGone extends StatelessWidget {
+ const _AgentGone({required this.name, required this.onPickAnother});
+
+ /// The agent as the cache knew it, so the sentence names what is missing
+ /// rather than gesturing at "the agent".
+ final String? name;
+
+ final VoidCallback onPickAnother;
@override
Widget build(BuildContext context) => Center(
- child: Column(
+ child: Padding(
+ padding: const EdgeInsets.symmetric(horizontal: 32),
+ child: Column(
+ mainAxisSize: MainAxisSize.min,
+ children: [
+ // The 300 weight every other glyph on this page uses.
+ Icon(LucideIcons.wind300, size: 26, color: AppPalette.textSecondary),
+ const SizedBox(height: 14),
+ Text(
+ name == null || name!.isEmpty
+ ? 'That agent is gone'
+ : '$name is gone',
+ textAlign: TextAlign.center,
+ style: TextStyle(
+ color: AppPalette.textPrimary,
+ fontSize: 15,
+ fontWeight: FontWeight.w600,
+ ),
+ ),
+ const SizedBox(height: 8),
+ Text(
+ 'It was closed on another device since you were last here.',
+ textAlign: TextAlign.center,
+ style: TextStyle(
+ color: AppPalette.textSecondary,
+ fontSize: 13,
+ height: 1.4,
+ ),
+ ),
+ const SizedBox(height: 18),
+ TextButton(
+ onPressed: onPickAnother,
+ style: TextButton.styleFrom(
+ foregroundColor: AppPalette.accent,
+ padding: const EdgeInsets.symmetric(horizontal: 18, vertical: 10),
+ ),
+ child: const Text('Open another agent'),
+ ),
+ ],
+ ),
+ ),
+ );
+}
+
+/// The terminal's body while its first keyframe is still crossing the network.
+///
+/// ⚠️ **A skeleton here, not a spinner, because the shape IS known** — that is
+/// the rule `shared/widgets/skeleton.dart` opens with. What arrives is a page of
+/// monospace lines, and drawing lines of the terminal's own type at the
+/// terminal's own leading means the keyframe lands INTO the layout already on
+/// screen rather than replacing a centred spinner with a wall of text. The
+/// screen stops flashing between two unrelated pictures.
+///
+/// The content itself cannot be cached: a terminal is a live screen a remote
+/// program is drawing, and the only authoritative copy is the keyframe the
+/// machine sends on attach (`terminal_keyframe`). Everything AROUND it is
+/// already on screen by now from the agent cache — the name, the project, the
+/// header — so this is the one part of the launch that still has to wait, and
+/// the skeleton is what makes that wait look like the thing being waited for.
+///
+/// Metrics come from `terminalFontStore`, which is loaded before the first frame
+/// (`core/startup.dart`), so these rows are the height the real ones will be.
+///
+/// ⚠️ **It draws the transcript's STRUCTURE, not a stack of grey bars.** The
+/// first version was a column of plain lines and read as a loading page for some
+/// other app — nothing about it suggested a terminal. What actually arrives has
+/// a strong, repeating shape: a prompt banner on its own lighter ground, a
+/// bulleted answer indented under it, a dim meta line closing the turn. Standing
+/// in for THAT is what makes the wait read as "your session is coming back"
+/// rather than "something is loading", and it is the same rule
+/// `PhoneListSkeleton` follows for a list of cards — the same cards, empty, at a
+/// real row's height.
+class _Attaching extends StatefulWidget {
+ const _Attaching();
+
+ @override
+ State<_Attaching> createState() => _AttachingState();
+}
+
+class _AttachingState extends State<_Attaching>
+ with SingleTickerProviderStateMixin {
+ /// How long the block takes to arrive, top edge to bottom.
+ ///
+ /// ⚠️ **Matched to the wait it covers, not chosen for its own sake.** Measured
+ /// on this app against a real machine, the gap between the agent list landing
+ /// and the terminal's first keyframe — which is exactly the stretch this
+ /// skeleton is on screen — runs about 2.5 to 3 seconds. At the 620ms this
+ /// started on, the sweep finished in the first fifth of that and then sat
+ /// perfectly still, which reads as a page that has given up rather than one
+ /// that is filling.
+ ///
+ /// So the sweep is paced to arrive at the bottom edge at roughly the moment
+ /// the real screen does. Finishing EARLY is the one direction that is fine and
+ /// is what a fast attach produces: the skeleton is simply replaced, complete,
+ /// by the terminal. Finishing late is the case the curve below handles.
+ static const _revealDuration = Duration(milliseconds: 2600);
+
+ /// How much of the pane the timed sweep covers before it hands over.
+ ///
+ /// ⚠️ **The sweep deliberately does not finish on its own.** A reveal that
+ /// completes and then holds still is the failure mode this pacing was changed
+ /// to fix; running to 100% just moves that stall from five seconds in to two
+ /// and a half. Stopping a little short instead means the last band of the
+ /// screen is still arriving whenever the keyframe lands, so the skeleton is
+ /// always replaced mid-motion — which reads as the real screen overtaking it
+ /// rather than as a placeholder that gave up waiting.
+ ///
+ /// The remainder is never shown filling: the terminal takes the pane. On an
+ /// attach slower than [_revealDuration] the bottom band simply stays dim, and
+ /// the pulse underneath keeps the block alive.
+ ///
+ /// 0.84 leaves roughly the last 9% of the pane below the soft edge — about one
+ /// turn on a phone. Worked out against [_feather] rather than guessed: the
+ /// edge travels `t * (1 + 2f) - f`, so it reaches the bottom at `t = 1`, and
+ /// values much above this finish the sweep after all.
+ static const _sweepExtent = 0.84;
+
+ late final AnimationController _reveal = AnimationController(
+ vsync: this,
+ duration: _revealDuration,
+ upperBound: _sweepExtent,
+ )..forward();
+
+ @override
+ void dispose() {
+ _reveal.dispose();
+ super.dispose();
+ }
+
+ /// The shapes turns are cut from, cycled to fill whatever height the pane has.
+ ///
+ /// ⚠️ **A fixed list of turns cannot fill a screen.** Four of them left the
+ /// top half of a tall phone empty, which reads as a page that finished loading
+ /// with almost nothing on it — the opposite of what a skeleton is for. The
+ /// build measures the pane and takes as many of these as it needs, so the
+ /// block reaches the top edge on any device at any terminal font size.
+ ///
+ /// Five, and a prime count, so cycling does not line the same shape up under
+ /// itself every other turn: with four the eye picks out the repeat immediately.
+ static const _shapes = <_SkeletonTurn>[
+ _SkeletonTurn(prompt: 0.44, answer: [0.89, 0.57], meta: 0.42),
+ _SkeletonTurn(prompt: 0.52, answer: [0.94, 0.88, 0.41], meta: 0.46),
+ _SkeletonTurn(prompt: 0.38, answer: [0.91, 0.62], meta: 0.44),
+ _SkeletonTurn(prompt: 0.57, answer: [0.83, 0.96, 0.49], meta: 0.39),
+ _SkeletonTurn(prompt: 0.61, answer: [0.86, 0.93, 0.77, 0.35], meta: null),
+ ];
+
+ @override
+ Widget build(BuildContext context) {
+ AppTheme.watch(context);
+ final style = terminalFontStore.value;
+ final fontSize = style.fontSize;
+ // The terminal's own line box, so a row here and a row of output occupy the
+ // same band. `height` is xterm's line-height multiplier.
+ final lineHeight = fontSize * style.height;
+ // Resolved exactly as [TerminalPanel] resolves it for the view underneath,
+ // so the skeleton's ground and the terminal's are the same colour.
+ final ground = terminalThemeFor(
+ AppTheme.palette.value,
+ terminalThemeStore.value,
+ ).background;
+ // ⚠️ **Mixed against the terminal's OWN ground, not taken from
+ // `AppSurface.recess`.** That token is a translucent well meant to sit on a
+ // card — around 6% white — and over this app's near-black terminal
+ // (`#181818`) it renders at about `#262626`: a difference of sixteen values,
+ // which is invisible on a phone screen in daylight and is why the first
+ // version of this skeleton could not be seen at all.
+ //
+ // These are opaque blends instead, so the contrast is a property of the bars
+ // rather than of whatever happens to be behind them, and the terminal's
+ // background is read from the user's chosen scheme so a light terminal theme
+ // gets bars that are darker than its ground rather than lighter.
+ final light = ThemeData.estimateBrightnessForColor(ground) ==
+ Brightness.light;
+ final rest = Color.alphaBlend(
+ (light ? Colors.black : Colors.white).withValues(alpha: 0.10),
+ ground,
+ );
+ final peak = Color.alphaBlend(
+ (light ? Colors.black : Colors.white).withValues(alpha: 0.17),
+ ground,
+ );
+ return SkeletonBlock(
+ semanticsLabel: 'Attaching to the agent',
+ child: _RevealDown(
+ listenable: _reveal,
+ child: ColoredBox(
+ // Opaque, because this covers a live [TerminalPanel] — see the note at
+ // the call site. Without it the empty emulator buffer shows between the
+ // bars and the two grounds differ by a hair, which reads as a smudge.
+ color: ground,
+ child: Padding(
+ // ⚠️ The terminal view's OWN padding (`TerminalPanel` passes
+ // `EdgeInsets.all(10)` to the xterm view), so a bar starts on the
+ // column the first character will occupy. A different gutter here
+ // would shift every line sideways the moment the keyframe lands.
+ padding: const EdgeInsets.all(10),
+ child: Pulse(
+ // The breath `shared/widgets/skeleton.dart` sets for a placeholder;
+ // one controller for the whole block rather than one per bar, so
+ // the rows pulse together instead of shimmering independently.
+ duration: const Duration(milliseconds: 1100),
+ builder: (context, t, _) {
+ final fill = Color.lerp(rest, peak, t)!;
+ // The prompt's banner sits on its own ground, a step above the
+ // terminal's — the band an agent paints behind the line it is
+ // answering, and the one element that makes this block read as a
+ // transcript rather than as a list of lines.
+ //
+ // 0.08, not the 0.05 this started at: the banner has to be legible
+ // as a BAND at arm's length on a phone, and at 0.05 over `#181818`
+ // it was a shade nobody would notice. Still well under the bars
+ // themselves (0.10–0.17), so it reads as the ground behind them
+ // rather than as another bar.
+ final banner = Color.lerp(
+ ground,
+ light ? Colors.black : Colors.white,
+ 0.08,
+ )!;
+ final bar = (fontSize * 0.62).clamp(5.0, 12.0).toDouble();
+ return LayoutBuilder(
+ builder: (context, constraints) {
+ // ⚠️ **As many turns as the pane is tall, not a fixed four.**
+ // A fixed list left the top half of a tall phone empty, which
+ // reads as a page that has finished loading and has almost
+ // nothing on it. One extra turn is added beyond the measured
+ // fit so the topmost one is genuinely cut by the edge rather
+ // than ending a few pixels short of it.
+ final height = constraints.maxHeight;
+ final perTurn = _turnHeight(
+ _shapes[0],
+ lineHeight: lineHeight,
+ );
+ final count = height.isFinite && perTurn > 0
+ ? (height / perTurn).ceil() + 1
+ : _shapes.length;
+ final turns = [
+ for (var i = 0; i < count; i++)
+ // Cycled from the back, so the LAST shape is always the
+ // one at the bottom edge: it is the only one written
+ // without a closing meta line, which is what an in-progress
+ // turn looks like.
+ _shapes[(_shapes.length - 1 - i % _shapes.length)],
+ ].reversed.toList();
+ final blocks = <Widget>[
+ for (var i = 0; i < turns.length; i++)
+ Opacity(
+ // Oldest at 0.4, newest at full: the block nearest the
+ // top edge is the one about to be clipped by it, so it
+ // fades INTO that edge rather than ending against it.
+ opacity: turns.length == 1
+ ? 1
+ : 0.4 + (i / (turns.length - 1)) * 0.6,
+ child: _turn(
+ turns[i],
+ lineHeight: lineHeight,
+ bar: bar,
+ fill: fill,
+ banner: banner,
+ // The newest turn ends at the bottom edge, as the live
+ // screen's does; only the ones above it are separated.
+ last: i == turns.length - 1,
+ ),
+ ),
+ ];
+ // ⚠️ Aligned to the BOTTOM and clipped at the top, which is how
+ // a terminal itself sits: the newest output is at the bottom
+ // edge and history runs off the top. `OverflowBox` lets the
+ // column exceed the pane — the extra turn above guarantees it
+ // does — and `ClipRect` cuts what runs past, instead of Flutter
+ // painting an overflow stripe over the whole thing.
+ return ClipRect(
+ child: OverflowBox(
+ alignment: Alignment.bottomLeft,
+ minHeight: 0,
+ maxHeight: double.infinity,
+ // ⚠️ The pane's own width is pinned back on, because
+ // `OverflowBox` relaxes BOTH axes and the rows inside are
+ // `FractionallySizedBox` — against an unbounded width they
+ // would have no fraction to take and the layout would throw.
+ minWidth: constraints.maxWidth,
+ maxWidth: constraints.maxWidth,
+ child: Column(
+ crossAxisAlignment: CrossAxisAlignment.stretch,
+ mainAxisSize: MainAxisSize.min,
+ children: blocks,
+ ),
+ ),
+ );
+ },
+ );
+ },
+ ),
+ ),
+ ),
+ ),
+ );
+ }
+
+ /// One turn: the prompt banner, the bulleted answer under it, the meta line.
+ ///
+ /// Every row is exactly one terminal line box tall, so the whole block
+ /// occupies a whole number of rows and the keyframe replaces it without the
+ /// page growing or shrinking by a fraction of a line.
+ /// What one turn occupies, so the build can work out how many fit.
+ ///
+ /// ⚠️ **Must stay in step with [_turn] below**, which is why the terms are
+ /// written in the same order as the widgets they measure: banner, gap, answer
+ /// lines, gap and meta line, trailing gap. A drift here does not break the
+ /// layout — the column is clipped either way — it just means a turn too few
+ /// (a band of empty ground at the top) or one too many (wasted build).
+ static double _turnHeight(
+ _SkeletonTurn turn, {
+ required double lineHeight,
+ }) =>
+ lineHeight + // the prompt banner
+ lineHeight * 0.35 + // the gap under it
+ lineHeight * turn.answer.length +
+ (turn.meta == null ? 0 : lineHeight * 0.35 + lineHeight) +
+ lineHeight * 0.9; // the gap to the next turn
+
+ static Widget _turn(
+ _SkeletonTurn turn, {
+ required double lineHeight,
+ required double bar,
+ required Color fill,
+ required Color banner,
+ bool last = false,
+ }) {
+ Widget line(double factor, {double indent = 0, double? height}) => SizedBox(
+ height: lineHeight,
+ child: Align(
+ alignment: Alignment.centerLeft,
+ child: Padding(
+ padding: EdgeInsets.only(left: indent),
+ child: FractionallySizedBox(
+ alignment: Alignment.centerLeft,
+ widthFactor: factor,
+ child: Container(
+ height: height ?? bar,
+ decoration: BoxDecoration(
+ color: fill,
+ borderRadius: BorderRadius.circular(3),
+ ),
+ ),
+ ),
+ ),
+ ),
+ );
+
+ return Column(
+ crossAxisAlignment: CrossAxisAlignment.stretch,
mainAxisSize: MainAxisSize.min,
children: [
- SizedBox.square(
- dimension: 22,
- child: CircularProgressIndicator(
- strokeWidth: 2,
- color: AppPalette.accent,
+ // The prompt, on its own full-width ground — the one element that makes
+ // this read as a transcript rather than as a list of lines.
+ Container(
+ height: lineHeight,
+ color: banner,
+ child: Row(
+ children: [
+ // The `›` gutter the real prompt keeps.
+ SizedBox(width: bar * 0.9),
+ Expanded(
+ child: FractionallySizedBox(
+ alignment: Alignment.centerLeft,
+ widthFactor: turn.prompt,
+ child: Container(
+ height: bar,
+ decoration: BoxDecoration(
+ color: fill,
+ borderRadius: BorderRadius.circular(3),
+ ),
+ ),
+ ),
+ ),
+ ],
),
),
- const SizedBox(height: 14),
- Text(
- 'Attaching to the agent…',
- style: TextStyle(color: AppPalette.textSecondary, fontSize: 14),
- ),
+ SizedBox(height: lineHeight * 0.35),
+ // The answer: a bullet on the first row, the rest indented under it.
+ for (var i = 0; i < turn.answer.length; i++)
+ if (i == 0)
+ SizedBox(
+ height: lineHeight,
+ child: Row(
+ crossAxisAlignment: CrossAxisAlignment.center,
+ children: [
+ Container(
+ width: bar * 0.55,
+ height: bar * 0.55,
+ decoration: BoxDecoration(
+ color: fill,
+ shape: BoxShape.circle,
+ ),
+ ),
+ SizedBox(width: bar * 0.7),
+ Expanded(
+ child: FractionallySizedBox(
+ alignment: Alignment.centerLeft,
+ widthFactor: turn.answer[i],
+ child: Container(
+ height: bar,
+ decoration: BoxDecoration(
+ color: fill,
+ borderRadius: BorderRadius.circular(3),
+ ),
+ ),
+ ),
+ ),
+ ],
+ ),
+ )
+ else
+ line(turn.answer[i], indent: bar * 1.25),
+ if (turn.meta != null) ...[
+ SizedBox(height: lineHeight * 0.35),
+ // The `✳ Crunched for 3s · done 10:36` line that closes a turn: always
+ // shorter, and thinner than a line of body text.
+ line(turn.meta!, height: bar * 0.7),
+ ],
+ if (!last) SizedBox(height: lineHeight * 0.9),
],
- ),
+ );
+ }
+}
+
+/// The shape of one transcript turn, for [_Attaching].
+/// Wipes [child] in from the top edge to the bottom over [listenable]'s 0→1.
+///
+/// ⚠️ **A wipe, not a fade or a slide.** The skeleton stands in for a terminal
+/// whose rows must not move — every bar is already at the pixel its text will
+/// occupy (see [_Attaching]) — so the reveal cannot translate anything. A plain
+/// fade would have the whole block appear at once, which says nothing about the
+/// direction output arrives from. Masking by height instead lets the rows arrive
+/// the way a screen paints: from the top, downward, each one landing where it
+/// will stay.
+///
+/// The leading edge is a short gradient rather than a hard line, so what crosses
+/// a row is a brightening rather than a switch — at 60fps a hard edge stepping
+/// down the screen reads as a tear.
+class _RevealDown extends StatelessWidget {
+ const _RevealDown({required this.listenable, required this.child});
+
+ final Animation<double> listenable;
+ final Widget child;
+
+ /// The soft edge's depth, as a fraction of the pane.
+ ///
+ /// 0.10, down from the 0.18 a fast sweep used: feather is a fraction of the
+ /// PANE, so at a slow rate a wide one keeps a fifth of the screen in permanent
+ /// half-light as it crawls past. Narrow enough to stay crisp, wide enough that
+ /// what crosses a row is still a brightening rather than a switch.
+ static const _feather = 0.10;
+
+ @override
+ Widget build(BuildContext context) => AnimatedBuilder(
+ animation: listenable,
+ // The subtree does not depend on `t`, so it is built once and reused across
+ // every frame of the sweep — the mask is the only thing that changes.
+ child: child,
+ builder: (context, built) {
+ // ⚠️ **Linear, and that is the point for a sweep this long.** Every eased
+ // curve front-loads the travel: `easeOutQuad` has the edge 84% of the way
+ // down at the halfway mark, so over a 2.6-second reveal the last row would
+ // take more than a second to gain its final sliver — a sweep that visibly
+ // stalls just before it arrives, which is the thing this pacing exists to
+ // avoid. A constant rate reads as steady progress, which is what it is
+ // standing in for.
+ final t = listenable.value;
+ // Kept even though the controller stops short of 1 (see `_sweepExtent`),
+ // because this widget must also be correct for a caller that runs it to
+ // completion — and a mask that covers nothing is pure cost per frame.
+ if (t >= 1) return built!;
+ // Travels from just above the top edge towards just past the bottom, so
+ // the first row is fully revealed rather than starting at half brightness.
+ // It does not arrive: the controller is bounded below the value that would
+ // take it there.
+ final edge = t * (1 + _feather * 2) - _feather;
+ return ShaderMask(
+ blendMode: BlendMode.dstIn,
+ shaderCallback: (bounds) => LinearGradient(
+ begin: Alignment.topCenter,
+ end: Alignment.bottomCenter,
+ colors: const [Colors.white, Colors.white, Colors.transparent],
+ // Clamped because a stop list must be non-decreasing and within 0..1;
+ // at the extremes of the travel above, both terms run outside it.
+ stops: [
+ 0,
+ (edge - _feather).clamp(0.0, 1.0),
+ edge.clamp(0.0, 1.0),
+ ],
+ ).createShader(bounds),
+ child: built,
+ );
+ },
);
}
+class _SkeletonTurn {
+ const _SkeletonTurn({
+ required this.prompt,
+ required this.answer,
+ required this.meta,
+ });
+
+ /// Width of the prompt text inside its banner, as a fraction of the pane.
+ final double prompt;
+
+ /// The answer's lines, longest first — a paragraph wraps full-width and its
+ /// last line runs short.
+ final List<double> answer;
+
+ /// The closing meta line, or null for the newest turn, which has not finished.
+ final double? meta;
+}
+
/// The header sliding up off the top of the page, fading as it goes.
///
/// ⚠️ **A translation, and it must stay one.** It used to shrink with
diff --git a/mobile/lib/settings/config_store.dart b/mobile/lib/settings/config_store.dart
index 722b7f680..651858916 100644
--- a/mobile/lib/settings/config_store.dart
+++ b/mobile/lib/settings/config_store.dart
@@ -28,10 +28,22 @@ class ConfigStore {
String? get skippedDesktopUpdateVersion => _cachedSkippedDesktopUpdateVersion;
Future<AppConfig> load() async {
- // Keep the tiny startup path sequential and predictable.
- final baseUrl = await _storage.read(_baseUrlKey);
- final environment = await _storage.read(_environmentKey);
- final skippedUpdate = await _storage.read(_skippedDesktopUpdateVersionKey);
+ // ⚠️ **One `readMany`, not three `read`s, and the difference is not cosmetic.**
+ // Every operation on [HarnessFileStore] takes an exclusive file lock and
+ // re-parses the whole of `state.json`, and they are queued process-wide — so
+ // three reads of three keys from one file cost three locks and three parses,
+ // strictly one after another, on the launch path. `readMany` answers all
+ // three from a single locked read. These keys are also a consistent set: a
+ // base URL from before a write and an environment from after it would
+ // describe a backend that was never configured.
+ final saved = await _storage.readMany([
+ _baseUrlKey,
+ _environmentKey,
+ _skippedDesktopUpdateVersionKey,
+ ]);
+ final baseUrl = saved[_baseUrlKey];
+ final environment = saved[_environmentKey];
+ final skippedUpdate = saved[_skippedDesktopUpdateVersionKey];
_cachedBaseUrl = baseUrl ?? defaultBaseUrl;
_cachedEnvironment = environment == 'stag' ? 'stag' : 'prod';
_cachedSkippedDesktopUpdateVersion = skippedUpdate?.trim().isEmpty ?? true
diff --git a/mobile/lib/shortcuts/app_keymap.dart b/mobile/lib/shortcuts/app_keymap.dart
index da6a58d98..3d94c4214 100644
--- a/mobile/lib/shortcuts/app_keymap.dart
+++ b/mobile/lib/shortcuts/app_keymap.dart
@@ -2,6 +2,7 @@ import 'dart:io';
import 'package:flutter/widgets.dart';
+import '../core/host_platform.dart';
import 'app_shortcuts.dart';
import 'keymap.dart';
import 'keymap_commands.dart';
@@ -31,6 +32,16 @@ class AppKeymap extends ChangeNotifier {
defaults: harnessDefaultBindings,
commands: harnessCommandById.keys.toSet(),
validate: (map) => validateNativeKeys(map, macOS: Platform.isMacOS),
+ // ⚠️ **Not watched on a phone, and the file is not editable there either.**
+ // Watching costs a symlink walk up the whole path and a `Directory.watch`
+ // per parent — and iOS does not implement `Directory.watch` at all, so
+ // every one of those throws, each failure schedules another reload, and the
+ // walk runs again. That whole sequence is on the critical path before the
+ // first frame (see `startHarness`), to notice edits to a dotfile that a
+ // touchscreen has no way to produce: there is no shell, no editor, and no
+ // sync into the app's sandbox. The file is still READ, so a keyboard
+ // attached to an iPad keeps whatever bindings a build ships with.
+ watchFiles: !isMobileHost,
);
Iterable<KeyBinding> bindings(
diff --git a/mobile/lib/state/app_state.dart b/mobile/lib/state/app_state.dart
index 4b42e2d48..001c2eb1a 100644
--- a/mobile/lib/state/app_state.dart
+++ b/mobile/lib/state/app_state.dart
@@ -24,11 +24,13 @@ import '../core/engine_availability.dart';
import '../core/local_hostname.dart';
import '../core/local_git_projects.dart';
import '../core/last_opened_agent.dart';
+import '../core/machine_cache.dart';
import '../core/test_run.dart';
import '../core/models.dart';
import '../core/project_folder.dart';
import '../core/project_history.dart';
import '../core/retry.dart';
+import '../logging/startup_trace.dart';
import '../settings/config_store.dart';
import '../stats/harness_stats.dart';
import '../terminal/terminal_session.dart';
@@ -161,6 +163,20 @@ class MachineState {
// crypto/pairing state the app has any data for.
bool needsLink = false;
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;
+
AgentLoadStatus agentLoadStatus = AgentLoadStatus.idle;
bool agentsRefreshing = false;
String? agentsLoadError;
@@ -1123,6 +1139,10 @@ class AppNotifier extends ChangeNotifier {
agentPreference = AgentPreference(paneLayoutStore?.storage),
projectHistory = ProjectHistory(paneLayoutStore?.storage),
lastOpenedAgent = LastOpenedAgent(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.
+ _machineCache = paneLayoutStore == null ? null : MachineCache(),
session = authSession,
_store = configStore,
cliLink = cliLink ?? CliLink(),
@@ -1191,6 +1211,11 @@ class AppNotifier extends ChangeNotifier {
/// The agent the phone's terminal had open, kept across launches — see [LastOpenedAgent].
final LastOpenedAgent lastOpenedAgent;
+ /// 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;
@@ -1698,7 +1723,10 @@ class AppNotifier extends ChangeNotifier {
try {
if (_store != null) {
try {
- config = await _store.load().timeout(const Duration(seconds: 5));
+ 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;
@@ -1853,7 +1881,10 @@ class AppNotifier extends ChangeNotifier {
// refreshes it itself. This app never reads, stores, or refreshes a token of its own; it just
// asks the CLI whether this computer is currently signed in.
try {
- final authStatus = await cliLogin.checkStatus();
+ final authStatus = await StartupTrace.time(
+ 'boot.checkSignIn',
+ cliLogin.checkStatus,
+ );
if (!_authWorkCurrent(revision)) return;
if (!authStatus.loggedIn) {
currentUser = null;
@@ -2083,16 +2114,81 @@ class AppNotifier extends ChangeNotifier {
// race `harness start`'s own backend handshake and surface a bogus 30s "Could not load
// machines" timeout. A daemon that never comes up still gets a home screen below, with
// the failure shown there as before, since that's where the retry affordance lives.
- _bootStatusMessage = 'Starting local service…';
+ // A viewer has no local service to start — `ensureCliDaemonReady` returns
+ // immediately below — so saying so was a sentence about somebody else's
+ // computer shown while this one read its own disk.
+ _bootStatusMessage = viewer == null
+ ? 'Starting local service…'
+ : '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 here rather
+ // than when that screen mounts — several state-file operations later, behind
+ // every one of their locks. See [LastOpenedAgent.prefetch].
+ lastOpenedAgent.prefetch();
// 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.
- await _restorePaneLayout();
- if (!_authWorkCurrent(revision)) return;
- await dial.restore();
+ //
+ // ⚠️ Together, not one after the other. Both read the same state file, and
+ // the store serializes them anyway — but serialized on ITS queue they cost
+ // one lock each back to back, whereas awaited separately here they also cost
+ // a scheduler hop each, and neither has ever depended on the other.
+ //
+ // `dial` is not asked about at all in a viewer: 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 machine…".
+ //
+ // ⚠️ 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.
+ Future<Object?>? machineRefresh;
+ if (viewer != null) {
+ _ensurePool();
+ 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',
+ () => Future.wait([
+ _restorePaneLayout(),
+ if (viewer == null) dial.restore(),
+ ]),
+ );
if (!_authWorkCurrent(revision)) return;
_ensurePool();
try {
@@ -2117,7 +2213,16 @@ class AppNotifier extends ChangeNotifier {
// metadata is independent of machine discovery and must not delay work.
unawaited(_loadProfile());
try {
- await refreshMachines();
+ // The request a viewer already has in flight (above), or a fresh one where
+ // there is none — a desktop, whose machine list is served by a daemon that
+ // was not confirmed up until `ensureCliDaemonReady` returned, so asking any
+ // earlier there would race the very handshake that gate exists to wait out.
+ if (machineRefresh == null) {
+ await refreshMachines();
+ } else {
+ final failure = await machineRefresh;
+ if (failure != null) throw failure;
+ }
} catch (error) {
if (!_authWorkCurrent(revision)) return;
_lastError = 'Could not load machines: ${describeApiError(error)}';
@@ -2558,6 +2663,13 @@ class AppNotifier extends ChangeNotifier {
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());
sessionPreviews.clear();
expandedMachines.clear();
selectedMachineId = null;
@@ -2762,6 +2874,17 @@ class AppNotifier extends ChangeNotifier {
_stopOfflineRetry(entry.key);
_stopLinkRetry(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));
@@ -2801,6 +2924,18 @@ class AppNotifier extends ChangeNotifier {
}
if (localEndpoint != null) _updateLocalProjectSnapshot(localEndpoint);
_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) {
+ unawaited(
+ cache.save(
+ machines,
+ isOnline: (machine) => _nodeOnlineFromStatus(machine.status) == true,
+ ),
+ );
+ }
notifyListeners();
}
@@ -3122,8 +3257,59 @@ class AppNotifier extends ChangeNotifier {
.machineId;
}
for (final machine in machines) {
- _connectMachine(machineStates[machine.machineId]!);
- unawaited(_loadMachineData(machineStates[machine.machineId]!));
+ 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.
+ //
+ // Nothing is lost by skipping them. `_applyNodeStatus` has already put
+ // each one on the 5-second offline poll (`_startOfflineRetry`), which
+ // dials the moment it comes back, and a pull-to-refresh still reaches
+ // every machine through `refreshMachines`. The tiles say "Offline", which
+ // is both true and immediate, instead of "Connecting…" for ten seconds
+ // before saying the same thing.
+ //
+ // 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 (!state.isLocalMachine &&
+ _nodeOnlineFromStatus(machine.status) == false) {
+ StartupTrace.mark('skipped offline machine ${machine.machineId}');
+ continue;
+ }
+ _connectMachine(state);
+ // ⚠️ **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 (_pool?[machine.machineId]?.isReady == true) {
+ unawaited(_loadMachineData(state));
+ }
}
}
@@ -3314,6 +3500,140 @@ class AppNotifier extends ChangeNotifier {
return _conn(machineId).sendTerminalBinary(encoded);
}
+ /// 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;
+ final cached = await StartupTrace.time('boot.machineCache', cache.read);
+ if (cached.isEmpty || _disposed || !_authWorkCurrent(revision)) return;
+ // The fetch got there first — it is the truth, and this has nothing to add.
+ if (machines.isNotEmpty || machineStates.isNotEmpty) return;
+ var warmed = 0;
+ var warmedAgents = 0;
+ final warmMachines = <Machine>[];
+ 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;
+ final state = machineStates.putIfAbsent(
+ machine.machineId,
+ () => MachineState(machine),
+ );
+ state.transportMode = MachineTransportMode.cloudE2ee;
+ // ⚠️ **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;
+ warmedAgents += entry.agents.length;
+ }
+ // ⚠️ **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 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.
+ _connectMachine(state);
+ warmMachines.add(machine);
+ warmed++;
+ }
+ if (warmed == 0) return;
+ // ⚠️ 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();
+ }
+
+ /// 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,
@@ -3345,7 +3665,12 @@ class AppNotifier extends ChangeNotifier {
Future<void> _performMachineDataLoad(MachineState machine) async {
final revision = _authRevision;
- final hadAgents = machine.agents.isNotEmpty;
+ // ⚠️ 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;
@@ -3355,27 +3680,84 @@ class AppNotifier extends ChangeNotifier {
debugPrint('agents_list start: ${machine.machine.machineId}');
try {
const inventoryTimeout = Duration(seconds: 10);
- await connection.waitUntilReady(timeout: inventoryTimeout);
- if (!_machineWorkCurrent(machine, revision)) return;
- // Keep the inventory's existing total budget, including connection time.
- // Capabilities get their own budget only once the handshake is complete.
- final remaining = inventoryTimeout - deadline.elapsed;
- if (remaining <= Duration.zero) {
- throw const WsRequestTimeout('agents_list');
+ // ⚠️ **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,
);
- final response = await connection.request(
- 'agents_list',
- timeout: remaining,
+ final response = await StartupTrace.time(
+ 'agents.list',
+ () => connection.request('agents_list', timeout: remaining),
);
if (!_machineWorkCurrent(machine, revision)) return;
- final agents = (response['agents'] as List<dynamic>? ?? [])
+ final rawAgents = response['agents'] as List<dynamic>? ?? [];
+ final agents = 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,
+ ]);
+ unawaited(
+ cache.save(
+ machines,
+ isOnline: (item) => _nodeOnlineFromStatus(item.status) == true,
+ ),
+ );
+ }
_replaceAgents(machine, agents);
machine.agentLoadStatus = AgentLoadStatus.loaded;
machine.agentsRefreshing = false;
@@ -3415,12 +3797,31 @@ class AppNotifier extends ChangeNotifier {
// keep timing out against the same dead session.
unawaited(connection.forceReconnect());
}
- } else {
+ } 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.
- if (!hadAgents && machine.agentLoadStatus != AgentLoadStatus.needsLink) {
+ //
+ // 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');
@@ -3541,6 +3942,37 @@ class AppNotifier extends ChangeNotifier {
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.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;
+ }
+
Future<void> _readTerminalCapabilities(
MachineState machine,
WsConn connection,
@@ -3553,25 +3985,13 @@ class AppNotifier extends ChangeNotifier {
timeout: const Duration(seconds: 8),
);
if (!_machineWorkCurrent(machine, revision)) return;
- machine.terminalCapabilityLoaded = true;
- 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;
+ _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 (_) {
if (!_machineWorkCurrent(machine, revision)) return;
machine.terminalCapabilityLoaded = true;
@@ -3593,6 +4013,10 @@ class AppNotifier extends ChangeNotifier {
}
void _replaceAgents(MachineState machine, List<Agent> agents) {
+ // 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();
for (final old in machine.agents.where(
(agent) => !nextIds.contains(agent.id),
@@ -4478,12 +4902,28 @@ class AppNotifier extends ChangeNotifier {
final pending = machine.pendingOfflineAgentId;
if (pending != null) {
unawaited(_recoverPendingAgent(machine, pending));
- } else if (panesFor(machineId).any(_paneNeedsAttach)) {
+ } else if (panesFor(machineId).any(_paneNeedsAttach) &&
+ _pool?[machineId]?.isReady == true) {
// A tile restored from the saved layout 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));
}
}
@@ -4505,6 +4945,15 @@ class AppNotifier extends ChangeNotifier {
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 (_pool?[machineId]?.isReady != true) {
+ 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,
@@ -4864,7 +5313,27 @@ class AppNotifier extends ChangeNotifier {
send: (type, payload) =>
_conn(pane.machineId).sendTerminalFrame(type, payload),
sendBinary: (frame) => _sendTerminalBinary(pane.machineId, frame),
- onOpenStalled: () => _conn(pane.machineId).forceReconnect(),
+ // ⚠️ **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;
+ },
);
pane.session = terminal;
terminal.addListener(notifyListeners);
diff --git a/mobile/lib/terminal/terminal_session.dart b/mobile/lib/terminal/terminal_session.dart
index 55193c8f6..a4174863a 100644
--- a/mobile/lib/terminal/terminal_session.dart
+++ b/mobile/lib/terminal/terminal_session.dart
@@ -87,7 +87,13 @@ class TerminalSession extends ChangeNotifier {
/// going stale silently (the relayed machine's own Harness process restarted, dropping its E2EE
/// session without the transport ever closing) so a reconnect looks like a couple of extra seconds
/// of "attaching" instead of a hang the user has to notice and manually retry.
- final Future<void> Function()? onOpenStalled;
+ /// Force a fresh transport dial for a stream that opened and then went silent.
+ ///
+ /// Returns whether a reconnect was actually started. False means the caller
+ /// declined — the transport is not up yet, so there is nothing to reconnect —
+ /// and [_recoverAndResend] then keeps its one-per-open budget rather than
+ /// spending it on a no-op.
+ final Future<bool> Function()? onOpenStalled;
TerminalSession({
required this.machineId,
@@ -128,6 +134,20 @@ class TerminalSession extends ChangeNotifier {
String? _openRequestId;
int? _expectedSeq;
+
+ /// Whether this session has drawn anything yet.
+ ///
+ /// False from the moment the session opens until the machine's first
+ /// `terminal_keyframe` lands — the window in which [status] already reads
+ /// `controlling` and the emulator's buffer is still empty, so a terminal built
+ /// on it paints a blank screen. The phone shows its skeleton across exactly
+ /// this gap (`phone/terminal_page.dart`), which is why the flag is public
+ /// rather than inferred from [status].
+ ///
+ /// Reads `_expectedSeq`, the sequence cursor set by that first frame and
+ /// cleared by every reopen (see `_armInitialKeyframeWatchdog`, which treats
+ /// the same null as "no keyframe arrived").
+ bool get hasRenderedFrame => _expectedSeq != null;
int _lastRenderedSeq = -1;
int _framesSinceAck = 0;
int _renderedSinceAckBytes = 0;
@@ -373,12 +393,21 @@ class TerminalSession extends ChangeNotifier {
) async {
final recover = onOpenStalled;
if (_openStallRecovered || recover == null) return false;
- _openStallRecovered = true;
+ var reconnected = false;
try {
- await recover();
+ reconnected = await recover();
} catch (_) {
- // Still worth polling for readiness even if the forced reconnect itself errored.
+ // A forced reconnect that threw still started one; poll for readiness.
+ reconnected = true;
}
+ // ⚠️ **The one forced reconnect per open is spent only if one happened.**
+ // The hook declines while the transport is still connecting — there is
+ // nothing to recover there, and redialling would destroy the dial in
+ // progress (see `onOpenStalled` in `app_state.dart`). Marking the budget
+ // spent on a decline would leave a stream that later stalls for real with no
+ // recovery left, which is the failure this whole path exists to handle.
+ if (!reconnected) return false;
+ _openStallRecovered = true;
for (var attempt = 0; attempt < 10; attempt++) {
if (!_isCurrent(generation) ||
status != TerminalSessionStatus.opening ||
diff --git a/mobile/lib/viewer/direct_auth.dart b/mobile/lib/viewer/direct_auth.dart
index 8f7a9b69e..f3baf97b9 100644
--- a/mobile/lib/viewer/direct_auth.dart
+++ b/mobile/lib/viewer/direct_auth.dart
@@ -28,21 +28,28 @@ class DirectAuth implements AccessTokenSource {
@override
Future<String> accessToken({bool force = false, String? failedToken}) async {
- final current = await session.accessToken();
+ // Token and expiry in one read: every WebSocket dial comes through here, and
+ // the two of them live in the same file behind the same exclusive lock, so
+ // asking separately doubled the disk work on the one call the launch and
+ // every reconnect wait on. See [AuthSession.accessTokenWithExpiry].
+ final saved = await session.accessTokenWithExpiry();
+ final current = saved.token;
if (current == null || current.isEmpty) {
throw const DirectAuthException('Not signed in.', signedOut: true);
}
// Someone else already refreshed past the token that failed — use theirs.
if (failedToken != null && failedToken != current) return current;
- if (!force && !await _isStale()) return current;
+ if (!force && !_isStale(saved.expiresAt)) return current;
return _refreshing ??= _refresh().whenComplete(() => _refreshing = null);
}
- Future<bool> _isStale() async {
- final expiresAt = await session.accessTokenExpiresAt();
- return expiresAt != null &&
- expiresAt.isBefore(DateTime.now().toUtc().add(_refreshSkew));
- }
+ /// A token with no recorded expiry is taken at face value: it is what a
+ /// session saved by a build that did not store one looks like, and refusing it
+ /// would sign that user out for no reason. A server rejection still routes
+ /// through `failedToken` above.
+ bool _isStale(DateTime? expiresAt) =>
+ expiresAt != null &&
+ expiresAt.isBefore(DateTime.now().toUtc().add(_refreshSkew));
Future<String> _refresh() async {
final refreshToken = await session.refreshToken();
diff --git a/mobile/lib/viewer/viewer_key_store.dart b/mobile/lib/viewer/viewer_key_store.dart
index 8514aa9f7..a7303731f 100644
--- a/mobile/lib/viewer/viewer_key_store.dart
+++ b/mobile/lib/viewer/viewer_key_store.dart
@@ -60,6 +60,20 @@ class ViewerKeyStore {
final LocalKeyValueStore _storage;
Future<E2eeIdentity>? _identity;
+ /// The linked machines, held after the first read — the same treatment
+ /// [identity] has always had, and for a sharper reason.
+ ///
+ /// [peers] is on the dial path: every connection, and every RECONNECT, asks
+ /// for the peer before it opens a socket (`viewerRelayCodecs`). Uncached, a
+ /// phone waking to four machines that each redial takes four exclusive locks
+ /// on `state.json` and four full parses of it — in series, because the store
+ /// queues them — while the screen says "Connecting to your machine…".
+ ///
+ /// Every write goes through [_write], which replaces this, so the cache cannot
+ /// outlive a link or an unlink. It is per-instance and the app builds one
+ /// store (`ViewerServices`), so there is no second copy to go stale.
+ Future<List<MachinePeer>>? _peers;
+
static const _seedKey = 'viewer_e2ee_identity_seed';
static const _peersKey = 'viewer_e2ee_machine_peers';
@@ -74,8 +88,10 @@ class ViewerKeyStore {
return minted;
}
- /// Newest link first.
- Future<List<MachinePeer>> peers() async {
+ /// Newest link first. Read once and held — see [_peers].
+ Future<List<MachinePeer>> peers() => _peers ??= _readPeers();
+
+ Future<List<MachinePeer>> _readPeers() async {
final raw = await _storage.read(_peersKey);
if (raw == null) return const [];
final Object? decoded;
@@ -118,8 +134,23 @@ class ViewerKeyStore {
return true;
}
- Future<void> _write(List<MachinePeer> peers) => _storage.write(
- _peersKey,
- jsonEncode([for (final peer in peers) peer.toJson()]),
- );
+ /// The one path that changes the peer list, so the one place the cache is
+ /// replaced.
+ ///
+ /// ⚠️ The cache is dropped BEFORE the write and reseeded only once it lands.
+ /// Seeding first would publish a list that a failed write never persisted, and
+ /// this app would then dial a machine it believes it linked until it was
+ /// relaunched. Dropping first costs at most one re-read on the next dial; both
+ /// orders keep [peers] sorted, because the reseeded list is sorted here the
+ /// same way [_readPeers] sorts the file.
+ Future<void> _write(List<MachinePeer> peers) async {
+ _peers = null;
+ await _storage.write(
+ _peersKey,
+ jsonEncode([for (final peer in peers) peer.toJson()]),
+ );
+ final sorted = [...peers]
+ ..sort((a, b) => b.linkedAt.compareTo(a.linkedAt));
+ _peers = Future.value(sorted);
+ }
}
diff --git a/mobile/lib/ws/ws_conn.dart b/mobile/lib/ws/ws_conn.dart
index d712b01a6..e4aa738a9 100644
--- a/mobile/lib/ws/ws_conn.dart
+++ b/mobile/lib/ws/ws_conn.dart
@@ -7,6 +7,7 @@ import 'package:web_socket_channel/web_socket_channel.dart';
import '../logging/app_log.dart';
import '../logging/redact.dart';
+import '../logging/startup_trace.dart';
import '../core/models.dart';
import 'relay_codec.dart';
import 'terminal_transport_plugin.dart';
@@ -199,6 +200,17 @@ class WsConn {
if (_closing || _connecting) return;
_connecting = true;
_ready = false;
+ // ⚠️ **The outbound queue starts empty on every dial, and it did not used
+ // to.** `_outboundTail` is a chain each send appends itself to, so one link
+ // that never completes stalls every frame queued behind it — for the life of
+ // the connection, redials included, because the chain outlived them. A dial
+ // whose `machine_select` never reached the socket therefore could not be
+ // rescued by dialling again: the new select joined the same stuck queue.
+ //
+ // Safe to drop here because a new socket makes the old queue meaningless.
+ // Anything still pending on it was addressed to a channel that is gone, and
+ // `_flushQueue` re-sends what actually matters once the session is ready.
+ _outboundTail = Future<void>.value();
WebSocketChannel? dialing;
onStatus(
_attempt == 0
@@ -206,16 +218,50 @@ class WsConn {
: ConnectionStatus.reconnecting,
);
try {
- final token = isLocal ? null : await accessTokenProvider(false, null);
+ // ⚠️ Started together, then awaited: the credential comes from the session
+ // (and may go to the network to refresh), while the codec comes off disk
+ // and mints an ephemeral key — neither has ever needed the other's result.
+ // In series they were two waits stacked in front of the dial, on the
+ // stretch the phone shows as "Connecting to your machine…", and every
+ // reconnect paid it again.
+ final codecs = isLocal ? null : relayCodecs;
+ final pendingToken = isLocal
+ ? null
+ : StartupTrace.time(
+ 'ws.accessToken',
+ () => accessTokenProvider(false, null),
+ );
+ // ⚠️ **The codec's own failure is captured HERE, where the future is made,
+ // not where it is awaited.** The credential is awaited first and can
+ // throw — a refresh against a dead network does — and every path out of
+ // this method from that point leaves nobody to await the codec. An
+ // unhandled rejection on that abandoned future reaches the zone's error
+ // handler and is reported as a crash, for a dial that merely failed.
+ //
+ // ⚠️ Captured, NOT flattened to null: a null codec means "this device has
+ // no link to that machine", which [_refusePeer] answers by closing the
+ // connection for good. A failed READ of the link is a different thing —
+ // the file was locked, or briefly unreadable — and must stay retryable, so
+ // it is rethrown below into the catch that schedules the reconnect.
+ final pendingCodec = codecs == null
+ ? null
+ : StartupTrace.time('ws.relayCodec', () => codecs(machineId))
+ .then<({RelayCodec? codec, Object? error})>(
+ (codec) => (codec: codec, error: null),
+ onError: (Object error) => (codec: null, error: error),
+ );
+ final token = await pendingToken;
if (!isLocal && (token == null || token.isEmpty)) {
throw StateError('WebSocket credential is missing');
}
if (_closing) return;
_tokenUsed = token;
- final codecs = isLocal ? null : relayCodecs;
- if (codecs != null) {
- final codec = await codecs(machineId);
+ if (pendingCodec != null) {
+ final result = await pendingCodec;
if (_closing) return;
+ final failure = result.error;
+ if (failure != null) throw failure;
+ final codec = result.codec;
if (codec == null) {
_refusePeer('NO_PEER_LINK');
return;
@@ -247,9 +293,28 @@ class WsConn {
? WebSocketChannel.connect(uri)
: WebSocketChannel.connect(uri, protocols: [token!]);
_channel = channel;
- await channel.ready.timeout(_dialTimeout);
+ await StartupTrace.time(
+ 'ws.dial',
+ () => channel.ready.timeout(_dialTimeout),
+ );
if (_closing || !identical(_channel, channel)) {
+ // Logged because this is a silent exit from a dial that otherwise looks
+ // successful — the trace shows `ws.dial` completing and then nothing at
+ // all, which is indistinguishable from a relay that went quiet.
+ final superseded = !identical(_channel, channel);
+ appLog.warn(
+ 'ws',
+ 'dial abandoned after ready (closing=$_closing '
+ 'superseded=$superseded) $machineId',
+ );
await channel.sink.close();
+ // ⚠️ A superseded dial must leave a live connection behind it. This used
+ // to just return, on the assumption that whoever replaced `_channel` was
+ // finishing the job — but the replacement is a `connect()` that
+ // `_connecting` had already turned away, so there was nobody to finish
+ // it. The guard in [reconnectNow] stops the overlap happening at all;
+ // this makes the outcome survivable if it ever does again.
+ if (superseded && !_closing && _channel == null) _scheduleReconnect();
return;
}
_sub = channel.stream.listen(
@@ -259,6 +324,19 @@ class WsConn {
);
final forceRelayReconnect = _forceRelayReconnect;
_forceRelayReconnect = false;
+ // ⚠️ **Armed BEFORE the send, and deliberately not after it.** `sendFrame`
+ // queues behind `_outboundTail`, so it resolves when this frame reaches
+ // the socket — which is not guaranteed to be soon, and on a fresh dial was
+ // observed never to happen at all. Arming afterwards made the watchdog
+ // itself unreachable in exactly the case it exists for: the launch hung
+ // with the last log line being the dial, and no select, no answer and no
+ // retry after it.
+ //
+ // Armed first, the timer covers the whole of "asked and not answered",
+ // whether the asking stalled in the queue or the answering stalled at the
+ // relay. Cancelled by [_markReady], by [_onDone] and by [close].
+ _armSelectWatchdog();
+ appLog.debug('ws', '→ machine_select $machineId');
await sendFrame({
'type': 'machine_select',
'payload': {
@@ -269,7 +347,12 @@ class WsConn {
});
} on WsCredentialRevoked catch (error) {
_signOut(error.message);
- } catch (_) {
+ } catch (error) {
+ // Swallowed for control flow — a failed dial is retried, not surfaced —
+ // but not silently: this branch covers the credential, the codec, the
+ // dial itself and the select, and with no line of its own a launch that
+ // died in any of them looked exactly like one that simply stopped.
+ appLog.warn('ws', 'dial failed $machineId', error: error);
_abandonDial(dialing);
if (!_closing) _scheduleReconnect();
} finally {
@@ -353,7 +436,52 @@ class WsConn {
});
}
+ /// How long the relay gets to answer `machine_select` before this redials.
+ ///
+ /// Measured against the real thing: a relay that answers at all answers in
+ /// well under a second (dial ~0.8s, then `machines_status` and the E2EE
+ /// welcome within ~1.3s). Six seconds is far outside that and still far inside
+ /// a person's patience.
+ static const _selectTimeout = Duration(seconds: 6);
+
+ Timer? _selectWatchdog;
+
+ /// Redial if the relay never answers the select.
+ ///
+ /// ⚠️ **A dial can complete and then go quiet, and nothing else notices.** The
+ /// socket opens, `machine_select` goes out, and the relay simply never sends
+ /// `machines_status` — observed on the FIRST dial of a launch, reproducibly,
+ /// against a machine that was up the whole time. There is no close, no error
+ /// and no frame: `_onDone` never runs, the reconnect backoff never arms, and
+ /// the connection sits there looking healthy forever.
+ ///
+ /// It used to be papered over from a long way away: `agents_list` would time
+ /// out after ten seconds, be misread as the machine having gone offline, and
+ /// `forceReconnect()` would redial — which worked, and cost twelve seconds and
+ /// a spurious "Disconnected" on screen. Removing that accidental rescue is
+ /// what turned this from slow into a permanent hang, which is how it was
+ /// finally found.
+ ///
+ /// Handled here, where the evidence is: this connection asked a question and
+ /// got no answer, so it asks again on a new socket. Six seconds rather than
+ /// ten, and no state anywhere else is told the machine is offline, because
+ /// nothing here says it is.
+ void _armSelectWatchdog() {
+ _selectWatchdog?.cancel();
+ _selectWatchdog = Timer(_selectTimeout, () {
+ if (_closing || _ready || _channel == null) return;
+ appLog.warn('ws', 'machine_select unanswered; redialling $machineId');
+ // Through the ordinary dial path, so the attempt counter and its backoff
+ // apply: a relay that is genuinely down must not be hammered every six
+ // seconds by a client that thinks it is being helpful.
+ _abandonDial(_channel);
+ _scheduleReconnect();
+ });
+ }
+
void _markReady() {
+ _selectWatchdog?.cancel();
+ _selectWatchdog = null;
_ready = true;
_attempt = 0;
onStatus(ConnectionStatus.connected);
@@ -381,7 +509,15 @@ class WsConn {
}
return;
case 'e2e_welcome':
- if (await codec.handleWelcome(payload)) {
+ // The verify and key agreement behind this are pure-Dart Ed25519/X25519
+ // on the UI isolate, so this span is CPU on the very thread drawing the
+ // spinner — worth its own line to tell it apart from time spent waiting
+ // on the machine to answer.
+ if (await StartupTrace.time(
+ 'ws.e2eeWelcome',
+ () => codec.handleWelcome(payload),
+ )) {
+ StartupTrace.mark('ws.ready');
_markReady();
_plugin?.onSessionReady();
} else {
@@ -734,6 +870,11 @@ class WsConn {
_codec = null;
_disposePlugin();
_ready = false;
+ // The socket answered by closing, which is an answer — the watchdog is for
+ // a socket that says nothing at all. Cancelled here so the redial below is
+ // the only one, rather than one of two racing each other.
+ _selectWatchdog?.cancel();
+ _selectWatchdog = null;
_rejectPending('WS disconnected');
if (_closing) {
onStatus(ConnectionStatus.disconnected);
@@ -799,8 +940,23 @@ class WsConn {
///
/// ⚠️ A no-op when [_closing]. That flag means somebody decided this connection should stop —
/// signed out, machine unlinked, 4403 — and resuming the app is not a reason to revive it.
+ /// ⚠️ **A no-op while a dial is already in flight, which `_channel` alone does
+ /// not tell you.** `_channel` is assigned only after `channel.ready` resolves,
+ /// so for the ~800ms a relay dial takes there is a connect running with a null
+ /// channel — and this would start a SECOND one. The second overwrote
+ /// `_channel`, the first then found itself superseded and bailed out without
+ /// sending `machine_select`, and the second never sent one either because
+ /// `connect()`'s own `_connecting` guard had turned it away. The socket was
+ /// open, the relay was waiting to be told which machine, and neither side ever
+ /// spoke: the launch hung on "Connecting to your machine…" indefinitely.
+ ///
+ /// Reachable on every launch, not just on a real resume: the phone's shell
+ /// calls `handleAppResumed` as it mounts, which is a few hundred milliseconds
+ /// after the warm start has begun dialling.
void reconnectNow() {
- if (_closing || _channel != null) return;
+ if (_closing || _connecting || _channel != null) {
+ return;
+ }
_reconnectTimer?.cancel();
_reconnectTimer = null;
// The clock restarts too. Failures from BEFORE the app went away say nothing about the network
@@ -829,6 +985,10 @@ class WsConn {
_disposePlugin();
_reconnectTimer?.cancel();
_reconnectTimer = null;
+ // A watchdog left running would redial a connection somebody deliberately
+ // closed — see [_armSelectWatchdog].
+ _selectWatchdog?.cancel();
+ _selectWatchdog = null;
_rejectPending('WS closed');
final sub = _sub;
_sub = null;
@@ -852,6 +1012,9 @@ class WsConn {
if (_closing || (!isLocal && relayCodecs == null)) return;
_forceRelayReconnect = true;
_reconnectTimer?.cancel();
+ // This dials again itself; a pending watchdog would make that two dials.
+ _selectWatchdog?.cancel();
+ _selectWatchdog = null;
_ready = false;
_codec = null;
_disposePlugin();
diff --git a/mobile/lib/ws/ws_pool.dart b/mobile/lib/ws/ws_pool.dart
index 0b6f9704d..ce0993bbd 100644
--- a/mobile/lib/ws/ws_pool.dart
+++ b/mobile/lib/ws/ws_pool.dart
@@ -4,6 +4,7 @@ import 'relay_codec.dart';
import 'terminal_transport_plugin.dart';
import '../core/models.dart';
+import '../logging/app_log.dart';
import 'ws_conn.dart';
/// Owns one SSO-authenticated [WsConn] per machine.
@@ -55,7 +56,17 @@ class WsPool {
!current.isClosed) {
return current;
}
- if (current != null) unawaited(current.close());
+ if (current != null) {
+ // Replacing a live connection is a real event — it closes a socket and
+ // starts a fresh handshake — and it used to leave no trace at all, which
+ // made a launch that did it twice impossible to read in the log.
+ appLog.warn(
+ 'ws',
+ 'replacing connection $machineId '
+ '(was ${current.endpointKey}, now $desiredKey)',
+ );
+ unawaited(current.close());
+ }
final conn = WsConn(
wsBaseUrl: wsBaseUrl,
autonomousEnv: autonomousEnv,
@@ -99,7 +110,14 @@ class WsPool {
Future<void> closeMachine(String machineId) async {
final conn = _conns.remove(machineId);
- if (conn != null) await conn.close();
+ if (conn != null) {
+ // Closing a machine's socket is deliberate and rare — a machine leaving
+ // the account, a re-link, a sign-out — so it is worth a line. A close that
+ // lands mid-dial looks, from inside `connect()`, exactly like being
+ // superseded, and without this there was no way to tell the two apart.
+ appLog.warn('ws', 'closeMachine $machineId');
+ await conn.close();
+ }
}
Future<void> closeAll() async {