replica-bridge 0.3.17 → 0.3.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "replica-bridge",
-  "version": "0.3.17",
+  "version": "0.3.18",
   "description": "Lets the ChatReplica iPhone app use Codex on this computer through a relay, end-to-end encrypted.",
   "type": "module",
   "bin": {

package/src/bridge/main.js

@@ -83,12 +83,19 @@ function startBridge()                {
   return service;
 }
 
-/** Warns, without stopping, when Codex does not answer the way the bridge will run it (through the login shell). */
+/**
+ * Warns, without stopping, when Codex does not answer the way the bridge will run it (through the login shell).
+ * The shell is interactive (-i) so it reads the rc file where people put Codex on PATH, and an interactive shell that
+ * shares this terminal takes job control of it: zsh, and some bash set-ups, left the terminal to their own process
+ * group, so the next read of the terminal (the [Y/n] question, or "Allow?") stopped this process ("[1]+ Stopped
+ * npx replica-bridge", 2026-11-08) and with it the relay connection. `detached` starts it in its own session, with no
+ * terminal to take; it still reads the rc file.
+ */
 function checkCodex() {
   const codex = values.codex ?? "codex";
   const loginShell = process.platform !== "win32" && !values["no-login-shell"] && process.env.SHELL;
   const result = loginShell
-    ? spawnCommandSync(process.env.SHELL , ["-lic", `"$0" --version`, codex], { encoding: "utf8", timeout: 15_000 })
+    ? spawnCommandSync(process.env.SHELL , ["-lic", `"$0" --version`, codex], { encoding: "utf8", timeout: 15_000, detached: true })
     : spawnCommandSync(codex, ["--version"], { encoding: "utf8", timeout: 15_000 });
   if (result.status === 0) return;
   console.warn(`Codex did not answer "${codex} --version". Install it (npm install -g @openai/codex) and sign in (codex login); the phone cannot use this computer until then.`);
@@ -111,7 +118,55 @@ async function wantBackground()                   {
   return ask("Keep it running in the background and start it at login, so you can close this terminal? [Y/n] ");
 }
 
-function install()       {
+/** How long to wait for the relay socket before saying it has not connected; a working network takes well under a second. */
+const RELAY_WAIT_MS = Number(process.env.REPLICA_BRIDGE_RELAY_WAIT_MS ?? 10_000);
+
+/**
+ * Said when the bridge has not reached the relay. Enrolling and pairing are plain HTTPS requests, so they work on a
+ * network that blocks the WebSocket; then the phone pairs and shows the computer offline with no hint why
+ * (2026-11-08). The bridge keeps retrying, so this is a warning, not a stop.
+ */
+function relayWarning(relay        , problem               )         {
+  const socket = relay.replace(/^http/, "ws");
+  return [
+    `This computer has not connected to the relay yet${problem ? `: ${problem}` : ` (no answer within ${RELAY_WAIT_MS / 1000} s)`}.`,
+    "Until it does, the phone shows this computer offline. Pairing still works, since it uses plain HTTPS, and the bridge keeps trying.",
+    `A proxy or firewall that lets HTTPS through but blocks WebSocket connections to ${socket} causes exactly this.`,
+  ].join("\n");
+}
+
+/** Waits for this process's bridge to reach the relay and warns when it does not. */
+async function checkRelay(bridge               , relay        )                   {
+  if (await bridge.waitForRelay(RELAY_WAIT_MS)) return true;
+  console.warn(relayWarning(relay, bridge.relayProblem));
+  return false;
+}
+
+/** The background service's log past `offset` bytes, or "" before it exists. */
+function logSince(offset        )         {
+  try { return fs.readFileSync(logPath()).subarray(offset).toString("utf8"); } catch { return ""; }
+}
+
+function logSize()         {
+  try { return fs.statSync(logPath()).size; } catch { return 0; }
+}
+
+/** The background service is another process: its log is the only place that says whether it reached the relay. */
+async function checkServiceRelay(offset        , relay        ) {
+  for (let waited = 0; waited < RELAY_WAIT_MS; waited += 250) {
+    if (/ connected to relay /.test(logSince(offset))) return;
+    await new Promise((resolve) => setTimeout(resolve, 250));
+  }
+  const text = logSince(offset);
+  if (/ connected to relay /.test(text)) return;
+  const problems = [...text.matchAll(/relay connection error: (.*)|relay refused the host connection: (HTTP \d+)/g)];
+  const last = problems.at(-1);
+  console.warn(relayWarning(relay, last ? (last[1] ?? `${last[2]} instead of a WebSocket`) : null));
+  console.warn(`The background service keeps trying; its log is ${logPath()}.`);
+}
+
+async function install()                {
+  const offset = logSize();
   const plan = installService(startArgs(), console.log);
   // The service writes its pid once it has started; `status` right after the install said "not running" before that.
   for (let waited = 0; !runningPid() && waited < 10_000; waited += 200) Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 200);
@@ -122,6 +177,7 @@ function install()       {
   if (process.platform === "linux" && !fs.existsSync(`/var/lib/systemd/linger/${user}`)) {
     console.log(`To start it when the computer boots, before anyone logs in: sudo loginctl enable-linger ${user}`);
   }
+  await checkServiceRelay(offset, loadState().relay);
 }
 
 async function pairOrExplain() {
@@ -156,19 +212,20 @@ async function main() {
         // The background service serves the phone: restart it onto a new set-up or a newer version, then pair.
         if (moved) console.log("Restarting the background service with the new set-up.");
         else if (installed.version !== PACKAGE_VERSION) console.log(`Updating the background service from ${installed.version} to ${PACKAGE_VERSION}.`);
-        if (moved || values.install || installed.version !== PACKAGE_VERSION) install();
+        if (moved || values.install || installed.version !== PACKAGE_VERSION) await install();
         if (moved || values.pair || !state.devices.length) await pairOrExplain();
         else status();
         break;
       }
       if (runningPid()) throw new Error(`a bridge already runs for this computer (pid ${runningPid()}); stop it first`);
       let bridge = startBridge();
+      await checkRelay(bridge, state.relay);
       if (values.pair || !state.devices.length) await pairOrExplain();
       if (loadState().devices.length && await wantBackground()) {
         // One bridge per computer: the relay keeps only the newest connection for it.
         bridge.stop();
         try {
-          install();
+          await install();
           process.exit(0);
         } catch (error) {
           console.error(`replica-bridge: could not set up the background service: ${(error         ).message}`);
@@ -177,11 +234,12 @@ async function main() {
       }
       for (const signal of ["SIGINT", "SIGTERM"]         ) process.on(signal, () => { bridge.stop(); process.exit(0); });
       console.log(`Running in this terminal: paired phones can use Codex on ${state.hostName} until it closes (Ctrl-C stops it).`);
+      if (!(await bridge.waitForRelay(RELAY_WAIT_MS))) console.warn(`Still not connected to the relay${bridge.relayProblem ? ` (${bridge.relayProblem})` : ""}: the phone shows ${state.hostName} offline until it is.`);
       break;
     }
     case "install":
       await ensureRelay(values.relay, console.log, values.name);
-      install();
+      await install();
       break;
     case "uninstall": {
       const plan = uninstallService();
@@ -196,7 +254,7 @@ async function main() {
       const state = await enroll(relay, { name: values.name, publicRelay: values["public-url"] });
       console.log(`Set up ${state.hostName} as ${state.hostId}. Next: "npx replica-bridge".`);
       console.log("Nobody owns it yet: the first phone that scans its QR code and is approved here claims it.");
-      if (readServiceInfo()) { console.log("Restarting the background service with the new set-up."); install(); }
+      if (readServiceInfo()) { console.log("Restarting the background service with the new set-up."); await install(); }
       break;
     }
     case "config": {
@@ -209,7 +267,7 @@ async function main() {
     case "pair":
       if ((await ensureRelay(values.relay, console.log, values.name)).moved && readServiceInfo()) {
         console.log("Restarting the background service with the new set-up.");
-        install();
+        await install();
       }
       await pair({ confirm: values.confirm, yes: values.yes, timeoutSeconds: Number(values.timeout), pngPath: values.png });
       if (!runningPid()) console.log(`Nothing serves this computer right now: run "npx replica-bridge" so the phone can connect.`);

package/src/bridge/service.js

@@ -121,12 +121,42 @@ export class BridgeService {
 
   get streamCount() { return this.streams.size; }
 
+  /** The relay socket is open: phones see this computer online. */
+  get relayConnected() { return this.relay?.readyState === WebSocket.OPEN; }
+
+  /** Why the last attempt to reach the relay failed, while it has not connected since. */
+  get relayProblem() { return this.lastRelayProblem; }
+
+          lastRelayProblem                = null;
+                   relayWaiters = new Set            ();
+
+  /**
+   * Waits up to `ms` for the relay socket to open. Pairing goes over plain HTTPS, so a network that lets HTTPS through
+   * but not the WebSocket (2026-11-08: two computers paired, never once came online, and the phone showed both
+   * offline) pairs fine and leaves nothing for the phone to reach; the caller says so instead of looking finished.
+   */
+  async waitForRelay(ms        )                   {
+    if (this.relayConnected) return true;
+    await new Promise      ((resolve) => {
+      const done = () => { clearTimeout(timer); this.relayWaiters.delete(done); resolve(); };
+      const timer = setTimeout(done, ms);
+      this.relayWaiters.add(done);
+    });
+    return this.relayConnected;
+  }
+
+  /** Only an open socket ends the wait early: a first attempt that fails often succeeds on the retry a second later. */
+          relayChanged() {
+    for (const waiter of [...this.relayWaiters]) waiter();
+  }
+
   // MARK: - Relay connection
 
           connectRelay() {
     const state = loadState();
     const ws = new WebSocket(relaySocketURL(state.relay, "/v1/host"), { headers: { authorization: `Bearer ${state.hostToken}` }, maxPayload: MAX_FRAME_BYTES + 4096, perMessageDeflate: false });
     this.relay = ws;
+    let refused = false;
     // A laptop that sleeps or changes networks keeps a socket the relay dropped long ago, and nothing here would
     // notice until the bridge sent something: the computer stayed offline for the phones. A missed pong ends it.
     let answered = true;
@@ -138,7 +168,14 @@ export class BridgeService {
     }, (this.options.relayPingSeconds ?? 30) * 1000);
     ws.on("pong", () => { answered = true; });
     ws.on("ping", () => { answered = true; });
-    ws.on("open", () => { answered = true; this.retry = 0; this.log(`connected to relay ${state.relay} as ${state.hostId}`); this.options.onRelayConnected?.(true); });
+    ws.on("open", () => {
+      answered = true;
+      this.retry = 0;
+      this.lastRelayProblem = null;
+      this.log(`connected to relay ${state.relay} as ${state.hostId}`);
+      this.options.onRelayConnected?.(true);
+      this.relayChanged();
+    });
     ws.on("message", (data         ) => {
       let envelope              ;
       try { envelope = JSON.parse(data.toString()); } catch { return; }
@@ -149,10 +186,16 @@ export class BridgeService {
     // process ran out of work and exited 0, which the background services read as "replaced" and left stopped.
     // Ending the socket goes through close and the usual backoff instead.
     ws.on("unexpected-response", (_req, res) => {
+      refused = true;
+      this.lastRelayProblem = `HTTP ${res.statusCode} instead of a WebSocket`;
       this.log(`relay refused the host connection: HTTP ${res.statusCode}; retrying`);
       ws.terminate();
     });
-    ws.on("error", (error) => this.log(`relay connection error: ${error.message}`));
+    ws.on("error", (error) => {
+      // Ending a refused socket also reports "closed before the connection was established"; the status says more.
+      if (!refused) this.lastRelayProblem = describeSocketError(error);
+      this.log(`relay connection error: ${this.lastRelayProblem}`);
+    });
     ws.on("close", (code) => {
       clearInterval(ping);
       if (ws !== this.relay) return; // a socket this bridge already replaced itself
@@ -420,9 +463,10 @@ export class BridgeService {
   }
 
   /** Runs a command to completion; true when it exits 0 within 30 s. Output is dropped (an rc file may print). */
-          run(command        , args          )                   {
+  /** `detached` for an interactive login shell, which would otherwise take the terminal of a bridge run in one (main.ts checkCodex). */
+          run(command        , args          , detached = false)                   {
     return new Promise((resolve, reject) => {
-      const child = spawnCommand(command, args, { stdio: "ignore" });
+      const child = spawnCommand(command, args, { stdio: "ignore", detached });
       const timer = setTimeout(() => { killCommand(child); resolve(false); }, 30_000);
       child.once("error", (error) => { clearTimeout(timer); reject(error); });
       child.once("exit", (code) => { clearTimeout(timer); resolve(code === 0); });
@@ -457,7 +501,7 @@ export class BridgeService {
     // (a SHELL from Git Bash is a POSIX path Node cannot run), so Codex is asked directly there.
     const shell = process.platform === "win32" ? null : process.env.SHELL || os.userInfo().shell;
     const started = this.options.loginShell !== false && shell
-      ? await this.run(shell, ["-lic", 'exec "$0" app-server daemon start', codex]).catch(() => false)
+      ? await this.run(shell, ["-lic", 'exec "$0" app-server daemon start', codex], true).catch(() => false)
       : false;
     if (!started && !(await this.run(codex, ["app-server", "daemon", "start"]).catch(() => false))) {
       throw new Error("codex app-server daemon start failed");
@@ -510,3 +554,13 @@ export function fitLine(line        , limit = RELAY_REPLY_LIMIT)
   if (id === undefined || id === null) return null;
   return JSON.stringify({ id, error: { code: -32010, message: `the reply is ${bytes} bytes, more than the relay carries (${limit})`, data: { replicaTooLarge: { bytes, limit } } } });
 }
+
+/**
+ * An error's message, or its code when Node leaves the message empty: a refused connection tried on both IPv4 and
+ * IPv6 is an AggregateError with message "" and the reasons in `errors`.
+ */
+export function describeSocketError(error       )         {
+  const parts = error instanceof AggregateError ? error.errors : [error];
+  const text = parts.map((e                           ) => e?.message || e?.code || String(e)).filter(Boolean);
+  return [...new Set(text)].join("; ") || error.name;
+}