relay-companion 0.1.71 → 0.1.73

package/bin/relay.js

@@ -28,6 +28,7 @@ import { pillStatusPath, waitForPillReady } from "../src/pill-control.js";
 import { liveToolRequirement, requiredLiveHosts, shouldRequireLiveTools } from "../src/setup-activation.js";
 import { openRelay, openTask } from "../src/materializer.js";
 import { runClaudeHook } from "../src/claude-hook.js";
+import { normalizePairingCode, persistPairedAccount } from "../src/account.js";
 import { resetCompanionStateForAccount } from "../src/notifications.js";
 import { finishSetupOpenRelay, normalizeSetupHost, setupOpenRelayToken, setupOpenStatus } from "../src/setup-open.js";
 
@@ -95,8 +96,10 @@ async function cmdPair(flags, { promptForDefaults = true } = {}) {
   }
   writeConfig({ apiUrl: url, webUrl: appUrl });
   const client = new RelayClient({ url });
-  const res = await client.registerDevice({ pairingCode: code, name, platform: process.platform });
-  writeConfig({ apiUrl: url, webUrl: appUrl, deviceToken: res.deviceToken, deviceId: res.deviceId, user: res.user });
+  const res = await client.registerDevice({ pairingCode: normalizePairingCode(code), name, platform: process.platform });
+  // The same persistence the pill's Settings tab uses (src/account.js), so the
+  // stored credential shape can never drift between the two pairing surfaces.
+  persistPairedAccount({ apiUrl: url, webUrl: appUrl, deviceName: name, registration: res });
   resetCompanionStateForAccount({ user: res.user, deviceId: res.deviceId });
   console.log(`Paired as ${res.user.name} <${res.user.email}>. This device is now connected to Relay.`);
 }

package/overlay/inbox.html

@@ -647,6 +647,62 @@
   }
   .sent-chip.read { background:rgba(46,160,67,.14); color:#1a7f37; border:1px solid rgba(46,160,67,.28); }
   .sent-chip.unread { background:transparent; color:var(--muted-2); border:1px solid rgba(31,26,23,.18); }
+
+  /* ---- Settings tab ---- */
+  /* The account block is flat content on the sheet, like rows: serif identity,
+     sans metadata, a tinted avatar disc. Depth only ever comes from tint and
+     the reused .open-actions light-built panel — never from borders. */
+  .sv-head { display:flex; align-items:center; justify-content:space-between; padding:10px 16px 8px; }
+  .sv-title { font-family:var(--serif); font-size:16px; font-weight:500; color:var(--ink); }
+  .sv-account { display:flex; align-items:center; gap:12px; padding:4px 16px 0; }
+  .sv-avatar {
+    flex:0 0 auto; width:38px; height:38px; border-radius:50%;
+    background:var(--accent-soft); color:var(--accent);
+    font-size:13px; font-weight:600; letter-spacing:.02em;
+    display:flex; align-items:center; justify-content:center;
+  }
+  .sv-id { min-width:0; display:flex; flex-direction:column; }
+  .sv-name { font-family:var(--serif); font-size:16px; font-weight:500; color:var(--ink); line-height:1.25; white-space:nowrap; overflow:hidden; text-overflow:ellipsis; }
+  .sv-email { font-size:11.5px; color:var(--muted); margin-top:1px; white-space:nowrap; overflow:hidden; text-overflow:ellipsis; }
+  .sv-device { font-size:11px; color:var(--muted-2); margin-top:2px; white-space:nowrap; overflow:hidden; text-overflow:ellipsis; }
+  .sv-copy { padding:2px 16px 0; font-size:12px; line-height:1.5; color:var(--muted); }
+  .sv-actions { margin:14px 12px 0; }
+  /* armed sign-out: the same flat menu row, flipped to the danger ink */
+  .oa-item.sv-signout-armed { color:#b4332a; }
+  .oa-item.sv-signout-armed:hover { background:rgba(180,51,42,.07); }
+  .oa-item.sv-signout-armed:active { background:rgba(180,51,42,.12); }
+  /* inline pairing-code entry: mono, tracked, uppercase — the code is the content */
+  .sv-pair { display:flex; gap:8px; margin:12px 16px 0; align-items:center; }
+  .sv-code {
+    flex:1 1 auto; min-width:0; appearance:none;
+    border:1px solid rgba(31,26,23,.14); border-radius:9px; padding:8px 11px;
+    font-family:var(--mono); font-size:13px; letter-spacing:.14em; text-transform:uppercase;
+    color:var(--ink); background:#fff; outline:none;
+    transition:border-color .15s var(--settle), box-shadow .15s var(--settle);
+  }
+  .sv-code::placeholder { font-family:var(--sans); letter-spacing:0; text-transform:none; color:var(--muted-3); }
+  .sv-code:focus { border-color:rgba(48,85,102,.42); box-shadow:0 0 0 3px rgba(48,85,102,.08); }
+  .sv-connect {
+    flex:0 0 auto; appearance:none; border:0; background:var(--accent); color:#fff;
+    font-family:var(--sans); font-size:12.5px; font-weight:600; padding:8px 15px; border-radius:9px;
+    cursor:pointer; transition:opacity .2s var(--settle);
+  }
+  .sv-connect:hover { opacity:.9; }
+  .sv-connect:disabled { opacity:.4; cursor:default; }
+  .sv-hint { padding:7px 16px 0; font-size:11px; line-height:1.45; color:var(--muted-2); }
+  .sv-err { margin-top:8px; padding:0 16px; }
+  .sv-note { padding:10px 16px 0; font-size:11.5px; color:#1a7f37; line-height:1.4; }
+  .sv-version { padding:20px 16px 12px; font-family:var(--mono); font-size:10.5px; color:var(--muted-3); }
+  /* signed-out call-to-action on the Relays empty state — quiet filled pill (th-count language) */
+  .sv-signin-banner {
+    appearance:none; border:0; cursor:pointer; margin-top:2px;
+    font-family:var(--sans); font-size:12px; font-weight:600; letter-spacing:.01em;
+    color:var(--accent); background:color-mix(in srgb, var(--accent) 9%, transparent);
+    box-shadow:inset 0 0 0 0.5px color-mix(in srgb, var(--accent) 14%, transparent);
+    border-radius:999px; padding:7px 15px;
+    transition:background-color .2s var(--settle);
+  }
+  .sv-signin-banner:hover { background:color-mix(in srgb, var(--accent) 15%, transparent); }
 </style>
 </head>
 <body>
@@ -684,6 +740,7 @@
       </button>
       <button class="tab" type="button" data-view="sent">Sent</button>
       <button class="tab" type="button" data-view="contacts">Contacts</button>
+      <button class="tab" type="button" data-view="settings">Settings</button>
       <button class="mark-all-read gone" id="markAllRead" type="button">Mark all as read</button>
     </nav>
 
@@ -697,6 +754,7 @@
           </svg>
           <div class="t1">No relays yet</div>
           <div class="t2">Questions, results, and notices will land here.</div>
+          <button class="sv-signin-banner gone" id="signInBanner" type="button">Sign in to Relay</button>
         </div>
       </section>
 
@@ -767,6 +825,9 @@
         <div class="cv-list" id="cvList"></div>
         <div id="contactsEmpty" class="cv-empty gone">No contacts yet.<br>Add someone, or your agent saves them as you relay.</div>
       </section>
+
+      <!-- Settings view (account card + sign-out / switch-account; rendered by JS) -->
+      <section class="view hidden" id="settingsView"></section>
     </div>
   </div>
 
@@ -811,6 +872,8 @@
   const thBackEl = document.getElementById("thBack");
   const thDetailNameEl = document.getElementById("thDetailName");
   const thHistoryEl = document.getElementById("thHistory");
+  const settingsViewEl = document.getElementById("settingsView");
+  const signInBannerEl = document.getElementById("signInBanner");
 
   const REDUCED = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
   const EXPANDED = { w: 344, h: 524 };
@@ -2582,6 +2645,201 @@
     applyView();
   }
 
+  // ---------- Settings view ----------
+  // The account card + sign-out / switch-account lifecycle. Renders from its own
+  // relay:accountInfo load (like Contacts), never from inbox pushes, so a typed
+  // pairing code is never rebuilt away mid-entry. Switch/sign-out succeed by
+  // RESTARTING the pill into the new account, so the success note is brief.
+  let settingsInfo = null;      // last relay:accountInfo payload (null while loading)
+  let settingsLoadSeq = 0;
+  let svPairOpen = false;       // inline code-entry row revealed
+  let svDraft = "";             // pairing-code text preserved across re-renders
+  let svBusy = false;           // pair / sign-out in flight
+  let svNote = "";              // success note while the pill restarts
+  let svError = "";
+  let svSignOutArmed = false;
+  let svSignOutTimer = null;
+  let svFocusCodeOnce = false;
+
+  function resetSignOutArm() {
+    svSignOutArmed = false;
+    if (svSignOutTimer) { clearTimeout(svSignOutTimer); svSignOutTimer = null; }
+  }
+  function svPairRowHtml() {
+    return `
+      <div class="sv-pair" data-stop="1">
+        <input class="sv-code" id="svCode" type="text" inputmode="text" autocomplete="off" spellcheck="false"
+          maxlength="16" placeholder="Pairing code" value="${esc(svDraft)}" ${svBusy ? "disabled" : ""} />
+        <button class="sv-connect" type="button" id="svConnect" ${svBusy ? "disabled" : ""}>${svBusy ? "Connecting…" : "Connect"}</button>
+      </div>
+      <div class="sv-hint">Your browser opened the Relay setup page — paste the pairing code it shows.</div>`;
+  }
+  function renderSettings() {
+    if (activeView !== "settings") return;
+    const info = settingsInfo;
+    if (!info) {
+      settingsViewEl.innerHTML = '<div class="td-quiet">Loading account…</div>';
+      return;
+    }
+    let html = "";
+    if (info.paired) {
+      const name = info.name || info.email || "Relay account";
+      html += `
+        <div class="sv-head"><span class="sv-title">Your account.</span></div>
+        <div class="sv-account">
+          <span class="sv-avatar">${esc(cvInitials(info.name, info.email))}</span>
+          <span class="sv-id">
+            <span class="sv-name">${esc(name)}</span>
+            ${info.email ? `<span class="sv-email">${esc(info.email)}</span>` : ""}
+            <span class="sv-device">This device · ${esc(info.deviceName || "")}</span>
+          </span>
+        </div>
+        <div class="open-actions sv-actions" data-stop="1" role="menu">
+          <button class="oa-item oa-primary" type="button" role="menuitem" id="svSwitch" ${svBusy ? "disabled" : ""}>Switch Account…</button>
+          <div class="oa-sep" role="separator"></div>
+          <button class="oa-item${svSignOutArmed ? " sv-signout-armed" : ""}" type="button" role="menuitem" id="svSignOut" ${svBusy ? "disabled" : ""}>${svSignOutArmed ? "Sign Out — click again to confirm" : "Sign Out"}</button>
+        </div>`;
+    } else {
+      html += `
+        <div class="sv-head"><span class="sv-title">Sign in to Relay.</span></div>
+        <div class="sv-copy">This device isn’t connected to an account yet. Sign in from your browser, then enter the pairing code here.</div>
+        <div class="open-actions sv-actions" data-stop="1" role="menu">
+          <button class="oa-item oa-primary" type="button" role="menuitem" id="svSwitch" ${svBusy ? "disabled" : ""}>Sign In to Relay</button>
+        </div>`;
+    }
+    if (svPairOpen) html += svPairRowHtml();
+    if (svNote) html += `<div class="sv-note">${esc(svNote)}</div>`;
+    html += `<div class="row-err sv-err" id="svErr">${esc(svError)}</div>`;
+    html += `<div class="sv-version">${esc(info.version ? `Relay ${info.version}` : "Relay")}</div>`;
+    settingsViewEl.innerHTML = html;
+    wireSettings();
+  }
+  function wireSettings() {
+    for (const z of settingsViewEl.querySelectorAll('[data-stop="1"]')) {
+      z.addEventListener("click", (e) => e.stopPropagation());
+    }
+    const switchEl = document.getElementById("svSwitch");
+    if (switchEl) switchEl.addEventListener("click", beginPairFlow);
+    const signOutEl = document.getElementById("svSignOut");
+    if (signOutEl) signOutEl.addEventListener("click", onSignOutClick);
+    const connectEl = document.getElementById("svConnect");
+    if (connectEl) connectEl.addEventListener("click", submitPairCode);
+    const codeEl = document.getElementById("svCode");
+    if (codeEl) {
+      // Same focusability contract as the contact form / quick reply: the window
+      // may take keyboard focus only while a text field needs it.
+      codeEl.addEventListener("focus", () => { if (window.relay.setFocusable) window.relay.setFocusable(true); });
+      codeEl.addEventListener("blur", () => { if (activeView !== "contacts" && window.relay.setFocusable) window.relay.setFocusable(false); });
+      codeEl.addEventListener("mousedown", () => setInteractive(true));
+      codeEl.addEventListener("input", () => {
+        svDraft = codeEl.value;
+        svError = "";
+        const errEl = document.getElementById("svErr");
+        if (errEl) errEl.textContent = ""; // clear inline, no rebuild mid-typing
+      });
+      codeEl.addEventListener("keydown", (ev) => {
+        if (ev.key === "Enter") { ev.preventDefault(); submitPairCode(); }
+      });
+      if (svFocusCodeOnce) {
+        svFocusCodeOnce = false;
+        if (window.relay.setFocusable) window.relay.setFocusable(true);
+        setTimeout(() => codeEl.focus(), 30);
+      }
+    }
+  }
+  // Switch account / sign in: open the pairing page in the browser and reveal
+  // the inline code-entry row in the same motion.
+  function beginPairFlow() {
+    if (svBusy) return;
+    resetSignOutArm();
+    svError = "";
+    svNote = "";
+    svPairOpen = true;
+    svFocusCodeOnce = true;
+    if (window.relay.openUrl) window.relay.openUrl((settingsInfo && settingsInfo.setupPath) || "/app/setup");
+    renderSettings();
+  }
+  async function submitPairCode() {
+    if (svBusy) return;
+    const codeEl = document.getElementById("svCode");
+    const code = (codeEl ? codeEl.value : svDraft).trim();
+    if (!code) {
+      svError = "Enter the pairing code from your browser.";
+      renderSettings();
+      return;
+    }
+    svBusy = true;
+    svError = "";
+    renderSettings();
+    let res = null;
+    try {
+      res = await window.relay.pairWithCode({ code });
+    } catch (err) {
+      res = { ok: false, error: (err && err.message) || "Could not connect this device." };
+    }
+    svBusy = false;
+    if (res && res.ok) {
+      svDraft = "";
+      svPairOpen = false;
+      svNote = res.email ? `Connected as ${res.email} — restarting Relay…` : "Connected — restarting Relay…";
+    } else {
+      svError = (res && res.error) || "Could not connect this device.";
+    }
+    renderSettings();
+  }
+  // Sign out is destructive-ish (this device stops receiving relays), so the
+  // button arms on the first click and only a second click within 4s commits.
+  async function onSignOutClick() {
+    if (svBusy) return;
+    if (!svSignOutArmed) {
+      svSignOutArmed = true;
+      if (svSignOutTimer) clearTimeout(svSignOutTimer);
+      svSignOutTimer = setTimeout(() => {
+        svSignOutTimer = null;
+        svSignOutArmed = false;
+        renderSettings();
+      }, 4000);
+      renderSettings();
+      return;
+    }
+    resetSignOutArm();
+    svBusy = true;
+    svError = "";
+    svNote = "";
+    renderSettings();
+    let res = null;
+    try {
+      res = await window.relay.signOut();
+    } catch (err) {
+      res = { ok: false, error: (err && err.message) || "Could not sign out." };
+    }
+    svBusy = false;
+    if (res && res.ok) svNote = "Signed out — restarting Relay…";
+    else svError = (res && res.error) || "Could not sign out.";
+    renderSettings();
+  }
+  async function loadSettings() {
+    const seq = ++settingsLoadSeq;
+    let info = null;
+    try {
+      info = window.relay.accountInfo ? await window.relay.accountInfo() : null;
+    } catch {}
+    if (seq !== settingsLoadSeq) return; // navigated / reloaded while fetching
+    const prevSig = JSON.stringify(settingsInfo);
+    settingsInfo = info && info.ok !== false ? info : { paired: false, name: "", email: "", deviceName: "", version: "" };
+    // Unchanged info: leave the DOM alone so a focused code input (and its
+    // caret) survives the refresh that happens on every visit to the tab.
+    if (JSON.stringify(settingsInfo) !== prevSig) renderSettings();
+  }
+  if (signInBannerEl) signInBannerEl.addEventListener("click", (e) => {
+    e.stopPropagation();
+    activeView = "settings";
+    syncTabs();
+    applyView();
+    renderAll();
+    beginPairFlow(); // the banner IS the sign-in affordance: browser + code row
+  });
+
   // ---------- views / tabs ----------
   function syncTabs() {
     // taskDetail belongs to Sent; the thread-detail view belongs to Relays —
@@ -2595,6 +2853,13 @@
     sentViewEl.classList.toggle("hidden", activeView !== "sent");
     taskDetailViewEl.classList.toggle("hidden", activeView !== "taskDetail");
     contactsViewEl.classList.toggle("hidden", activeView !== "contacts");
+    settingsViewEl.classList.toggle("hidden", activeView !== "settings");
+    if (activeView === "settings") {
+      renderSettings(); // paint immediately from the last known info…
+      loadSettings();   // …then refresh it from config
+    } else {
+      resetSignOutArm(); // leaving the view disarms the confirm state
+    }
     if (activeView === "threads") {
       // Entered only by clicking a conversation row (threadDetailId set there).
       renderThreads();
@@ -2630,6 +2895,10 @@
 
   function renderAll() {
     syncDismissControl();
+    // Signed out: the Relays empty state carries a slim sign-in affordance.
+    if (signInBannerEl) {
+      signInBannerEl.classList.toggle("gone", !payload.account || payload.account.paired !== false);
+    }
     // Relays badge/count reflect only the items that show in the Relays tab
     // (the clean split keeps task_request / share_approval out of this count).
     const unread = (payload.relays || []).filter((r) => r.unread && isRelayListKind(r)).length;

package/overlay/main.cjs

@@ -62,6 +62,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 +133,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 +201,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 });
@@ -228,6 +253,24 @@ function loadRelayModules() {
   return relayModulesPromise;
 }
 
+// Account lifecycle deps (ESM, lazy like the modules above): src/account.js is
+// the shared pair/sign-out config persistence, src/notifications.js owns the
+// packet-store reset that re-stages the new account's inbox cleanly.
+let accountModulesPromise = null;
+function loadAccountModules() {
+  if (!accountModulesPromise) {
+    const accountUrl = pathToFileURL(path.join(__dirname, "..", "src", "account.js")).href;
+    const notificationsUrl = pathToFileURL(path.join(__dirname, "..", "src", "notifications.js")).href;
+    accountModulesPromise = Promise.all([import(accountUrl), import(notificationsUrl)])
+      .then(([account, notifications]) => ({ account, notifications }))
+      .catch((error) => {
+        accountModulesPromise = null;
+        throw error;
+      });
+  }
+  return accountModulesPromise;
+}
+
 let sentStagerPromise = null;
 function loadSentStager() {
   if (!sentStagerPromise) {
@@ -332,6 +375,118 @@ function account() {
   };
 }
 
+function pillVersion() {
+  try {
+    return String(require("../package.json").version || "");
+  } catch {
+    return "";
+  }
+}
+
+// The Settings account card: who this pill is signed in as, on which device,
+// running which build. deviceName is remembered from pairing when available.
+function accountInfo() {
+  const cfg = readConfigFile();
+  const user = cfg.user || {};
+  return {
+    ok: true,
+    paired: Boolean(deviceToken()),
+    name: user.name || "",
+    email: user.email || "",
+    deviceName: String(cfg.deviceName || "").trim() || os.hostname(),
+    version: pillVersion(),
+    setupPath: "/app/setup",
+  };
+}
+
+// After an account change the daemon must restart into the new credentials, or
+// it keeps polling (and staging) as the OLD account until its next launch.
+function restartCompanionDaemon() {
+  try {
+    let cmd = null;
+    let args = null;
+    if (process.platform === "darwin") {
+      const uid = typeof process.getuid === "function" ? process.getuid() : 501;
+      cmd = "/bin/launchctl";
+      args = ["kickstart", "-k", `gui/${uid}/work.relay.companion`];
+    } else if (process.platform === "win32") {
+      cmd = "cmd";
+      args = ["/c", 'schtasks /End /TN "Relay Companion Daemon" & schtasks /Run /TN "Relay Companion Daemon"'];
+    }
+    if (!cmd) return;
+    const child = spawn(cmd, args, { detached: true, stdio: "ignore" });
+    child.on("error", (error) => console.error("[overlay] daemon restart spawn failed:", error && error.message));
+    child.unref();
+  } catch (error) {
+    console.error("[overlay] daemon restart failed:", error && error.message);
+  }
+}
+
+// Relaunch the pill itself so every cache (sent, contacts, attention queue,
+// renderer state) is rebuilt from the new account. launchd / the Scheduled Task
+// respawns it; app.relaunch() covers a bare `relay pill` run. Delayed a beat so
+// the invoking IPC reply reaches the renderer first.
+function relaunchPillSoon() {
+  setTimeout(() => {
+    try {
+      app.relaunch();
+    } catch (error) {
+      console.error("[overlay] relaunch failed:", error && error.message);
+    }
+    app.exit(0);
+  }, 600);
+}
+
+// Switch account: register this device against the pairing code, persist the
+// fresh credentials with the SAME shape `relay pair` writes, wipe the local
+// packet store for the new account, then restart the daemon and the pill.
+async function pairWithCode(input) {
+  try {
+    const raw = input && typeof input === "object" ? input.code : input;
+    const [{ account: accountMod, notifications }, { RelayClient }] = await Promise.all([
+      loadAccountModules(),
+      loadRelayModules(),
+    ]);
+    const code = accountMod.normalizePairingCode(raw);
+    if (!code) return { ok: false, error: "Enter the pairing code from your browser." };
+    const deviceName = accountMod.deviceNameForPairing(readConfigFile());
+    const client = new RelayClient();
+    const res = await client.registerDevice({ pairingCode: code, name: deviceName, platform: process.platform });
+    accountMod.persistPairedAccount({ deviceName, registration: res });
+    notifications.resetCompanionStateForAccount(
+      { user: res.user, deviceId: res.deviceId, force: true },
+      { statePath: STATE_PATH },
+    );
+    restartCompanionDaemon();
+    relaunchPillSoon();
+    return { ok: true, email: (res.user && res.user.email) || "" };
+  } catch (error) {
+    const message = error && error.message ? error.message : String(error);
+    console.error("[overlay] pair with code failed:", message);
+    return { ok: false, error: message };
+  }
+}
+
+// Sign out: drop the credentials (keeping URLs + device name), wipe the local
+// packet store, then restart the daemon and the pill into the signed-out state.
+async function signOutAccount() {
+  try {
+    const { account: accountMod, notifications } = await loadAccountModules();
+    accountMod.persistSignedOutAccount();
+    notifications.resetCompanionStateForAccount(
+      { user: null, deviceId: "", force: true },
+      { statePath: STATE_PATH },
+    );
+    restartCompanionDaemon();
+    relaunchPillSoon();
+    return { ok: true };
+  } catch (error) {
+    const message = error && error.message ? error.message : String(error);
+    console.error("[overlay] sign out failed:", message);
+    return { ok: false, error: message };
+  }
+}
+
 // Turn an actionUrl (absolute https, or a relative path) into an absolute URL.
 function absoluteUrl(pathOrUrl) {
   const value = String(pathOrUrl || "").trim();
@@ -545,11 +700,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);
   }
@@ -569,6 +742,7 @@ async function refreshTasks() {
     tasksCache = [];
     return tasksCache;
   }
+  if (!deviceToken()) return tasksCache; // signed out: skip the poll entirely
   try {
     const client = await relayClient();
     const res = await client.listTasks();
@@ -593,7 +767,13 @@ 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 {
     const client = await relayClient();
     const res = await client.listContacts();
@@ -611,6 +791,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);
@@ -658,6 +839,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(() => {});
@@ -678,6 +860,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;
@@ -690,6 +887,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 {
@@ -713,6 +911,7 @@ const dwellMs = () => Number(process.env.RELAY_OVERLAY_NOTIFICATION_MS) || 7000;
 
 function idleSecondsSafe() {
   try {
+    perf.inc("idleQueries");
     return powerMonitor.getSystemIdleTime();
   } catch {
     return 0;
@@ -744,21 +943,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()) {
@@ -775,7 +988,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]),
   );
@@ -800,7 +1013,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);
@@ -818,7 +1031,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;
@@ -840,6 +1053,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;
@@ -849,12 +1070,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);
 }
@@ -883,6 +1113,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);
@@ -936,7 +1170,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).
@@ -1130,9 +1364,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);
@@ -1162,6 +1398,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);
     });
@@ -1530,6 +1767,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
@@ -1758,6 +1996,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],
@@ -1817,6 +2056,12 @@ function openUrlTarget(url) {
     return;
   }
   const target = absoluteUrl(url);
+  // Sandboxed harness runs must never pop the user's real browser (the same
+  // contract that keeps them from launching Claude/Codex).
+  if (process.env.RELAY_OVERLAY_TEST_NO_HOST_OPEN === "1") {
+    console.error("[overlay] test seam: suppressed external open:", target);
+    return;
+  }
   shell.openExternal(target).catch((error) => console.error("[overlay] open failed:", error && error.message));
 }
 
@@ -1825,7 +2070,21 @@ function openUrlTarget(url) {
 function anchorTopRight() {
   const display = screen.getDisplayNearestPoint(screen.getCursorScreenPoint()) || screen.getPrimaryDisplay();
   const wa = display.workArea;
-  return { x: wa.x + wa.width - WIN.width - MARGIN, y: wa.y + MARGIN, width: WIN.width, height: WIN.height };
+  const anchor = { x: wa.x + wa.width - WIN.width - MARGIN, y: wa.y + MARGIN, width: WIN.width, height: WIN.height };
+  if (process.env.RELAY_OVERLAY_TEST === "1") {
+    // Sandboxed harness runs must never materialize under the user's parked
+    // cursor: a pointer resting on the card holds notifications open BY DESIGN
+    // (macOS banners do the same), which would wedge every dwell-based scenario
+    // when the mouse happens to sit in the top-right corner. Flip the sandbox
+    // window to the opposite edge instead. Production placement is unchanged.
+    try {
+      const p = screen.getCursorScreenPoint();
+      const overlaps =
+        p.x >= anchor.x && p.x < anchor.x + anchor.width && p.y >= anchor.y && p.y < anchor.y + anchor.height;
+      if (overlaps) anchor.x = wa.x + MARGIN;
+    } catch {}
+  }
+  return anchor;
 }
 
 // Show the overlay window. Electron's forwarded-mousemove stream (the thing that
@@ -1837,6 +2096,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;
   }
@@ -1850,6 +2110,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
@@ -1858,6 +2119,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 });
   }
 }
 
@@ -1867,7 +2133,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();
   }
@@ -1889,6 +2171,7 @@ function refreshOverlayForActiveSpace({ force = false } = {}) {
 }
 
 function readHostProcesses(cb) {
+  perf.inc("spawns");
   if (process.platform === "win32") {
     execFile("tasklist", ["/FO", "CSV", "/NH"], cb);
     return;
@@ -1911,7 +2194,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
@@ -1920,9 +2203,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) -----------------------------
@@ -1955,6 +2244,12 @@ let hitTimer = null;
 let hitIgnoring = true; // mirrors the last setIgnoreMouseEvents call
 let hitHover = false;
 let lastHostProbeAt = 0;
+// Harness seam: a sandboxed e2e run shares the screen with the user's REAL
+// mouse, and a pointer that happens to rest on the card rect legitimately
+// holds notifications open (the macOS-banner rule) — wedging every dwell-based
+// scenario. The harness drives only synthetic input, so in this mode the hit
+// test ignores the physical cursor entirely. Never set outside the harness.
+const HIT_TEST_POINTER_BLIND = process.env.RELAY_OVERLAY_TEST_IGNORE_POINTER === "1";
 
 function applyIgnore(next) {
   if (next === hitIgnoring) return;
@@ -1995,6 +2290,14 @@ function scheduleHit(ms) {
 function hitTick() {
   hitTimer = null;
   if (!win || win.isDestroyed()) return;
+  if (HIT_TEST_POINTER_BLIND) {
+    // Interactive everywhere, hover never asserted: synthetic-input runs must
+    // not have their dwell/fold behavior steered by the user's parked mouse.
+    applyIgnore(false);
+    applyHover(false);
+    scheduleHit(POLL_HIDDEN_MS);
+    return;
+  }
   if (!win.isVisible()) {
     // A hidden window must never hold clicks, and must not cost a cursor read.
     applyIgnore(true);
@@ -2005,6 +2308,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 {
@@ -2137,13 +2441,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) })),
@@ -2151,13 +2471,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 }));
 }
@@ -2415,6 +2748,11 @@ ipcMain.handle("relay:contacts", () => readContacts());
 ipcMain.handle("relay:contactSave", (_e, input) => saveContact(input));
 ipcMain.handle("relay:contactDelete", (_e, input) => deleteContactFromBook(input));
 
+// Settings tab: account card + the sign-out / switch-account lifecycle.
+ipcMain.handle("relay:accountInfo", () => accountInfo());
+ipcMain.handle("relay:pairWithCode", (_e, input) => pairWithCode(input));
+ipcMain.handle("relay:signOut", () => signOutAccount());
+
 // 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
 // asks us to grant it while a field is open and revoke it the moment the form closes.
@@ -2434,6 +2772,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);
   }
 });
@@ -2563,9 +2902,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,
@@ -2582,6 +2938,7 @@ if (!gotSingleInstanceLock) {
         },
         setSentCache: (items) => {
           sentCache = Array.isArray(items) ? items : [];
+          sentFingerprint = sentFingerprintOf(sentCache);
           return pushInbox(true);
         },
         getWin: () => win,
@@ -2594,6 +2951,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/preload.cjs

@@ -46,6 +46,11 @@ contextBridge.exposeInMainWorld("relay", {
   contactSave: (input) => ipcRenderer.invoke("relay:contactSave", input),
   contactDelete: (input) => ipcRenderer.invoke("relay:contactDelete", input),
 
+  // settings / account (switch + sign-out relaunch the pill on success)
+  accountInfo: () => ipcRenderer.invoke("relay:accountInfo"),
+  pairWithCode: (input) => ipcRenderer.invoke("relay:pairWithCode", input),
+  signOut: () => ipcRenderer.invoke("relay:signOut"),
+
 
   // window plumbing
   setFocusable: (v) => ipcRenderer.send("relay:setFocusable", v),

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.71",
+  "version": "0.1.73",
   "description": "Relay companion for ordinary messages, with dormant coordination features available only by explicit opt-in.",
   "type": "module",
   "bin": {

package/src/account.js

@@ -0,0 +1,65 @@
+import os from "node:os";
+import { readConfig, writeConfigObject } from "./config.js";
+
+/**
+ * Account lifecycle for the companion: the ONE config-write shape shared by
+ * `relay pair` (bin/relay.js cmdPair) and the pill's Settings tab, so switching
+ * accounts from either surface persists identical credentials. The pure shapes
+ * are exported separately from the fs-touching persist helpers for unit tests.
+ */
+
+/**
+ * Pairing codes are 8 chars from an unambiguous uppercase alphabet
+ * (services/devices.ts). The server only trims + uppercases, so typed
+ * "abcd-efgh" / "ABCD EFGH" variants are folded here before the request.
+ */
+export function normalizePairingCode(raw) {
+  return String(raw ?? "")
+    .replace(/[\s-]+/g, "")
+    .toUpperCase();
+}
+
+/** The device name a re-pair should register: the remembered one, else the hostname. */
+export function deviceNameForPairing(config = readConfig()) {
+  const stored = String((config && config.deviceName) || "").trim();
+  return stored || os.hostname();
+}
+
+/**
+ * The post-registration config: everything the old config had, plus the fresh
+ * credentials. apiUrl/webUrl/deviceName are only written when explicitly given
+ * (the pill switches accounts without touching the URLs it was launched with).
+ */
+export function pairedAccountConfig(existing, { apiUrl, webUrl, deviceName, registration } = {}) {
+  const res = registration || {};
+  return {
+    ...(existing || {}),
+    ...(apiUrl ? { apiUrl } : {}),
+    ...(webUrl ? { webUrl } : {}),
+    ...(deviceName ? { deviceName } : {}),
+    deviceToken: res.deviceToken || "",
+    deviceId: res.deviceId || "",
+    user: res.user || null,
+  };
+}
+
+/**
+ * Sign-out clears the credential set — user, deviceToken, and the deviceId that
+ * belongs to that token — while preserving apiUrl/webUrl, the device name, the
+ * companion mode, and any other settings on the file.
+ */
+export function signedOutAccountConfig(existing) {
+  const next = { ...(existing || {}) };
+  delete next.user;
+  delete next.deviceToken;
+  delete next.deviceId;
+  return next;
+}
+
+export function persistPairedAccount({ apiUrl, webUrl, deviceName, registration } = {}) {
+  return writeConfigObject(pairedAccountConfig(readConfig(), { apiUrl, webUrl, deviceName, registration }));
+}
+
+export function persistSignedOutAccount() {
+  return writeConfigObject(signedOutAccountConfig(readConfig()));
+}

package/src/config.js

@@ -23,7 +23,9 @@ export function configDir() {
 }
 
 export function configPath() {
-  return path.join(configDir(), "config.json");
+  // RELAY_CONFIG (a full file path) matches the overlay's readConfigFile
+  // resolution, so a sandboxed pill and these helpers agree on ONE file.
+  return process.env.RELAY_CONFIG || path.join(configDir(), "config.json");
 }
 
 export function readConfig() {
@@ -51,19 +53,25 @@ export function readConfig() {
   }
 }
 
-export function writeConfig(patch) {
-  const dir = configDir();
-  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
-  const next = { ...readConfig(), ...patch };
+/**
+ * Replace config.json with exactly `next` (no merge). This is the primitive that
+ * lets sign-out REMOVE keys — writeConfig's patch merge can only add or overwrite.
+ */
+export function writeConfigObject(next) {
+  const file = configPath();
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
   // Atomic write: a crash mid-write must not truncate config.json and wipe the
   // device token (which would put the daemon into a launchd crash loop).
-  const file = configPath();
   const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
   fs.writeFileSync(tmp, JSON.stringify(next, null, 2), { mode: 0o600 });
   fs.renameSync(tmp, file);
   return next;
 }
 
+export function writeConfig(patch) {
+  return writeConfigObject({ ...readConfig(), ...patch });
+}
+
 export function apiUrl() {
   return (
     process.env.RELAY_API_URL ||

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,