relay-companion 0.1.72 → 0.1.74

package/overlay/main.cjs

@@ -21,6 +21,24 @@
 //     auth. ack/mark-read writes state.json directly (atomic temp+rename).
 
 const { app, BrowserWindow, Menu, Tray, ipcMain, nativeImage, powerMonitor, shell, screen, systemPreferences } = require("electron");
+
+// A closed stdout/stderr pipe must never kill the pill. When whatever launched
+// us goes away (launchd log rotation, a terminal that spawned `relay pill`, a
+// parent harness exiting), the next console write throws EPIPE — and an
+// unhandled throw in the main process shows Electron's "A JavaScript error
+// occurred" dialog and takes the overlay down. Logging is diagnostic; it is
+// never worth a crash, so swallow write errors on both streams and treat a
+// stray EPIPE as a no-op.
+for (const stream of [process.stdout, process.stderr]) {
+  try {
+    stream.on("error", () => {});
+  } catch {}
+}
+process.on("uncaughtException", (error) => {
+  if (error && (error.code === "EPIPE" || error.code === "ERR_STREAM_DESTROYED")) return;
+  throw error;
+});
+
 const fs = require("node:fs");
 const os = require("node:os");
 const path = require("node:path");
@@ -62,6 +80,7 @@ const {
   companionModeFromRuntime,
   taskFeaturesAllowed,
 } = require("./mode-policy.cjs");
+const perf = require("./perf-counters.cjs");
 
 const RELAY_HOME = process.env.RELAY_HOME || process.env.RELAY_COMPANION_HOME || path.join(os.homedir(), ".relay-companion");
 const STATE_PATH = path.join(RELAY_HOME, "state.json");
@@ -132,17 +151,40 @@ let pendingReopenNonce = "";
 let lastReopenNonce = "";
 let lastPillStatusSig = "";
 const PRESENTED_RELAY_CAP = 500;
+// Dirty gate: the guaranteed-attention machinery calls writeOverlayPrefs on every
+// safety tick while the queue is non-empty, which used to SYNC-write an identical
+// 9KB file every 2.5s for hours (observed live on 2026-08-05: a fresh mtime on
+// every 5s sample). Serialize first and skip the disk entirely when the content
+// is byte-identical to the last successful write. Every real state change still
+// persists immediately — including the in-flight marker BEFORE renderer delivery
+// (beginShow mutates the queue, so that serialization always differs). The write
+// itself is now atomic (tmp+rename): a crash mid-write must never corrupt the
+// durable attention queue it exists to protect.
+let lastPrefsSerialized = "";
 function writeOverlayPrefs() {
+  let tmp = "";
   try {
-    fs.mkdirSync(RELAY_HOME, { recursive: true });
     const prefs = attention.saveQueue(attentionQueue, {
       dismissed,
       attentionLatched,
       presentedRelayIds: [...presentedRelayIds],
       activeAttentionIds: [...activeAttentionIds],
     });
-    fs.writeFileSync(OVERLAY_PREFS_PATH, `${JSON.stringify(prefs, null, 2)}\n`);
+    const serialized = `${JSON.stringify(prefs, null, 2)}\n`;
+    if (serialized === lastPrefsSerialized) {
+      perf.inc("prefsWriteSkips");
+      return;
+    }
+    fs.mkdirSync(RELAY_HOME, { recursive: true });
+    tmp = `${OVERLAY_PREFS_PATH}.${process.pid}.${Date.now()}.tmp`;
+    fs.writeFileSync(tmp, serialized);
+    fs.renameSync(tmp, OVERLAY_PREFS_PATH);
+    lastPrefsSerialized = serialized;
+    perf.inc("prefsWrites");
   } catch (error) {
+    try {
+      if (tmp) fs.rmSync(tmp, { force: true });
+    } catch {}
     console.error(`[overlay] ${new Date().toISOString()} prefs write failed:`, error && error.message);
   }
 }
@@ -177,6 +219,7 @@ function writePillStatus(reopenNonce = "") {
     fs.writeFileSync(tmp, `${JSON.stringify(status, null, 2)}\n`);
     fs.renameSync(tmp, PILL_STATUS_PATH);
     lastPillStatusSig = sig;
+    perf.inc("statusWrites");
   } catch (error) {
     try {
       if (tmp) fs.rmSync(tmp, { force: true });
@@ -675,12 +718,29 @@ async function markAllVisibleRelaysRead() {
 
 let sentCache = [];
 let sentLoadedOnce = null;
+// Fingerprint over exactly the fields the inbox signature (and therefore the
+// renderer) can observe, so "did anything change?" costs a tiny stringify
+// instead of a full payload rebuild per refresh.
+let sentFingerprint = "";
+function sentFingerprintOf(items) {
+  return JSON.stringify(
+    (items || []).map((r) => [
+      r.relayId,
+      r.state,
+      r.updatedAt,
+      r.delivery && r.delivery.state,
+      r.delivery && r.delivery.channel,
+      r.hasAttachments,
+    ]),
+  );
+}
 async function refreshSent() {
   if (!deviceToken()) return sentCache; // signed out: nothing to fetch, no 401 log storm
   try {
     const client = await relayClient();
     const res = await client.sent();
     sentCache = Array.isArray(res && res.items) ? res.items : [];
+    sentFingerprint = sentFingerprintOf(sentCache);
   } catch (error) {
     console.error("[overlay] listSent failed:", error && error.message);
   }
@@ -725,6 +785,11 @@ function ensureTasksLoaded() {
 
 let contactsCache = [];
 let contactsLoadedOnce = null;
+let contactsFingerprint = "";
+function contactsFingerprintOf(list) {
+  // Same triple the inbox signature hashes for contacts.
+  return JSON.stringify((list || []).map((c) => [c.id, c.name, c.email]));
+}
 async function refreshContacts() {
   if (!deviceToken()) return contactsCache; // signed out: skip the poll entirely
   try {
@@ -744,6 +809,7 @@ async function refreshContacts() {
         };
       })
       .sort((a, b) => String(a.name).localeCompare(String(b.name)));
+    contactsFingerprint = contactsFingerprintOf(contactsCache);
   } catch (error) {
     // Keep the last good cache; a transient network failure must not blank the UI.
     console.error("[overlay] listContacts failed:", error && error.message);
@@ -791,6 +857,7 @@ async function deleteContactFromBook(input) {
 // 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() {
+  perf.inc("payloadBuilds");
   // 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(() => {});
@@ -811,6 +878,21 @@ function buildPayload() {
 // 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();
+// state.json generation gate for the 2.5s safety poll: reading + parsing a
+// ~500KB store and re-deriving a 150-row payload every tick is what kept the
+// pill hot all day. The safety tick now costs ONE stat() unless the file
+// actually changed since the last full push (fs.watch/watchFile still fire the
+// real pushes on change; this closes their races). Content changes always move
+// mtimeMs/size because every writer uses temp+rename or a direct rewrite.
+let lastStateStatSig = "";
+function stateFileStatSig() {
+  try {
+    const st = fs.statSync(STATE_PATH);
+    return `${st.mtimeMs}:${st.size}`;
+  } catch {
+    return "missing";
+  }
+}
 const USER_IDLE_THRESHOLD_SECONDS = 15;
 let systemSuspended = false;
 let screenLocked = false;
@@ -823,6 +905,7 @@ function userIsAway() {
   if (process.env.RELAY_OVERLAY_TEST_FORCE_ACTIVE === "1") return false;
   if (systemSuspended || screenLocked || !loginSessionActive) return true;
   try {
+    perf.inc("idleQueries");
     const state = powerMonitor.getSystemIdleState(USER_IDLE_THRESHOLD_SECONDS);
     return state === "idle" || state === "locked";
   } catch {
@@ -846,6 +929,7 @@ const dwellMs = () => Number(process.env.RELAY_OVERLAY_NOTIFICATION_MS) || 7000;
 
 function idleSecondsSafe() {
   try {
+    perf.inc("idleQueries");
     return powerMonitor.getSystemIdleTime();
   } catch {
     return 0;
@@ -877,21 +961,35 @@ function abortCurrentShow(reason) {
 // card was visible). A wake resets the idle counter, so the sampler alone —
 // not a single end-of-dwell reading — is what makes wake-to-black-screen
 // dwells fail closed and stay queued.
-function beginShowSampling(entryIds, digest) {
+function beginShowSampling(entryIds, digest, { sticky = false } = {}) {
   const idleAtStart = idleSecondsSafe();
   const startedAt = Date.now();
   const show = { ids: entryIds, digest: Boolean(digest), startedAt, idleAtStart, inputSeen: false, sampler: null };
+  // Sticky cards latch open indefinitely and only ever confirm via a renderer
+  // interaction (interacted=true), which needs no idle evidence — so don't run
+  // a 1Hz idle query for the whole time one sits on screen.
+  if (sticky) return show;
+  // Cap the sampler at a few dwells past the fold deadline: the renderer's
+  // attentionDone lands within one dwell, and evidence gathered after ~30s
+  // could never belong to this card's visible interval anyway.
+  const samplerCapMs = Math.max(dwellMs() * 4, 30000);
   show.sampler = setInterval(() => {
     const elapsed = (Date.now() - startedAt) / 1000;
     const expected = show.idleAtStart + elapsed;
     if (idleSecondsSafe() < expected - 1) show.inputSeen = true;
+    if (Date.now() - startedAt > samplerCapMs && show.sampler) {
+      clearInterval(show.sampler);
+      show.sampler = null;
+    }
   }, 1000);
   return show;
 }
 
 // One card (or one digest) at a time. Every exit from the queue is either a
 // confirmed dwell/interaction or an explicit per-relay user act elsewhere.
-function pumpAttention() {
+// prebuiltPayload lets pushInboxNow hand over the payload it just derived, so
+// the hot pump path never parses state.json a second time per tick.
+function pumpAttention(prebuiltPayload = null) {
   if (!win || win.isDestroyed() || !pillReady || !rendererListening) return false;
   if (currentShow || attention.hasShowing(attentionQueue)) return false;
   if (userIsAway()) {
@@ -908,7 +1006,7 @@ function pumpAttention() {
     if (!hasFresh) return false;
   }
 
-  const payload = buildPayload();
+  const payload = prebuiltPayload || buildPayload();
   const unreadRows = new Map(
     visibleRelayRows(payload.relays).filter((r) => r.unread).map((r) => [r.id, r]),
   );
@@ -933,7 +1031,7 @@ function pumpAttention() {
     if (!row) {
       attention.drop(attentionQueue, entry.id);
       writeOverlayPrefs();
-      return pumpAttention();
+      return pumpAttention(payload); // same store generation: reuse the build
     }
     sticky = entry.sticky === true;
     attention.beginShow(attentionQueue, entry.id);
@@ -951,7 +1049,7 @@ function pumpAttention() {
   deferredAttention = false;
   maybeShow({ force: true });
   activeAttentionIds = new Set(ids);
-  currentShow = beginShowSampling(ids, digestMode);
+  currentShow = beginShowSampling(ids, digestMode, { sticky });
   setThrottlingForShow(true);
   lastEngagedAt = Date.now(); // a live card warrants tight sent/host cadence briefly
   currentShow.sticky = sticky;
@@ -973,6 +1071,14 @@ function pumpAttention() {
 // The return pump replaces the old fixed [0,1200,4500]ms retries: while relays
 // still owe a notification it keeps trying every 2s — across slow wakes, slow
 // Wi-Fi reassociation and the daemon's next poll — until the queue drains.
+//
+// It is a RETRY loop, not a maintenance loop (2026-08-05 freeze audit): the old
+// per-tick refreshOverlayForActiveSpace({force:true}) spawned `ps` and forced a
+// window-server re-assertion every 2s for as long as anything was queued — with
+// a sticky card latched on stage, that was a permanent hot loop. Space presence
+// is owned by events (Space changes, show edges, return-from-away, display
+// changes); pumpAttention's own maybeShow({force:true}) still raises the window
+// whenever a card actually fires.
 let returnPumpTimer = null;
 function startReturnPump() {
   if (returnPumpTimer) return;
@@ -982,12 +1088,21 @@ function startReturnPump() {
       returnPumpTimer = null;
       return;
     }
-    if (userIsAway()) return;
+    // A card is on stage: its confirm/abort exit re-pumps (or restarts this
+    // pump). Ticking during the dwell was pure churn.
+    if (currentShow || attention.hasShowing(attentionQueue)) return;
+    if (userIsAway()) {
+      // Park entirely while away: the 1s deferred-attention poll owns the
+      // return edge and restarts the pump via reconcileAttentionAfterReturn.
+      deferredAttention = true;
+      clearInterval(returnPumpTimer);
+      returnPumpTimer = null;
+      return;
+    }
     // Returning from away cuts through a snooze: the user left, so what they
     // dismissed is stale context and unseen relays must surface again.
     dismissSnoozedIds = new Set();
     burstShown = 0;
-    refreshOverlayForActiveSpace({ force: true });
     pumpAttention();
   }, 2000);
 }
@@ -1016,6 +1131,10 @@ function pushInbox(force) {
 }
 async function pushInboxNow(force) {
   if (!win || win.isDestroyed()) return;
+  // Record the state.json generation BEFORE reading it: a write that lands
+  // mid-read leaves the stat differing on the next safety tick, so the racing
+  // change is re-pushed rather than silently skipped.
+  lastStateStatSig = stateFileStatSig();
   const payload = buildPayload();
   const rows = payload.relays;
   const notifiableRows = visibleRelayRows(rows);
@@ -1069,7 +1188,7 @@ async function pushInboxNow(force) {
     lastSig = sig;
     if (win && !win.isDestroyed()) win.webContents.send("inbox", payload);
   }
-  pumpAttention();
+  pumpAttention(payload); // reuse this build; pumping must not re-read the store
 }
 
 // Refresh state-derived rows only (fast path used by fs.watch + the safety poll).
@@ -1263,9 +1382,11 @@ function taskVersion(taskId) {
 // Best-effort frontmost-app bundle id (no permission prompt; uses lsappinfo).
 function frontmostBundleId(cb) {
   if (process.platform !== "darwin") return cb(null);
+  perf.inc("spawns");
   execFile("/usr/bin/lsappinfo", ["front"], (e1, asn) => {
     const a = String(asn || "").trim();
     if (e1 || !a) return cb(null);
+    perf.inc("spawns");
     execFile("/usr/bin/lsappinfo", ["info", "-only", "bundleid", a], (e2, out) => {
       const m = String(out || "").match(/"CFBundleIdentifier"\s*=\s*"([^"]+)"/);
       cb(e2 ? null : m ? m[1] : null);
@@ -1295,6 +1416,7 @@ function activateHost(host, observedBundle = null) {
       if (lastError) console.error("[overlay] activateHost failed:", host, lastError && lastError.message);
       return;
     }
+    perf.inc("spawns");
     execFile("/usr/bin/open", ["-b", bundle], (error) => {
       if (error) tryBundle(index + 1, error);
     });
@@ -1663,6 +1785,7 @@ async function openPacket(packetId, { sent = false, fresh = false } = {}) {
       // then keep the row spinner alive while it does post-import title repair.
       env.RELAY_IMPORT_CLAUDE_DESKTOP = "0";
     }
+    perf.inc("spawns");
     const child = spawn(
       process.execPath,
       // --fresh ("Open in new chat"): the materializer ignores the remembered
@@ -1891,6 +2014,7 @@ function openTaskDetail(taskId) {
       // Let the overlay own the actual deep-link launch (see openPacket).
       env.RELAY_IMPORT_CLAUDE_DESKTOP = "0";
     }
+    perf.inc("spawns");
     const child = spawn(
       process.execPath,
       [RELAY_CLI, "open", "--task", taskId, "--host", host, COMPANION_MODE_CLI_ARG],
@@ -1990,6 +2114,7 @@ function showOverlayWindow({ force = false, reposition = true } = {}) {
   if (!win || win.isDestroyed()) return;
   const visible = win.isVisible();
   if (visible && !force) {
+    perf.inc("spaceAsserts");
     reinforceSpacePresence(win);
     return;
   }
@@ -2003,6 +2128,7 @@ function showOverlayWindow({ force = false, reposition = true } = {}) {
   // No reinforceSpacePresence before this call: showInactiveOnAllSpaces must observe
   // whether the collection behavior actually drifted to decide between a real
   // re-attach and a no-op — repairing it first would force the re-show every time.
+  perf.inc("spaceAsserts");
   const shown = showInactiveOnAllSpaces(win, { force });
   if (shown) {
     // hidden -> shown only: re-assert click-through and reset the renderer's
@@ -2011,6 +2137,11 @@ function showOverlayWindow({ force = false, reposition = true } = {}) {
     // the pointer handshake is live — a dead card until the pointer re-enters.
     win.setIgnoreMouseEvents(true, { forward: true });
     win.webContents.send("shown");
+    // Becoming visible is when host-running freshness starts mattering for
+    // click routing again; the hidden poll cadence is slow, so take one
+    // reading at the show edge (process list only — the frontmost probe
+    // belongs to hover/click time).
+    pollHosts({ probeFrontmost: false });
   }
 }
 
@@ -2020,7 +2151,23 @@ function maybeShow({ force = false, reposition = true } = {}) {
   // trayForcedVisible honors an explicit status-area click even when no host runs.
   const wanted = overlayWanted({ hostRunning, trayForcedVisible, trayAvailable, dismissed, ghostActive, attentionLatched });
   if (wanted) {
-    showOverlayWindow({ force, reposition });
+    // macOS steady state (already visible, nothing forcing): leave the
+    // window-server state alone. The old unconditional showOverlayWindow here
+    // re-asserted Space presence from every periodic caller (host poll, return
+    // pump), which is timer-driven window-server load. Presence repair now runs
+    // only on the events that can actually break it: Space changes, show edges,
+    // wake/unlock reconciles, display changes and explicit forces.
+    //
+    // Windows is EXCLUDED from the fast path on purpose: the OS strips
+    // WS_EX_TOPMOST in ways Electron's cached isAlwaysOnTop() cannot observe
+    // (see space-presence.cjs), so the periodic reinforce IS the topmost
+    // self-heal there — and SetWindowPos on an already-topmost window is not a
+    // visible reorder on Windows.
+    if (!force && win.isVisible() && process.platform === "darwin") {
+      // no-op on the window
+    } else {
+      showOverlayWindow({ force, reposition });
+    }
   } else if (win.isVisible()) {
     win.hide();
   }
@@ -2042,6 +2189,7 @@ function refreshOverlayForActiveSpace({ force = false } = {}) {
 }
 
 function readHostProcesses(cb) {
+  perf.inc("spawns");
   if (process.platform === "win32") {
     execFile("tasklist", ["/FO", "CSV", "/NH"], cb);
     return;
@@ -2064,7 +2212,7 @@ function updateHostRunningFromProcesses(text) {
   hostRunning = hostTracker.update(claudeRunning, codexRunning);
 }
 
-function pollHosts() {
+function pollHosts({ probeFrontmost = true } = {}) {
   // Show whenever EITHER host app is running; track the foregrounded one for click routing.
   readHostProcesses((err, stdout) => {
     // On a process-list error, leave the last-known running state untouched rather than
@@ -2073,9 +2221,15 @@ function pollHosts() {
     if (hostRunning) trayForcedVisible = false; // normal host-based visibility takes back over
     maybeShow();
   });
-  frontmostBundleId((bundle) => {
-    rememberForegroundHost(hostFromBundle(bundle));
-  });
+  // The frontmost probe is two more spawns and only feeds lastHost, whose job is
+  // click routing. Clicks always take a fresh frontmost reading, and the hover
+  // approach probe captures the just-before-click state — so the periodic loop
+  // only pays for it while the user is plausibly about to click (engaged).
+  if (probeFrontmost) {
+    frontmostBundleId((bundle) => {
+      rememberForegroundHost(hostFromBundle(bundle));
+    });
+  }
 }
 
 // ---- pointer hit test (main-process authority) -----------------------------
@@ -2172,6 +2326,7 @@ function hitTick() {
   let bounds;
   let point;
   try {
+    perf.inc("cursorReads");
     bounds = win.getContentBounds(); // frameless: content == frame; follows setPos for free
     point = screen.getCursorScreenPoint();
   } catch {
@@ -2304,13 +2459,29 @@ function createWindow() {
       if (!file || String(file).startsWith("state.json")) pushInboxQuiet();
     });
   } catch {}
-  setInterval(() => pushInboxQuiet(), 2500); // safety net for state.json
+  // Safety net for state.json: ONE stat() per tick unless the file generation
+  // actually moved since the last full push. The full 500KB parse + payload +
+  // signature rebuild every 2.5s regardless of change was a top contributor to
+  // the pill's always-on CPU (2026-08-05 freeze audit).
+  setInterval(() => {
+    if (stateFileStatSig() === lastStateStatSig) {
+      perf.inc("statePollSkips");
+      return;
+    }
+    pushInboxQuiet();
+  }, 2500);
   // Adaptive cadences (visibility.cjs): tight loops only while the user is
   // engaged; idle machines get slow heartbeats instead of spawn/fetch storms.
   const testMode = process.env.RELAY_OVERLAY_TEST === "1";
   const sentLoop = () => {
+    const fingerprintBefore = sentFingerprint;
     refreshSent()
-      .then(() => pushInbox(false))
+      .then(() => {
+        // Only rebuild + repush when the sig-relevant fields moved; an idle
+        // machine's unchanged Sent list should cost the fetch and nothing more.
+        if (sentFingerprint !== fingerprintBefore) return pushInbox(false);
+        perf.inc("sentPushSkips");
+      })
       .catch(() => {})
       .finally(() =>
         setTimeout(sentLoop, sentRefreshDelayMs({ testMode, engaged: isEngaged(), showActive: Boolean(currentShow) })),
@@ -2318,13 +2489,26 @@ function createWindow() {
   };
   setTimeout(sentLoop, 5000);
   setInterval(() => {
+    const fingerprintBefore = contactsFingerprint;
     refreshContacts()
-      .then(() => pushInbox(false))
+      .then(() => {
+        if (contactsFingerprint !== fingerprintBefore) return pushInbox(false);
+        perf.inc("contactsPushSkips");
+      })
       .catch(() => {});
   }, 60000); // slow contact refresh; the contacts view also refreshes on open
   const hostLoop = () => {
-    pollHosts();
-    setTimeout(hostLoop, hostPollDelayMs({ testMode, engaged: isEngaged() }));
+    // Engaged: fresh frontmost capture for imminent clicks. Otherwise the
+    // process-list read alone keeps hostRunning/click-routing state warm.
+    pollHosts({ probeFrontmost: isEngaged() });
+    setTimeout(
+      hostLoop,
+      hostPollDelayMs({
+        testMode,
+        engaged: isEngaged(),
+        visible: Boolean(win && !win.isDestroyed() && win.isVisible()),
+      }),
+    );
   };
   setTimeout(hostLoop, hostPollDelayMs({ testMode, engaged: true }));
 }
@@ -2606,6 +2790,7 @@ ipcMain.on("relay:cardSize", (_e, w, h) => {
 ipcMain.on("relay:setPos", (_e, x, y) => {
   if (win && !win.isDestroyed() && Number.isFinite(x) && Number.isFinite(y)) {
     win.setPosition(Math.round(x), Math.round(y));
+    perf.inc("spaceAsserts");
     reinforceSpacePresence(win);
   }
 });
@@ -2735,9 +2920,26 @@ if (!gotSingleInstanceLock) {
     createTray();
     installActiveSpaceWatcher();
     installPowerAttentionLifecycle();
-    // 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") {
+    // Display topology changes are the remaining event that can strand the
+    // overlay (stale bounds, dropped always-on-top after a monitor swap).
+    // Event-driven repair replaces the old every-poll re-assertion.
+    try {
+      screen.on("display-added", () => maybeShow({ force: true }));
+      screen.on("display-removed", () => maybeShow({ force: true }));
+      screen.on("display-metrics-changed", () => maybeShow({ force: true }));
+    } catch (error) {
+      console.error("[overlay] display watcher failed:", error && error.message);
+    }
+    // Perf-counter log line for live diagnosis (opt-in, stderr → pill.log).
+    if (process.env.RELAY_OVERLAY_PERF_LOG === "1") {
+      perf.startPerfLog({ log: (line) => console.error(line) });
+    }
+    // Test seam: the e2e harness (test/e2e-overlay.mjs) and the perf harness
+    // (test/perf-overlay.mjs) drive the real state machine over the main-process
+    // inspector. RELAY_OVERLAY_PERF=1 exposes the seam WITHOUT flipping the
+    // RELAY_OVERLAY_TEST cadences, so measurements see production timing.
+    // Never set outside the harnesses.
+    if (process.env.RELAY_OVERLAY_TEST === "1" || process.env.RELAY_OVERLAY_PERF === "1") {
       global.__relayTest = {
         showFromTray,
         requestExternalReopen,
@@ -2754,6 +2956,7 @@ if (!gotSingleInstanceLock) {
         },
         setSentCache: (items) => {
           sentCache = Array.isArray(items) ? items : [];
+          sentFingerprint = sentFingerprintOf(sentCache);
           return pushInbox(true);
         },
         getWin: () => win,
@@ -2766,6 +2969,7 @@ if (!gotSingleInstanceLock) {
           return ids;
         },
         pumpAttention,
+        perf: () => perf.snapshot(),
         state: () => ({
           dismissed,
           attentionLatched,

package/overlay/perf-counters.cjs

@@ -0,0 +1,48 @@
+// Always-on, near-zero-cost perf counters for the overlay main process.
+//
+// Motivation (2026-08-05 whole-Mac stutter investigation): the pill's background
+// cost is invisible until it is measured. Every recurring expense — process
+// spawns, window-server re-assertions, cursor/idle queries, full payload builds,
+// prefs writes — increments a named counter here, so a live overlay (or the
+// sandboxed e2e/perf harness) can report exact per-minute rates instead of
+// guesses. Incrementing a property on a plain object is nanoseconds; the module
+// never allocates on the hot path.
+//
+// Reading:
+//   - test seam: global.__relayTest.perf() returns snapshot()
+//   - log line: RELAY_OVERLAY_PERF_LOG=1 prints per-minute deltas to stderr
+
+"use strict";
+
+const counters = Object.create(null);
+const startedAt = Date.now();
+
+function inc(name, by = 1) {
+  counters[name] = (counters[name] || 0) + by;
+}
+
+function snapshot() {
+  return { ...counters, uptimeMs: Date.now() - startedAt };
+}
+
+// Per-minute delta logger. Off unless explicitly enabled; unref'd so it never
+// keeps the process alive.
+function startPerfLog({ log = () => {}, intervalMs = 60000, now = Date.now } = {}) {
+  let last = { ...counters };
+  let lastAt = now();
+  const timer = setInterval(() => {
+    const at = now();
+    const minutes = Math.max((at - lastAt) / 60000, 1e-6);
+    const deltas = {};
+    for (const key of Object.keys(counters)) {
+      deltas[key] = Math.round(((counters[key] || 0) - (last[key] || 0)) / minutes);
+    }
+    last = { ...counters };
+    lastAt = at;
+    log(`[overlay] perf/min ${JSON.stringify(deltas)}`);
+  }, intervalMs);
+  if (timer && typeof timer.unref === "function") timer.unref();
+  return timer;
+}
+
+module.exports = { inc, snapshot, startPerfLog };

package/overlay/visibility.cjs

@@ -103,11 +103,14 @@ function recoverInterruptedAttentionPrefs(input = {}) {
 // ---- adaptive poll cadences (the anti-spawn-storm rules) -------------------
 // Host detection spawns real processes (lsappinfo/ps on macOS, tasklist on
 // Windows — expensive there and AV-scanned). Poll fast only while the user is
-// plausibly about to click the pill; idle machines get a slow heartbeat.
+// plausibly about to click the pill; idle machines get a slow heartbeat, and a
+// HIDDEN pill (dismissed or not on screen) backs off further still — host
+// freshness only matters again at the show edge, which takes its own reading.
 // Windows idles slower still because its per-spawn cost dwarfs macOS's.
-function hostPollDelayMs({ testMode = false, engaged = false, platform = process.platform } = {}) {
+function hostPollDelayMs({ testMode = false, engaged = false, visible = true, platform = process.platform } = {}) {
   if (testMode) return 1500;
   if (engaged) return platform === "win32" ? 3000 : 1500;
+  if (!visible) return platform === "win32" ? 45000 : 30000;
   return platform === "win32" ? 20000 : 10000;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "relay-companion",
-  "version": "0.1.72",
+  "version": "0.1.74",
   "description": "Relay companion for ordinary messages, with dormant coordination features available only by explicit opt-in.",
   "type": "module",
   "bin": {

package/src/task-daemon.js

@@ -123,6 +123,13 @@ async function pollVisibleTaskEvents({ client, ledger, tasks, log }) {
   return visibleEvents;
 }
 
+// Content signature for the ledger write-skip below. updatedAt is stamped fresh
+// on every write by design, so it is excluded — with it included no two polls
+// could ever match and the skip would be dead code.
+export function ledgerContentSignature(ledger) {
+  return JSON.stringify({ ...ledger, updatedAt: null });
+}
+
 // The ledger's dedupe maps grow forever (processedMessages, taskEvents, plainRelays,
 // notifications, sessions). Left unbounded, the daemon JSON.parse+stringify+fsyncs a
 // multi-megabyte file every 4s poll. Keep the newest N entries by processedAt so the
@@ -241,9 +248,13 @@ export async function pollOrdinaryRelayOnce({
   stagePlainRelay = defaultStagePlainRelayItem,
 } = {}) {
   const ledger = readTaskLedger();
+  // Write-skip (2026-08-05 always-on-cost audit): an idle account rewrote an
+  // identical ~150KB ledger every 4s poll, forever. Only touch the disk when a
+  // poll actually changed the dedupe state.
+  const ledgerBaseline = ledgerContentSignature(ledger);
   const ordinaryRelays = await pollPlainInbox({ client, ledger, stagePlainRelay, log });
   pruneLedger(ledger);
-  writeTaskLedger(ledger);
+  if (ledgerContentSignature(ledger) !== ledgerBaseline) writeTaskLedger(ledger);
   return { ordinaryRelays };
 }
 
@@ -255,6 +266,7 @@ export async function pollTaskRuntimeOnce({
   adapters,
 } = {}) {
   const ledger = readTaskLedger();
+  const ledgerBaseline = ledgerContentSignature(ledger); // see pollOrdinaryRelayOnce
   let inbox = { messages: [], sessions: [] };
   try {
     inbox = await client.agentInbox();
@@ -349,7 +361,7 @@ export async function pollTaskRuntimeOnce({
 
   const humanPolling = await pollHumanNotifications({ client, ledger, stageCompanionItem, stagePlainRelay, log });
   pruneLedger(ledger);
-  writeTaskLedger(ledger);
+  if (ledgerContentSignature(ledger) !== ledgerBaseline) writeTaskLedger(ledger);
   return {
     sessions: touched,
     messages: processedMessages,