relay-companion 0.1.40 → 0.1.41

package/bin/relay.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import os from "node:os";
 import path from "node:path";
+import { randomUUID } from "node:crypto";
 import { fileURLToPath } from "node:url";
 import { createRequire } from "node:module";
 import { spawnSync, spawn } from "node:child_process";
@@ -10,8 +11,9 @@ import { RelayClient } from "../src/client.js";
 import { writeConfig, readConfig, apiUrl, DEFAULT_API_URL, DEFAULT_WEB_URL } from "../src/config.js";
 import { runTaskDaemon, pollTaskRuntimeOnce } from "../src/task-daemon.js";
 import { runMcpServer } from "../src/mcp.js";
-import { runSetupInstall, runUninstall } from "../src/install.js";
+import { repairDesktopSurfaces, runSetupInstall, runUninstall } from "../src/install.js";
 import { runUpdateOnce } from "../src/auto-update.js";
+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 { resetCompanionStateForAccount } from "../src/notifications.js";
@@ -35,6 +37,16 @@ function parseFlags(argv) {
   return { flags, positional };
 }
 
+function companionVersion() {
+  try {
+    const require = createRequire(import.meta.url);
+    const pkg = require("../package.json");
+    return typeof pkg.version === "string" ? pkg.version : "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
 async function prompt(question, fallback = "") {
   const rl = readline.createInterface({ input: stdin, output: stdout });
   const answer = (await rl.question(question)).trim();
@@ -97,7 +109,7 @@ function printActivationStatus(activation) {
 }
 
 function statusAreaReopenText() {
-  if (process.platform === "darwin") return "the Relay icon in the menu bar";
+  if (process.platform === "darwin") return "the Relay app in Spotlight or the Relay icon in the menu bar";
   if (process.platform === "win32") return "the Relay icon in the system tray near the clock";
   return "the Relay icon in the system tray";
 }
@@ -180,6 +192,22 @@ async function cmdInstall() {
   await applyInstall({ requireLiveTools: shouldRequireLiveTools(), requiredHosts: requiredLiveHosts() });
 }
 
+function cmdRepairDesktop(flags = {}) {
+  const reload = !flags["no-restart"];
+  const repaired = repairDesktopSurfaces({ reload });
+  if (!repaired.ok) {
+    const failures = [
+      !repaired.daemon?.ok && `daemon: ${repaired.daemon?.reason || "install failed"}`,
+      !repaired.pill?.ok && `pill: ${repaired.pill?.reason || "install failed"}`,
+    ].filter(Boolean);
+    throw new Error(`Could not repair Relay desktop services (${failures.join(", ")}).`);
+  }
+  const appText = repaired.pill?.appPath ? ` Relay.app is installed at ${repaired.pill.appPath}.` : "";
+  const restartText = reload ? "Relay background services were reloaded." : "Relay background service files were refreshed without restarting them.";
+  console.log(`${restartText}${appText}`);
+  return repaired;
+}
+
 /** Remove the Relay tools from both agents and stop the background daemon. */
 async function cmdUninstall() {
   runUninstall();
@@ -274,8 +302,8 @@ async function cmdAnswerQuestion(flags) {
   console.log("Sent answer to Relay. The waiting task agent will resume on the next daemon poll.");
 }
 
-/** Launch the desktop Relay companion pill (Electron overlay). */
-function cmdPill() {
+/** Launch (or signal) the desktop Relay companion pill and verify it is visible. */
+async function cmdPill() {
   const here = path.dirname(fileURLToPath(import.meta.url));
   const overlayMain = path.resolve(here, "../overlay/main.cjs");
   // require("electron") returns the path to the electron binary when resolved under node.
@@ -293,25 +321,44 @@ function cmdPill() {
   if (typeof electronPath !== "string") {
     throw new Error("Could not resolve the Electron binary. Run `npm install` in packages/companion.");
   }
-  const child = spawn(electronPath, [overlayMain], {
+  const reopenNonce = `cli-${process.pid}-${randomUUID()}`;
+  let spawnError = null;
+  const child = spawn(electronPath, [overlayMain, "--relay-reopen", reopenNonce], {
     detached: true,
     stdio: "ignore",
     env: { ...process.env },
   });
+  child.on("error", (error) => {
+    spawnError = error;
+  });
   child.unref();
-  console.log(`Relay pill launched. It shows when Claude Code or Codex is running; reopen it from ${statusAreaReopenText()} after hiding it.`);
+  const result = await waitForPillReady(reopenNonce);
+  if (!result.ok) {
+    const detail = spawnError ? ` ${spawnError.message || spawnError}` : "";
+    throw new Error(
+      `Relay was started but did not confirm that its pill became visible.${detail} Check ${pillStatusPath()} and ~/.relay/pill.log.`,
+    );
+  }
+  console.log(`Relay pill is visible. Reopen it from ${statusAreaReopenText()} after hiding it.`);
 }
 
 async function main() {
   const [command, ...rest] = process.argv.slice(2);
   const { flags, positional } = parseFlags(rest);
   switch (command) {
+    case "version":
+    case "--version":
+    case "-v":
+      console.log(companionVersion());
+      return;
     case "setup":
       return cmdSetup(flags);
     case "pair":
       return cmdPair(flags);
     case "install":
       return cmdInstall();
+    case "repair-desktop":
+      return cmdRepairDesktop(flags);
     case "uninstall":
       return cmdUninstall();
     case "whoami":
@@ -341,10 +388,12 @@ async function main() {
           "",
           "Usage:",
           "  relay setup [--code CODE] [--name NAME]               Pair this machine and add Relay to Claude Code + Codex",
+          "  relay version                                         Print the installed Relay companion version",
           "  relay setup --code CODE --open-relay TOKEN --host codex|claude",
           "  relay setup --interactive                             Prompt for API URL and device name during setup",
           "  relay install                                         Add Relay to your agents (device already paired)",
           "  relay uninstall                                       Remove Relay from your agents and stop the daemon",
+          "  relay repair-desktop [--no-restart]                  Repair Relay.app and background services without changing MCP/account state",
           "  relay pair [--api URL] [--web URL] [--code CODE]      Pair this machine only (no agent install)",
           "  relay tasks                                           Pull and process task agent runtime once",
           "  relay open <id> --host claude|codex                  Materialize a staged Relay row into a native agent session",

package/overlay/host-select.cjs

@@ -11,12 +11,22 @@
 // desktop it breaks"). The running-process signal (from `ps`, which is Space-agnostic)
 // is the reliable tiebreaker, so it now sits ahead of the installed-preference default.
 
+const CLAUDE_DESKTOP_BUNDLE = "com.anthropic.claudefordesktop";
+const CODEX_DESKTOP_BUNDLES = ["com.openai.codex", "com.openai.chat"];
+
 function hostFromBundle(bundle) {
-  if (bundle === "com.anthropic.claudefordesktop") return "claude";
-  if (bundle === "com.openai.codex") return "codex";
+  if (bundle === CLAUDE_DESKTOP_BUNDLE) return "claude";
+  if (CODEX_DESKTOP_BUNDLES.includes(bundle)) return "codex";
   return null;
 }
 
+function activationBundleCandidates(host, observedBundle = null) {
+  if (host === "claude") return [CLAUDE_DESKTOP_BUNDLE];
+  if (host !== "codex") return [];
+  const observed = CODEX_DESKTOP_BUNDLES.includes(observedBundle) ? observedBundle : null;
+  return [...new Set([observed, ...CODEX_DESKTOP_BUNDLES].filter(Boolean))];
+}
+
 function isRelayBundle(bundle) {
   const clean = String(bundle || "").toLowerCase();
   return clean.includes("relay") || clean.includes("electron");
@@ -103,4 +113,31 @@ function runningHostsFromProcessList(text, platform = process.platform) {
   };
 }
 
-module.exports = { hostFromBundle, isRelayBundle, defaultClickHost, chooseClickHost, runningHostsFromProcessList };
+// Terminal Claude Code is useful diagnostic state, but it is not a desktop surface
+// Relay can foreground: Relay's Claude materializer opens a claude:// resume link in
+// Claude Desktop. Keep this separate from runningHostsFromProcessList so a terminal-
+// only process never diverts a click away from a usable Codex/ChatGPT desktop window.
+function terminalClaudeCodeRunningFromProcessList(text, platform = process.platform) {
+  const lines = String(text || "").split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+  if (platform === "darwin") {
+    return lines.some(
+      (line) =>
+        !/\.app\/Contents\//i.test(line) &&
+        /(?:^|\/)claude(?:-code)?(?:\.exe)?$/i.test(line),
+    );
+  }
+  if (platform === "win32") {
+    return lines.some((line) => /(?:^|[\\/\"])(?:claude-code|claude)(?:\.exe)?(?:\"|$)/i.test(line));
+  }
+  return lines.some((line) => /(?:^|\/)claude(?:-code)?$/i.test(line));
+}
+
+module.exports = {
+  hostFromBundle,
+  activationBundleCandidates,
+  isRelayBundle,
+  defaultClickHost,
+  chooseClickHost,
+  runningHostsFromProcessList,
+  terminalClaudeCodeRunningFromProcessList,
+};

package/overlay/main.cjs

@@ -29,8 +29,20 @@ const { execFile, execFileSync, spawn, pathToFileURL } = (() => {
   const url = require("node:url");
   return { execFile: cp.execFile, execFileSync: cp.execFileSync, spawn: cp.spawn, pathToFileURL: url.pathToFileURL };
 })();
-const { hostFromBundle, chooseClickHost, runningHostsFromProcessList } = require("./host-select.cjs");
-const { overlayWanted, createHostRunningTracker, shouldIgnoreDismiss, boundedPresentedRelayIds } = require("./visibility.cjs");
+const {
+  hostFromBundle,
+  activationBundleCandidates,
+  chooseClickHost,
+  runningHostsFromProcessList,
+  terminalClaudeCodeRunningFromProcessList,
+} = require("./host-select.cjs");
+const {
+  overlayWanted,
+  createHostRunningTracker,
+  shouldIgnoreDismiss,
+  boundedPresentedRelayIds,
+  recoverInterruptedAttentionPrefs,
+} = require("./visibility.cjs");
 const { withJsonLock } = require("../src/state-lock.cjs");
 const {
   reinforceSpacePresence,
@@ -41,6 +53,7 @@ const {
 
 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");
+const PILL_STATUS_PATH = path.join(RELAY_HOME, "pill-status.json");
 // The companion CLI entrypoint (same path the overlay resolves its ESM modules
 // from). Spawned with ELECTRON_RUN_AS_NODE so Electron runs it as plain Node.
 const RELAY_CLI = path.resolve(__dirname, "..", "bin", "relay.js");
@@ -56,6 +69,7 @@ let trayAvailable = false;
 let hostRunning = false; // Claude or Codex desktop app is running (either)
 let claudeRunning = false; // Claude Desktop process is running (any macOS Space)
 let codexRunning = false; // Codex process is running (any macOS Space)
+let terminalClaudeCodeRunning = false; // diagnostic only; not a foregroundable desktop host
 let lastHost = null; // most-recently foregrounded host: "claude" | "codex"
 let lastHostSeenAt = 0;
 let lastSig = "";
@@ -69,29 +83,71 @@ let overlayPrefs = {};
 try {
   overlayPrefs = JSON.parse(fs.readFileSync(OVERLAY_PREFS_PATH, "utf8")) || {};
 } catch {}
+const recoveredAttentionPrefs = recoverInterruptedAttentionPrefs(overlayPrefs);
+overlayPrefs = recoveredAttentionPrefs.prefs;
 let dismissed = overlayPrefs.dismissed === true;
 let attentionLatched = overlayPrefs.attentionLatched === true;
 const presentedRelayIds = new Set(
   Array.isArray(overlayPrefs.presentedRelayIds) ? overlayPrefs.presentedRelayIds.filter(Boolean).map(String) : [],
 );
+let activeAttentionIds = new Set();
 let ghostActive = false; // a ghost notification is on screen while dismissed
 let trayForcedVisible = false; // tray click while no host is running still shows the card
+let pillReady = false;
+let pendingReopenNonce = "";
+let lastReopenNonce = "";
+let lastPillStatusSig = "";
 const PRESENTED_RELAY_CAP = 500;
 function writeOverlayPrefs() {
   try {
     fs.mkdirSync(RELAY_HOME, { recursive: true });
     fs.writeFileSync(
       OVERLAY_PREFS_PATH,
-      `${JSON.stringify({ dismissed, attentionLatched, presentedRelayIds: [...presentedRelayIds] }, null, 2)}\n`,
+      `${JSON.stringify({ dismissed, attentionLatched, presentedRelayIds: [...presentedRelayIds], activeAttentionIds: [...activeAttentionIds] }, null, 2)}\n`,
     );
   } catch (error) {
     console.error("[overlay] prefs write failed:", error && error.message);
   }
 }
+// Commit startup recovery before Electron is ready. A second crash before the
+// recovered stack is rendered must still leave those ids eligible for replay.
+if (recoveredAttentionPrefs.interruptedAttentionIds.length) writeOverlayPrefs();
 function setDismissed(value) {
   dismissed = Boolean(value);
   writeOverlayPrefs();
 }
+
+function writePillStatus(reopenNonce = "") {
+  if (reopenNonce) lastReopenNonce = String(reopenNonce);
+  const stableStatus = {
+    pid: process.pid,
+    ready: pillReady,
+    visible: Boolean(win && !win.isDestroyed() && win.isVisible()),
+    dismissed: Boolean(dismissed),
+    reopenNonce: lastReopenNonce,
+    terminalClaudeCodeRunning,
+  };
+  const sig = JSON.stringify(stableStatus);
+  if (sig === lastPillStatusSig) return stableStatus;
+  const status = {
+    ...stableStatus,
+    updatedAt: new Date().toISOString(),
+  };
+  let tmp = "";
+  try {
+    fs.mkdirSync(RELAY_HOME, { recursive: true });
+    tmp = `${PILL_STATUS_PATH}.${process.pid}.${Date.now()}.tmp`;
+    fs.writeFileSync(tmp, `${JSON.stringify(status, null, 2)}\n`);
+    fs.renameSync(tmp, PILL_STATUS_PATH);
+    lastPillStatusSig = sig;
+  } catch (error) {
+    try {
+      if (tmp) fs.rmSync(tmp, { force: true });
+    } catch {}
+    console.error("[overlay] status write failed:", error && error.message);
+  }
+  return status;
+}
 function markRelaysPresented(ids, retainedUnreadIds = []) {
   const current = [...presentedRelayIds];
   const bounded = boundedPresentedRelayIds(
@@ -155,6 +211,15 @@ async function relayClient() {
 }
 
 app.setName("Relay");
+function reopenNonceFromArgs(argv) {
+  const args = Array.isArray(argv) ? argv.map(String) : [];
+  for (let i = 0; i < args.length; i += 1) {
+    if (args[i] === "--relay-reopen") return args[i + 1] || "";
+    if (args[i].startsWith("--relay-reopen=")) return args[i].slice("--relay-reopen=".length);
+  }
+  return "";
+}
+pendingReopenNonce = reopenNonceFromArgs(process.argv);
 // 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) {
@@ -164,7 +229,7 @@ if (process.env.RELAY_OVERLAY_USER_DATA) {
     console.error("[overlay] userData override failed:", error && error.message);
   }
 }
-const gotSingleInstanceLock = app.requestSingleInstanceLock();
+const gotSingleInstanceLock = app.requestSingleInstanceLock({ relayReopenNonce: pendingReopenNonce });
 
 // ---- config / account ----------------------------------------------------
 
@@ -446,7 +511,6 @@ let systemSuspended = false;
 let screenLocked = false;
 let loginSessionActive = true;
 let deferredAttention = false;
-let activeAttentionIds = new Set();
 let testAwayOverride = null;
 
 function userIsAway() {
@@ -499,9 +563,12 @@ function presentUnopenedStack(payload, unpresented) {
   trayForcedVisible = false;
   deferredAttention = false;
   maybeShow({ force: true });
-  win.webContents.send("newRelay", stack, { ghost: false, stacked: true });
   activeAttentionIds = new Set(stack.map((row) => row.id));
   markRelaysPresented(unpresented.map((row) => row.id), stack.map((row) => row.id));
+  // Persist the in-flight marker before renderer delivery. If the process dies at
+  // any point during the animation, startup recovery can replay the whole stack.
+  writeOverlayPrefs();
+  win.webContents.send("newRelay", stack, { ghost: false, stacked: true });
   syncTray();
   return true;
 }
@@ -733,14 +800,20 @@ function rememberForegroundHost(host) {
 // (good) but didnt foreground claude"). `open -b <bundle>` activates the app — switching
 // to its Space and launching it if it wasn't running. `-g` is intentionally NOT passed,
 // because raising the app is exactly the point.
-const HOST_BUNDLE_ID = { claude: "com.anthropic.claudefordesktop", codex: "com.openai.codex" };
-function activateHost(host) {
+function activateHost(host, observedBundle = null) {
   if (process.platform !== "darwin") return; // Windows foregrounding is handled by its own open path
-  const bundle = HOST_BUNDLE_ID[host];
-  if (!bundle) return;
-  execFile("/usr/bin/open", ["-b", bundle], (error) => {
-    if (error) console.error("[overlay] activateHost failed:", host, error && error.message);
-  });
+  const bundles = activationBundleCandidates(host, observedBundle);
+  const tryBundle = (index, lastError = null) => {
+    const bundle = bundles[index];
+    if (!bundle) {
+      if (lastError) console.error("[overlay] activateHost failed:", host, lastError && lastError.message);
+      return;
+    }
+    execFile("/usr/bin/open", ["-b", bundle], (error) => {
+      if (error) tryBundle(index + 1, error);
+    });
+  };
+  tryBundle(0);
 }
 
 function appInstalled(appName) {
@@ -1024,7 +1097,7 @@ async function openPacket(packetId, { sent = false } = {}) {
         // Raise the host so the relay is visible, whichever open path ran (Claude deep
         // link, Codex bridge, or a plain url). This is the fix for "opened in the right
         // host but didn't foreground it".
-        activateHost(host);
+        activateHost(host, bundle);
         if (url && !skipExternalOpen) {
           const webFallback = row && row.taskId ? taskWebUrl(row.taskId) : row && row.actionUrl ? absoluteUrl(row.actionUrl) : webBase();
           if (claudeSessionIdFromUrl(url)) {
@@ -1099,7 +1172,7 @@ function openTaskDetail(taskId) {
         freshlyForged = Boolean(parsed.claudeFreshlyForged);
       } catch {}
       if (url || skipExternalOpen) {
-        activateHost(host); // raise the host so the opened task is visible
+        activateHost(host, bundle); // raise the host so the opened task is visible
         if (url && !skipExternalOpen) {
           if (claudeSessionIdFromUrl(url)) {
             openClaudeDeepLinkVerified(url, taskWebUrl(taskId), taskId, { freshlyForged });
@@ -1193,6 +1266,7 @@ function maybeShow({ force = false, reposition = true } = {}) {
     win.hide();
   }
   syncTray(); // keep the tray tooltip in step with the pill's actual visibility
+  writePillStatus();
 }
 
 function refreshOverlayForActiveSpace({ force = false } = {}) {
@@ -1222,6 +1296,7 @@ function updateHostRunningFromProcesses(text) {
   // not the frontmost app — the signal click routing uses to beat frontmost's
   // Space-blindness.
   const running = runningHostsFromProcessList(text, process.platform);
+  terminalClaudeCodeRunning = terminalClaudeCodeRunningFromProcessList(text, process.platform);
   claudeRunning = running.claudeRunning;
   codexRunning = running.codexRunning;
   hostRunning = hostTracker.update(claudeRunning, codexRunning);
@@ -1309,7 +1384,13 @@ function createWindow() {
     // 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));
+    pillReady = true;
+    // Relay is independently useful and searchable even when no host app happens to
+    // be open. A normal login launch still respects the persisted dismissed preference.
+    maybeShow({ force: true });
     pollHosts();
+    if (pendingReopenNonce) requestExternalReopen(pendingReopenNonce);
+    else writePillStatus();
   });
 
   try {
@@ -1421,6 +1502,20 @@ function showFromTray() {
   syncTray();
 }
 
+// Spotlight's Relay.app and `relay pill` both launch another copy of the overlay.
+// Electron forwards that launch to this single-instance owner. Treat it exactly like
+// an explicit "Show Relay" action: revoke any old dismissal, open the full card, and
+// acknowledge the caller only after the OS window reports visible.
+function requestExternalReopen(reopenNonce = "") {
+  if (reopenNonce) pendingReopenNonce = String(reopenNonce);
+  if (!pillReady || !win || win.isDestroyed()) return false;
+  const nonce = pendingReopenNonce;
+  pendingReopenNonce = "";
+  showFromTray();
+  writePillStatus(nonce);
+  return pillIsOnScreen();
+}
+
 // Whether the pill card is actually on screen right now.
 function pillIsOnScreen() {
   return Boolean(win && !win.isDestroyed() && win.isVisible() && !dismissed);
@@ -1438,6 +1533,7 @@ function hideFromTray() {
   trayForcedVisible = false;
   if (win && !win.isDestroyed() && win.isVisible()) win.hide();
   syncTray();
+  writePillStatus();
 }
 
 let lastTrayToggleAt = 0;
@@ -1566,7 +1662,9 @@ ipcMain.on("relay:dismiss", () => {
   if (shouldIgnoreDismiss({ now: Date.now(), lastTrayShowAt })) return;
   lastTrayShowAt = 0; // honored: clear the guard so it can't linger
   if (!trayAvailable) {
-    setDismissed(false);
+    dismissed = false;
+    activeAttentionIds = new Set();
+    writeOverlayPrefs();
     ghostActive = false;
     trayForcedVisible = true;
     maybeShow();
@@ -1580,6 +1678,7 @@ ipcMain.on("relay:dismiss", () => {
   ghostActive = false;
   trayForcedVisible = false;
   if (win && !win.isDestroyed() && win.isVisible()) win.hide();
+  writePillStatus();
 });
 // The user engaged with a ghost notification (tapped the lockup to expand it):
 // the card is fully open again, so leave dismissed mode.
@@ -1593,6 +1692,7 @@ ipcMain.on("relay:undismiss", () => {
 ipcMain.on("relay:notifDone", () => {
   ghostActive = false;
   if (dismissed && win && !win.isDestroyed() && win.isVisible()) win.hide();
+  writePillStatus();
 });
 // The notification stack completed its visible interval and folded into the pill.
 // Main tracks this boundary so a later lock does not replay a stack the user already
@@ -1605,7 +1705,10 @@ ipcMain.on("relay:attentionDone", (_event, ids) => {
   // it pending for their next input. This covers walking away just before an arrival,
   // not only explicit sleep/lock events.
   if (userIsAway()) requeueActiveAttention();
-  else activeAttentionIds = new Set();
+  else {
+    activeAttentionIds = new Set();
+    writeOverlayPrefs();
+  }
 });
 ipcMain.handle("relay:soundBytes", (_e, name) => {
   const clean = String(name).replace(/[^A-Za-z]/g, "");
@@ -1625,12 +1728,18 @@ ipcMain.handle("relay:soundBytes", (_e, name) => {
 if (!gotSingleInstanceLock) {
   app.quit();
 } else {
-  app.on("second-instance", () => {
-    if (!win || win.isDestroyed()) return;
+  app.on("second-instance", (_event, argv, _workingDirectory, additionalData = {}) => {
+    const nonce =
+      (additionalData && typeof additionalData.relayReopenNonce === "string" && additionalData.relayReopenNonce) ||
+      reopenNonceFromArgs(argv);
     pollHosts();
-    maybeShow();
+    requestExternalReopen(nonce);
   });
 
+  // LaunchServices may reactivate the existing process instead of executing the
+  // launcher again. Activation is still an explicit user request to restore Relay.
+  app.on("activate", () => requestExternalReopen());
+
   app.whenReady().then(() => {
     if (process.platform === "darwin" && app.dock) app.dock.hide(); // accessory: no dock icon, no NC banners
     createWindow();
@@ -1642,6 +1751,8 @@ if (!gotSingleInstanceLock) {
     if (process.env.RELAY_OVERLAY_TEST === "1") {
       global.__relayTest = {
         showFromTray,
+        requestExternalReopen,
+        writePillStatus,
         toggleFromTray,
         pillIsOnScreen,
         maybeShow,
@@ -1663,6 +1774,7 @@ if (!gotSingleInstanceLock) {
           ghostActive,
           trayForcedVisible,
           hostRunning,
+          terminalClaudeCodeRunning,
           deferredAttention,
           presentedRelayIds: [...presentedRelayIds],
           activeAttentionIds: [...activeAttentionIds],

package/overlay/relayAppIcon.svg

@@ -0,0 +1,27 @@
+<svg width="1024" height="1024" viewBox="0 0 32 32" xmlns="http://www.w3.org/2000/svg">
+  <defs>
+    <linearGradient id="relayGradient" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#C1C1FA"/>
+      <stop offset="16%" stop-color="#C0B1F9"/>
+      <stop offset="38%" stop-color="#7790F7"/>
+      <stop offset="58%" stop-color="#5F74F6"/>
+      <stop offset="82%" stop-color="#342CF5"/>
+      <stop offset="100%" stop-color="#3229F5"/>
+    </linearGradient>
+    <radialGradient id="relayHighlight" cx="28%" cy="4%" r="50%">
+      <stop offset="0%" stop-color="#C1C1FA"/>
+      <stop offset="36%" stop-color="#C0B1F9" stop-opacity="0.82"/>
+      <stop offset="100%" stop-color="#C0B1F9" stop-opacity="0"/>
+    </radialGradient>
+    <radialGradient id="relayGlow" cx="72%" cy="36%" r="58%">
+      <stop offset="0%" stop-color="#7590F7" stop-opacity="0.82"/>
+      <stop offset="100%" stop-color="#7590F7" stop-opacity="0"/>
+    </radialGradient>
+  </defs>
+  <rect width="32" height="32" rx="7" fill="#f7f4ef"/>
+  <rect x="5.5" y="13.5" width="5" height="5" rx="0.5" fill="#D9704E"/>
+  <rect x="13.5" y="13.5" width="5" height="5" rx="0.5" fill="#111111"/>
+  <rect x="21.5" y="13.5" width="5" height="5" rx="0.5" fill="url(#relayGradient)"/>
+  <rect x="21.5" y="13.5" width="5" height="5" rx="0.5" fill="url(#relayHighlight)"/>
+  <rect x="21.5" y="13.5" width="5" height="5" rx="0.5" fill="url(#relayGlow)"/>
+</svg>

package/overlay/visibility.cjs

@@ -1,11 +1,13 @@
 // Pure overlay-visibility logic, extracted from main.cjs so the state machine that
 // decides when the pill window is on screen is unit-testable without Electron.
 //
-// The window is wanted when a host app is running (or the user explicitly clicked the
-// status-area icon), unless the user dismissed the pill — with a ghost notification
-// temporarily overriding a dismissal.
+// Relay is an independently installed desktop surface, not a child of Claude/Codex.
+// Keep it available whenever its background process runs; only an explicit dismissal
+// hides it. Host-running remains an input for click routing and backwards-compatible
+// callers, but closing an agent terminal/app must never make Relay disappear.
 
 function overlayWanted({
+  persistent = true,
   hostRunning = false,
   trayForcedVisible = false,
   trayAvailable = false,
@@ -14,7 +16,7 @@ function overlayWanted({
   attentionLatched = false,
 } = {}) {
   const dismissedEffective = trayAvailable && dismissed;
-  return (hostRunning || trayForcedVisible || attentionLatched) && (!dismissedEffective || ghostActive);
+  return (persistent || hostRunning || trayForcedVisible || attentionLatched) && (!dismissedEffective || ghostActive);
 }
 
 // Debounced "a host is running" tracker. The OFF transition requires `missThreshold`
@@ -72,4 +74,36 @@ function boundedPresentedRelayIds(currentIds, newlyPresentedIds, retainedUnreadI
   return [...ids];
 }
 
-module.exports = { overlayWanted, createHostRunningTracker, shouldIgnoreDismiss, boundedPresentedRelayIds };
+// An attention stack is recorded as presented before its seven-second animation
+// starts. If the process dies during that interval, the renderer never gets to send
+// `attentionDone`, so those ids must be put back into the unpresented pool on the next
+// launch. Clear the in-flight marker at the same time: if the new process also dies
+// before it can present the recovered stack, the ids are already absent from history
+// and remain eligible on the following launch.
+function recoverInterruptedAttentionPrefs(input = {}) {
+  const prefs = input && typeof input === "object" && !Array.isArray(input) ? input : {};
+  const activeAttentionIds = [...new Set(
+    (Array.isArray(prefs.activeAttentionIds) ? prefs.activeAttentionIds : [])
+      .map((value) => String(value || ""))
+      .filter(Boolean),
+  )];
+  const active = new Set(activeAttentionIds);
+  const presentedRelayIds = [...new Set(
+    (Array.isArray(prefs.presentedRelayIds) ? prefs.presentedRelayIds : [])
+      .map((value) => String(value || ""))
+      .filter(Boolean),
+  )].filter((id) => !active.has(id));
+
+  return {
+    prefs: { ...prefs, presentedRelayIds, activeAttentionIds: [] },
+    interruptedAttentionIds: activeAttentionIds,
+  };
+}
+
+module.exports = {
+  overlayWanted,
+  createHostRunningTracker,
+  shouldIgnoreDismiss,
+  boundedPresentedRelayIds,
+  recoverInterruptedAttentionPrefs,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "relay-companion",
-  "version": "0.1.40",
+  "version": "0.1.41",
   "description": "Relay companion: connects local coding agents to Relay tasks, approvals, and connector tools.",
   "type": "module",
   "bin": {
@@ -10,6 +10,7 @@
   "scripts": {
     "mcp": "node src/mcp.js",
     "daemon": "node src/task-daemon.js",
+    "postinstall": "node src/postinstall.js",
     "test": "node --test test/*.test.mjs"
   },
   "dependencies": {