replica-bridge 0.1.0 → 0.3.1

package/README.md

@@ -5,4 +5,10 @@ Lets the ChatReplica iPhone app use Codex on this computer. Needs Codex installe
     npx replica-bridge
 
 The first run sets this computer up with the relay, shows a QR code to scan in the app (远程 › 添加连接 › 配对新设备),
-and keeps running: paired phones can use Codex here while it does. `npx replica-bridge --help` lists the other commands.
+then offers to keep running in the background and start at login (macOS launchd, Linux systemd, Windows Task
+Scheduler), so the terminal can be closed. Run it again for the status.
+
+    npx replica-bridge pair         pair another phone
+    npx replica-bridge uninstall    stop and remove the background service
+
+`npx replica-bridge --help` lists the other commands.

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "replica-bridge",
-  "version": "0.1.0",
+  "version": "0.3.1",
   "description": "Lets the ChatReplica iPhone app use Codex on this computer through a relay, end-to-end encrypted.",
   "type": "module",
   "bin": {
     "replica-bridge": "src/bridge/main.js"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=20.11"
   },
   "dependencies": {
     "qrcode": "1.5.4",

package/src/bridge/command.js

@@ -0,0 +1,28 @@
+// Running Codex, npm and the service managers the same way on macOS, Linux and Windows.
+import { spawn, spawnSync } from "node:child_process";
+                                                                                       
+
+/** One argument as cmd.exe reads it. */
+export function quoteForCmd(arg        )         {
+  return /^[\w\-.:\\/=@]+$/.test(arg) ? arg : `"${arg.replace(/"/g, '""')}"`;
+}
+
+/**
+ * On Windows npm installs commands such as codex as `codex.cmd`, which Node runs only through cmd.exe
+ * (spawn without a shell fails with EINVAL or ENOENT), so the command line goes through the shell there.
+ */
+export function spawnCommand(command        , args          , options               = {})               {
+  if (process.platform !== "win32") return spawn(command, args, options);
+  return spawn([command, ...args].map(quoteForCmd).join(" "), [], { ...options, shell: true, windowsHide: true });
+}
+
+export function spawnCommandSync(command        , args          , options                   = {}) {
+  if (process.platform !== "win32") return spawnSync(command, args, options);
+  return spawnSync([command, ...args].map(quoteForCmd).join(" "), [], { ...options, shell: true, windowsHide: true });
+}
+
+/** Stops a command from spawnCommand; on Windows that is cmd.exe, so the whole tree goes (taskkill /T). */
+export function killCommand(child              ) {
+  if (process.platform === "win32" && child.pid && child.exitCode === null) spawnSync("taskkill", ["/pid", String(child.pid), "/T", "/F"], { stdio: "ignore", windowsHide: true });
+  else child.kill();
+}

package/src/bridge/install.js

@@ -0,0 +1,253 @@
+// Keeping the bridge running after its terminal closes, the way Codex keeps its app-server: a per-user background
+// service that starts at login and restarts when it fails. macOS: a launchd agent. Linux: a systemd user service.
+// Windows: a Task Scheduler task at logon that runs a hidden script, which restarts the bridge when it exits.
+// The service runs a copy installed under ~/.config/replica-bridge/app, not the npx cache, which npm may clear.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnCommandSync } from "./command.js";
+import { bridgeHome } from "./state.js";
+
+export const PACKAGE_VERSION         = JSON.parse(fs.readFileSync(path.resolve(import.meta.dirname, "../../package.json"), "utf8")).version;
+
+                                                                                                                                  
+
+                              
+                            
+                                                                                                       
+                
+               
+                     
+                                                          
+                    
+                              
+              
+ 
+
+                              
+                                             
+                                                                                   
+                                                                     
+                                                                       
+                                        
+                
+ 
+
+export const serviceLabel = () => process.env.REPLICA_BRIDGE_LABEL ?? "replica-bridge";
+export const logPath = (home = bridgeHome()) => path.join(home, "bridge.log");
+const infoPath = () => path.join(bridgeHome(), "service.json");
+const pidPath = () => path.join(bridgeHome(), "bridge.pid");
+
+const xml = (text        ) => text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+/** systemd unit-file quoting: specifiers (%) doubled, backslashes and quotes escaped. */
+const unitQuote = (text        ) => `"${text.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/%/g, "%%")}"`;
+/** A VBScript string literal. */
+const vbs = (text        ) => `"${text.replace(/"/g, '""')}"`;
+
+/** The service files and the commands that load and unload them; pure, so each platform can be checked anywhere. */
+export function servicePlan(spec             )              {
+  const log = logPath(spec.bridgeHome);
+  switch (spec.platform) {
+    case "darwin": {
+      const label = `com.chatreplica.${spec.label}`;
+      const plist = path.join(spec.home, "Library", "LaunchAgents", `${label}.plist`);
+      const target = `gui/${spec.uid}`;
+      const env = Object.entries(spec.env).map(([k, v]) => `    <key>${xml(k)}</key><string>${xml(v)}</string>`).join("\n");
+      const content = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>${xml(label)}</string>
+  <key>ProgramArguments</key>
+  <array>
+${spec.program.map((a) => `    <string>${xml(a)}</string>`).join("\n")}
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict>
+${env}
+  </dict>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><dict><key>SuccessfulExit</key><false/></dict>
+  <key>ThrottleInterval</key><integer>10</integer>
+  <key>ProcessType</key><string>Background</string>
+  <key>StandardOutPath</key><string>${xml(log)}</string>
+  <key>StandardErrorPath</key><string>${xml(log)}</string>
+</dict>
+</plist>
+`;
+      return {
+        files: [{ path: plist, content }],
+        install: [
+          { command: "launchctl", args: ["bootout", `${target}/${label}`], optional: true },
+          { command: "launchctl", args: ["bootstrap", target, plist] },
+        ],
+        uninstall: [{ command: "launchctl", args: ["bootout", `${target}/${label}`], optional: true }],
+        where: `launchd agent ${label} (${plist})`,
+      };
+    }
+    case "linux": {
+      const unit = `${spec.label}.service`;
+      const file = path.join(spec.home, ".config", "systemd", "user", unit);
+      const content = `[Unit]
+Description=replica-bridge: ChatReplica phones use Codex on this computer
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+ExecStart=${spec.program.map(unitQuote).join(" ")}
+Restart=on-failure
+RestartSec=10
+${Object.entries(spec.env).map(([k, v]) => `Environment=${unitQuote(`${k}=${v}`)}`).join("\n")}
+StandardOutput=append:${log}
+StandardError=append:${log}
+
+[Install]
+WantedBy=default.target
+`;
+      return {
+        files: [{ path: file, content }],
+        install: [
+          { command: "systemctl", args: ["--user", "daemon-reload"] },
+          { command: "systemctl", args: ["--user", "enable", unit] },
+          { command: "systemctl", args: ["--user", "restart", unit] },
+        ],
+        uninstall: [
+          { command: "systemctl", args: ["--user", "disable", "--now", unit], optional: true },
+        ],
+        where: `systemd user service ${unit} (${file})`,
+      };
+    }
+    case "win32": {
+      const script = path.join(spec.bridgeHome, "run-bridge.vbs");
+      // wscript shows no window; the loop brings the bridge back ten seconds after it fails. Exit code 0 means another
+      // bridge took this computer over (or it was told to stop), so the loop ends.
+      const content = [
+        `' replica-bridge background service (Task Scheduler task "${spec.label}"). Made by "replica-bridge install".`,
+        `Set shell = CreateObject("WScript.Shell")`,
+        ...Object.entries({ ...spec.env, REPLICA_BRIDGE_LOG: log }).map(([k, v]) => `shell.Environment("Process")(${vbs(k)}) = ${vbs(v)}`),
+        `Do`,
+        `  code = shell.Run(${vbs(spec.program.map((a) => `"${a}"`).join(" "))}, 0, True)`,
+        `  If code = 0 Then Exit Do`,
+        `  WScript.Sleep 10000`,
+        `Loop`,
+        "",
+      ].join("\r\n");
+      return {
+        files: [{ path: script, content }],
+        install: [
+          { command: "schtasks", args: ["/End", "/TN", spec.label], optional: true },
+          { command: "schtasks", args: ["/Create", "/F", "/TN", spec.label, "/SC", "ONLOGON", "/RL", "LIMITED", "/TR", `wscript.exe "${script}"`] },
+          { command: "schtasks", args: ["/Run", "/TN", spec.label] },
+        ],
+        uninstall: [
+          { command: "schtasks", args: ["/End", "/TN", spec.label], optional: true },
+          { command: "schtasks", args: ["/Delete", "/F", "/TN", spec.label], optional: true },
+        ],
+        where: `Task Scheduler task "${spec.label}" (${script})`,
+      };
+    }
+    default:
+      throw new Error(`no background service for ${spec.platform}: keep "replica-bridge start" running yourself`);
+  }
+}
+
+/** What the service passes on: PATH (so it finds codex and node) and the bridge's and Codex's own settings. */
+function serviceEnv()                         {
+  const env                         = {};
+  for (const [key, value] of Object.entries(process.env)) {
+    if (value !== undefined && (key === "PATH" || key === "Path" || /^(CODEX_|REPLICA_|RELAY_ENV$)/.test(key)) && key !== "REPLICA_BRIDGE_LOG") env[key] = value;
+  }
+  env.REPLICA_BRIDGE_SERVICE = "1";
+  return env;
+}
+
+/**
+ * The script the service runs. From npx (inside node_modules) a copy of this version is installed under
+ * ~/.config/replica-bridge/app, since npm may clear its npx cache; from a working copy, the working copy itself.
+ */
+function installedScript(say                        )         {
+  const current = process.argv[1] ? fs.realpathSync(process.argv[1]) : "";
+  if (!current.split(path.sep).includes("node_modules")) return current;
+  const app = path.join(bridgeHome(), "app");
+  const spec = process.env.REPLICA_BRIDGE_PACKAGE ?? `replica-bridge@${PACKAGE_VERSION}`;
+  say(`Installing ${spec} in ${app}…`);
+  fs.mkdirSync(app, { recursive: true });
+  // npx's own npm_* settings (a temporary prefix, for one) must not leak into this install.
+  const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => !/^npm_/i.test(key)));
+  const result = spawnCommandSync("npm", ["install", "--prefix", app, "--no-audit", "--no-fund", "--omit=dev", "--loglevel=error", spec], { stdio: "inherit", env });
+  if (result.status !== 0) throw new Error(`npm install ${spec} failed`);
+  return path.join(app, "node_modules", "replica-bridge", "src", "bridge", "main.js");
+}
+
+function run(steps                        ) {
+  for (const step of steps) {
+    const result = spawnCommandSync(step.command, step.args, { encoding: "utf8" });
+    if (result.status !== 0 && !step.optional) {
+      throw new Error(`${step.command} ${step.args.join(" ")} failed: ${(result.stderr || result.stdout || result.error?.message || "").toString().trim()}`);
+    }
+  }
+}
+
+export function readServiceInfo()                     {
+  try { return JSON.parse(fs.readFileSync(infoPath(), "utf8"))               ; } catch { return null; }
+}
+
+function spec(program          )              {
+  return { platform: process.platform, label: serviceLabel(), home: os.homedir(), bridgeHome: bridgeHome(), program, env: serviceEnv(), uid: os.userInfo().uid };
+}
+
+/** Installs (or replaces) the background service and starts it. `startArgs` are the options `start` keeps. */
+export function installService(startArgs          , say                        )              {
+  servicePlan(spec([])); // fails early on a platform without a service manager
+  stopRunning();
+  const program = [process.execPath, installedScript(say), "start", ...startArgs];
+  const plan = servicePlan(spec(program));
+  fs.mkdirSync(bridgeHome(), { recursive: true, mode: 0o700 });
+  for (const file of plan.files) {
+    fs.mkdirSync(path.dirname(file.path), { recursive: true });
+    fs.writeFileSync(file.path, file.content);
+  }
+  run(plan.install);
+  const info              = { platform: process.platform, label: serviceLabel(), version: PACKAGE_VERSION, program, installedAt: new Date().toISOString() };
+  fs.writeFileSync(infoPath(), JSON.stringify(info, null, 2) + "\n");
+  return plan;
+}
+
+export function uninstallService()                     {
+  const info = readServiceInfo();
+  if (!info) return null;
+  const plan = servicePlan({ ...spec(info.program), label: info.label });
+  run(plan.uninstall);
+  stopRunning();
+  for (const file of plan.files) fs.rmSync(file.path, { force: true });
+  if (process.platform === "linux") run([{ command: "systemctl", args: ["--user", "daemon-reload"], optional: true }]);
+  fs.rmSync(infoPath(), { force: true });
+  return plan;
+}
+
+// MARK: The running service's pid, so `status` can tell whether it runs and a second bridge does not start beside it.
+
+export function writePid() {
+  fs.mkdirSync(bridgeHome(), { recursive: true, mode: 0o700 });
+  fs.writeFileSync(pidPath(), String(process.pid));
+}
+
+export function clearPid() {
+  try { if (fs.readFileSync(pidPath(), "utf8").trim() === String(process.pid)) fs.rmSync(pidPath()); } catch { /* gone */ }
+}
+
+/** The background bridge's pid while it runs. */
+export function runningPid()                {
+  let pid        ;
+  try { pid = Number(fs.readFileSync(pidPath(), "utf8").trim()); } catch { return null; }
+  if (!pid || pid === process.pid) return null;
+  try { process.kill(pid, 0); return pid; } catch (error) { return (error                         ).code === "EPERM" ? pid : null; }
+}
+
+/** The service manager stops its own process; on Windows the loop's bridge is left, so it goes by pid. */
+function stopRunning() {
+  const pid = runningPid();
+  if (!pid) return;
+  try { process.kill(pid); } catch { /* already gone */ }
+  fs.rmSync(pidPath(), { force: true });
+}

package/src/bridge/main.js

@@ -1,19 +1,23 @@
 #!/usr/bin/env node
 // replica-bridge: runs on the computer that has Codex. See docs/RELAY.md.
-// The first pair or start sets the computer up by itself (anonymous enrollment); init does it explicitly.
-//   (no command) [--relay <url>] [--name <name>] [--pair] [--codex <path>]
-//       what `npx replica-bridge` runs: set up if needed, keep the bridge running, and show a QR code while no
-//       phone is paired yet (or with --pair)
+//   (no command)   what `npx replica-bridge` runs. The first time: set this computer up with the relay, show a QR
+//                  code, and once a phone is paired offer to keep the bridge running in the background (install).
+//                  Later: show the status, updating the background service when this is a newer version.
+//                  [--relay <url>] [--name <name>] [--pair] [--install | --no-install] [--codex <path>]
+//   pair [--relay <url>] [--confirm] [--yes] [--png <file>] [--timeout <seconds>]
+//   install | uninstall | status
+//   start [--codex <path>] [--stream-ttl <seconds>] [--no-login-shell]   the bridge in this terminal
 //   init [--relay <url>] [--public-url <url>] [--name <name>]
 //   config [--public-url <url>]
-//   pair [--relay <url>] [--confirm] [--yes] [--png <file>] [--timeout <seconds>]
-//   start [--codex <path>] [--stream-ttl <seconds>] [--no-login-shell]
 //   devices
 //   revoke <deviceId>
-import { spawnSync } from "node:child_process";
-import { parseArgs } from "node:util";
+import fs from "node:fs";
+import readline from "node:readline/promises";
+import { parseArgs, format } from "node:util";
 import { relayRequest } from "../http.js";
+import { spawnCommandSync } from "./command.js";
 import { defaultRelayURL, enroll, ensureEnrolled } from "./enroll.js";
+import { PACKAGE_VERSION, clearPid, installService, logPath, readServiceInfo, runningPid, servicePlan, uninstallService, writePid } from "./install.js";
 import { pair, publicRelayURL } from "./pair.js";
 import { BridgeService } from "./service.js";
 import { loadState, saveState } from "./state.js";
@@ -33,62 +37,152 @@ const { values, positionals } = parseArgs({
     png: { type: "string" },
     timeout: { type: "string", default: "600" },
     pair: { type: "boolean", default: false },
+    install: { type: "boolean", default: false },
+    "no-install": { type: "boolean", default: false },
     help: { type: "boolean", short: "h", default: false },
+    version: { type: "boolean", short: "v", default: false },
     codex: { type: "string" },
     "stream-ttl": { type: "string", default: "1800" },
     "no-login-shell": { type: "boolean", default: false },
   },
 });
 
-const usage = `usage: replica-bridge [command] (docs/RELAY.md)
-  (none)          set up, keep running, and show a QR code until a phone is paired (--pair shows one anyway)
-  pair            show a QR code for another phone
-  start           keep running without showing a QR code
-  init            set up only (--relay <url>, --name <name>)
-  config          show the relay, this computer and its owner
-  devices         list paired phones
-  revoke <id>     remove a phone
+const usage = `replica-bridge ${PACKAGE_VERSION}: lets the ChatReplica app use Codex on this computer (docs/RELAY.md)
+  npx replica-bridge              the only command most people need: sets up, pairs a phone, keeps running
+                                  in the background; run again for the status
+  npx replica-bridge pair         pair another phone
+  npx replica-bridge uninstall    stop and remove the background service
+Others: status, install, start (in this terminal), init, config, devices, revoke <id>.
 The relay is ${defaultRelayURL()} unless --relay or REPLICA_RELAY says otherwise.`;
 
-function startService() {
-  const service = new BridgeService({ codexPath: values.codex, loginShell: !values["no-login-shell"], streamTTLSeconds: Number(values["stream-ttl"]) });
+// The Windows service has no terminal to write to: its output goes to the log file it names.
+if (process.env.REPLICA_BRIDGE_LOG) {
+  const log = fs.createWriteStream(process.env.REPLICA_BRIDGE_LOG, { flags: "a" });
+  console.log = console.warn = console.error = (...args           ) => { log.write(format(...args) + "\n"); };
+}
+
+/** The options `start` keeps when the background service runs it. */
+function startArgs()           {
+  const args           = [];
+  if (values.codex) args.push("--codex", values.codex);
+  if (values["no-login-shell"]) args.push("--no-login-shell");
+  if (values["stream-ttl"] !== "1800") args.push("--stream-ttl", values["stream-ttl"] );
+  return args;
+}
+
+function startBridge()                {
+  // Exit 0: the background services restart the bridge only when it fails, so the newer bridge keeps the computer.
+  const service = new BridgeService({ codexPath: values.codex, loginShell: !values["no-login-shell"], streamTTLSeconds: Number(values["stream-ttl"]), onReplaced: () => process.exit(0) });
   service.start();
-  for (const signal of ["SIGINT", "SIGTERM"]         ) process.on(signal, () => { service.stop(); process.exit(0); });
+  return service;
 }
 
 /** Warns, without stopping, when Codex does not answer the way the bridge will run it (through the login shell). */
 function checkCodex() {
   const codex = values.codex ?? "codex";
-  const loginShell = !values["no-login-shell"] && process.env.SHELL;
+  const loginShell = process.platform !== "win32" && !values["no-login-shell"] && process.env.SHELL;
   const result = loginShell
-    ? spawnSync(process.env.SHELL , ["-lic", `"$0" --version`, codex], { encoding: "utf8", timeout: 15_000 })
-    : spawnSync(codex, ["--version"], { encoding: "utf8", timeout: 15_000 });
+    ? spawnCommandSync(process.env.SHELL , ["-lic", `"$0" --version`, codex], { encoding: "utf8", timeout: 15_000 })
+    : 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.`);
 }
 
+function serviceSupported()          {
+  try { servicePlan({ platform: process.platform, label: "x", home: "/", bridgeHome: "/", program: [], env: {}, uid: 0 }); return true; } catch { return false; }
+}
+
+async function ask(question        )                   {
+  const prompt = readline.createInterface({ input: process.stdin, output: process.stdout });
+  try { return !/^n(o)?$/i.test((await prompt.question(question)).trim()); } finally { prompt.close(); }
+}
+
+/** --install, --no-install, or ask in a terminal; never without one. */
+async function wantBackground()                   {
+  if (values["no-install"] || !serviceSupported()) return false;
+  if (values.install) return true;
+  if (!process.stdin.isTTY) return false;
+  return ask("Keep it running in the background and start it at login, so you can close this terminal? [Y/n] ");
+}
+
+function install()       {
+  const plan = installService(startArgs(), console.log);
+  console.log(`Running in the background: ${plan.where}. It starts at login and comes back if it stops, so this terminal can be closed.`);
+  console.log(`Log: ${logPath()}. Remove it with "npx replica-bridge uninstall".`);
+  if (process.platform === "linux") console.log(`To keep it running while you are logged out: loginctl enable-linger ${process.env.USER ?? "$USER"}`);
+}
+
+async function pairOrExplain() {
+  try {
+    await pair({ confirm: values.confirm, yes: values.yes, timeoutSeconds: Number(values.timeout), pngPath: values.png });
+  } catch (error) {
+    console.error(`replica-bridge: ${(error         ).message}. Pair later with "npx replica-bridge pair".`);
+  }
+}
+
+function status() {
+  let state;
+  try { state = loadState(); } catch { console.log(`Not set up yet: run "npx replica-bridge".`); return; }
+  const info = readServiceInfo();
+  const pid = runningPid();
+  console.log(`${state.hostName} (${state.hostId}), relay ${state.relay}`);
+  console.log(`Owner: ${state.owner ? `${state.owner.login} (${state.owner.provider})` : "none yet"}; paired phones: ${state.devices.map((d) => d.name).join(", ") || "none"}`);
+  if (info) console.log(`Background service ${info.version}: ${pid ? `running (pid ${pid})` : "installed, not running right now"}. Log: ${logPath()}`);
+  else console.log(pid ? `Running (pid ${pid}).` : `Not running: "npx replica-bridge" sets up the background service.`);
+}
+
 async function main() {
+  if (values.version) { console.log(PACKAGE_VERSION); return; }
   if (values.help || command === "help") { console.log(usage); return; }
   switch (command) {
     case undefined:
     case "up": {
+      const installed = readServiceInfo();
+      if (installed && !values.pair && !values.install) {
+        if (installed.version !== PACKAGE_VERSION) {
+          console.log(`Updating the background service from ${installed.version} to ${PACKAGE_VERSION}.`);
+          install();
+        }
+        status();
+        break;
+      }
       checkCodex();
       const state = await ensureEnrolled(values.relay, console.log, values.name);
-      startService();
-      if (values.pair || !state.devices.length) {
+      if (installed && !values.install) { await pairOrExplain(); break; } // the background service serves the phone
+      if (runningPid()) throw new Error(`a bridge already runs for this computer (pid ${runningPid()}); stop it first`);
+      let bridge = startBridge();
+      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 {
-          await pair({ confirm: values.confirm, yes: values.yes, timeoutSeconds: Number(values.timeout), pngPath: values.png });
+          install();
+          process.exit(0);
         } catch (error) {
-          console.error(`replica-bridge: ${(error         ).message}. Pair later with "replica-bridge pair".`);
+          console.error(`replica-bridge: could not set up the background service: ${(error         ).message}`);
+          bridge = startBridge();
         }
       }
-      console.log(`Running: paired phones can use Codex on ${state.hostName} while this keeps running (Ctrl-C stops it).`);
+      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).`);
       break;
     }
+    case "install":
+      await ensureEnrolled(values.relay, console.log, values.name);
+      install();
+      break;
+    case "uninstall": {
+      const plan = uninstallService();
+      console.log(plan ? `Removed the background service (${plan.where}). This computer stays paired; "npx replica-bridge" sets it up again.` : "No background service is installed.");
+      break;
+    }
+    case "status":
+      status();
+      break;
     case "init": {
       const relay = values.relay ?? defaultRelayURL();
       const state = await enroll(relay, { name: values.name, publicRelay: values["public-url"] });
-      console.log(`Set up ${state.hostName} as ${state.hostId}. Next: "replica-bridge start" (keep it running), then "replica-bridge pair".`);
+      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.");
       break;
     }
@@ -102,11 +196,17 @@ async function main() {
     case "pair":
       await ensureEnrolled(values.relay, console.log, values.name);
       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.`);
       break;
-    case "start":
+    case "start": {
       await ensureEnrolled(values.relay, console.log, values.name);
-      startService();
+      const asService = process.env.REPLICA_BRIDGE_SERVICE === "1";
+      if (runningPid()) throw new Error(`a bridge already runs for this computer (pid ${runningPid()})${asService ? "" : '; "npx replica-bridge uninstall" stops the background one'}`);
+      const bridge = startBridge();
+      if (asService) { writePid(); process.on("exit", clearPid); }
+      for (const signal of ["SIGINT", "SIGTERM"]         ) process.on(signal, () => { bridge.stop(); process.exit(0); });
       break;
+    }
     case "devices": {
       const state = loadState();
       const { owner, devices } = await relayRequest                                                                                                                                                                                   (state.relay, "GET", "/v1/host/devices", { token: state.hostToken });

package/src/bridge/service.js

@@ -3,7 +3,6 @@
 // The bridge does not run or configure Codex: when no app-server answers it asks Codex to start its own managed
 // one (`codex app-server daemon start`). A stream outlives the phone's connection for `streamTTL`, buffering what
 // the app-server says, so a phone that drops off the network resumes where it left off.
-import { spawn } from "node:child_process";
                                                        
 import crypto from "node:crypto";
 import os from "node:os";
@@ -15,7 +14,10 @@ import {
 } from "../protocol.js";
                                                                             
 import { relaySocketURL } from "../http.js";
+import { killCommand, spawnCommand } from "./command.js";
 import { hostKeyPair, loadState } from "./state.js";
+import { annotateWriterError } from "./writer.js";
+                                          
                                               
 
                                  
@@ -28,6 +30,13 @@ import { hostKeyPair, loadState } from "./state.js";
                        
                             
                                   
+     
+                                                                                                                
+                                                                                          
+     
+                          
+                                                                                          
+                                                            
  
 
                   
@@ -39,6 +48,8 @@ import { hostKeyPair, loadState } from "./state.js";
                     
                                 
                                   
+                                                                                                                       
+                         
  
 
                 
@@ -92,10 +103,16 @@ export class BridgeService {
     ws.on("unexpected-response", (_req, res) => this.log(`relay refused the host connection: HTTP ${res.statusCode}`));
     ws.on("error", (error) => this.log(`relay connection error: ${error.message}`));
     ws.on("close", (code) => {
+      if (ws !== this.relay) return; // a socket this bridge already replaced itself
       for (const conn of this.conns.values()) this.detach(conn);
       this.conns.clear();
       if (this.stopped) return;
-      if (code === CloseCode.replaced) this.log("another bridge with the same identity connected; reconnecting anyway");
+      if (code === CloseCode.replaced) {
+        this.log("another bridge for this computer connected to the relay, which keeps only the newest; stopping this one");
+        this.stop();
+        this.options.onReplaced?.();
+        return;
+      }
       const delay = Math.min(30_000, 1000 * 2 ** this.retry++);
       setTimeout(() => this.connectRelay(), delay);
     });
@@ -176,6 +193,10 @@ export class BridgeService {
       this.scheduleAck(stream);
     } else if (message.t === "ack") {
       conn.stream?.out.ack(message.seq);
+    } else if (message.t === "closed") {
+      // The phone is done with this stream: stop its proxy now, so the app-server unloads the threads it followed and
+      // the computer's other Codex apps can open them, rather than holding them for streamTTL.
+      if (conn.stream) this.endStream(conn.stream, "the phone closed the stream");
     }
   }
 
@@ -202,12 +223,17 @@ export class BridgeService {
 
           async openStream(deviceId        )                  {
     const appServer = await this.connectAppServer();
-    const stream         = { id: crypto.randomBytes(12).toString("base64url"), deviceId, appServer, out: new StreamBuffer(), in: new StreamBuffer(), conn: null, expiry: null, ackTimer: null };
+    const stream         = { id: crypto.randomBytes(12).toString("base64url"), deviceId, appServer, out: new StreamBuffer(), in: new StreamBuffer(), conn: null, expiry: null, ackTimer: null, relayed: Promise.resolve() };
     this.streams.set(stream.id, stream);
     appServer.on("message", (data         ) => {
-      let item;
-      try { item = stream.out.push(data.toString()); } catch { return this.endStream(stream, "the phone stayed away too long and the buffer filled up"); }
-      if (stream.conn) this.sendInner(stream.conn, { t: "msg", seq: item.seq, line: item.line });
+      const annotated = annotateWriterError(data.toString(), this.options.findWriter);
+      stream.relayed = stream.relayed.then(async () => {
+        const line = await annotated;
+        if (!this.streams.has(stream.id)) return;
+        let item;
+        try { item = stream.out.push(line); } catch { return this.endStream(stream, "the phone stayed away too long and the buffer filled up"); }
+        if (stream.conn) this.sendInner(stream.conn, { t: "msg", seq: item.seq, line: item.line });
+      });
     });
     appServer.on("close", () => this.endStream(stream, "codex app-server closed the connection"));
     appServer.on("error", (error) => this.log(`app-server stream ${stream.id}: ${error.message}`));
@@ -251,19 +277,19 @@ export class BridgeService {
    */
           openProxy()                     {
     return new Promise((resolve, reject) => {
-      const child               = spawn(this.options.codexPath ?? "codex", ["app-server", "proxy"], { stdio: ["pipe", "pipe", "pipe"] });
+      const child               = spawnCommand(this.options.codexPath ?? "codex", ["app-server", "proxy"], { stdio: ["pipe", "pipe", "pipe"] });
       let stderr = "";
       child.stderr .on("data", (chunk) => { stderr = (stderr + chunk).slice(-2000); });
       const pipe = Duplex.from({ readable: child.stdout , writable: child.stdin  })                                    ;
       // The HTTP client that carries the WebSocket handshake tunes its socket; a pipe has nothing to tune.
       for (const name of ["setNoDelay", "setKeepAlive", "setTimeout", "ref", "unref"]) pipe[name] = () => pipe;
       const ws = new WebSocket("ws://localhost/", { createConnection: () => pipe         , perMessageDeflate: false, maxPayload: MAX_FRAME_BYTES });
-      const fail = (why        ) => { ws.removeAllListeners("open"); child.kill(); reject(new Error(why)); };
+      const fail = (why        ) => { ws.removeAllListeners("open"); killCommand(child); reject(new Error(why)); };
       child.once("error", (error) => fail(`could not run codex: ${error.message}`));
       child.once("exit", (code) => { if (ws.readyState !== WebSocket.OPEN) fail(`codex app-server proxy exited (${code})${stderr ? `: ${stderr.trim()}` : ""}`); });
       ws.once("error", (error) => { if (ws.readyState !== WebSocket.OPEN) fail(error.message); });
       ws.once("open", () => {
-        ws.on("close", () => child.kill());
+        ws.on("close", () => killCommand(child));
         resolve(ws);
       });
     });
@@ -272,8 +298,8 @@ 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          )                   {
     return new Promise((resolve, reject) => {
-      const child = spawn(command, args, { stdio: "ignore" });
-      const timer = setTimeout(() => { child.kill(); resolve(false); }, 30_000);
+      const child = spawnCommand(command, args, { stdio: "ignore" });
+      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); });
     });
@@ -289,8 +315,9 @@ export class BridgeService {
     // people configure Codex (config.toml, auth.json, cc-switch, keys exported in their shell rc), the daemon should
     // see what their terminal sees, so ask through their login shell; fall back to a direct start.
     const codex = this.options.codexPath ?? "codex";
-    // launchd services may have no SHELL; the account's login shell is the same answer.
-    const shell = process.env.SHELL || os.userInfo().shell;
+    // launchd services may have no SHELL; the account's login shell is the same answer. Windows has no login shell
+    // (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)
       : false;

package/src/bridge/writer.js

@@ -0,0 +1,67 @@
+// Which app holds a thread when the app-server answers "thread <id> already has an active writer". Codex lets one
+// process write a thread at a time through a lock file, `$CODEX_HOME/thread-writer-locks/<id>.lock`, and the error
+// does not say who has it. On the computer the bridge can: whoever has the lock file open. The answer goes back to
+// the phone in the error's `data.replicaWriter`, so the app can say "the ChatGPT desktop app has this task" rather
+// than "another Codex session". Only macOS and Linux (lsof); elsewhere, or when lsof finds nothing, the error passes
+// through unchanged.
+import { execFile } from "node:child_process";
+import os from "node:os";
+import path from "node:path";
+
+/** The app holding a thread's lock, as the phone reads it. */
+                                                                                 
+
+                         
+                 
+              
+ 
+
+const ACTIVE_WRITER = /^thread ([0-9A-Za-z-]+) already has an active writer/;
+
+/**
+ * The app behind a process's command line. The ChatGPT desktop app runs its own app-server from inside its bundle
+ * (`/Applications/ChatGPT.app/Contents/Resources/codex-cli/CodexCLI.app/…/codex app-server`, observed with
+ * ChatGPT 155.0.8059.80); `codex exec` runs one for the length of the command.
+ */
+export function classifyWriter(command        )            {
+  if (/\/(ChatGPT|Codex)\.app\//.test(command)) return "chatgpt-desktop";
+  if (/(^|[\s/])codex(\.exe)?\s+(.*\s)?exec(\s|$)/.test(command)) return "codex-exec";
+  if (/(^|[\s/])codex(\.exe)?(\s|$)/.test(command)) return "codex-cli";
+  return "other";
+}
+
+function run(command        , args          )                  {
+  return new Promise((resolve) => {
+    execFile(command, args, { timeout: 3000 }, (_error, stdout) => resolve(String(stdout ?? "")));
+  });
+}
+
+/** Who has the thread's lock file open; null when nobody does or it cannot be told on this platform. */
+export async function findWriter(threadId        , codexHome = process.env.CODEX_HOME || path.join(os.homedir(), ".codex"))                         {
+  if (process.platform === "win32") return null;
+  const lock = path.join(codexHome, "thread-writer-locks", `${threadId}.lock`);
+  const pids = (await run("lsof", ["-t", "--", lock])).split(/\s+/).map(Number).filter((pid) => pid > 0 && pid !== process.pid);
+  for (const pid of pids) {
+    const command = (await run("ps", ["-o", "command=", "-p", String(pid)])).trim();
+    if (command) return { app: classifyWriter(command), pid };
+  }
+  return null;
+}
+
+/**
+ * An app-server line with the writer added to an "already has an active writer" error, or the line itself. Lines
+ * that cannot be such an error are not parsed.
+ */
+export async function annotateWriterError(line        , find                                               = findWriter)                  {
+  if (!line.includes("already has an active writer")) return line;
+  let message;
+  try { message = JSON.parse(line); } catch { return line; }
+  const error = message?.error;
+  const threadId = typeof error?.message === "string" ? ACTIVE_WRITER.exec(error.message)?.[1] : undefined;
+  if (!threadId) return line;
+  const writer = await find(threadId).catch(() => null);
+  if (!writer) return line;
+  const data = error.data && typeof error.data === "object" && !Array.isArray(error.data) ? error.data : {};
+  message.error = { ...error, data: { ...data, replicaWriter: writer } };
+  return JSON.stringify(message);
+}