relay-companion 0.1.22 → 0.1.24

package/bin/relay.js

@@ -96,6 +96,12 @@ function printActivationStatus(activation) {
   }
 }
 
+function statusAreaReopenText() {
+  if (process.platform === "darwin") return "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";
+}
+
 /** Register the Relay tools into Claude Code + Codex and start the receive daemon. */
 async function applyInstall({ requireLiveTools = false, requiredHosts = requiredLiveHosts() } = {}) {
   const { installed, missing, daemon, pill, activations = [] } = await runSetupInstall();
@@ -108,10 +114,18 @@ async function applyInstall({ requireLiveTools = false, requiredHosts = required
   if (daemon.ok) console.log("Relay is running in the background and will start automatically when you log in.");
   else if (daemon.reason === "autostart_unsupported_platform") {
     console.log("Run `relay daemon` to receive relays (background autostart is macOS-only for now).");
+  } else {
+    const detail = daemon.reason ? ` (${daemon.reason})` : "";
+    console.log(`Could not install Relay background autostart${detail}. Run \`relay daemon\` to receive relays.`);
   }
-  if (pill?.ok) console.log("The Relay pill is open and will start automatically when you log in.");
+  if (pill?.ok) console.log(`The Relay pill is open and will start automatically when you log in. Reopen it from ${statusAreaReopenText()} after hiding it.`);
   else if (pill?.reason === "pill_runtime_missing") {
     console.log("Run `relay pill` to open the Relay pill.");
+  } else if (pill?.reason === "autostart_unsupported_platform") {
+    console.log(`Run \`relay pill\` to open the Relay pill. Reopen it from ${statusAreaReopenText()} after hiding it.`);
+  } else if (pill) {
+    const detail = pill.reason ? ` (${pill.reason})` : "";
+    console.log(`Could not install Relay pill autostart${detail}. Run \`relay pill\` to open it.`);
   }
   const liveRequirement = liveToolRequirement({ activations, requiredHosts });
   if (requireLiveTools && installed.length && !liveRequirement.ok) {
@@ -280,7 +294,7 @@ function cmdPill() {
     env: { ...process.env },
   });
   child.unref();
-  console.log("Relay pill launched. It shows when Claude Code or Codex is running.");
+  console.log(`Relay pill launched. It shows when Claude Code or Codex is running; reopen it from ${statusAreaReopenText()} after hiding it.`);
 }
 
 async function main() {

package/overlay/inbox.html

@@ -103,8 +103,8 @@
     color:var(--accent); line-height:1; transition:color .3s var(--settle);
   }
   .count.zero { color:var(--muted-3); }
-  /* ✕ — fully hide the overlay; the Relay mark in the menu bar brings it back. Present in
-     every card state (expanded, pill, notification) so the pill is always escapable. */
+  /* ✕ — fully hide the overlay; the Relay mark in the OS status area brings it back.
+     Present in every card state (expanded, pill, notification) so the pill is always escapable. */
   .close-x {
     flex:0 0 auto; appearance:none; border:0; background:transparent; cursor:pointer;
     width:20px; height:20px; border-radius:6px; padding:0; margin-left:6px; margin-right:-6px;
@@ -114,6 +114,8 @@
   }
   .close-x:hover { color:var(--ink-2); background:rgba(31,26,23,.06); }
   .close-x:active { color:var(--ink); }
+  .close-x.unavailable { opacity:.38; cursor:default; }
+  .close-x.unavailable:hover { color:var(--muted-3); background:transparent; }
   @keyframes countRoll { from { transform:translateY(-6px); opacity:.3; } to { transform:none; opacity:1; } }
 
   /* tab control — individual rounded-rect buttons (the loved control) */
@@ -528,7 +530,7 @@
       <span class="spacer"></span>
       <span class="minimize-hint">Minimize</span>
       <span class="count zero" id="count">0</span>
-      <button class="close-x" id="closeX" type="button" aria-label="Hide Relay" title="Hide Relay — reopen from the menu bar">
+      <button class="close-x" id="closeX" type="button" aria-label="Hide Relay" title="Hide Relay - reopen from the Relay icon">
         <svg width="9" height="9" viewBox="0 0 10 10" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" aria-hidden="true"><path d="M1 1l8 8M9 1L1 9"/></svg>
       </button>
     </div>
@@ -737,7 +739,7 @@
     snapSize(EXPANDED.w, EXPANDED.h);
   }
   // ✕ — the card leaves gracefully, then the main process hides the window and keeps
-  // it hidden (persisted) until the menu-bar Relay mark is clicked.
+  // it hidden (persisted) until the status-area Relay mark is clicked.
   function dismissOverlay() {
     if (cardEl.classList.contains("bye")) return;
     if (ghostTimer) { clearTimeout(ghostTimer); ghostTimer = null; }
@@ -778,7 +780,7 @@
       dismissOverlay(); // rides the ghostOut exit, then main re-hides the window
     }, 7000);
   }
-  // Menu-bar Relay mark clicked: the card comes back FULLY OPEN (never the pill).
+  // Status-area Relay mark clicked: the card comes back FULLY OPEN (never the pill).
   function trayOpen() {
     const wasOffstage = cardEl.classList.contains("offstage") || cardEl.classList.contains("bye");
     if (ghostTimer) { clearTimeout(ghostTimer); ghostTimer = null; }
@@ -854,6 +856,7 @@
   closeXEl.addEventListener("mousedown", (e) => { e.stopPropagation(); });
   closeXEl.addEventListener("click", (e) => {
     e.stopPropagation();
+    if (closeXEl.disabled) return;
     dismissOverlay();
   });
 
@@ -1099,7 +1102,7 @@
 
   // ---------- state ----------
   let activeView = "relays";
-  let payload = { account: { paired: false }, relays: [], tasks: [], contacts: [] };
+  let payload = { account: { paired: false }, ui: { canDismiss: true, reopenSurface: "the Relay icon" }, relays: [], tasks: [], contacts: [] };
   let prevRelayIds = new Set();
   let contactsList = [];
   let cvEditing = null;
@@ -1928,6 +1931,7 @@
   }
 
   function renderAll() {
+    syncDismissControl();
     // 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;
@@ -1940,10 +1944,23 @@
     // contacts renders from its own load path
   }
 
+  function syncDismissControl() {
+    const ui = (payload && payload.ui) || {};
+    const canDismiss = ui.canDismiss !== false;
+    const surface = ui.reopenSurface || "the Relay icon";
+    closeXEl.disabled = !canDismiss;
+    closeXEl.classList.toggle("unavailable", !canDismiss);
+    closeXEl.title = canDismiss
+      ? `Hide Relay - reopen from ${surface}`
+      : "Hide Relay unavailable because the Relay status icon did not load.";
+    closeXEl.setAttribute("aria-label", canDismiss ? "Hide Relay" : "Relay status icon unavailable");
+  }
+
   function onPayload(next) {
     if (!next || typeof next !== "object") return;
     payload = {
       account: next.account || payload.account,
+      ui: next.ui || payload.ui,
       relays: Array.isArray(next.relays) ? next.relays : [],
       tasks: Array.isArray(next.tasks) ? next.tasks : [],
       contacts: Array.isArray(next.contacts) ? next.contacts : (payload.contacts || []),

package/overlay/main.cjs

@@ -7,9 +7,10 @@
 // click-through, so the overlay never blocks the app behind it.
 //
 // Visibility: the card carries a ✕ that hides the overlay entirely (persisted). The Relay
-// mark in the macOS menu bar (Tray) brings it back fully open. While dismissed, fresh
-// relays still show the designed banner as a "ghost" notification — the window appears
-// just for the banner, which fades away instead of folding back into a pill.
+// mark in the OS status area (macOS menu bar, Windows system tray) brings it back fully
+// open. While dismissed, fresh relays still show the designed banner as a "ghost"
+// notification — the window appears just for the banner, which fades away instead of
+// folding back into a pill.
 //
 // Data:
 //   - Relay attention rows come from ${RELAY_HOME:-~/.relay-companion}/state.json under
@@ -19,7 +20,7 @@
 //   - Mutations (accept/reject/approve/decline/answer) call RelayClient with device-token
 //     auth. ack/mark-read writes state.json directly (atomic temp+rename).
 
-const { app, BrowserWindow, Tray, ipcMain, nativeImage, shell, screen } = require("electron");
+const { app, BrowserWindow, Menu, Tray, ipcMain, nativeImage, shell, screen } = require("electron");
 const fs = require("node:fs");
 const os = require("node:os");
 const path = require("node:path");
@@ -43,6 +44,7 @@ const DEFAULT_WEB_BASE = "https://sendrelays.com";
 
 let win = null;
 let tray = null;
+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)
@@ -51,7 +53,7 @@ let lastHostSeenAt = 0;
 let lastSig = "";
 
 // Dismissed mode: the user clicked the ✕ on the card, so the overlay stays hidden
-// until they click the Relay menu-bar icon. Persisted across relaunches. While
+// until they click the Relay status-area icon. Persisted across relaunches. While
 // dismissed, a fresh relay still shows the designed notification (a "ghost" peek):
 // the window appears just for the banner, then hides again when it finishes.
 const OVERLAY_PREFS_PATH = path.join(RELAY_HOME, "overlay-prefs.json");
@@ -71,6 +73,12 @@ function setDismissed(value) {
   }
 }
 
+function reopenSurfaceName() {
+  if (process.platform === "darwin") return "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";
+}
+
 // The ESM companion modules (config/client) are loaded lazily via dynamic import,
 // because this overlay runs as CommonJS under Electron while the package is ESM.
 let relayModules = null;
@@ -306,6 +314,10 @@ async function buildPayload() {
   const [relays, contacts] = [readRelays(), await readContacts()];
   return {
     account: account(),
+    ui: {
+      canDismiss: trayAvailable,
+      reopenSurface: reopenSurfaceName(),
+    },
     relays,
     tasks: tasksCache,
     contacts,
@@ -326,7 +338,7 @@ async function pushInbox(force) {
       // newest arrival drives the peek. While dismissed, the same designed banner still
       // shows — as a "ghost": the window appears for the notification only, and the
       // renderer fades it out (never folding back into a pill) when it's done.
-      if (dismissed) {
+      if (trayAvailable && dismissed) {
         if (hostRunning) {
           ghostActive = true;
           showOverlayWindow();
@@ -499,6 +511,7 @@ function taskVersion(taskId) {
 
 // Best-effort frontmost-app bundle id (no permission prompt; uses lsappinfo).
 function frontmostBundleId(cb) {
+  if (process.platform !== "darwin") return cb(null);
   execFile("/usr/bin/lsappinfo", ["front"], (e1, asn) => {
     const a = String(asn || "").trim();
     if (e1 || !a) return cb(null);
@@ -518,10 +531,20 @@ function rememberForegroundHost(host) {
 function appInstalled(appName) {
   const name = String(appName || "").replace(/[^A-Za-z0-9 ._-]/g, "");
   if (!name) return false;
-  const candidates = [
-    path.join("/Applications", `${name}.app`),
-    path.join(os.homedir(), "Applications", `${name}.app`),
-  ];
+  let candidates = [];
+  if (process.platform === "darwin") {
+    candidates = [
+      path.join("/Applications", `${name}.app`),
+      path.join(os.homedir(), "Applications", `${name}.app`),
+    ];
+  } else if (process.platform === "win32") {
+    const exe = `${name}.exe`;
+    candidates = [
+      process.env.LOCALAPPDATA && path.join(process.env.LOCALAPPDATA, "Programs", name, exe),
+      process.env.PROGRAMFILES && path.join(process.env.PROGRAMFILES, name, exe),
+      process.env["PROGRAMFILES(X86)"] && path.join(process.env["PROGRAMFILES(X86)"], name, exe),
+    ].filter(Boolean);
+  }
   return candidates.some((candidate) => fs.existsSync(candidate));
 }
 
@@ -843,8 +866,9 @@ function showOverlayWindow() {
 function maybeShow() {
   if (!win || win.isDestroyed()) return;
   // Dismissed keeps the window hidden except while a ghost notification is up.
-  // trayForcedVisible honors an explicit menu-bar click even when no host runs.
-  const wanted = (hostRunning || trayForcedVisible) && (!dismissed || ghostActive);
+  // trayForcedVisible honors an explicit status-area click even when no host runs.
+  const dismissedEffective = trayAvailable && dismissed;
+  const wanted = (hostRunning || trayForcedVisible) && (!dismissedEffective || ghostActive);
   if (wanted) {
     showOverlayWindow();
   } else if (win.isVisible()) {
@@ -852,19 +876,38 @@ function maybeShow() {
   }
 }
 
-function pollHosts() {
-  // Show whenever EITHER host app is running; track the foregrounded one for click routing.
-  execFile("/bin/ps", ["-Ao", "comm"], (err, stdout) => {
-    const s = String(stdout || "");
+function readHostProcesses(cb) {
+  if (process.platform === "win32") {
+    execFile("tasklist", ["/FO", "CSV", "/NH"], cb);
+    return;
+  }
+  execFile("/bin/ps", ["-Ao", "comm"], cb);
+}
+
+function updateHostRunningFromProcesses(text) {
+  const s = String(text || "");
+  if (process.platform === "darwin") {
     // `ps` lists processes on every macOS Space, so this sees a host even when it is
     // not the frontmost app — the signal click routing uses to beat frontmost's
-    // Space-blindness. On a `ps` error, leave the last-known running state untouched
-    // rather than flapping both hosts to "not running".
-    if (!err) {
-      claudeRunning = /\/Claude\.app\/Contents\/MacOS\/Claude(\n|$)/.test(s);
-      codexRunning = /\/Codex\.app\/Contents\/MacOS\/Codex(\n|$)/.test(s);
-    }
-    hostRunning = claudeRunning || codexRunning;
+    // Space-blindness.
+    claudeRunning = /\/Claude\.app\/Contents\/MacOS\/Claude(\n|$)/.test(s);
+    codexRunning = /\/Codex\.app\/Contents\/MacOS\/Codex(\n|$)/.test(s);
+  } else if (process.platform === "win32") {
+    claudeRunning = /"Claude\.exe"/i.test(s);
+    codexRunning = /"Codex\.exe"/i.test(s);
+  } else {
+    claudeRunning = /(^|\n)Claude(\n|$)/.test(s) || /(^|\n)claude(\n|$)/.test(s);
+    codexRunning = /(^|\n)Codex(\n|$)/.test(s) || /(^|\n)codex(\n|$)/.test(s);
+  }
+  hostRunning = claudeRunning || codexRunning;
+}
+
+function pollHosts() {
+  // 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
+    // flapping both hosts to "not running".
+    if (!err) updateHostRunningFromProcesses(stdout);
     if (hostRunning) trayForcedVisible = false; // normal host-based visibility takes back over
     maybeShow();
   });
@@ -934,27 +977,59 @@ function createWindow() {
   setInterval(pollHosts, 1500);
 }
 
-// ---- menu bar (tray) -------------------------------------------------------
+// ---- OS status area (tray/menu bar) ----------------------------------------
+
+// The Relay mark lives in the OS status area: macOS menu bar, Windows system tray.
+// Clicking it brings the card back FULLY OPEN (never the folded pill) — the
+// counterpart to the card's ✕, which hides the overlay entirely.
+function createNonMacTrayIcon() {
+  const svg = `
+    <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 16 16">
+      <rect x="1" y="6" width="4" height="4" rx="0.6" fill="#D9704E"/>
+      <rect x="6" y="6" width="4" height="4" rx="0.6" fill="#F8FAFC"/>
+      <rect x="11" y="6" width="4" height="4" rx="0.6" fill="#3B82F6"/>
+    </svg>
+  `.trim();
+  const icon = nativeImage.createFromDataURL(`data:image/svg+xml;charset=utf-8,${encodeURIComponent(svg)}`);
+  return icon && !icon.isEmpty() ? icon.resize({ width: 16, height: 16 }) : null;
+}
+
+function createTrayIcon() {
+  const templateIcon = nativeImage.createFromPath(path.join(__dirname, "relayTrayTemplate.png"));
+  if (process.platform === "darwin") {
+    if (templateIcon && !templateIcon.isEmpty() && templateIcon.setTemplateImage) templateIcon.setTemplateImage(true);
+    return templateIcon && !templateIcon.isEmpty() ? templateIcon : null;
+  }
+  const icon = createNonMacTrayIcon();
+  return icon && !icon.isEmpty() ? icon : templateIcon && !templateIcon.isEmpty() ? templateIcon : null;
+}
+
+function showFromTray() {
+  setDismissed(false);
+  ghostActive = false;
+  if (!hostRunning) trayForcedVisible = true; // an explicit click always gets the card
+  maybeShow();
+  if (win && !win.isDestroyed()) win.webContents.send("openFull");
+}
 
-// The Relay mark lives in the macOS menu bar. Clicking it brings the card back
-// FULLY OPEN (never the folded pill) — the counterpart to the card's ✕, which
-// hides the overlay entirely. The *Template naming makes macOS tint the mark
-// for light/dark menu bars automatically.
 function createTray() {
-  const icon = nativeImage.createFromPath(path.join(__dirname, "relayTrayTemplate.png"));
-  if (icon.isEmpty()) {
-    console.error("[overlay] tray icon missing; menu bar reopen unavailable");
+  const icon = createTrayIcon();
+  if (!icon || icon.isEmpty()) {
+    trayAvailable = false;
+    setDismissed(false);
+    console.error("[overlay] tray icon missing; status-area reopen unavailable");
     return;
   }
   tray = new Tray(icon);
-  tray.setToolTip("Relay");
-  tray.on("click", () => {
-    setDismissed(false);
-    ghostActive = false;
-    if (!hostRunning) trayForcedVisible = true; // an explicit click always gets the card
-    maybeShow();
-    if (win && !win.isDestroyed()) win.webContents.send("openFull");
-  });
+  trayAvailable = true;
+  tray.setToolTip(`Relay - click to show the pill`);
+  tray.setContextMenu(
+    Menu.buildFromTemplate([
+      { label: "Show Relay", click: showFromTray },
+    ]),
+  );
+  tray.on("click", showFromTray);
+  tray.on("double-click", showFromTray);
 }
 
 // ---- ipc -----------------------------------------------------------------
@@ -1011,9 +1086,17 @@ ipcMain.on("relay:interactive", (_e, interactive) => {
 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));
 });
-// ✕ on the card: hide the overlay entirely until the menu-bar Relay mark is clicked.
+// ✕ on the card: hide the overlay entirely until the status-area Relay mark is clicked.
 // The renderer plays its exit animation first, then sends this.
 ipcMain.on("relay:dismiss", () => {
+  if (!trayAvailable) {
+    setDismissed(false);
+    ghostActive = false;
+    trayForcedVisible = true;
+    maybeShow();
+    if (win && !win.isDestroyed()) win.webContents.send("openFull");
+    return;
+  }
   setDismissed(true);
   ghostActive = false;
   trayForcedVisible = false;

package/overlay/preload.cjs

@@ -5,7 +5,7 @@ contextBridge.exposeInMainWorld("relay", {
   onInbox: (cb) => ipcRenderer.on("inbox", (_e, payload) => cb(payload)),
   onNewRelay: (cb) => ipcRenderer.on("newRelay", (_e, relay, opts) => cb(relay, opts || {})),
   onOpenDone: (cb) => ipcRenderer.on("openDone", (_e, id) => cb(id)),
-  onOpenFull: (cb) => ipcRenderer.on("openFull", () => cb()), // menu-bar icon clicked
+  onOpenFull: (cb) => ipcRenderer.on("openFull", () => cb()), // status-area icon clicked
   onShown: (cb) => ipcRenderer.on("shown", () => cb()), // window re-shown; reset hover handshake
 
   // pull the full payload on demand
@@ -38,7 +38,7 @@ contextBridge.exposeInMainWorld("relay", {
   setPos: (x, y) => ipcRenderer.send("relay:setPos", x, y),
   soundBytes: (name) => ipcRenderer.invoke("relay:soundBytes", name),
 
-  // dismissal (the card's ✕ / the menu-bar mark / ghost notifications)
+  // dismissal (the card's ✕ / the status-area mark / ghost notifications)
   dismiss: () => ipcRenderer.send("relay:dismiss"),
   undismiss: () => ipcRenderer.send("relay:undismiss"),
   notifDone: () => ipcRenderer.send("relay:notifDone"),

package/package.json

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

package/src/codex-desktop.js

@@ -46,7 +46,10 @@ export async function notifyCodexDesktopThreads({
   threadIds = [],
   pinnedThreadIds = null,
   openThreadId = null,
-  timeoutMs = Number(process.env.RELAY_CODEX_DESKTOP_TIMEOUT_MS || 4000),
+  primeOpen = true,
+  // The open path navigates hotkey -> (prime wait) -> /local inside the renderer,
+  // so the inspector eval must outlast RELAY_CODEX_OPEN_PRIME_MS; default higher.
+  timeoutMs = Number(process.env.RELAY_CODEX_DESKTOP_TIMEOUT_MS || 8000),
 } = {}) {
   if (process.env.RELAY_CODEX_DESKTOP_REFRESH === "0") return { attempted: false, reason: "disabled" };
   if (process.platform !== "darwin") return { attempted: false, reason: "not-darwin" };
@@ -59,7 +62,7 @@ export async function notifyCodexDesktopThreads({
   const pids = await findCodexMainPids();
   if (!pids.length) return { attempted: true, ok: false, reason: "codex-not-running", results: [] };
 
-  const expression = buildCodexDesktopRefreshExpression({ threadIds: ids, pinnedThreadIds: pinnedIds, openThreadId: openId });
+  const expression = buildCodexDesktopRefreshExpression({ threadIds: ids, pinnedThreadIds: pinnedIds, openThreadId: openId, primeOpen });
   const results = [];
   for (const pid of pids) {
     try {
@@ -88,9 +91,15 @@ export async function relayRefreshCodexRenderer(payload) {
   if (!bridge?.sendMessageFromView) return { ok: false, reason: "missing-electron-bridge" };
 
   const sent = [];
-  async function send(message) {
+  // Bound every bridge send. Some host messages (notably maybe-resume-conversation)
+  // can hang indefinitely; the original serial awaits then block the navigation
+  // that follows, leaving the thread unopened. Cap each send so the open proceeds.
+  async function send(message, timeoutMs = 2000) {
     try {
-      await bridge.sendMessageFromView(message);
+      await Promise.race([
+        bridge.sendMessageFromView(message),
+        new Promise((_, reject) => setTimeout(() => reject(new Error("send-timeout")), timeoutMs)),
+      ]);
       sent.push({ type: message.type, ok: true });
     } catch (error) {
       sent.push({ type: message.type, ok: false, error: String(error?.message || error) });
@@ -127,33 +136,52 @@ export async function relayRefreshCodexRenderer(payload) {
     await send({ type: "broadcast-conversation-snapshot-for-host", hostId, conversationId: threadId });
   }
   if (payload.openThreadId) {
-    try {
-      const encoded = encodeURIComponent(String(payload.openThreadId));
-      // Codex renders a thread through two separate router surfaces: the main
-      // window (sidebar + recents rail) at /local/<id>, and the borderless hotkey
-      // "quick chat" overlay at /hotkey-window/thread/<id>. The app's own
-      // navigation chooses between them by whether the current window is the
-      // hotkey one (its QH() keys off location.pathname). Mirror that here so the
-      // thread opens in whichever surface the user is actually in — otherwise
-      // every open is forced into the overlay even when the main window is up.
-      const path = location.pathname.startsWith("/hotkey-window")
-        ? `/hotkey-window/thread/${encoded}`
-        : `/local/${encoded}`;
-      window.postMessage({ type: "navigate-to-route", path }, location.origin);
-      sent.push({ type: "navigate-to-route", ok: true, threadId: payload.openThreadId, path });
-    } catch (error) {
-      sent.push({ type: "navigate-to-route", ok: false, error: String(error?.message || error) });
+    const encoded = encodeURIComponent(String(payload.openThreadId));
+    const navTo = (path) => {
+      try {
+        window.postMessage({ type: "navigate-to-route", path }, location.origin);
+        sent.push({ type: "navigate-to-route", ok: true, path });
+      } catch (error) {
+        sent.push({ type: "navigate-to-route", ok: false, path, error: String(error?.message || error) });
+      }
+    };
+    // Codex renders a thread through two router surfaces: the main window
+    // (sidebar + recents rail) at /local/<id>, and the borderless hotkey
+    // "quick chat" view at /hotkey-window/thread/<id>. Two facts drive the logic:
+    //   1. The app uses an in-memory router, so location.pathname is ALWAYS
+    //      /index.html — it never reveals the current route or window kind.
+    //   2. The /local/<id> route CANNOT cold-load an externally-created relay
+    //      thread: it renders the empty "New chat" state and never recovers.
+    //      Only /hotkey-window/thread/<id> loads such a thread from disk into the
+    //      renderer store. Once loaded, /local/<id> renders it fine.
+    // So to land the user in the main window WITH content, prime the load via the
+    // hotkey route, then switch to /local/<id> once it is warm. The hotkey view
+    // shows the thread during the prime, so the transition is content -> content,
+    // never a blank flash. The second materializer pass runs with primeOpen=false
+    // and just re-asserts /local (the thread is warm by then).
+    const inHotkeyWindow = /hotkey-window/.test(location.href) || /hotkey-window/.test(location.search || "");
+    const primeMs = Number.isFinite(payload.primeMs) ? payload.primeMs : 1200;
+    if (inHotkeyWindow) {
+      navTo(`/hotkey-window/thread/${encoded}`);
+    } else if (payload.primeOpen === false) {
+      navTo(`/local/${encoded}`);
+    } else {
+      navTo(`/hotkey-window/thread/${encoded}`);
+      await new Promise((resolve) => setTimeout(resolve, primeMs));
+      navTo(`/local/${encoded}`);
     }
   }
 
   return { ok: sent.some((item) => item.ok), href: location.href, openThreadId: payload.openThreadId || null, sent };
 }
 
-export function buildCodexDesktopRefreshExpression({ threadIds = [], pinnedThreadIds = null, openThreadId = null } = {}) {
+export function buildCodexDesktopRefreshExpression({ threadIds = [], pinnedThreadIds = null, openThreadId = null, primeOpen = true } = {}) {
   const rendererCode = `(${relayRefreshCodexRenderer.toString()})(${JSON.stringify({
     threadIds: uniqueStrings(threadIds),
     pinnedThreadIds,
     openThreadId: String(openThreadId || "").trim() || null,
+    primeOpen: primeOpen !== false,
+    primeMs: Number(process.env.RELAY_CODEX_OPEN_PRIME_MS) || 1200,
   })})`;
   // Only bring a window forward when we're actually opening a thread.
   const wantsFocus = Boolean(String(openThreadId || "").trim());

package/src/install.js

@@ -15,6 +15,9 @@ import { activateCodexMcp, verifyClaudeMcpRegistration } from "./setup-activatio
 
 const DAEMON_LAUNCH_LABEL = "work.relay.companion";
 const PILL_LAUNCH_LABEL = "work.relay.companion.pill";
+const WINDOWS_DAEMON_TASK_NAME = "Relay Companion Daemon";
+const WINDOWS_PILL_TASK_NAME = "Relay Companion Pill";
+const DEFAULT_NPM_INSTALL_TIMEOUT_MS = 10 * 60 * 1000;
 
 export const PACKAGE_NAME = "relay-companion";
 
@@ -45,7 +48,9 @@ export function resolveStableBin() {
   const here = relayBinPath();
   const ephemeral = /[\\/](_npx|\.npm[\\/]_npx|npm-cache[\\/]_npx)[\\/]/.test(here);
   if (!ephemeral) return here;
-  const install = run("npm", ["install", "-g", `${PACKAGE_NAME}@latest`]);
+  const install = run("npm", ["install", "-g", `${PACKAGE_NAME}@latest`], {
+    timeoutMs: npmInstallTimeoutMs(),
+  });
   if (!install.ok) return here; // fall back; caller still gets a working (if cache-bound) path
   const rootRes = spawnSync("npm", ["root", "-g"], { encoding: "utf8", timeout: 20_000 });
   const root = (rootRes.stdout || "").trim();
@@ -53,8 +58,13 @@ export function resolveStableBin() {
   return fs.existsSync(globalBin) ? globalBin : here;
 }
 
-function run(cmd, args) {
-  const res = spawnSync(cmd, args, { encoding: "utf8", timeout: 20_000 });
+function npmInstallTimeoutMs(env = process.env) {
+  const parsed = Number(env.RELAY_NPM_INSTALL_TIMEOUT_MS);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_NPM_INSTALL_TIMEOUT_MS;
+}
+
+function run(cmd, args, { timeoutMs = 20_000 } = {}) {
+  const res = spawnSync(cmd, args, { encoding: "utf8", timeout: timeoutMs });
   return {
     ok: !res.error && res.status === 0,
     status: res.status,
@@ -63,6 +73,163 @@ function run(cmd, args) {
   };
 }
 
+export function claudeCodeConfigPath() {
+  return process.env.CLAUDE_CODE_CONFIG || path.join(os.homedir(), ".claude.json");
+}
+
+export function codexConfigPath() {
+  if (process.env.CODEX_CONFIG) return process.env.CODEX_CONFIG;
+  const home = process.env.CODEX_HOME || path.join(os.homedir(), ".codex");
+  return path.join(home, "config.toml");
+}
+
+function readJsonObject(file) {
+  const text = fs.readFileSync(file, "utf8");
+  const parsed = JSON.parse(text);
+  return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+}
+
+function writeJsonAtomic(file, value) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`);
+  fs.renameSync(tmp, file);
+}
+
+function writeTextAtomic(file, value) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(tmp, value);
+  fs.renameSync(tmp, file);
+}
+
+export function writeClaudeCodeMcpConfig(bin = relayBinPath(), node = process.execPath, configPath = claudeCodeConfigPath()) {
+  if (!fs.existsSync(configPath)) return { ok: false, reason: "claude_config_missing", configPath };
+  try {
+    const cfg = readJsonObject(configPath);
+    const existingServers =
+      cfg.mcpServers && typeof cfg.mcpServers === "object" && !Array.isArray(cfg.mcpServers)
+        ? cfg.mcpServers
+        : {};
+    cfg.mcpServers = {
+      ...existingServers,
+      relay: {
+        type: "stdio",
+        command: node,
+        args: [bin, "mcp"],
+        env: {},
+      },
+    };
+    writeJsonAtomic(configPath, cfg);
+    return { ok: true, method: "config", configPath };
+  } catch (error) {
+    return {
+      ok: false,
+      reason: "claude_config_write_failed",
+      configPath,
+      detail: error && error.message ? error.message : String(error),
+    };
+  }
+}
+
+export function removeClaudeCodeMcpConfig(configPath = claudeCodeConfigPath()) {
+  if (!fs.existsSync(configPath)) return { ok: true, configPath };
+  try {
+    const cfg = readJsonObject(configPath);
+    if (cfg.mcpServers && typeof cfg.mcpServers === "object" && !Array.isArray(cfg.mcpServers)) {
+      delete cfg.mcpServers.relay;
+      writeJsonAtomic(configPath, cfg);
+    }
+    return { ok: true, configPath };
+  } catch (error) {
+    return {
+      ok: false,
+      reason: "claude_config_write_failed",
+      configPath,
+      detail: error && error.message ? error.message : String(error),
+    };
+  }
+}
+
+function tomlQuote(value) {
+  return JSON.stringify(String(value));
+}
+
+export function codexRelayMcpTomlSection(bin = relayBinPath(), node = process.execPath) {
+  return [
+    "[mcp_servers.relay]",
+    `command = ${tomlQuote(node)}`,
+    `args = [${[bin, "mcp"].map(tomlQuote).join(", ")}]`,
+    "startup_timeout_sec = 30",
+    "tool_timeout_sec = 300",
+    "",
+  ].join("\n");
+}
+
+export function replaceTomlTable(text, tableName, replacement) {
+  const header = `[${tableName}]`;
+  const lines = String(text || "").split(/\r?\n/);
+  const start = lines.findIndex((line) => line.trim() === header);
+  const cleanReplacement = String(replacement || "").trimEnd();
+  if (start === -1) {
+    const prefix = String(text || "").trimEnd();
+    return `${prefix}${prefix ? "\n\n" : ""}${cleanReplacement}\n`;
+  }
+
+  let end = start + 1;
+  while (end < lines.length && !/^\s*\[[^\]]+\]\s*$/.test(lines[end])) end += 1;
+  const before = lines.slice(0, start).join("\n").trimEnd();
+  const after = lines.slice(end).join("\n").trimStart();
+  return `${before ? `${before}\n\n` : ""}${cleanReplacement}${after ? `\n\n${after}` : ""}\n`;
+}
+
+export function removeTomlTable(text, tableName) {
+  const header = `[${tableName}]`;
+  const lines = String(text || "").split(/\r?\n/);
+  const start = lines.findIndex((line) => line.trim() === header);
+  if (start === -1) return String(text || "");
+
+  let end = start + 1;
+  while (end < lines.length && !/^\s*\[[^\]]+\]\s*$/.test(lines[end])) end += 1;
+  const before = lines.slice(0, start).join("\n").trimEnd();
+  const after = lines.slice(end).join("\n").trimStart();
+  return `${before}${before && after ? "\n\n" : ""}${after}${before || after ? "\n" : ""}`;
+}
+
+export function writeCodexMcpConfig(bin = relayBinPath(), node = process.execPath, configPath = codexConfigPath()) {
+  const configDir = path.dirname(configPath);
+  if (!fs.existsSync(configPath) && !fs.existsSync(configDir)) {
+    return { ok: false, reason: "codex_config_missing", configPath };
+  }
+  try {
+    const existing = fs.existsSync(configPath) ? fs.readFileSync(configPath, "utf8") : "";
+    writeTextAtomic(configPath, replaceTomlTable(existing, "mcp_servers.relay", codexRelayMcpTomlSection(bin, node)));
+    return { ok: true, method: "config", configPath };
+  } catch (error) {
+    return {
+      ok: false,
+      reason: "codex_config_write_failed",
+      configPath,
+      detail: error && error.message ? error.message : String(error),
+    };
+  }
+}
+
+export function removeCodexMcpConfig(configPath = codexConfigPath()) {
+  if (!fs.existsSync(configPath)) return { ok: true, configPath };
+  try {
+    writeTextAtomic(configPath, removeTomlTable(fs.readFileSync(configPath, "utf8"), "mcp_servers.relay"));
+    return { ok: true, configPath };
+  } catch (error) {
+    return {
+      ok: false,
+      reason: "codex_config_write_failed",
+      configPath,
+      detail: error && error.message ? error.message : String(error),
+    };
+  }
+}
+
 function electronPathForPackageRoot(packageRoot) {
   try {
     const require = createRequire(path.join(packageRoot, "package.json"));
@@ -80,22 +247,54 @@ export function commandExists(cmd) {
 }
 
 /** Register the Relay MCP into Claude Code at user scope (loads in every session). Idempotent. */
-export function installClaudeCode(bin = relayBinPath(), node = process.execPath) {
-  run("claude", ["mcp", "remove", "-s", "user", "relay"]); // ignore if absent
-  const res = run("claude", ["mcp", "add", "-s", "user", "relay", "--", node, bin, "mcp"]);
-  return res.ok || /already exists/i.test(res.out);
+export function installClaudeCode(bin = relayBinPath(), node = process.execPath, { command = "claude" } = {}) {
+  let cliResult = null;
+  if (commandExists(command)) {
+    run(command, ["mcp", "remove", "-s", "user", "relay"]); // ignore if absent
+    cliResult = run(command, ["mcp", "add", "-s", "user", "relay", "--", node, bin, "mcp"]);
+    if (cliResult.ok || /already exists/i.test(cliResult.out)) {
+      return { ok: true, method: "cli" };
+    }
+  }
+
+  const configResult = writeClaudeCodeMcpConfig(bin, node);
+  if (configResult.ok) return configResult;
+  if (cliResult) return { ok: false, reason: "registration_failed", detail: cliResult.out, configPath: configResult.configPath };
+  return { ok: false, reason: "claude_code_not_found", configPath: configResult.configPath };
 }
 
 /** Register the Relay MCP into Codex (loads in every session). Idempotent. */
-export function installCodex(bin = relayBinPath(), node = process.execPath) {
-  run("codex", ["mcp", "remove", "relay"]); // ignore if absent
-  const res = run("codex", ["mcp", "add", "relay", "--", node, bin, "mcp"]);
-  return res.ok || /already exists/i.test(res.out);
+export function installCodex(bin = relayBinPath(), node = process.execPath, { command = "codex" } = {}) {
+  let cliResult = null;
+  if (commandExists(command)) {
+    run(command, ["mcp", "remove", "relay"]); // ignore if absent
+    cliResult = run(command, ["mcp", "add", "relay", "--", node, bin, "mcp"]);
+    if (cliResult.ok || /already exists/i.test(cliResult.out)) {
+      return { ok: true, method: "cli" };
+    }
+  }
+
+  const configResult = writeCodexMcpConfig(bin, node);
+  if (configResult.ok) return configResult;
+  if (cliResult) return { ok: false, reason: "registration_failed", detail: cliResult.out, configPath: configResult.configPath };
+  return { ok: false, reason: "codex_not_found", configPath: configResult.configPath };
 }
 
 /** Install + load a launchd agent that keeps `relay daemon` running (macOS). Idempotent. */
-export function installDaemonAutostart(bin = relayBinPath(), node = process.execPath) {
-  if (process.platform !== "darwin") return { ok: false, reason: "autostart_unsupported_platform" };
+export function installDaemonAutostart(bin = relayBinPath(), node = process.execPath, { platform = process.platform, runCommand = run } = {}) {
+  if (platform === "win32") {
+    const logPath = path.join(os.homedir(), ".relay", "daemon.log");
+    fs.mkdirSync(path.dirname(logPath), { recursive: true });
+    const res = installWindowsLogonTask({
+      taskName: WINDOWS_DAEMON_TASK_NAME,
+      executable: node,
+      args: [bin, "daemon"],
+      logPath,
+      runCommand,
+    });
+    return { ...res, logPath };
+  }
+  if (platform !== "darwin") return { ok: false, reason: "autostart_unsupported_platform" };
   const home = os.homedir();
   const plistPath = path.join(home, "Library", "LaunchAgents", `${DAEMON_LAUNCH_LABEL}.plist`);
   const logPath = path.join(home, ".relay", "daemon.log");
@@ -125,20 +324,32 @@ export function installDaemonAutostart(bin = relayBinPath(), node = process.exec
 </plist>
 `;
   fs.writeFileSync(plistPath, plist);
-  run("launchctl", ["unload", plistPath]); // ignore if not loaded
-  const res = run("launchctl", ["load", plistPath]);
+  runCommand("launchctl", ["unload", plistPath]); // ignore if not loaded
+  const res = runCommand("launchctl", ["load", plistPath]);
   return { ok: res.ok, plistPath, logPath };
 }
 
 /** Install + load a launchd agent that starts the visible Relay pill (macOS). */
-export function installPillAutostart(bin = relayBinPath()) {
-  if (process.platform !== "darwin") return { ok: false, reason: "autostart_unsupported_platform" };
+export function installPillAutostart(bin = relayBinPath(), { platform = process.platform, runCommand = run } = {}) {
+  if (platform !== "darwin" && platform !== "win32") return { ok: false, reason: "autostart_unsupported_platform" };
   const packageRoot = packageRootForBin(bin);
   const electronPath = electronPathForPackageRoot(packageRoot);
   const overlayMain = path.join(packageRoot, "overlay", "main.cjs");
   if (!electronPath || !fs.existsSync(overlayMain)) {
     return { ok: false, reason: "pill_runtime_missing", electronPath, overlayMain };
   }
+  if (platform === "win32") {
+    const logPath = path.join(os.homedir(), ".relay", "pill.log");
+    fs.mkdirSync(path.dirname(logPath), { recursive: true });
+    const res = installWindowsLogonTask({
+      taskName: WINDOWS_PILL_TASK_NAME,
+      executable: electronPath,
+      args: [overlayMain],
+      logPath,
+      runCommand,
+    });
+    return { ...res, electronPath, overlayMain, logPath };
+  }
 
   const home = os.homedir();
   const plistPath = path.join(home, "Library", "LaunchAgents", `${PILL_LAUNCH_LABEL}.plist`);
@@ -167,11 +378,37 @@ export function installPillAutostart(bin = relayBinPath()) {
 </plist>
 `;
   fs.writeFileSync(plistPath, plist);
-  run("launchctl", ["unload", plistPath]); // ignore if not loaded
-  const res = run("launchctl", ["load", plistPath]);
+  runCommand("launchctl", ["unload", plistPath]); // ignore if not loaded
+  const res = runCommand("launchctl", ["load", plistPath]);
   return { ok: res.ok, plistPath, logPath };
 }
 
+function quoteWindowsCmdArg(value) {
+  return `"${String(value).replaceAll('"', '\\"')}"`;
+}
+
+export function windowsTaskAction(executable, args = [], logPath = null, comspec = process.env.ComSpec || "cmd.exe") {
+  const command = [quoteWindowsCmdArg(executable), ...args.map(quoteWindowsCmdArg)].join(" ");
+  const redirect = logPath ? ` >> ${quoteWindowsCmdArg(logPath)} 2>&1` : "";
+  return `${quoteWindowsCmdArg(comspec)} /d /s /c "${command}${redirect}"`;
+}
+
+function installWindowsLogonTask({ taskName, executable, args = [], logPath = null, runCommand = run }) {
+  const action = windowsTaskAction(executable, args, logPath);
+  const create = runCommand("schtasks", ["/Create", "/TN", taskName, "/SC", "ONLOGON", "/TR", action, "/F"]);
+  if (!create.ok) {
+    return { ok: false, reason: "scheduled_task_create_failed", taskName, action, detail: create.out };
+  }
+  const start = runCommand("schtasks", ["/Run", "/TN", taskName]);
+  return {
+    ok: true,
+    taskName,
+    action,
+    started: start.ok,
+    startDetail: start.ok ? "" : start.out,
+  };
+}
+
 /**
  * Detect Claude Code + Codex, register the Relay MCP into each present, and
  * start the receive daemon. Returns a summary for the CLI to print.
@@ -181,18 +418,24 @@ export async function runSetupInstall() {
   const installed = [];
   const missing = [];
   const activations = [];
-  if (commandExists("claude")) {
-    if (installClaudeCode(bin)) {
-      installed.push("Claude Code");
-      activations.push(verifyClaudeMcpRegistration());
-    } else missing.push("Claude Code (registration failed)");
-  } else missing.push("Claude Code");
-  if (commandExists("codex")) {
-    if (installCodex(bin)) {
-      installed.push("Codex");
-      activations.push(await activateCodexMcp());
-    } else missing.push("Codex (registration failed)");
-  } else missing.push("Codex");
+  const claude = installClaudeCode(bin);
+  if (claude.ok) {
+    installed.push("Claude Code");
+    activations.push(verifyClaudeMcpRegistration({ configPath: claude.configPath }));
+  } else if (claude.reason === "claude_code_not_found") {
+    missing.push("Claude Code");
+  } else {
+    missing.push("Claude Code (registration failed)");
+  }
+  const codex = installCodex(bin);
+  if (codex.ok) {
+    installed.push("Codex");
+    activations.push(await activateCodexMcp());
+  } else if (codex.reason === "codex_not_found") {
+    missing.push("Codex");
+  } else {
+    missing.push("Codex (registration failed)");
+  }
   const daemon = installDaemonAutostart(bin);
   const pill = installPillAutostart(bin);
   return { installed, missing, daemon, pill, activations };
@@ -202,6 +445,8 @@ export async function runSetupInstall() {
 export function runUninstall() {
   run("claude", ["mcp", "remove", "-s", "user", "relay"]);
   run("codex", ["mcp", "remove", "relay"]);
+  removeClaudeCodeMcpConfig();
+  removeCodexMcpConfig();
   if (process.platform === "darwin") {
     const plistPath = path.join(os.homedir(), "Library", "LaunchAgents", `${DAEMON_LAUNCH_LABEL}.plist`);
     run("launchctl", ["unload", plistPath]);
@@ -217,5 +462,10 @@ export function runUninstall() {
     } catch {
       /* already gone */
     }
+  } else if (process.platform === "win32") {
+    run("schtasks", ["/End", "/TN", WINDOWS_DAEMON_TASK_NAME]);
+    run("schtasks", ["/Delete", "/TN", WINDOWS_DAEMON_TASK_NAME, "/F"]);
+    run("schtasks", ["/End", "/TN", WINDOWS_PILL_TASK_NAME]);
+    run("schtasks", ["/Delete", "/TN", WINDOWS_PILL_TASK_NAME, "/F"]);
   }
 }

package/src/materializer.js

@@ -257,13 +257,19 @@ async function materializeRowInHost({ id, row, rowState = {}, host = "claude", l
     // works. The refresh therefore discards the stale cache entry and navigates
     // through the bridge, which forces the view to reload the now-complete file.
     // The codex:// deep link is only the fallback when the bridge is unreachable.
+    // First pass PRIMES the open: it navigates to /hotkey-window/thread/<id>
+    // (the only route that cold-loads an externally-created thread from disk),
+    // waits, then switches to /local/<id> so the thread shows in the main window
+    // with the sidebar. The /local route alone renders an empty "New chat" pane
+    // for a fresh relay thread and never recovers.
     const desktopOpenResult = await refreshCodexDesktopForThreads([threadId], { force: true, openThreadId: threadId });
     // The desktop occasionally re-caches the conversation between our discard
     // and the view's load, so a single refresh still races on some first opens.
-    // A second discard + navigate pass after a short settle has rendered
-    // deterministically in every observed failure case.
+    // The second pass runs with primeOpen=false — the thread is warm from the
+    // first pass, so a plain /local navigate re-asserts it deterministically
+    // without a second hotkey->local visual transition.
     await sleep(Number(process.env.RELAY_CODEX_OPEN_SECOND_PASS_MS || 1200));
-    const secondPassResult = await refreshCodexDesktopForThreads([threadId], { force: true, openThreadId: threadId });
+    const secondPassResult = await refreshCodexDesktopForThreads([threadId], { force: true, openThreadId: threadId, primeOpen: false });
     openedInHost = Boolean(desktopOpenResult?.ok || secondPassResult?.ok);
     skipExternalOpen = openedInHost;
     url = `codex://threads/${encodeURIComponent(threadId)}`;
@@ -393,7 +399,7 @@ function ensureRelayCodexIndexMarker({ threadId, sessionPath, packetId }) {
   }
 }
 
-async function refreshCodexDesktopForThreads(threadIds, { force = false, openThreadId = null } = {}) {
+async function refreshCodexDesktopForThreads(threadIds, { force = false, openThreadId = null, primeOpen = true } = {}) {
   const uniqueThreadIds = Array.from(new Set(threadIds.filter(Boolean)));
   if (!uniqueThreadIds.length && !force) return null;
   try {
@@ -401,6 +407,7 @@ async function refreshCodexDesktopForThreads(threadIds, { force = false, openThr
       threadIds: uniqueThreadIds,
       pinnedThreadIds: readPinnedThreadIds(),
       openThreadId,
+      primeOpen,
     });
     if (process.env.RELAY_DEBUG && result.attempted && !result.ok) {
       console.error(`Relay Codex desktop refresh did not reach a running window: ${JSON.stringify(result)}`);

package/src/setup-activation.js

@@ -1,4 +1,7 @@
 import { spawn, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
 import readline from "node:readline";
 
 const DEFAULT_TIMEOUT_MS = 12_000;
@@ -144,7 +147,7 @@ class JsonlRpcClient {
 
 function classifyCodexActivationError(error) {
   const text = `${error?.message || ""}\n${error?.stderr || ""}\n${error?.data ? JSON.stringify(error.data) : ""}`;
-  if (/app-server-control|control socket|No such file|not running|missing/i.test(text)) {
+  if (/app-server-control|control socket|No such file|not running|missing|ENOENT|not found/i.test(text)) {
     return "codex_control_socket_unavailable";
   }
   if (/experimentalApi/i.test(text)) return "codex_experimental_api_rejected";
@@ -229,9 +232,32 @@ export async function activateCodexMcp({
   }
 }
 
-export function verifyClaudeMcpRegistration({ runCommand, command = "claude" } = {}) {
+function defaultClaudeConfigPath() {
+  return process.env.CLAUDE_CODE_CONFIG || path.join(os.homedir(), ".claude.json");
+}
+
+function claudeConfigHasRelay(configPath = defaultClaudeConfigPath()) {
+  try {
+    const cfg = JSON.parse(fs.readFileSync(configPath, "utf8"));
+    const relay = cfg?.mcpServers?.relay;
+    return Boolean(relay?.command && Array.isArray(relay?.args) && relay.args.includes("mcp"));
+  } catch {
+    return false;
+  }
+}
+
+export function verifyClaudeMcpRegistration({ runCommand, command = "claude", configPath = defaultClaudeConfigPath() } = {}) {
   const run = runCommand || ((cmd, args) => spawnSyncCompat(cmd, args));
   const res = run(command, ["mcp", "get", "relay"]);
+  if (!res.ok && claudeConfigHasRelay(configPath)) {
+    return {
+      host: "Claude Code",
+      ok: true,
+      currentSessionReady: false,
+      reason: "registered_in_claude_config",
+      detail: configPath,
+    };
+  }
   return {
     host: "Claude Code",
     ok: Boolean(res.ok),