replica-bridge 0.3.15 → 0.3.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "replica-bridge",
-  "version": "0.3.15",
+  "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/board.js

@@ -23,7 +23,14 @@ const CATCH_UP_PAGES = 1000;
 /** More changed tasks than this in one event, and the phone reads the whole board instead. */
 export const CHANGED_ITEMS_MAX = 200;
 /** What this bridge can do beyond reading, for board/state (PROTOCOL.md "看板"). */
-export const BOARD_CAPS = ["post", "delta"]         ;
+export const BOARD_CAPS = ["post", "delta", "items", "tasks"]         ;
+/** Up to this many changed tasks in one event come with their contents (`task`); past it the phone reads them itself. */
+export const CARRIED_TASKS_MAX = 50;
+/** A task bigger than this is left for the phone to read. */
+const CARRIED_TASK_MAX_BYTES = 256 * 1024;
+
+/** What the backend says a changed task now is: its view, or gone (404). Missing when the read failed. */
+                                                  
 
 /** The backend's own cap on a request body (agens-backend src/http.mjs BODY_MAX). */
 export const POST_BODY_MAX_BYTES = 16 * 1024;
@@ -31,10 +38,11 @@ const REC = "[A-Za-z0-9_.:-]+";
 
 /**
  * GETs (#367). /session also writes TASK.md in the task's working folder, which is what 开工 asks for; /share and /me
- * only read. Not /assist, /mcp, /search, /changes (the bridge's own poll) or anything under /ui.
+ * only read. From 0.3.16 also one item, a task's source (`?offset=` pages its text), as the backend's own page opens it.
+ * Not /assist, /mcp, /search, /context, /changes (the bridge's own poll) or anything under /ui.
  */
 const READS = [/^\/v1\/status$/, /^\/v1\/today$/, /^\/v1\/recommendations$/, new RegExp(`^/v1/recommendations/${REC}$`),
-  new RegExp(`^/v1/recommendations/${REC}/(share|session)$`), /^\/v1\/me$/];
+  new RegExp(`^/v1/recommendations/${REC}/(share|session)$`), /^\/v1\/me$/, new RegExp(`^/v1/items/${REC}$`)];
 
 /** POSTs (#367): a task's follow-up actions, cancelling its preparation note, and muting a conversation. Nothing else. */
 const WRITES = [new RegExp(`^/v1/recommendations/${REC}/actions$`), new RegExp(`^/v1/recommendations/${REC}/prep/cancel$`), /^\/v1\/me\/muted$/];
@@ -110,10 +118,17 @@ const DEFAULT_STREAM_RETRY_SECONDS = 30;
  
 
 /** Changes as a phone gets them: one per task, the latest, or a reset when there are too many. */
-function changedEvent(items               )             {
+/** The latest change of each task, in the order they last changed. */
+function latestOf(items               )                {
   const latest = new Map                     ();
   for (const item of items) { latest.delete(item.recId); latest.set(item.recId, item); }
-  return latest.size > CHANGED_ITEMS_MAX ? { t: "board/changed", reset: true } : { t: "board/changed", items: [...latest.values()] };
+  return [...latest.values()];
+}
+
+function changedEvent(items               , carried = new Map                 ())             {
+  const latest = latestOf(items);
+  if (latest.length > CHANGED_ITEMS_MAX) return { t: "board/changed", reset: true };
+  return { t: "board/changed", items: latest.map((item) => ({ ...item, ...carried.get(item.recId) })) };
 }
 
 function changeOf(value         )                     {
@@ -135,6 +150,8 @@ export class BoardReader {
           round = 0;
   /** The backend's push stream: open, unknown (try it), or not there (an older backend answers 404). */
           stream                         = null;
+  /** Changes go out one batch at a time and in order, each after its tasks were read. */
+          delivery                = Promise.resolve();
           streamSupported                 = null;
   /** Not before this time (ms) after the backend refused a stream for a passing reason. */
           streamRetryAt = 0;
@@ -215,6 +232,7 @@ export class BoardReader {
     this.end = null;
     this.up = null;
     this.polling = false;
+    this.delivery = Promise.resolve();
     this.round++;
   }
 
@@ -259,20 +277,63 @@ export class BoardReader {
       return;
     }
     if (round !== this.round || !this.subs.has(sub)) return;
+    // What changed comes with the tasks as they are now; reading them takes a moment, in which more may change, so
+    // read the log again up to where the shared reader got before this subscriber starts hearing from it.
+    let carried = new Map                 ();
+    if (!reset && missed.length) {
+      carried = await this.carry(missed);
+      try {
+        for (let page = 0; cursor !== null && cursor < this.end  && page < CATCH_UP_PAGES; page++) {
+          const { items, next } = await this.changes(cursor);
+          missed.push(...items);
+          if (next === cursor && items.length === 0) break;
+          cursor = next;
+        }
+      } catch { /* the late ones go without contents; the phone reads them */ }
+      if (round !== this.round || !this.subs.has(sub)) return;
+    }
     sub.admitting = false;
     sub.cursor = Math.max(cursor ?? this.end , this.end );
     sub.listener(this.state(true, sub.cursor));
     if (reset) sub.listener({ t: "board/changed", reset: true });
-    else if (missed.length) sub.listener(changedEvent(missed));
+    else if (missed.length) sub.listener(changedEvent(missed, carried));
+  }
+
+  /**
+   * Reads each changed task (its latest change only) from the backend, so the phone needs no read of its own. Only while
+   * a phone is subscribed, which is while its 任务 page is on screen, so marking them seen is what the phone's own read
+   * did before. Too many at once, and the phone reads them (or the whole board) itself.
+   */
+          async carry(items               )                                {
+    const carried = new Map                 ();
+    const latest = latestOf(items);
+    if (latest.length > CARRIED_TASKS_MAX) return carried;
+    await Promise.all(latest.map(async ({ recId }) => {
+      const answer = await this.answer(`/v1/recommendations/${encodeURIComponent(recId)}`);
+      if ("error" in answer) return;
+      if (answer.status === 404) { carried.set(recId, { gone: true }); return; }
+      if (answer.status !== 200 || Buffer.byteLength(answer.body, "utf8") > CARRIED_TASK_MAX_BYTES) return;
+      try { carried.set(recId, { task: JSON.parse(answer.body) }); } catch { /* the phone reads it */ }
+    }));
+    return carried;
+  }
+
+  /** Reads the changed tasks, then tells each subscriber; batches stay in order. */
+          send(items               , end        ) {
+    const round = this.round;
+    this.delivery = this.delivery.then(async () => {
+      const carried = await this.carry(items);
+      if (round === this.round) this.deliver(items, end, carried);
+    });
   }
 
   /** New changes up to `end`: each subscriber gets those past its own place. */
-          deliver(items               , end        ) {
+          deliver(items               , end        , carried = new Map                 ()) {
     for (const sub of this.subs) {
       if (sub.cursor === null) continue;
       const fresh = items.filter((item) => item.seq > sub.cursor );
       sub.cursor = Math.max(sub.cursor, end);
-      if (fresh.length) sub.listener(changedEvent(fresh));
+      if (fresh.length) sub.listener(changedEvent(fresh, carried));
     }
   }
 
@@ -312,7 +373,7 @@ export class BoardReader {
     if (up) this.end = end;
     this.setUp(up);
     if (!up) return;
-    if (items.length) this.deliver(items, end );
+    if (items.length) this.send(items, end );
     for (const sub of this.subs) if (sub.cursor === null) void this.admit(sub);
     if (this.streamSupported !== false && Date.now() >= this.streamRetryAt) void this.openStream(round);
   }
@@ -363,7 +424,7 @@ export class BoardReader {
       pending = [];
       const end = Math.max(this.end ?? 0, ...batch.map((item) => item.seq));
       this.end = end;
-      this.deliver(batch, end);
+      this.send(batch, end);
     };
     try {
       const decoder = new TextDecoder();

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;
+}

package/src/protocol.js

@@ -249,13 +249,15 @@ export class FrameCipher {
                                                                                                                               
 /** One task that changed, from agens-backend's change log (0.3.14). */
                                                                        
+/** As a phone gets it from 0.3.17 on: the task as the backend now has it (`GET /v1/recommendations/:id`), or gone. */
+                                                                           
 /**
  * What a subscriber hears. From 0.3.14 a board/state that says up also gives `seq` (where in the change log the phone
  * starts), `caps` and the bridge's version, and board/changed names the tasks, or says `reset` when there are too many.
  */
                         
                                                                                      
-                                                                
+                                                                   
 
                                                                  
 /** One segment of a long line: `data` is base64 of bytes [segment * chunk size, …) of the payload, `size` its length. */