relay-companion 0.1.34 → 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

@@ -452,6 +452,14 @@
   .cv-input::placeholder { color:var(--muted-3); }
   .cv-input:focus { border-color:rgba(48,85,102,.42); box-shadow:0 0 0 3px rgba(48,85,102,.08); }
   .cv-form-actions { display:flex; align-items:center; justify-content:flex-end; gap:14px; margin-top:1px; }
+  .cv-delete {
+    appearance:none; border:0; background:transparent; color:#b4332a; font-family:var(--sans);
+    font-size:12.5px; font-weight:600; cursor:pointer; transition:opacity .15s var(--settle), color .15s var(--settle);
+    margin-right:auto; padding:0;
+  }
+  .cv-delete:hover { opacity:.72; }
+  .cv-delete.armed { color:#8f261f; }
+  .cv-delete:disabled { opacity:.4; cursor:default; }
   .cv-cancel { appearance:none; border:0; background:transparent; color:var(--muted); font-family:var(--sans); font-size:12.5px; font-weight:500; cursor:pointer; transition:color .15s var(--settle); }
   .cv-cancel:hover { color:var(--ink-2); }
   .cv-save {
@@ -601,6 +609,7 @@
           <div class="cv-hint" id="cvHint"></div>
           <div class="cv-error" id="cvError"></div>
           <div class="cv-form-actions">
+            <button class="cv-delete gone" type="button" id="cvDelete">Delete</button>
             <button class="cv-cancel" type="button" id="cvCancel">Cancel</button>
             <button class="cv-save" type="submit" id="cvSave">Save</button>
           </div>
@@ -643,6 +652,7 @@
   const cvErrorEl = document.getElementById("cvError");
   const cvSaveEl = document.getElementById("cvSave");
   const cvCancelEl = document.getElementById("cvCancel");
+  const cvDeleteEl = document.getElementById("cvDelete");
 
   const REDUCED = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
   const EXPANDED = { w: 344, h: 524 };
@@ -748,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; }
@@ -755,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();
@@ -766,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");
@@ -790,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();
@@ -833,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);
@@ -1848,6 +1876,8 @@
   const COMMON_DOMAINS = ["gmail.com","outlook.com","hotmail.com","yahoo.com","icloud.com","me.com","proton.me","protonmail.com","live.com","aol.com"];
   let cvEmailsList = [];     // committed, lowercased, deduped addresses (the chips)
   let cvSuggIdx = 0;         // highlighted suggestion row
+  let cvDeleteArmed = false;
+  let cvDeleteTimer = null;
   function isValidEmail(s) { return EMAIL_RE.test(String(s).trim()); }
   function cvSuggestions() {
     const draft = cvEmailEl.value;
@@ -1907,6 +1937,21 @@
     cvEmailsList = cvEmailsList.filter((x) => x !== e);
     renderEmailChips();
   }
+  function editingContactId() {
+    return cvEditing && (cvEditing.id || cvEditing.contactId) ? String(cvEditing.id || cvEditing.contactId) : "";
+  }
+  function resetDeleteButton() {
+    cvDeleteArmed = false;
+    if (cvDeleteTimer) { clearTimeout(cvDeleteTimer); cvDeleteTimer = null; }
+    cvDeleteEl.textContent = "Delete";
+    cvDeleteEl.classList.remove("armed");
+    cvDeleteEl.disabled = false;
+  }
+  function syncDeleteButton() {
+    resetDeleteButton();
+    const canDelete = Boolean(editingContactId());
+    cvDeleteEl.classList.toggle("gone", !canDelete);
+  }
   cvEmailsEl.addEventListener("mousedown", (e) => {
     if (e.target === cvEmailsEl) { e.preventDefault(); cvEmailEl.focus(); }
   });
@@ -1944,6 +1989,7 @@
     cvErrorEl.textContent = "";
     cvSuggestEl.classList.add("hidden"); cvSuggestEl.innerHTML = "";
     renderEmailChips();
+    syncDeleteButton();
     cvFormEl.classList.remove("hidden");
     if (window.relay.setFocusable) window.relay.setFocusable(true);
     setInteractive(true);
@@ -1957,10 +2003,37 @@
     cvErrorEl.textContent = "";
     cvHintEl.textContent = "";
     cvSuggestEl.classList.add("hidden"); cvSuggestEl.innerHTML = "";
+    cvDeleteEl.classList.add("gone");
+    resetDeleteButton();
     if (window.relay.setFocusable) window.relay.setFocusable(false);
   }
   cvAddEl.addEventListener("click", () => openContactForm(null));
   cvCancelEl.addEventListener("click", closeContactForm);
+  cvDeleteEl.addEventListener("click", async () => {
+    const contactId = editingContactId();
+    if (!contactId || cvDeleteEl.disabled) return;
+    if (!cvDeleteArmed) {
+      cvDeleteArmed = true;
+      cvDeleteEl.textContent = "Delete?";
+      cvDeleteEl.classList.add("armed");
+      cvDeleteTimer = setTimeout(resetDeleteButton, 3500);
+      return;
+    }
+    cvDeleteEl.disabled = true;
+    cvSaveEl.disabled = true;
+    cvErrorEl.textContent = "";
+    try {
+      const next = await window.relay.contactDelete({ contactId });
+      if (Array.isArray(next)) contactsList = next;
+      closeContactForm();
+      renderContacts();
+    } catch (err) {
+      cvErrorEl.textContent = (err && err.message) ? err.message : "Could not delete.";
+      cvDeleteEl.disabled = false;
+      cvSaveEl.disabled = false;
+      resetDeleteButton();
+    }
+  });
   cvFormEl.addEventListener("submit", async (e) => {
     e.preventDefault();
     const name = [cvFirstEl.value, cvLastEl.value].map((s) => s.trim()).filter(Boolean).join(" ");
@@ -1973,7 +2046,8 @@
     cvErrorEl.textContent = "";
     try {
       // Match the website's ContactWrite shape: emails[] is the identity, email = primary.
-      const next = await window.relay.contactSave({ name, emails, email: emails[0] });
+      const contactId = editingContactId();
+      const next = await window.relay.contactSave({ contactId, name, emails, email: emails[0] });
       if (Array.isArray(next)) contactsList = next;
       closeContactForm();
       renderContacts();
@@ -2070,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,32 +309,48 @@ 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 {
-          id: c.id || "",
+          id: c.id || c.contactId || "",
           name: c.name || emails[0] || "",
           email: emails[0] || c.email || "",
           emails,
+          onRelay: Boolean(c.onRelay),
           updatedAt: c.updatedAt || null,
         };
       })
       .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) {
+  const contactId = String((input && input.contactId) || "").trim();
   const name = String((input && input.name) || "").trim();
   const emails = Array.isArray(input && input.emails)
     ? input.emails.map((e) => String(e || "").trim()).filter(Boolean)
@@ -333,32 +360,56 @@ async function saveContact(input) {
   if (!name) throw new Error("A name is required");
   for (const e of emails) if (!e.includes("@")) throw new Error("That email looks off.");
   const client = await relayClient();
-  await client.upsertContact({ name, emails, email: emails[0] || "" });
+  if (contactId) await client.updateContact(contactId, { name, emails, email: emails[0] || "" });
+  else await client.upsertContact({ name, emails, email: emails[0] || "" });
+  return readContacts();
+}
+
+async function deleteContactFromBook(input) {
+  const contactId = String((input && input.contactId) || input || "").trim();
+  if (!contactId) throw new Error("Missing contact id.");
+  const client = await relayClient();
+  await client.deleteContact(contactId);
   return readContacts();
 }
 
 // ---- 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) {
@@ -382,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,
@@ -394,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") }))
@@ -520,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) {
@@ -701,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();
@@ -712,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);
   };
@@ -792,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));
           }
@@ -864,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));
           }
@@ -942,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()) {
@@ -977,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") {
@@ -992,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() {
@@ -1046,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();
@@ -1060,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();
   });
@@ -1079,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);
 }
 
@@ -1124,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
@@ -1188,6 +1301,7 @@ ipcMain.handle("relay:decline", (_e, taskId, approvalId) => declineShare(taskId,
 ipcMain.handle("relay:answer", (_e, taskId, messageId, text, packetId) => answerQuestion(taskId, messageId, text, packetId));
 ipcMain.handle("relay:contacts", () => readContacts());
 ipcMain.handle("relay:contactSave", (_e, input) => saveContact(input));
+ipcMain.handle("relay:contactDelete", (_e, input) => deleteContactFromBook(input));
 
 // The overlay is normally focusable:false so it never steals keyboard focus from
 // Claude/Codex. Text fields (the contact form, quick reply) need focus, so the renderer
@@ -1217,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;
@@ -1272,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/preload.cjs

@@ -32,6 +32,7 @@ contextBridge.exposeInMainWorld("relay", {
   // contacts
   contacts: () => ipcRenderer.invoke("relay:contacts"),
   contactSave: (input) => ipcRenderer.invoke("relay:contactSave", input),
+  contactDelete: (input) => ipcRenderer.invoke("relay:contactDelete", input),
 
   // window plumbing
   setFocusable: (v) => ipcRenderer.send("relay:setFocusable", v),