relay-companion 0.1.35 → 0.1.36

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/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) {
@@ -712,7 +772,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 +783,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 +870,18 @@ 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) {
         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 +944,17 @@ 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) {
         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 +1024,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 +1064,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 +1083,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 +1137,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 +1165,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 +1185,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 +1235,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 +1331,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 +1390,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 = () => {} } = {}) {

package/overlay/visibility.cjs

@@ -0,0 +1,54 @@
+// Pure overlay-visibility logic, extracted from main.cjs so the state machine that
+// decides when the pill window is on screen is unit-testable without Electron.
+//
+// The window is wanted when a host app is running (or the user explicitly clicked the
+// status-area icon), unless the user dismissed the pill — with a ghost notification
+// temporarily overriding a dismissal.
+
+function overlayWanted({
+  hostRunning = false,
+  trayForcedVisible = false,
+  trayAvailable = false,
+  dismissed = false,
+  ghostActive = false,
+} = {}) {
+  const dismissedEffective = trayAvailable && dismissed;
+  return (hostRunning || trayForcedVisible) && (!dismissedEffective || ghostActive);
+}
+
+// Debounced "a host is running" tracker. The OFF transition requires `missThreshold`
+// consecutive polls with neither host present: a host relaunching during its own
+// auto-update (or one truncated process-list read) must not blink the pill off.
+function createHostRunningTracker({ missThreshold = 3 } = {}) {
+  let running = false;
+  let missStreak = 0;
+  return {
+    update(claudeRunning, codexRunning) {
+      if (claudeRunning || codexRunning) {
+        missStreak = 0;
+        running = true;
+      } else {
+        missStreak += 1;
+        if (missStreak >= missThreshold) running = false;
+      }
+      return running;
+    },
+    get running() {
+      return running;
+    },
+  };
+}
+
+// A dismiss whose IPC was ALREADY in flight when a tray "Show Relay" landed would hide
+// the pill the user just reopened. The renderer's cancelBye() prevents the exit timer
+// from firing after a reopen, so this guard only needs to cover the narrow window where
+// the dismiss IPC had already been SENT (~IPC latency). Keep it short — a wide window
+// would swallow a GENUINE ✕ click made shortly after Show Relay. lastTrayShowAt must be
+// reset once a dismiss is honored so the guard never lingers across interactions.
+function shouldIgnoreDismiss({ now, lastTrayShowAt, windowMs = 250 } = {}) {
+  if (!lastTrayShowAt) return false;
+  const delta = Number(now) - Number(lastTrayShowAt);
+  return delta >= 0 && delta < windowMs;
+}
+
+module.exports = { overlayWanted, createHostRunningTracker, shouldIgnoreDismiss };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "relay-companion",
-  "version": "0.1.35",
+  "version": "0.1.36",
   "description": "Relay companion: connects local coding agents to Relay tasks, approvals, and connector tools.",
   "type": "module",
   "bin": {