The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
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.dartindex 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.dartindex 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? nulldiff --git a/mobile/lib/core/harness_file_store.dart b/mobile/lib/core/harness_file_store.dartindex 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.dartindex 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.dartnew file mode 100644index 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.dartindex 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.dartnew file mode 100644index 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.dartindex 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 isdiff --git a/mobile/lib/phone/phone_status.dart b/mobile/lib/phone/phone_status.dartindex 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.dartindex 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;@overrideWidget 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 withdiff --git a/mobile/lib/settings/config_store.dart b/mobile/lib/settings/config_store.dartindex 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 ?? truediff --git a/mobile/lib/shortcuts/app_keymap.dart b/mobile/lib/shortcuts/app_keymap.dartindex 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.dartindex 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.dartindex 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.dartindex 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 {@overrideFuture<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.dartindex 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.dartindex 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.dartindex 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 {