relay-companion 0.1.35 → 0.1.37

package/bin/relay.js

@@ -104,8 +104,13 @@ function statusAreaReopenText() {
 
 /** Register the Relay tools into Claude Code + Codex and start the receive daemon. */
 async function applyInstall({ requireLiveTools = false, requiredHosts = requiredLiveHosts() } = {}) {
-  const { installed, missing, daemon, pill, activations = [] } = await runSetupInstall();
+  const { installed, missing, daemon, pill, activations = [], binStable = true } = await runSetupInstall();
   if (installed.length) console.log(`Added Relay to ${installed.join(" and ")} on this machine.`);
+  if (!binStable) {
+    console.log(
+      "Heads up: Relay is running from a temporary npx cache and couldn't global-install. It may stop working when that cache is cleaned — run `npm install -g relay-companion` to make it permanent.",
+    );
+  }
   for (const m of missing) {
     if (!/registration failed/.test(m)) console.log(`${m} was not found here, so it was skipped.`);
     else console.log(`Could not register ${m}.`);

package/overlay/host-select.cjs

@@ -22,28 +22,31 @@ function isRelayBundle(bundle) {
   return clean.includes("relay") || clean.includes("electron");
 }
 
-// Cold-start choice when NEITHER agent is running: pick by what's installed.
-// macOS preserves the original preference (Codex, then Claude). Windows is
-// Claude-only for now: the Codex materializer still depends on macOS Codex
-// Desktop paths/app-server behavior, while Claude's claude:// resume handler is
-// registered by Claude Desktop on Windows.
+// Cold-start choice when NEITHER agent is foregrounded/running: pick by what's
+// installed. When BOTH are available and neither is foregrounded, prefer Claude
+// (per the product rule: "if I have claude and codex and neither is foregrounded,
+// foreground claude"). Windows is Claude-only for now: the Codex materializer still
+// depends on macOS Codex Desktop paths/app-server behavior, while Claude's claude://
+// resume handler is registered by Claude Desktop on Windows.
 function defaultClickHost({ codexInstalled = false, claudeInstalled = false, platform = process.platform } = {}) {
   if (platform === "win32") return "claude";
-  if (codexInstalled) return "codex";
   if (claudeInstalled) return "claude";
-  return "codex";
+  if (codexInstalled) return "codex";
+  return "claude";
 }
 
 // Decide which host a pill click should open into. Precedence, strongest signal first:
-//   1. The frontmost app IS a host — the user is literally looking at it.
+//   1. The frontmost app IS a host — the user is literally looking at it, so open there.
+//      (Codex frontmost -> Codex; Claude frontmost -> Claude.)
 //   2. The click momentarily activated the accessory overlay (or no frontmost app could
-//      be read) AND a host was foregrounded moments ago — use that captured host.
+//      be read) AND a host was foregrounded moments ago — use that just-foregrounded host.
 //   3. Exactly one host PROCESS is running — route to it. This is the off-Space fix:
 //      `ps` sees a host on any Space, so a running-but-not-frontmost Claude wins over a
-//      closed Codex instead of cold-starting Codex.
-//   4. Both hosts are running and none is frontmost — fall back to the most-recently
-//      foregrounded host if we ever saw one.
-//   5. Nothing better — installed-preference default (true cold start).
+//      closed Codex instead of cold-starting Codex. (Only Codex up -> Codex; only Claude
+//      up -> Claude.)
+//   4. Both hosts are running but NEITHER is foregrounded — prefer Claude (product rule).
+//   5. Nothing running — installed-preference default (true cold start; prefers Claude
+//      when both are installed).
 function chooseClickHost({
   frontHost = null,
   bundle = null,
@@ -67,7 +70,8 @@ function chooseClickHost({
 
   if (claudeRunning && !effectiveCodexRunning) return "claude";
   if (effectiveCodexRunning && !claudeRunning) return "codex";
-  if (claudeRunning && effectiveCodexRunning && lastHost) return lastHost;
+  // Both running, neither foregrounded (and none foregrounded moments ago): prefer Claude.
+  if (claudeRunning && effectiveCodexRunning) return "claude";
 
   return defaultClickHost({ codexInstalled: effectiveCodexInstalled, claudeInstalled, platform });
 }

package/overlay/inbox.html

@@ -758,6 +758,15 @@
   }
   // ✕ — the card leaves gracefully, then the main process hides the window and keeps
   // it hidden (persisted) until the status-area Relay mark is clicked.
+  // The exit is cancellable: if the user reopens (tray click / new ghost banner) while
+  // the bye animation is in flight, the pending timeout must NOT fire — it would
+  // dismiss the pill they just reopened and park the card offstage under a visible
+  // window (a click that "does nothing").
+  let byeTimer = null;
+  function cancelBye() {
+    if (byeTimer) { clearTimeout(byeTimer); byeTimer = null; }
+    cardEl.classList.remove("bye");
+  }
   function dismissOverlay() {
     if (cardEl.classList.contains("bye")) return;
     if (ghostTimer) { clearTimeout(ghostTimer); ghostTimer = null; }
@@ -765,7 +774,8 @@
     const wasGhost = ghost;
     cardEl.classList.add("bye");
     setInteractive(false);
-    setTimeout(() => {
+    byeTimer = setTimeout(() => {
+      byeTimer = null;
       if (wasGhost) window.relay.notifDone(); // already dismissed; just re-hide the window
       else window.relay.dismiss();
       resetOffstage();
@@ -776,6 +786,7 @@
   // when done it fades away instead of folding back into anything.
   function ghostArrival(row) {
     if (ghostTimer) { clearTimeout(ghostTimer); ghostTimer = null; }
+    cancelBye(); // a banner arriving mid-exit must not be torn down by the old exit
     clearPeek();
     collapsed = false;
     cardEl.classList.remove("collapsed", "offstage", "bye");
@@ -800,6 +811,7 @@
   // Status-area Relay mark clicked: the card comes back FULLY OPEN (never the pill).
   function trayOpen() {
     const wasOffstage = cardEl.classList.contains("offstage") || cardEl.classList.contains("bye");
+    cancelBye(); // a reopen mid-exit must survive: the pending dismiss would hide us again
     if (ghostTimer) { clearTimeout(ghostTimer); ghostTimer = null; }
     ghost = false;
     clearPeek();
@@ -843,8 +855,14 @@
     scrollEl.scrollTop = 0;
     springTo(PEEK.w, peekHeight());
     playTink();
-    peekTimer = setTimeout(() => {
-      peekTimer = null; peeking = false;
+    peekTimer = setTimeout(function tick() {
+      peekTimer = null;
+      // Never fold the banner away while the pointer is on it or a reply is being
+      // typed — that rug-pulls the user mid-interaction and can trap keyboard focus
+      // in a now-invisible textarea. Check again shortly instead (macOS banners
+      // hold while hovered too). Mirrors the ghost-notification guard.
+      if (interactive || quickReplyIsActive()) { peekTimer = setTimeout(tick, 4000); return; }
+      peeking = false;
       cardEl.classList.remove("peek");
       collapsed = true; cardEl.classList.add("collapsed");
       springTo(PILL.w, PILL.h);
@@ -2126,6 +2144,15 @@
     onPayload(p);
     console.log("[overlay] booted ok, relays=" + (p && p.relays ? p.relays.length : 0) + " sent=" + (p && p.sent ? p.sent.length : 0));
   }).catch((e) => console.log("[overlay] refresh failed", e && e.message ? e.message : e));
+
+  // Keep the relative "3m / 2h" times honest now that identical payloads are no longer
+  // re-pushed. Skip while the pointer is on the card (a rebuild under the pointer wipes
+  // hover state) and while dragging; the next tick catches up.
+  setInterval(() => {
+    if (dragging || interactive) return;
+    if (activeView === "relays") renderRelays();
+    else if (activeView === "sent") renderSent();
+  }, 60000);
 </script>
 </body>
 </html>

package/overlay/main.cjs

@@ -30,6 +30,8 @@ const { execFile, execFileSync, spawn, pathToFileURL } = (() => {
   return { execFile: cp.execFile, execFileSync: cp.execFileSync, spawn: cp.spawn, pathToFileURL: url.pathToFileURL };
 })();
 const { hostFromBundle, chooseClickHost } = require("./host-select.cjs");
+const { overlayWanted, createHostRunningTracker, shouldIgnoreDismiss } = require("./visibility.cjs");
+const { withJsonLock } = require("../src/state-lock.cjs");
 const {
   reinforceSpacePresence,
   resetWindowZoom,
@@ -113,6 +115,15 @@ async function relayClient() {
 }
 
 app.setName("Relay");
+// Test seam: an isolated userData dir gives the e2e harness its own single-instance
+// lock, so a sandboxed overlay can run beside the real pill without fighting it.
+if (process.env.RELAY_OVERLAY_USER_DATA) {
+  try {
+    app.setPath("userData", process.env.RELAY_OVERLAY_USER_DATA);
+  } catch (error) {
+    console.error("[overlay] userData override failed:", error && error.message);
+  }
+}
 const gotSingleInstanceLock = app.requestSingleInstanceLock();
 
 // ---- config / account ----------------------------------------------------
@@ -298,14 +309,19 @@ function ensureTasksLoaded() {
   return tasksLoadedOnce;
 }
 
-// ---- contacts (live) -----------------------------------------------------
+// ---- contacts (cached; refreshed on a slow interval + on demand) ----------
+// Contacts must NEVER be fetched per state push: a slow or failing network would
+// stall every inbox paint and blank the list (observed live: "listContacts failed:
+// fetch failed" every 2.5s while offline). Keep the last good list; refresh lazily.
 
-async function readContacts() {
+let contactsCache = [];
+let contactsLoadedOnce = null;
+async function refreshContacts() {
   try {
     const client = await relayClient();
     const res = await client.listContacts();
     const contacts = Array.isArray(res && res.contacts) ? res.contacts : [];
-    return contacts
+    contactsCache = contacts
       .map((c) => {
         const emails = Array.isArray(c.emails) ? c.emails.filter(Boolean) : c.email ? [c.email] : [];
         return {
@@ -319,9 +335,18 @@ async function readContacts() {
       })
       .sort((a, b) => String(a.name).localeCompare(String(b.name)));
   } catch (error) {
+    // Keep the last good cache; a transient network failure must not blank the UI.
     console.error("[overlay] listContacts failed:", error && error.message);
-    return [];
   }
+  return contactsCache;
+}
+function ensureContactsLoaded() {
+  if (!contactsLoadedOnce) contactsLoadedOnce = refreshContacts().catch(() => contactsCache);
+  return contactsLoadedOnce;
+}
+async function readContacts() {
+  await refreshContacts();
+  return contactsCache;
 }
 
 async function saveContact(input) {
@@ -350,26 +375,41 @@ async function deleteContactFromBook(input) {
 
 // ---- payload assembly + push to renderer ---------------------------------
 
-async function buildPayload() {
-  await ensureSentLoaded();
-  const [relays, contacts] = [readRelays(), await readContacts()];
+// buildPayload is synchronous over CACHES so the first paint never waits on the
+// network. Relays come straight from local state.json (instant, works offline); sent
+// + contacts are served from cache and their first background load triggers its own
+// pushInbox when it lands. This is what makes the pill appear immediately even on a
+// black-holed network (the client fetch timeout is 15s — far too long to block paint).
+function buildPayload() {
+  // Kick the first loads without awaiting; each calls pushInbox(false) on completion.
+  if (!sentLoadedOnce) ensureSentLoaded().then(() => pushInbox(false)).catch(() => {});
+  if (!contactsLoadedOnce) ensureContactsLoaded().then(() => pushInbox(false)).catch(() => {});
   return {
     account: account(),
     ui: {
       canDismiss: trayAvailable,
       reopenSurface: reopenSurfaceName(),
     },
-    relays,
+    relays: readRelays(),
     sent: sentCache,
     tasks: [],
-    contacts,
+    contacts: contactsCache,
   };
 }
 
 let knownIds = null; // null until first load, so we never "notify" for rows already present
-async function pushInbox(force) {
+// Pushes are serialized: overlapping timers (fs.watch + safety poll + sent refresh)
+// must not interleave sends, or the renderer can paint an older payload last.
+let pushChain = Promise.resolve();
+function pushInbox(force) {
+  pushChain = pushChain.then(() => pushInboxNow(force)).catch((error) => {
+    console.error("[overlay] pushInbox failed:", error && error.message);
+  });
+  return pushChain;
+}
+async function pushInboxNow(force) {
   if (!win || win.isDestroyed()) return;
-  const payload = await buildPayload();
+  const payload = buildPayload();
   const rows = payload.relays;
   const notifiableRows = visibleRelayRows(rows);
   if (knownIds === null) {
@@ -393,7 +433,19 @@ async function pushInbox(force) {
     }
   }
   const sig = JSON.stringify({
-    relays: rows.map((r) => [r.id, r.relayNotificationKind, r.unread, r.title, r.senderName, r.urgency]),
+    // Include the answered-state fields: a question answered on the web / in a host
+    // session flips quickReply/humanAnswered without changing unread/title, and
+    // omitting them left a live reply box in the pill for an already-answered question.
+    relays: rows.map((r) => [
+      r.id,
+      r.relayNotificationKind,
+      r.unread,
+      r.title,
+      r.senderName,
+      r.urgency,
+      r.quickReply,
+      r.humanAnswered,
+    ]),
     sent: payload.sent.map((r) => [
       r.relayId,
       r.state,
@@ -405,31 +457,37 @@ async function pushInbox(force) {
     contacts: payload.contacts.map((c) => [c.id, c.name, c.email]),
     account: [payload.account.paired, payload.account.email],
   });
-  if (!force && sig === lastSig) {
-    if (!win || win.isDestroyed()) return;
-  }
+  // Unchanged data: skip the send entirely. Re-sending identical payloads made the
+  // renderer rebuild its DOM every few seconds (hover flicker, restarted transitions).
+  if (!force && sig === lastSig) return;
   lastSig = sig;
   if (win && !win.isDestroyed()) win.webContents.send("inbox", payload);
 }
 
 // Refresh state-derived rows only (fast path used by fs.watch + the safety poll).
 function pushInboxQuiet() {
-  pushInbox(false).catch((error) => console.error("[overlay] pushInbox failed:", error && error.message));
+  pushInbox(false);
 }
 
 // ---- mark-read (write state.json directly) -------------------------------
 
 function ackPacket(packetId) {
   if (!packetId) return;
-  const store = readStore();
-  if (!store.packets || !store.packets[packetId]) return;
-  const row = store.packets[packetId];
-  store.packets[packetId] = {
-    ...row,
-    state: "read",
-    updatedAt: new Date().toISOString(),
-  };
-  writeStateAtomic(store);
+  // Locked read-modify-write: the daemon stages rows into the same file, and an
+  // unsynchronized ack racing a stage would silently drop the new relay.
+  const row = withJsonLock(STATE_PATH, () => {
+    const store = readStore();
+    if (!store.packets || !store.packets[packetId]) return null;
+    const existing = store.packets[packetId];
+    store.packets[packetId] = {
+      ...existing,
+      state: "read",
+      updatedAt: new Date().toISOString(),
+    };
+    writeStateAtomic(store);
+    return existing;
+  });
+  if (!row) return;
   if (row.relayNotificationKind === "plain_relay") {
     relayClient()
       .then((client) => client.markRead(packetId, { idempotencyKey: idempotencyKey("read") }))
@@ -531,18 +589,20 @@ async function answerQuestion(taskId, messageId, text, packetId) {
 }
 
 function markQuestionAnswered(packetId, answerMarkdown) {
-  const store = readStore();
-  const row = store.packets && store.packets[packetId];
-  if (!row) return;
-  store.packets[packetId] = {
-    ...row,
-    state: "read",
-    quickReply: false,
-    humanAnswered: true,
-    humanAnswerMarkdown: answerMarkdown,
-    updatedAt: new Date().toISOString(),
-  };
-  writeStateAtomic(store);
+  withJsonLock(STATE_PATH, () => {
+    const store = readStore();
+    const row = store.packets && store.packets[packetId];
+    if (!row) return;
+    store.packets[packetId] = {
+      ...row,
+      state: "read",
+      quickReply: false,
+      humanAnswered: true,
+      humanAnswerMarkdown: answerMarkdown,
+      updatedAt: new Date().toISOString(),
+    };
+    writeStateAtomic(store);
+  });
 }
 
 function taskVersion(taskId) {
@@ -571,6 +631,23 @@ function rememberForegroundHost(host) {
   lastHostSeenAt = Date.now();
 }
 
+// Bring the host app to the FOREGROUND so the just-opened relay is actually visible.
+// shell.openExternal(claude://…) / the Codex bridge route the content to the host but
+// do NOT reliably raise it: the overlay is a non-activating accessory window, and a
+// host sitting on another macOS Space stays put (observed live: "it opened it in claude
+// (good) but didnt foreground claude"). `open -b <bundle>` activates the app — switching
+// to its Space and launching it if it wasn't running. `-g` is intentionally NOT passed,
+// because raising the app is exactly the point.
+const HOST_BUNDLE_ID = { claude: "com.anthropic.claudefordesktop", codex: "com.openai.codex" };
+function activateHost(host) {
+  if (process.platform !== "darwin") return; // Windows foregrounding is handled by its own open path
+  const bundle = HOST_BUNDLE_ID[host];
+  if (!bundle) return;
+  execFile("/usr/bin/open", ["-b", bundle], (error) => {
+    if (error) console.error("[overlay] activateHost failed:", host, error && error.message);
+  });
+}
+
 function appInstalled(appName) {
   const name = String(appName || "").replace(/[^A-Za-z0-9 ._-]/g, "");
   if (!name) return false;
@@ -712,7 +789,7 @@ function claudeLastFocusedAt(metaPath) {
     return 0;
   }
 }
-function openClaudeDeepLinkVerified(url, fallbackUrl, label) {
+function openClaudeDeepLinkVerified(url, fallbackUrl, label, { freshlyForged = false } = {}) {
   const fire = () =>
     shell.openExternal(url).catch((error) => console.error("[overlay] openExternal failed:", error && error.message));
   if (process.platform !== "darwin") return fire();
@@ -723,13 +800,20 @@ function openClaudeDeepLinkVerified(url, fallbackUrl, label) {
   const logOffset = claudeLogSize();
   fire();
   if (!metaPath && logOffset < 0) return; // nothing to verify against — legacy behavior
+  // On a FIRST open the companion CLI just forged the session and stamped
+  // lastFocusedAt=now — so the "focused moments ago" recency check would be vacuously
+  // true and confirm a resume that a wedged Claude actually swallowed (no nudge, no web
+  // fallback). Suppress recency ONLY on a fresh forge (signalled by the CLI). On a
+  // resume of an already-imported session the CLI does NOT stamp the timestamp, so a
+  // recent lastFocusedAt is a GENUINE Claude focus — keep trusting it, or a real resume
+  // the user was just looking at would falsely fall back to the web view.
   const confirmed = () => {
     if (metaPath) {
       const focusedAt = claudeLastFocusedAt(metaPath);
-      // Advanced past the pre-fire baseline, or focused moments ago (covers a
-      // focus write racing our baseline snapshot) — either way Claude has it.
+      // A genuine Claude focus advances the timestamp past our pre-fire baseline.
       if (focusedAt > focusBaseline) return true;
-      if (focusedAt && Date.now() - focusedAt < 15000) return true;
+      // Recency: trust it unless the CLI's own bootstrap write made it vacuously fresh.
+      if (!freshlyForged && focusedAt && Date.now() - focusedAt < 15000) return true;
     }
     return claudeLogSawResume(sessionId, logOffset);
   };
@@ -803,16 +887,22 @@ function openPacket(packetId) {
     child.on("exit", (code) => {
       let url = null;
       let skipExternalOpen = false;
+      let freshlyForged = false;
       try {
         const parsed = JSON.parse(out.trim());
         url = parsed.url || null;
         skipExternalOpen = Boolean(parsed.skipExternalOpen);
+        freshlyForged = Boolean(parsed.claudeFreshlyForged);
       } catch {}
       if (url || skipExternalOpen) {
+        // Raise the host so the relay is visible, whichever open path ran (Claude deep
+        // link, Codex bridge, or a plain url). This is the fix for "opened in the right
+        // host but didn't foreground it".
+        activateHost(host);
         if (url && !skipExternalOpen) {
           const webFallback = row && row.taskId ? taskWebUrl(row.taskId) : row && row.actionUrl ? absoluteUrl(row.actionUrl) : webBase();
           if (claudeSessionIdFromUrl(url)) {
-            openClaudeDeepLinkVerified(url, webFallback, packetId);
+            openClaudeDeepLinkVerified(url, webFallback, packetId, { freshlyForged });
           } else {
             shell.openExternal(url).catch((error) => console.error("[overlay] openExternal failed:", error && error.message));
           }
@@ -875,15 +965,18 @@ function openTaskDetail(taskId) {
     child.on("exit", (code) => {
       let url = null;
       let skipExternalOpen = false;
+      let freshlyForged = false;
       try {
         const parsed = JSON.parse(out.trim());
         url = parsed.url || null;
         skipExternalOpen = Boolean(parsed.skipExternalOpen);
+        freshlyForged = Boolean(parsed.claudeFreshlyForged);
       } catch {}
       if (url || skipExternalOpen) {
+        activateHost(host); // raise the host so the opened task is visible
         if (url && !skipExternalOpen) {
           if (claudeSessionIdFromUrl(url)) {
-            openClaudeDeepLinkVerified(url, taskWebUrl(taskId), taskId);
+            openClaudeDeepLinkVerified(url, taskWebUrl(taskId), taskId, { freshlyForged });
           } else {
             shell.openExternal(url).catch((error) => console.error("[overlay] openExternal failed:", error && error.message));
           }
@@ -953,16 +1046,21 @@ function showOverlayWindow({ force = false, reposition = true } = {}) {
   }
   placeOverlayWindow({ reposition });
   const shown = showInactiveOnAllSpaces(win, { force });
-  win.setIgnoreMouseEvents(true, { forward: true });
-  if (shown) win.webContents.send("shown");
+  if (shown) {
+    // hidden -> shown only: re-assert click-through and reset the renderer's
+    // interactivity handshake. Touching setIgnoreMouseEvents on an already-visible
+    // window would silently flip it click-through while the renderer still thinks
+    // the pointer handshake is live — a dead card until the pointer re-enters.
+    win.setIgnoreMouseEvents(true, { forward: true });
+    win.webContents.send("shown");
+  }
 }
 
 function maybeShow({ force = false, reposition = true } = {}) {
   if (!win || win.isDestroyed()) return;
   // Dismissed keeps the window hidden except while a ghost notification is up.
   // trayForcedVisible honors an explicit status-area click even when no host runs.
-  const dismissedEffective = trayAvailable && dismissed;
-  const wanted = (hostRunning || trayForcedVisible) && (!dismissedEffective || ghostActive);
+  const wanted = overlayWanted({ hostRunning, trayForcedVisible, trayAvailable, dismissed, ghostActive });
   if (wanted) {
     showOverlayWindow({ force, reposition });
   } else if (win.isVisible()) {
@@ -988,6 +1086,10 @@ function readHostProcesses(cb) {
   execFile("/bin/ps", ["-Ao", "comm"], cb);
 }
 
+// Debounced OFF transition (~3 misses = ~4.5s at the 1.5s poll): a host relaunching
+// during its own auto-update, or one truncated process-list read, must not blink the
+// pill off and back on.
+const hostTracker = createHostRunningTracker({ missThreshold: 3 });
 function updateHostRunningFromProcesses(text) {
   const s = String(text || "");
   if (process.platform === "darwin") {
@@ -1003,7 +1105,7 @@ function updateHostRunningFromProcesses(text) {
     claudeRunning = /(^|\n)Claude(\n|$)/.test(s) || /(^|\n)claude(\n|$)/.test(s);
     codexRunning = /(^|\n)Codex(\n|$)/.test(s) || /(^|\n)codex(\n|$)/.test(s);
   }
-  hostRunning = claudeRunning || codexRunning;
+  hostRunning = hostTracker.update(claudeRunning, codexRunning);
 }
 
 function pollHosts() {
@@ -1057,7 +1159,21 @@ function createWindow() {
     console.error("[renderer]", d);
   });
   win.webContents.on("preload-error", (_e, p, err) => console.error("[preload-error]", p, err && err.message));
-  win.webContents.on("render-process-gone", (_e, det) => console.error("[render-gone]", JSON.stringify(det)));
+  // A dead renderer leaves an invisible, unrecoverable window (the tray click would
+  // "do nothing"). Reload it — with a short backoff so a hard crash can't hot-loop.
+  let renderGoneAt = 0;
+  win.webContents.on("render-process-gone", (_e, det) => {
+    console.error("[render-gone]", JSON.stringify(det));
+    if (!win || win.isDestroyed()) return;
+    const delay = Date.now() - renderGoneAt < 30000 ? 5000 : 250;
+    renderGoneAt = Date.now();
+    setTimeout(() => {
+      if (!win || win.isDestroyed()) return;
+      lastSig = ""; // force a full repaint after reload
+      knownIds = null;
+      win.webContents.reload();
+    }, delay);
+  });
   win.webContents.on("did-finish-load", () => resetWindowZoom(win));
   win.webContents.on("zoom-changed", (event) => {
     if (event && typeof event.preventDefault === "function") event.preventDefault();
@@ -1071,7 +1187,8 @@ function createWindow() {
     }
   });
   win.once("ready-to-show", () => {
-    // buildPayload() awaits the first sent-relay load, so a single push paints all tabs.
+    // First paint is instant: relays come from local state.json; the sent + contacts
+    // background loads kicked off here each re-push when they land (buildPayload).
     pushInbox(true).catch((error) => console.error("[overlay] initial push failed:", error && error.message));
     pollHosts();
   });
@@ -1090,6 +1207,11 @@ function createWindow() {
       .then(() => pushInbox(false))
       .catch(() => {});
   }, 5000); // live sent-relay refresh
+  setInterval(() => {
+    refreshContacts()
+      .then(() => pushInbox(false))
+      .catch(() => {});
+  }, 60000); // slow contact refresh; the contacts view also refreshes on open
   setInterval(pollHosts, 1500);
 }
 
@@ -1135,7 +1257,9 @@ function createTrayIcon() {
   return icon && !icon.isEmpty() ? icon : templateIcon && !templateIcon.isEmpty() ? templateIcon : null;
 }
 
+let lastTrayShowAt = 0;
 function showFromTray() {
+  lastTrayShowAt = Date.now();
   setDismissed(false);
   ghostActive = false;
   trayForcedVisible = true; // an explicit click always gets the card
@@ -1229,6 +1353,10 @@ ipcMain.on("relay:setPos", (_e, x, y) => {
 // ✕ on the card: hide the overlay entirely until the status-area Relay mark is clicked.
 // The renderer plays its exit animation first, then sends this.
 ipcMain.on("relay:dismiss", () => {
+  // Ignore only a dismiss whose IPC was already in flight when a tray "Show Relay"
+  // just landed (narrow window). A genuine ✕ click is always honored.
+  if (shouldIgnoreDismiss({ now: Date.now(), lastTrayShowAt })) return;
+  lastTrayShowAt = 0; // honored: clear the guard so it can't linger
   if (!trayAvailable) {
     setDismissed(false);
     ghostActive = false;
@@ -1284,6 +1412,18 @@ if (!gotSingleInstanceLock) {
     createWindow();
     createTray();
     installActiveSpaceWatcher();
+    // Test seam: the e2e harness (test/e2e-overlay.mjs) drives the real state machine
+    // over the main-process inspector. Never set outside the harness.
+    if (process.env.RELAY_OVERLAY_TEST === "1") {
+      global.__relayTest = {
+        showFromTray,
+        maybeShow,
+        refreshOverlayForActiveSpace,
+        pollHosts,
+        getWin: () => win,
+        state: () => ({ dismissed, ghostActive, trayForcedVisible, hostRunning, visible: win && !win.isDestroyed() ? win.isVisible() : null }),
+      };
+    }
   });
 
   app.on("window-all-closed", () => {

package/overlay/space-presence.cjs

@@ -21,11 +21,18 @@ function resetWindowZoom(win) {
 function reinforceSpacePresence(win, { moveTop = false } = {}) {
   if (!isUsableWindow(win)) return false;
   resetWindowZoom(win);
+  // Only touch window-server state that actually drifted. Re-asserting
+  // setVisibleOnAllWorkspaces / setAlwaysOnTop unconditionally (every 1.5s poll +
+  // every Space change) reorders the window each time and reads as flicker.
   try {
-    win.setVisibleOnAllWorkspaces(true, { visibleOnFullScreen: true });
+    if (typeof win.isVisibleOnAllWorkspaces !== "function" || !win.isVisibleOnAllWorkspaces()) {
+      win.setVisibleOnAllWorkspaces(true, { visibleOnFullScreen: true });
+    }
   } catch {}
   try {
-    win.setAlwaysOnTop(true, "floating");
+    if (typeof win.isAlwaysOnTop !== "function" || !win.isAlwaysOnTop()) {
+      win.setAlwaysOnTop(true, "floating");
+    }
   } catch {}
   if (moveTop && typeof win.moveTop === "function") {
     try {
@@ -43,11 +50,14 @@ function showInactiveOnAllSpaces(win, { force = false } = {}) {
     return false;
   }
 
+  // NEVER hide() an already-visible window here: the hide/show cycle was a visible
+  // blink on every forced re-show (twice per Space change). showInactive() on a
+  // visible window is enough to re-attach it to the active Space once the
+  // all-workspaces collection behavior has been re-asserted above.
   reinforceSpacePresence(win);
-  if (visible && force && typeof win.hide === "function") win.hide();
   if (typeof win.showInactive === "function") win.showInactive();
   reinforceSpacePresence(win, { moveTop: true });
-  return true;
+  return !visible;
 }
 
 function subscribeActiveSpaceChanges(systemPreferences, callback, { log = () => {} } = {}) {