Omniscio

Mobile Access — staying connected (part 2)

Part 2 of the Mobile Access page: what the phone shows when the connection is poor and how it recovers — the offline and reconnecting indicators, how fast a page resumes, the recovery that runs when the app looks stuck, the transport that survives a freeze, signing in on a phone, and the settings behind it all.

On this page

What it is

This is part 2 of the Mobile Access page. It covers the connection itself: what you see when it wobbles, and what the app does about it.

Where to find it

On your phone, in the running app — the indicators appear on screen, and the settings that govern them live in the desktop's mobile-access configuration.

How it behaves

Connectivity indicators (the connection banner and the dropped-action toast)

When you're using Omniscio in a browser (mobile or desktop), connectivity is fragile in a way the desktop app never has to deal with — Wi-Fi drops, cell handoff, the OS suspending a backgrounded tab, the WebSocket idling out behind a corporate proxy. Omniscio shows a slim connection banner across the top of the app so you can tell at a glance whether what you're looking at is live, slow, or stale. It can hold four strips:

  • Offline. An amber strip reading "You are offline. Some features are unavailable." It only appears after the browser has reported offline for 5 seconds continuously — a brief blink (sub-second online → offline → online, common on cell handoff) is suppressed so it doesn't flash every time you walk between rooms. It disappears the moment the browser reports online again; the 5-second gate applies only going into offline. It shows in the desktop app too.
  • Reconnecting… A calm grey strip with a pulsing dot while the WebSocket is down and the app is getting it back. It follows time since the outage began, not the number of reconnect attempts: it appears once the outage is 2 seconds old (WS_RECONNECT_CHIP_GRACE_MS), however long each attempt hangs. One attempt on a black-holed link can run the full connect timeout (12 seconds, or longer once the link has been measured as slow — see The timeouts follow the link below), which is how the old attempt-count gate left a phone blank for 25–44 seconds (2026-09-24 report). Every connection attempt starts the clock — a cold page load and each scheduled retry in ipc-ws-transport.ts calls markReconnecting() — and a later attempt in the same outage never restarts it, so a blip that recovers inside 2 seconds never flashes the strip. Coming back to the app is different: that reconnect is deliberate, so it owns the strip — it drops any strip (and any running clock) left over from while the page was hidden, and shows it only if the reconnect has not opened after 1.5 seconds (RESUME_RECONNECT_CHIP_DELAY_MS). Most resumes reconnect in about half a second, so usually you see nothing at all. Your own tap shows it at once instead of waiting out the grace: one that fails because the link is already down, one made while a reconnect attempt is under way, and one of yours that the phone drops when it gives up on the link (that one also says it didn't go through — see below). If an action you take fails because the link is already down, the strip shows at once (markReconnectingNow()), before the "that didn't go through" toast. A successful reconnect clears it; a rejected device credential (a 4001 close) cancels it, so it never appears over the pairing card. How fast it clears is covered in Reconnect speed (page resume + backoff) below.
  • Waiting for your computer… A calm grey strip with an hourglass for the other kind of trouble: the WebSocket still looks open, but nothing has come back from your computer while a request is waiting on it — either the computer is busy, or the link has quietly died and the phone hasn't given up on it yet. It appears once 10 seconds have passed since the first unanswered heartbeat ping with nothing received in that time (noteSilentWait() in the transport, anchored to that first ping so a slow-but-alive reopen never shows it), and any message from the computer clears it. It is display-only: it never changes when the phone declares the link dead — the heartbeat's deferral rules and their 20-second cap still decide that — and once the phone gives up on the link, "Reconnecting…" replaces it at once. It also appears sooner for a request you made — one that began within 5 seconds of a tap or key press — once that request has had no answer for 5 seconds and nothing at all has come back from the computer for 10 seconds (HOST_QUIET_MS, the transport's own "this socket is alive" window), including when the screen you tapped has to download its code first (ws-user-wait.ts). Both have to hold: any frame from the computer — a pong, a push, any reply — clears the strip and holds it back while it keeps arriving, because the strip's words are a claim about the computer, and a computer that is answering is not one you are waiting on. That second condition is what keeps the strip honest on a busy box: a phone's request tail is fat (measured 2026-09-26 over ~2 h of main.log: 4,889 session-history fetches, p50 240 ms, p99 26.7 s, 3.1 % past 5 s), one screen open fires dozens of requests at once, and on elapsed time alone the strip lit up continually on links whose own tape shows a pong landing a second later — the "continually getting waiting on your computer notices on mobile" report. A genuinely dropped link (the 2026-09-24 report) delivers nothing, so the strip still appears there, now about 10 seconds after the drop instead of 5. The app's own background traffic (refreshes, heartbeat timers, log shipping, code warms, the conversations it quietly pre-loads for the sessions you are likely to open next, and the reply suggestions it prepares in advance) never counts, and it clears the moment that answer arrives. Those pre-loads start right after your taps and wait on the computer's low-priority queue, so counting them once kept the strip up for half a minute after everything you asked for had already arrived — it looked exactly like a dropped connection (fixed 2026-09-25). Off switch for this tap-triggered part: localStorage['amc-disable-waiting-notice'] = '1' in the phone's browser.
  • Connection lost — tap to reload. A red strip once the fast-retry budget is used up (markGaveUp()). The transport keeps retrying quietly underneath at a capped backoff, but you get a distinct, actionable sign that live updates have stalled instead of a silently frozen screen; tapping it reloads the page, the guaranteed recovery. A successful reconnect clears it, and so does reopening the app, which starts a fresh cycle and shows "Reconnecting…" instead.

At most one of the three link strips shows at a time — Connection lost first, then Reconnecting…, then Waiting for your computer… — while the offline strip is independent and can sit above one. The link strips are browser-only: the desktop app has no WebSocket to lose, so ConnectionBanner.tsx never draws them there.

Always visible, never in the way. The banner is drawn on the page itself, on the connectionBanner layer (1150) of the z-index ladder, above every dialog, sheet and menu, so a dropped link is never hidden behind whatever you have open. It cannot live inside the app's own tree: the app root is its own stacking layer, and dialogs are drawn on the page beside it, so nothing inside the app can paint over them. An invisible placeholder at the top of the app keeps the banner's space, so it covers nothing. The phone's notifications are drawn on the page too, one layer higher (toast, 1200), so a notification that lands on the banner's strip while you type stays readable. Taps pass through the banner to whatever is underneath; only the reload button takes one.

Dropped-action heads-up. If a data-changing action you take (send a reply, snooze, save) can't reach the server because the WebSocket is down for longer than a blip, a one-off amber toast — "You're offline — that didn't go through. It'll work again once you reconnect." — tells you that specific action didn't land. Most of the time you never see it, because a user write taken while the socket is down is HELD first and sent once the socket reopens (up to 8 s, WS_WRITE_HOLD_FOR_OPEN_MS); the toast only appears when that hold expires because the link really is gone. The hold runs before anything is sent, so a held action lands exactly once. Kill switch: localStorage['amc-disable-broad-write-hold'] = '1' restores the older behaviour, where only creating a session was held. It is deliberately scoped to actions you take: the app's own background traffic (session / inbox / status polls, the activity + UI-usage + diagnostic heartbeat timers, the log shipping, and the passive composer typing-speed sampler typing-insights:sample) hits the same dead socket but simply retries on reconnect, so it never raises the toast — which is why typing in the composer on a dropped link is silent (2026-10-27 report). The suppress-vs-surface split is decided by isSilentOfflineDropChannel in the not-connected path of ipc-ws-transport.ts — a background invoke is suppressed, a genuine user action surfaces — and it coalesces to one toast per outage (markReconnectingNow() and the diagnostic breadcrumb still fire for a suppressed drop, so the Reconnecting… strip above is unaffected). The same message also fires when one of your requests was already sent and the phone drops it on giving up the link, not only when a tap finds the link down.

Where the state lives. The offline strip and the link strips are intentionally independent: you can be online (the browser thinks the network is fine) while the WebSocket is mid-reconnect, and you can be flat-out offline. Together they tell "the network is gone" apart from "the pipe to your computer is being rebuilt" and "the pipe is open but your computer is slow to answer". All of it is read from the useConnectivityStore Zustand store (connectivity-store.ts) — isOnline for the offline strip, wsReconnecting / wsAwaitingReply / wsWaitingOnHost (the tap-triggered wait, set only by ws-user-wait.ts) / wsGaveUp for the link strips — and set through intent-named helpers in ws-reconnect-state.ts (markReconnecting / markReconnectingNow / markAwaitingReply / markConnected / markGaveUp / markAuthStopped), which also own the one grace timer, plus a window.addEventListener('offline') debounce timer for the offline strip. The promises are locked in mobile-ws-stall-guard-contract.md (Connection banner).

Reconnect speed (page resume + backoff)

When you tab back to Omniscio on mobile after the OS has backgrounded the browser — even briefly, like a quick file-picker takeover or a phone call — the WebSocket has often gone silently dead. The TCP connection still looks OPEN from the browser's view, but the radio went to sleep, the cell↔Wi-Fi handoff dropped packets, or a captive portal is now blocking it. Omniscio's reconnect path is tuned for this exact case: as soon as the page becomes visible again, the dead socket is aborted and a fresh WebSocket connects in the same tick. The user-visible result is that the reconnect finishes in well under a second instead of occasionally hanging for ~20s while the browser waits out a stale TCP timeout — and, because a resume reconnect only shows the "Reconnecting…" chip past 1.5 s, a normal return to the app shows no chip at all.

A resume that lands on a stuck handshake no longer waits out the cold-load timeout. The rebuild is immediate, but the handshake it starts can hang — the browser will hold a route the radio dropped. That attempt used to be judged by the timeout meant for a COLD first load, which reads the worst recent round trip and can be as long as a minute, and at its deadline an answered /health/live probe extended the wait rather than starting over. So a resume that hit a stuck handshake sat there: measured on the owner's box on 2 November 2026, resume p95 was 6.1 seconds and the worst 12.3 seconds, almost exactly that timeout. A resume's own attempt is now judged on its own budget — under 2 seconds on a healthy link, never above the 12 seconds the cold load starts from — and when the computer proves it is answering while the handshake still has not opened, the phone stops waiting and rebuilds once, immediately. If the probe cannot reach the computer at all, the radio really is asleep and the phone waits exactly as it did before, so nothing is torn down that had a chance. Invariant: resume-judged-by-a-resume-budget in mobile-ws-stall-guard-contract.md.

Requests made during a resume wait for the new connection. On a phone the first reconnect attempt often dies at once as the network resets on wake, and the next one opens about half a second later. Anything the app (or you) asks for in that gap — a list refresh, a rename, a reply — now waits for that open and then goes through, rather than failing with "WebSocket not connected" and a "that didn't go through" toast. The wait is bounded by WS_READ_HOLD_FOR_OPEN_MS (15 s) from the wake; past that the connection is genuinely down, and the request fails the usual way, with the chip and the heads-up. A connection that drops on its own (no resume) still fails requests straight away, as before. Invariants: chip-deliberate-reconnect-delay and deliberate-reconnect-holds-requests in mobile-ws-stall-guard-contract.md.

A background load that loses the link says nothing and retries itself once. The run-location picker's read of your saved SSH remotes (use-ssh-remotes.ts) is the case the owner hit: on a phone the SSH family is normally refused and stays silent, but during a reconnect the read came back as a transport drop instead and raised a red "Couldn't load your remotes" on top of the reconnect — an alarm for something he never asked for (2026-10-27). A transport failure (isWsTransportDownError, which already knows every "the socket never took it" string) or simply being offline/reconnecting is now treated as a BLIP: no toast, and the read re-issues itself once on the next socket open. A genuine failure — including a genuine failure of that retry — still raises the one retryable toast, so the desktop's behaviour and the "your remotes failed to load is not the same as you have none" rule are unchanged.

The update offer never lands on a reconnect. The "An Omniscio update is ready to load" prompt is raised when the service worker never confirms the new build inside its 90 s bound (see the update section below). It is now shown only while the link is actually usable (wsOpen && isOnline, the RAW socket state rather than the display-debounced chip), so a card can no longer appear on top of a reconnect — and a card raised during an outage would be useless anyway, since the reload it offers could not load anything. During an outage the offer defers and appears once on the next healthy connection, still at most once per build per page.

A resume on a socket that is still alive re-reads nothing. The browser view of "dead" is not always right, so the resume first asks the socket itself: if ANY frame arrived within the last 10 seconds, the connection is proven alive, and the resume keeps it, pings it once and stops there. It does not re-download your state — a socket that just answered has missed nothing. That matters on a phone, where locking the screen and unlocking it is the most common way back into the app: before, each of those returns re-ran the whole reconnect re-read (every list, your open conversation, every store), about 16 MB a pass, several times a minute. What a real gap still costs is covered in When a push is lost below.

When a push is lost. Two things can lose a push, and each heals the same way — one re-sync of the app's state. (1) A frame lost on the wire: every push frame carries a per-connection sequence number, so a jumped number proves a loss, and the app re-syncs at most once every 10 seconds. (2) A frame the computer deliberately shed because the phone's outbound queue was over its 4 MB cap: it was never sent, so it consumes no sequence number and the phone would otherwise never know. The desktop counts those sheds per connection — only for frames this phone would actually have received — and echoes the count on every heartbeat reply, so a risen count is the phone's signal that it missed a state change. A shed-driven re-sync is limited to one every five minutes, because the re-read's own replies are what fills that queue: without its own, longer floor a congested phone would re-read on a loop. Both paths are silenced by the one amc-disable-push-seq-resync browser flag. Invariants: shed-is-counted-not-stamped, pong-carries-the-shed, shed-heals-the-phone in mobile-ws-heartbeat-contract.md and resume-on-a-live-socket-reads-nothing in mobile-ws-stall-guard-contract.md.

Two backoff tables. Reconnect attempts pick a delay schedule based on whether the page is currently visible:

  • Visible (you're staring at the screen): 0ms, 500ms, 1s, 2s, 3s, 5s, 10s, 20s, 30s, 30s, …. The first attempt fires synchronously inside scheduleReconnect() — no setTimeout tick, the new WebSocket is constructed in the same JS task as the close handler that scheduled it.
  • Hidden (tab backgrounded, screen off): 1s, 2s, 4s, 8s, 16s, 30s, …. Slower because there's no user waiting and we want to spare the radio.

The schedule is selected per-attempt off !document.hidden, so a backgrounded retry that lands while you're tabbed back to Omniscio picks the visible table.

The timeouts follow the link, not a fixed number. Omniscio measures the phone's round trip from its own heartbeat (the pong's arrival minus the send time of the ping it answers) and scales two decisions off it by clamp(4 × round trip, floor, ceiling) — four round trips is roughly what a WebSocket handshake costs: TCP, TLS, the upgrade, plus one spare.

  • How long a connect attempt may run — 12 s on a healthy or still-unmeasured link (a cold load behaves exactly as it always did), up to 60 s on a slow one. Before this, a link measuring 3–6 s per round trip aborted every reconnect attempt at a flat 12 s before it could open: on 2026-10-16 that was 37 aborted attempts in 24 hours, and the worst outage ran 97 s across six of them.
  • How long a live socket may go unanswered before it is declared dead — 10 s normally, up to 30 s on a slow link. A flat 10 s expired between two answers that were 12 s apart, so eight sockets were torn down after 21–27 s while 15–78 requests were still being answered. The ceiling stays under the ~30 s Android Doze idle-TCP reap, and the timeout that bounds the in-flight-request deferral (20 s) is unchanged — it only ever governs a socket that answered nothing at all, which is the one that should die.

Both figures are measured, not guessed: the client keeps the round trips of the last four answered pings, so one lucky fast pong cannot erase a slow stretch. Each pong is timed against the ping it actually answers, and a replaced socket starts with no pings outstanding, so a dead socket's leftovers can never bias the next one. The same scaling does not touch the "Waiting for your computer…" threshold, the resume socket-reuse check, or anything on the desktop side — those keep their fixed windows. Invariants: connect-watchdog-scales-to-link and recent-inbound-window-scales-to-link in mobile-ws-stall-guard-contract.md and mobile-ws-heartbeat-contract.md.

forceImmediateReconnect() semantics. Three resume paths share the same primitive in ipc.ts:

  1. triggerResumeRefresh after a hidden→visible flip ≥ 2s. Sends a best-effort close(4001, 'resume-refresh') for server-side telemetry — the actual reconnect does not wait for the close handler to fire (iOS Safari can take 5–10s to deliver close on a dead TCP connection). After the best-effort close, the orphan socket reference is aborted and a new one is constructed synchronously.
  2. Quick-flip visibility resume (< 2s hidden) when the socket is not OPEN. If the socket is CONNECTING (a zombie handshake that started before the OS suspended the page and never completed), CLOSING, CLOSED, or null, the resume goes through forceImmediateReconnect. Calling plain connectWs() here would short-circuit on readyState === CONNECTING and leave us stuck with the dead zombie until its OS-level handshake timeout (10–30s on iOS Safari) — that's the bug that produced the occasional ~20s tail.
  3. pageshow from bfcache. Same path as visibility resume — bfcache restores can leave a dead socket in any readyState.

In every path the helper clears any pending reconnect timer, resets the attempt counter, starts the deliberate-reconnect window (the 1.5 s chip delay and the request hold above), closes the orphan socket (best-effort try/catch), rejects in-flight invoke() promises so callers retry against the new socket, stops the heartbeat, and calls connectWs() synchronously.

Orphan guards on the WebSocket listeners. After connectWs() constructs a socket, every listener (open / message / close / error) closure-captures it as newSocket and short-circuits with if (newSocket !== ws) return at the top of its body. This is the safety net for the synchronous-replace pattern: when forceImmediateReconnect aborts an in-flight handshake and swaps in a new ws, a late-firing event from the orphan can no longer double-schedule reconnect work, double-fire markConnected, or double-drain the command queue.

Self-recovery under load (server-side watchdog)

The web-access server runs inside the main Electron process, so under an extreme local load storm (the machine pinned at ~90%+ CPU by parallel builds + many live sessions) it can stop completing new mobile connections, emit no error, and recover only on a full app restart — a silent outage to the person on the phone (incident 2026-06-17: ~69 min of zero connections, "mobile isn't accessible. wth?"). A main-process watchdog (web-access-watchdog.ts) closes that gap. The exact internal wedge couldn't be pinned to one line (rate-limiter / origin-guard / keepalive theories were each falsified against the live logs), so the fix is deliberately mechanism-agnostic resilience + visibility, not a one-line bug fix:

  • Active self-probe that reaches main. Every 60 s (first probe after a 90 s boot grace) it dials the server's OWN loopback http://127.0.0.1:<port>/login through the shared fetchWithTimeout. Deliberately NOT /health/live: with the off-loop worker transport (the default) the worker answers that path itself and never forwards it to main, so it could only ever prove the worker socket accepted while a main-side wedge — the very outage this exists for — read 200 forever. /login is forwarded to main and served pre-auth there, so the probe exercises the same bridge every real phone request uses. Literal 127.0.0.1, never localhost (the server may bind IPv4-only and localhost can resolve to ::1 and miss it). It probes only when webAccessEnabled + a token are set — never on "zero clients connected", which is ambiguous (nobody may currently be using mobile).
  • Restart just the listener. After 3 consecutive probe failures it runs stopWebAccess() then startWebAccess(...) — never an app restart — with a 5-minute cooldown so it can't flap, and a re-check of the shutdown flag immediately before the restart so it never re-binds a server the app is tearing down.
  • Tells you — including when the restart did not work. One dismissible inbox alert per episode (deduped by a stable key via the shared createAlert primitive, so a flap never spams). The restart's RESULT is probed rather than assumed (startWebAccess returning means the restart resolved, not that mobile access serves — the worker binds asynchronously), so a restart that left the listener just as unresponsive raises the didn't help message instead of a false "I fixed it". Every probe failure + restart is logged under [WebAccess][watchdog] — the 2026-06-17 incident left no trail; this guarantees the next one does.
  • Default-on, with an AMC_DISABLE_WEBACCESS_WATCHDOG=1 kill switch; it appears in the Resources diagnostics panel. Honest limit: it shares the same main event loop, so it can't cure an absolute CPU peak in real time — it recovers the persistent wedge (server stayed dead after load eased) and makes it visible + logged. Invariants are locked in web-access-watchdog-contract.md.

Freeze-aware transport under load (don't mistake a stall for a dead connection)

Under that same storm the main event loop can freeze for many seconds at a time (11–64 s observed, blocked on saturated disk I/O). Because the keepalive ping, the watchdog probe, and the reconnect chip all run on that loop, a freeze used to look like a dead connection and tear it down — the recurring "mobile disconnects under load" report. A shared mainLoopStalledWithin() signal (off the main-process stall detector) now makes all three freeze-aware:

  • Server keepalive ping — during a known freeze it re-pings instead of terminating the client (the pong is buffered-but-unprocessed, not dead). A genuinely dead socket is still reaped on the first healthy tick / by the OS TCP timeout.
  • Watchdog — a probe failure that coincides with a freeze does not count toward the 3-strike restart, so a load storm never triggers a needless restart that drops every device (a real wedge, with the loop responsive, still restarts).
  • Reconnecting… strip — shown only once an outage is 2 seconds old, or 1.5 seconds into a resume (above), so a sub-second blip never flashes it.

Kill switch AMC_DISABLE_WS_STALL_GUARD=1. Invariants: mobile-ws-stall-guard-contract.md.

Account sign-in on mobile (Global Auth gate)

Separate from the web-access token above, Omniscio can also show a Firebase-backed "Sign in to continue" account wall before the app loads (the Global Auth gate — default-staged, off unless an install turns it on). On a phone this needs care, because the gate's Google/GitHub sign-in is a desktop OAuth flow: it opens a browser on the computer running Omniscio with a desktop-side loopback callback, which a phone can't complete (the mobile WebSocket drops before the desktop flow returns — a 129 s hang in the reported incident). So on a web/mobile client the gate doesn't offer the sign-in buttons — it shows "Sign in from the desktop app — this device will sign in automatically once you do." The mobile client shares the desktop's cached identity, and the GLOBAL_AUTH_CHANGED push (forwarded via INBOX_ALLOWED_CHANNELS) flips the phone to signed-in the moment the desktop signs in, no reload. GLOBAL_AUTH_LOGIN / GLOBAL_AUTH_LINK_PROVIDER are refused over the WS bridge (BLOCKED_CHANNELS) as a backstop, so a stray tap can never silently open a desktop browser.

A second mobile-specific wrinkle the same change fixes: the renderer holds a brief neutral splash until the first auth-status check returns, instead of optimistically painting the inbox and then swapping to the gate — on a phone that swap was a visible "inbox flash → sign-in screen." Full invariants + tests: global-auth-gate-contract.md.

When the desktop CAN'T sign in either (the silent dead state — fixed 2026-08-25)

There is a third case, and until 2026-08-25 it was completely silent. If the desktop install requires sign-in but was built with no sign-in configuration, the gate goes inert — isGateActive returns false, so no sign-in wall renders and there is nothing to tap. Approving a phone for mobile access needs an account, so the phone is refused on every request while the desktop inbox stays empty and the app says nothing. The reported symptom was exactly that: Mobile Access enabled, phone fully locked out, no explanation anywhere.

The gate still goes inert (making it active would wall the app behind a sign-in screen that can never succeed), but it is no longer silent: a startup check raises ONE deduped inbox row — "Sign-in is not set up on this computer" — naming what is actually broken (approving your phone, cloud sync, sharing) and the real remedy. It clears itself once sign-in works.

Who hits it: not a customer on an official release — those builds are guarded to carry all four sign-in credentials. It is a fresh developer clone with an unseeded secrets vault (npm run secrets:pull now also warns loudly in that case) or a local npm run package:win, which deliberately ships {} so a developer's vault can't leak into a shippable app. Invariants: global-auth-gate-contract.md § NEVER-SILENT (G-NS1…G-NS6); history: signin-dead-state-postmortem.md.

Surviving ANY freeze: off-loop transport (Tier 2, default ON)

The stall-aware fix above keeps a freeze from being mistaken for a dead connection, but the listener + its keepalive still run on the main loop — so a freeze long enough still risks the phone giving up. The durable fix moves the whole web/WS listener off the main loop into a Node worker_thread with its own event loop, behind AMC_WS_OFFLOAD (env) / wsOffloadEnabled (the Settings → Remote Access → Advanced → "Freeze-proof mobile connection" toggle), default ON since 2026-08-28 — existing installs are brought onto it by a one-shot migration, and the toggle stays the off-switch. While the main loop is frozen on disk I/O, the worker keeps answering the phone's app-level ping locally — the connection stays up and streaming just pauses then resumes, instead of the phone self-killing its socket after ~20 s of no pong.

  • It's a single-port proxy. Tailscale (private serve, or public Funnel) exposes one URL → one port, so the worker OWNS that port (http + the ws server) and forwards data inward. The worker answers /health/live + ping/pong and serves static assets locally; it forwards every WS invoke (and the push-subscribe / token-touch / perf-report / device-geo writes) to main, which runs the actual IPC handlers and relays the reply — stamped with the same requestId the in-main path puts on it, so a phone-originated call is traceable end to end on either transport.
  • Every frame type works on both transports. A frame with no explicit branch in the router is silently discarded by the SHIPPED transport, so the two dispatch paths are pinned against each other: one test drives every client frame type through both and asserts the same outcome (a locally-answered ping, a forwarded invoke, a main-side write, or an explicit refusal), and it fails the build when a frame type is added in-main with no parity row. plugin-bridge and plugin-ui-pass (a phone plugin's actions and its page pass) are forwarded to main after the same per-frame sign-in re-check an invoke gets, and main applies the device-approval gate before the plugin relay — so a phone plugin's buttons work on the default transport too (Phone Simulator covers which plugins open on the phone). The second-factor kill-switch refusal also runs at ADMISSION on both connection handlers, from one worker-safe module, so a degraded QA build cannot be probed off-machine through either transport.
  • The security boundary doesn't fork. The token compare, CSWSH origin check, DNS-rebinding host-allowlist, idle-expiry, the per-IP brute-force lockout, and the blocked-channel / throttle / outbound-sanitize dispatch policy are the same code the in-main path uses (shared worker-safe modules — web-access-guards.ts + the reused web-access-ws policy), so the worker can't drift into a weaker boundary.
  • Mobile access is never lost. If the worker fails to spawn or dies unexpectedly, the transport falls back to the in-main server. The path is chosen at startup — flipping the flag needs a restart. A real-device freeze smoke is the gate before the default flips ON. (The worker's /health/live still hits the never-frozen worker for a plain orchestrator liveness check — but the watchdog's own probe deliberately does NOT use it, because it has to see main: see "Active self-probe that reaches main" above.)

Invariants: ws-offloop-contract.md. Built on the worker_thread host pattern (lifecycle mirrors the v2 plugin worker), NOT a utilityProcess — the freezes are I/O-wait, not a main crash, so an own-loop thread is sufficient and lower-risk.

Visibility-resume + active-session preservation

When the page hides for more than 2 seconds (e.g. the mobile file picker takes over the screen, the user switches tabs, or the OS backgrounds the browser), Omniscio's resume handler (ipc.ts triggerResumeRefresh) decides from the socket's own proof of life: a socket that delivered a frame in the last 10 seconds is kept and pinged (nothing is re-read — see Reconnect speed above), and a stale or dead one is torn down and reconnected synchronously. Once a NEW WebSocket is open, the reconnect handler in App.tsx re-runs WEB_BOOTSTRAP, and useSessionStore.getState().hydrateMinimal(...) replaces the sessions array with the fresh active-only payload. There's a subtle catch: listActiveSessions() excludes statuses ready and terminating (rare/ephemeral on desktop, where Phase 2 backfill picks them up). Without protection, a brand-new no-prompt session — which transitions starting → ready immediately and is the very session the user is currently attaching a file to — would vanish from state on reconnect, orphaning activeSessionId and rendering "No session selected". To prevent that, hydrateMinimal upserts the active session: if activeSessionId is set and the incoming bootstrap doesn't include it, the existing in-memory session row is appended. This keeps the bootstrap payload tight while making mobile attach-to-new-session reliable. See postmortem.

What settings the phone receives (and what it may write back)

A phone never gets the desktop's whole settings object. Two things come off it on the way out, at every remote seam — the settings:changed push on both transports, and the reply to any channel that answers with the whole object (settings:get, settings:update, and the two per-key patches settings:patch-array-item / settings:patch-map-item) — and neither is ever removed from storage:

  • the existing remote strip: provider keys, tokens, and the saved quick-email / quick-SMS recipient lists;
  • overseerSessionAssignments, cut to sessions that are not archived. That map was 79% of a ~1.03 MB payload and 99% of it belonged to archived sessions no phone surface shows.

Because the phone holds a reduced view, overseerSessionAssignments is also read-only to a remote device: a settings save from the phone has that key dropped before the handler runs, so the stored map can never be replaced by the subset. Desktop and the CLI still read and write the full map.

If the session lookup fails (a boot-window push, teardown) the phone gets the secret-stripped but untrimmed payload and one warning is logged — a push is never dropped on that path.

Reading the phone's inbound traffic (chB=)

The hourly log line the phone writes to main.log (and that the app also keeps in its own small logs/phone-telemetry.log, so it survives main.log rotating) names where its inbound bytes came from:

[ws-telemetry] v=1 dev=… hour=… ev=… … inB=2345678 chB=settings:get:910000,session:output:640000,…,other:12000 top=…

chB= lists the top channels by bytes, biggest first, counting push events and invoke replies alike. Every channel's total is kept for the hour and the ranking happens when the line is written, so the 12 names are the biggest by bytes, however late or however gradually a channel earned them — the tail is folded, bytes included, into other, so the totals still add up. It sits before top= so truncation never cuts it. inB= is still the total. Use this when "the phone is slow" needs a culprit rather than an estimate.

bootB= is the payload BEFORE compression, so never compare it with a compressed figure. The socket path negotiates permessage-deflate and the HTTP path is brotli; a ~2.6 MB bootB and a ~640 KB /bootstrap body can be the same payload. When you need the composition rather than the total, the desktop logs [mobile-perf] bootstrap-bytes once per bootstrap: the exact serialized size, whether the session slice was full or a delta, the row count, and the eight largest fields by bytes.

A slow /bootstrap is left alone; only a stalled one is abandoned. Both paths carry the same payload, so the socket is a fallback. Its 1,200 ms budget now measures a stall — the timer restarts on every body chunk — so a slow-but-flowing HTTP download finishes over brotli instead of being aborted midway and re-requested whole over the socket. The very first byte is allowed 2,500 ms, because the desktop builds the payload before sending anything and a slow link can outlast the shorter window with the fast path perfectly healthy. A dead fast path (an error, a non-JSON answer, or a body that produces nothing) still falls back at once.

Reading the phone's speed (frz200=, visAny=, inVisB=, coldB=, heapPk=, loads=, cap=)

The same hourly line now carries what the phone measured about its own speed, so the crew scoreboard reads a number instead of someone's hand reading. visAny= is visible wall time, and it is the denominator every rate uses — frz200= is the count of ≥ 200 ms UI stalls inside it, and inVisB= the inbound payload received inside it. That pairing is the whole point: visMs= (the older field) counts time the page was visible and connected, so dividing by it would inflate the freeze rate exactly in the hour the socket was the problem, and the row's original inB= counts frames received while the page was hidden.

coldB= is the first bootstrap reply of the document — the cold hydration. It is deliberately not bootB=: every reconnect re-hydrates with a small WEB_BOOTSTRAP delta, so bootB / loads reads best in exactly the hours the connection was worst. loads= is one per document.

cap= says which probes the browser could supply (heap, or none). frz200=0 on a row whose cap is present is a real, good reading; a missing probe is unmeasured and the readings refuse rather than print a zero. heapPk= is a sampled high-water, not a peak — the browser reports performance.memory in rounded values from a slowly refreshed cache, and the API does not exist at all in Safari, so the heap reading is deliberately absent on iOS rather than guessed.

The instrument is a 100 ms drift sampler that notices the main thread did not run; it is not the Long Tasks API, which Safari lacks, and it is not the renderer-diagnostics observer, which is behind a toggle that ships off.

Why the socket dropped, not just that it did

drop= says how many drops the hour held; it never said why, and main.log — which did — rotates away in about ninety minutes. So the same line now carries a per-cause breakdown of exactly the drops it counts:

[ws-telemetry] v=1 dev=… hour=… drop=2/0 dropWhy=close-noframe-1006-visible:2 …

Every bucket is <cause>-visible or <cause>-hidden, and the buckets always add up to drop=: an hour persisted by an older bundle has drops and no causes, so its remainder prints as unknown-v / unknown-h rather than vanishing. The vocabulary is only what a PHONE can actually observe:

bucket what it means
pong-timeout the phone's own heartbeat got no pong before its deadline
dead-connection the phone's own heartbeat tick found the socket unresponsive
close-noframe-1006 (-1005) the socket ended with no close frame at all — a reset, a dead radio, or the server killing it
close-frame-<code> a close frame arrived; its code is named as it came
server-auth-close that frame said 4001 — the web-access token was rotated, expired or rejected
server-device-blocked that frame said 4003 — the device was revoked
+pend appended to any bucket when invokes were still in flight at the close
unknown nothing observable; the phone says so rather than guessing

A keepalive kill is never server-pong-timeout on this line, and that is deliberate. The server that owns remote phone sockets ends a silent phone with a hard reset, so the phone receives no close frame and sees only 1006 — naming the server from the phone would be a guess. That half lives on the desktop, in ONE durable row per phone close appended to the existing ~/.amc telemetry tape (src/main/services/web/funnel-hop-ledger.ts, kind: 'ws-close'): the server's own verdict (server-pong-timeout, server-ping-unanswered, server-auth-close, server-device-blocked, server-shutdown, server-push-send-failed, socket-error, client), the code the phone saw, the outbox bytes queued at that moment, the age of the ping that never came back and how long the socket had been open. Read both with npm run scripts:run -- tunnel:blackouts, whose phone-closes section prints them newest first; the tape is count-bounded and holds weeks of healthy history, far past the log's ninety minutes.

Read it as a needs-reading first, not a push problem: on 2026-10-25 the phone's hour read other:653810246, alert:inbox-list:40942579, session:get-history:19105353 while the desktop's own push counter ([tick] … push= in heartbeat.log) showed ~0.016 MB/s and settings:changed was writing ~23 times an hour. Neither a push nor the settings object can produce that; ~90% of the phone's inbound was its own invoke replies, which is the shape a repeated full read fan-out makes.

The phone only downloads screens you open

A phone runs the same renderer bundle as the desktop, so anything the desktop loads at startup used to be loaded on the phone too — whether or not that screen had ever been opened. On build 1e2ae141 that was most of the phone's hourly traffic: the share list (2.74 MB), the recipe config list (0.45 MB) and the whole quick-reply library (~0.84 MB) all arrived with their screens closed, and a phone visible for under two minutes still pulled 24–29 MB in the hour.

Each of those now waits for its own screen:

  • Shares loads when the Shares screen opens — the list, your @mentions and the unread total together. A share link you tap without opening Shares first fetches the list at that moment, so it still resolves as your own share.
  • Quick replies load when you open the picker, so the first open of a cold page shows its brief spinner. Desktop still warms them at startup; a phone does not.
  • Recipes are the exception and still load at startup on every client. A running recipe is an inbox row and paints the "Running Recipes" section, so the phone cannot draw those without the config list.

The desktop is unchanged in every case.

A reconnect re-seeds nothing you are not looking at

A push that lands while the socket is down is never replayed, so a reconnect re-seeds the stores that otherwise stay live off push alone: every inbox source, the automation / cron / CLI-approval / alert / intake stores behind the inbox rows, the helpdesk badge, and the AI-credential status. That is about 25 requests, and on 2026-10-30 they were the reason the owner's phone "waits a lot": a reconnect fired all of them at a machine whose database worker was already 100–215 jobs deep, his own tap queued behind the burst, the socket then delivered nothing for ten seconds, and dead-detection dropped his requests and forced a reconnect that fired the burst again.

The re-seed now has to be covering a real gap, and it waits for a screen that can show it:

  • A dead-detection blink re-seeds nothing. A blink is roughly 21 seconds plus the handshake and it covers no gap, so nothing is stale and nothing is re-read.
  • A live-socket resync always re-seeds, whatever the gap says — nothing is being conserved there.
  • Off an outage the re-seed runs at reconnect only when the inbox list is on screen or the socket had delivered nothing for 60 seconds (RECONNECT_RESYNC_MIN_OUTAGE_MS).
  • Off a long gap with a session full-screen on a phone, the reloads are queued instead and run the moment any list surface comes back — so a burst never lands on someone reading a session. The queue holds one entry per store however many reconnects arrive, survives the app being backgrounded and resumed, and drains all of its stores on a single show, so no store has to remember to add itself.

The desktop is unaffected: the gate only ever defers where a phone is showing a session.

The session re-sync keeps its baseline

The 30 s active-list re-sync is a hash delta: the phone sends the hash of every row it holds and gets back only what changed. It also used to throw that baseline away every ten minutes and ask for the whole list again — about 2 MB per wake, which on a phone that is awake for a few ticks an hour was most of the session:list-delta traffic. That net is gone; the delta now rides until a reply cannot be resolved (a row named with no row to match), which still takes one full list and logs it.

The first tick after a page load is a delta too (2026-10-30). It was not: the startup payload shipped trimmed rows while the re-sync shipped the wide DB row and hashed that, so the hashes the bootstrap handed the phone described bytes the re-sync never sent. Every one missed, and the phone re-downloaded the whole active list a second after painting it — measured on the owner's phone at 1,543 sessions, a 5,324,499-byte cold reply with changed=1543 held=0, right after a 620,819-byte bootstrap. That is the double download.

There is now one projection and one hash, buildWebSessionListRows + shipSparseWebSessionRow (src/main/services/web/web-session-list-row.ts), and both channels hash exactly the row they ship. So the bootstrap's per-row hashes are a real baseline: seedSessionListBaselineFromBootstrap hands them to the re-sync store after the hydrate, and the first tick carries only the rows the bootstrap deliberately withheld — the paused ones "active sessions first" deferred. On the same install that is 1,133 paused rows: 913,116 bytes, an 83% cut, with the rows themselves now the lean ones the phone was already rendering.

Two consequences worth knowing:

  • A row the re-sync DELIVERS is the trimmed row, so the store hydrates it with the same per-row defaults a bootstrap row gets (hydrateWebSessionListRow). A 30 s tick therefore leaves the phone holding exactly what a cold load leaves it holding — no wider, no narrower.
  • The bootstrap's focus session is the one row whose seed is patched in after the byte budget (applyFocusSeed), so its hash cannot match the re-sync's and it re-ships once per page load. That is bounded, it is ~700 bytes, and it is why the re-sync does not pay a second DB read on a 30 s path to agree about one row.

A trimmed message preview is outside the row hash (2026-11-01). A row's hash stands for the row as shipped, with one exception: when the byte budget trimmed the row's last-message seed to a preview (lastAgentMessageSeedTruncated: true), the preview text is left out of the hash (hashWebSessionRow in src/main/services/session/session-list-delta.ts). The preview length is an equal share of a 96 KB budget across every preview row, so it moves whenever any waiting session arrives or leaves — and with it the hash of every other preview row. Measured on the owner's phone on 2026-10-31: 103 of 125 warm ticks re-shipped 250–499 rows (~400 KB each, ~0.65 MB per visible minute), while ticks with no arrival re-shipped 1–42. With the text out of the hash, a tick re-ships only rows that really changed. A row whose message changes still re-ships, because lastAgentMessageAt and the flag stay in the hash. A phone may keep a preview a few bytes longer or shorter than a fresh bootstrap would give it; a trimmed seed is never painted as the final view, so the difference never shows.

Each reply now reports itself to the desktop log. The phone kept this as a console.info, and a phone has no console relay, so the hourly session:list-delta bytes could not be attributed to a cold page load or a warm re-sync. Every reply also ships one tagged ClientLog beacon — [ClientLog:session-delta] with rows, changed, baseline (cold / warm), held, visible and bytes — through the same authenticated /client-log path the other phone breadcrumbs use. A cold reply always ships, because a cold reply is the shape that costs a whole active list; a warm one ships at most once per 10 s, deliberately well under the 30 s re-sync cadence so timer jitter can never suppress a re-sync's own line while a burst of them is still clamped. The route's per-IP bucket (10/min, burst 30) stays the hard cap. The local console line stays exactly as it was — it costs nothing and DevTools still shows it. Desktop never takes this path — it asks for the plain session:list and returns before the delta store is reached.

A session's message queue reaches only the phone that has it open

session:queued-messages-changed carries a session's whole pending queue on every enqueue, edit, reorder and drain. Only the open chat's queue list reads it, so a web/mobile client receives it only while subscribed to that session (scope session with the matching sessionId); an inbox-scope client gets none (OPEN_SESSION_ONLY_CHANNELS in src/main/services/web/web-access-push-filter.ts). Measured on the owner's phone: up to 5.5 MB in one hour for queues nobody had open. Because a closed session's queue stops updating, the web queue list forgets that session's cached queue when it unmounts (forgetQueuedMessages), and its pull on the next open fills it again, so a return never paints a stale queue. Scope all and the desktop app are unchanged.

What never crosses to the phone

Two channels are cut at the device boundary, on purpose:

  • debug:log is never forwarded to a web/mobile client at any scope, including a client that asked for all. No remote surface draws the desktop debug log, the frame cannot be shed under backpressure, and its payload is raw main-process log text (paths, session ids). The desktop renderer gets it over its own IPC. The panel on a phone still replays the ring buffer when it opens (logs:get-buffer); it simply does not live-tail.
  • The kept over cap warning only names a channel that client would receive. Both relay paths evaluate the subscription scope filter before the per-client backlog decision, so a frame the phone can never be sent is never counted or logged as if it were filling the phone's queue. Before that, the line named channels the filter dropped one line later — which is how debug:log came to be read as the flood.

Dividing is what turns a byte count into a cause. Take the hour's bytes for one channel and divide by that reply's real size: a quotient near the call count means the channel is busy, and a quotient of a handful means each reply is huge. Both were true on 2026-10-25 — alert:inbox-list sent 1,340,663 bytes about 30 times an hour, and session:get-history was allowed a 5 MB reply against a 4 MB outbound queue — and both are now bounded:

  • A reply to a paired device is budgeted to half its outbound queue (REMOTE_INVOKE_REPLY_MAX_BYTES). The history budget IS that number and it now reaches the full read as well as the lite one, so one open cannot fill the queue its own pong is waiting behind.
  • An alert push refreshes ONE card. The phone reads that row through alert:get instead of re-reading the list, and the list itself arrives as a summary row whose body is a preview — the reading pane hydrates the full row when it opens.

A session you cannot open never appears — or answers — on the phone

The phone bridge is treated as an untrusted transport, so the question "what can a leaked or shared pairing token read?" is answered by one rule: a session the phone may not open may not be listed, searched or served either.

  • The rule itself. isHiddenFromRemoteRead in src/shared/session-live.ts reads the four fields the by-id gate has always read — status, silent, parked_at, shared_grant. It hides a silent recipe session, a parked (deliberately held) session, a share the owner has closed, and a session that is gone. A session that is mid-run (running / starting) is never hidden, whoever asks.
  • Every list-shaped read applies it. SESSION_LIST and SESSION_LIST_DELTA, SESSION_LIST_ARCHIVED and SESSION_LIST_ARCHIVED_BY_SOURCE, SEARCH_ALL (full-text, title and meaning legs alike), the WEB_BOOTSTRAP payload and the HTTP /bootstrap route. The single gate is src/main/services/session/session-visible-to-transport.ts; search passes session ids and gets back the hidden subset in one batched read, so a page of hits costs one query rather than one per row.
  • An attachment is not an existence oracle. GET /attachment/:sessionId/:filename is served only by the web-access bridge, so its caller is always remote. A session the caller may not read answers exactly as a missing file — 404 Not Found, same status, same body, same headers — and the visibility check runs before the file is touched. The path itself still goes through the canonical getAttachmentPath → isWithinRoot containment, and a refusal there is a flat 400, never a thrown error escaping the request listener.
  • The desktop is untouched. The install owner's own window sees every row it saw before, from the same SQL: the filter is a no-op whenever the caller is not the web-remote transport. Only the paired phone's view narrows.
  • Registered, not remembered. tests/unit/lint/22/session-read-visibility-surfaces.test.ts fails the build if any of those reads stops naming its gate, so a new list-shaped read has to register in the same PR that adds it. It also pins the HTTP /bootstrap route's remoteTransport: true, because a plain HTTP request seeds no inbound request context and would otherwise read as local.

Known residual (deliberate, no rows and no ids): the archived SESSION_COUNT_ARCHIVED channel and the projectPausedCounts / projectEndedInterruptedCounts badges in the bootstrap are not narrowed, so a count can read higher than the rows the phone can see. They reveal a number, never a session.

The first tap downloads nothing the screen isn't using

The UI anchor registry — the control-metadata table behind UI Usage tracking — is a 3.6 MB chunk (≈840 KB gzipped, ≈650 KB brotli) and it used to arrive on a phone's first tap. The app-wide click listener had to know which anchors are catalogued before it could count a click, and that answer only lived in the registry, which is lazily imported everywhere else. So the very first click pulled the whole table, and did not even count the tap.

The listener now records a click from the anchor's shape alone — a cheap, registry-free test — and the catalogue decision happens in the desktop's main process when the batch arrives, where the same table already ships as a runtime asset. A tap transfers 0 bytes of it. The registry now loads only for a screen that really needs it: Settings → Diagnostics → UI Usage, the mod-studio anchor picker, and the onboarding studio editor.

Settings keys (reference)

Key Default Notes
webAccessEnabled false Master switch for the HTTP+WebSocket server
webAccessPort 9876 Range 1024–65535; shared by the local URL and the Tailscale address
webAccessToken auto-UUID Token-gates every request
tunnelEnabled false Auto-start Tailscale access when web access starts; persists across app restarts
tunnelPublicAccess false Public (Funnel) instead of private (serve); an install already using the public tunnel is seeded true once

These five keys live in config.json; only webAccessPort is written via the standard settings IPC. The other four are mutated through dedicated IPC handlers (WEB_ACCESS_START / WEB_ACCESS_STOP, TUNNEL_START / TUNNEL_STOP, and TUNNEL_SET_PUBLIC_ACCESS for the public switch, which is refused over the phone bridge and has no CLI route). Rotation has its own channel, WEB_ACCESS_ROTATE_TOKEN (web-access:rotate-token): the main process's rotateWebAccessToken() persists the new token, re-stamps the lifecycle timestamps, bounces a RUNNING transport onto it, and pushes SETTINGS_CHANGED. It is desktop-only — refused over the phone bridge and classified security-boundary-human-only for cli-parity, because it MINTS a credential. webAccessToken itself is an InternalOnlyKey and must never be written through SETTINGS_UPDATE: Zod strips it, the all-stripped guard raises settings.saveError.unknownKey, and the user sees a false "the app didn't recognize it" toast (that was the Regenerate double-toast bug, fixed 2026-10-07).

Last verified 2026-10-27