@deepdream314/remodex 1.3.9 → 1.3.11

package/bin/remodex.js

@@ -1,19 +1,26 @@
 #!/usr/bin/env node
 // FILE: remodex.js
-// Purpose: CLI surface for foreground bridge runs, pairing reset, thread resume, and macOS service control.
+// Purpose: CLI surface for foreground bridge runs, pairing reset, thread resume, and local service control.
 // Layer: CLI binary
 // Exports: none
 // Depends on: ../src
 
 const {
+  getLinuxBridgeServiceStatus,
   getMacOSBridgeServiceStatus,
+  printLinuxBridgePairingQr,
   printMacOSBridgePairingQr,
+  printLinuxBridgeServiceStatus,
   printMacOSBridgeServiceStatus,
   readBridgeConfig,
+  resetLinuxBridgePairing,
   resetMacOSBridgePairing,
+  runLinuxBridgeService,
   runMacOSBridgeService,
   startBridge,
+  startLinuxBridgeService,
   startMacOSBridgeService,
+  stopLinuxBridgeService,
   stopMacOSBridgeService,
   resetBridgePairing,
   openLastActiveThread,
@@ -22,14 +29,21 @@ const {
 const { version } = require("../package.json");
 
 const defaultDeps = {
+  getLinuxBridgeServiceStatus,
   getMacOSBridgeServiceStatus,
+  printLinuxBridgePairingQr,
   printMacOSBridgePairingQr,
+  printLinuxBridgeServiceStatus,
   printMacOSBridgeServiceStatus,
   readBridgeConfig,
+  resetLinuxBridgePairing,
   resetMacOSBridgePairing,
+  runLinuxBridgeService,
   runMacOSBridgeService,
   startBridge,
+  startLinuxBridgeService,
   startMacOSBridgeService,
+  stopLinuxBridgeService,
   stopMacOSBridgeService,
   resetBridgePairing,
   openLastActiveThread,
@@ -67,6 +81,16 @@ async function main({
       return;
     }
 
+    if (platform === "linux") {
+      const result = await deps.startLinuxBridgeService({
+        waitForPairing: true,
+      });
+      deps.printLinuxBridgePairingQr({
+        pairingSession: result.pairingSession,
+      });
+      return;
+    }
+
     deps.startBridge();
     return;
   }
@@ -77,28 +101,41 @@ async function main({
   }
 
   if (command === "run-service") {
-    deps.runMacOSBridgeService();
+    if (platform === "darwin") {
+      deps.runMacOSBridgeService();
+      return;
+    }
+
+    if (platform === "linux") {
+      deps.runLinuxBridgeService();
+      return;
+    }
+
+    deps.startBridge();
     return;
   }
 
   if (command === "start") {
-    assertMacOSCommand(command, {
+    deps.readBridgeConfig();
+    const result = await startManagedBridgeService({
+      commandName: command,
       platform,
+      deps,
       consoleImpl,
       exitImpl,
     });
-    deps.readBridgeConfig();
-    const result = await deps.startMacOSBridgeService({
-      waitForPairing: false,
-    });
     emitResult({
       payload: {
         ok: true,
         currentVersion: version,
+        platform,
         plistPath: result?.plistPath,
+        unitPath: result?.unitPath,
         pairingSession: result?.pairingSession,
       },
-      message: "[remodex] macOS bridge service is running.",
+      message: platform === "darwin"
+        ? "[remodex] macOS bridge service is running."
+        : "[remodex] Linux bridge service is running.",
       jsonOutput,
       consoleImpl,
     });
@@ -106,23 +143,26 @@ async function main({
   }
 
   if (command === "restart") {
-    assertMacOSCommand(command, {
+    deps.readBridgeConfig();
+    const result = await startManagedBridgeService({
+      commandName: command,
       platform,
+      deps,
       consoleImpl,
       exitImpl,
     });
-    deps.readBridgeConfig();
-    const result = await deps.startMacOSBridgeService({
-      waitForPairing: false,
-    });
     emitResult({
       payload: {
         ok: true,
         currentVersion: version,
+        platform,
         plistPath: result?.plistPath,
+        unitPath: result?.unitPath,
         pairingSession: result?.pairingSession,
       },
-      message: "[remodex] macOS bridge service restarted.",
+      message: platform === "darwin"
+        ? "[remodex] macOS bridge service restarted."
+        : "[remodex] Linux bridge service restarted.",
       jsonOutput,
       consoleImpl,
     });
@@ -130,18 +170,21 @@ async function main({
   }
 
   if (command === "stop") {
-    assertMacOSCommand(command, {
+    stopManagedBridgeService({
       platform,
+      deps,
       consoleImpl,
       exitImpl,
     });
-    deps.stopMacOSBridgeService();
     emitResult({
       payload: {
         ok: true,
         currentVersion: version,
+        platform,
       },
-      message: "[remodex] macOS bridge service stopped.",
+      message: platform === "darwin"
+        ? "[remodex] macOS bridge service stopped."
+        : "[remodex] Linux bridge service stopped.",
       jsonOutput,
       consoleImpl,
     });
@@ -149,19 +192,25 @@ async function main({
   }
 
   if (command === "status") {
-    assertMacOSCommand(command, {
+    const status = getManagedBridgeServiceStatus({
       platform,
+      deps,
       consoleImpl,
       exitImpl,
     });
     if (jsonOutput) {
       emitJson({
-        ...deps.getMacOSBridgeServiceStatus(),
+        ...status,
         currentVersion: version,
       });
       return;
     }
-    deps.printMacOSBridgeServiceStatus();
+    printManagedBridgeServiceStatus({
+      platform,
+      deps,
+      consoleImpl,
+      exitImpl,
+    });
     return;
   }
 
@@ -179,6 +228,18 @@ async function main({
           jsonOutput,
           consoleImpl,
         });
+      } else if (platform === "linux") {
+        deps.resetLinuxBridgePairing();
+        emitResult({
+          payload: {
+            ok: true,
+            currentVersion: version,
+            platform,
+          },
+          message: "[remodex] Stopped the Linux bridge service and cleared the saved pairing state. Run `remodex up` to pair again.",
+          jsonOutput,
+          consoleImpl,
+        });
       } else {
         deps.resetBridgePairing();
         emitResult({
@@ -296,14 +357,89 @@ function assertMacOSCommand(name, {
   consoleImpl = console,
   exitImpl = process.exit,
 } = {}) {
-  if (platform === "darwin") {
+  if (platform === "darwin" || platform === "linux") {
     return;
   }
 
-  consoleImpl.error(`[remodex] \`${name}\` is only available on macOS. Use \`remodex up\` or \`remodex run\` for the foreground bridge on this OS.`);
+  consoleImpl.error(`[remodex] \`${name}\` is only available on macOS and Linux. Use \`remodex up\` or \`remodex run\` for the foreground bridge on this OS.`);
   exitImpl(1);
 }
 
+async function startManagedBridgeService({
+  commandName = "start",
+  platform = process.platform,
+  deps = defaultDeps,
+  consoleImpl = console,
+  exitImpl = process.exit,
+} = {}) {
+  assertMacOSCommand(commandName, {
+    platform,
+    consoleImpl,
+    exitImpl,
+  });
+  if (platform === "darwin") {
+    return deps.startMacOSBridgeService({
+      waitForPairing: false,
+    });
+  }
+  return deps.startLinuxBridgeService({
+    waitForPairing: false,
+  });
+}
+
+function stopManagedBridgeService({
+  platform = process.platform,
+  deps = defaultDeps,
+  consoleImpl = console,
+  exitImpl = process.exit,
+} = {}) {
+  assertMacOSCommand("stop", {
+    platform,
+    consoleImpl,
+    exitImpl,
+  });
+  if (platform === "darwin") {
+    deps.stopMacOSBridgeService();
+    return;
+  }
+  deps.stopLinuxBridgeService();
+}
+
+function getManagedBridgeServiceStatus({
+  platform = process.platform,
+  deps = defaultDeps,
+  consoleImpl = console,
+  exitImpl = process.exit,
+} = {}) {
+  assertMacOSCommand("status", {
+    platform,
+    consoleImpl,
+    exitImpl,
+  });
+  if (platform === "darwin") {
+    return deps.getMacOSBridgeServiceStatus();
+  }
+  return deps.getLinuxBridgeServiceStatus();
+}
+
+function printManagedBridgeServiceStatus({
+  platform = process.platform,
+  deps = defaultDeps,
+  consoleImpl = console,
+  exitImpl = process.exit,
+} = {}) {
+  assertMacOSCommand("status", {
+    platform,
+    consoleImpl,
+    exitImpl,
+  });
+  if (platform === "darwin") {
+    deps.printMacOSBridgeServiceStatus();
+    return;
+  }
+  deps.printLinuxBridgeServiceStatus();
+}
+
 function isVersionCommand(value) {
   return value === "-v" || value === "--v" || value === "-V" || value === "--version" || value === "version";
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepdream314/remodex",
-  "version": "1.3.9",
+  "version": "1.3.11",
   "description": "Local bridge between Codex and the Remodex mobile app. Run `remodex up` to start.",
   "main": "src/index.js",
   "bin": {

package/src/account-status.js

@@ -80,6 +80,44 @@ function redactAuthStatus(authStatus = null, extras = {}) {
 
 // ─── Settled snapshot helpers ───────────────────────────────
 
+function applyLocalAuthFallbackToSettledAuthStatus(
+  authStatusResult = null,
+  localAuthResult = null
+) {
+  const localAuthStatus = localAuthResult?.status === "fulfilled" ? localAuthResult.value : null;
+  if (!localAuthStatus?.token || !localAuthStatus?.isChatGPT) {
+    return authStatusResult;
+  }
+
+  if (authStatusResult?.status === "fulfilled") {
+    const authStatus = authStatusResult.value;
+    if (normalizeString(authStatus?.authToken)) {
+      return authStatusResult;
+    }
+
+    return {
+      status: "fulfilled",
+      value: {
+        ...authStatus,
+        authMethod: normalizeString(localAuthStatus.authMethod)
+          || normalizeString(authStatus?.authMethod)
+          || "chatgpt",
+        authToken: localAuthStatus.token,
+        requiresOpenaiAuth: localAuthStatus.requiresOpenaiAuth ?? authStatus?.requiresOpenaiAuth,
+      },
+    };
+  }
+
+  return {
+    status: "fulfilled",
+    value: {
+      authMethod: normalizeString(localAuthStatus.authMethod) || "chatgpt",
+      authToken: localAuthStatus.token,
+      requiresOpenaiAuth: localAuthStatus.requiresOpenaiAuth,
+    },
+  };
+}
+
 // Collapses settled bridge RPC results into one safe snapshot, even if one side fails.
 // Input: Promise.allSettled-style results → Output: sanitized account status object
 // Throws if both the account read and auth status fail, so the bridge can surface a real error.
@@ -141,6 +179,7 @@ function parseBoolean(value) {
 }
 
 module.exports = {
+  applyLocalAuthFallbackToSettledAuthStatus,
   composeAccountStatus,
   composeSanitizedAuthStatusFromSettledResults,
   redactAuthStatus,

package/src/bridge.js

@@ -22,8 +22,13 @@ const { handleGitRequest } = require("./git-handler");
 const { handleThreadContextRequest } = require("./thread-context-handler");
 const { handleWorkspaceRequest } = require("./workspace-handler");
 const { createNotificationsHandler } = require("./notifications-handler");
-const { createVoiceHandler, resolveVoiceAuth } = require("./voice-handler");
 const {
+  createVoiceHandler,
+  readLocalChatGPTAuthTokenFromDisk,
+  resolveVoiceAuth,
+} = require("./voice-handler");
+const {
+  applyLocalAuthFallbackToSettledAuthStatus,
   composeSanitizedAuthStatusFromSettledResults,
 } = require("./account-status");
 const { createBridgePackageVersionStatusReader } = require("./package-version-status");
@@ -528,7 +533,7 @@ function startBridge({
       case "account/login/openOnMac":
         return openPendingAuthLoginOnMac(params);
       case "voice/resolveAuth":
-        return resolveVoiceAuth(sendCodexRequest);
+        return resolveVoiceAuth(sendCodexRequest, params);
       default:
         throw new Error(`Unsupported bridge-managed account method: ${method}`);
     }
@@ -537,7 +542,7 @@ function startBridge({
   // Combines account/read + getAuthStatus into one safe snapshot for the phone UI.
   // The two RPCs are settled independently so one transient failure does not hide the other.
   async function readSanitizedAuthStatus() {
-    const [accountReadResult, authStatusResult, bridgeVersionInfoResult] = await Promise.allSettled([
+    const [accountReadResult, authStatusResult, bridgeVersionInfoResult, localAuthResult] = await Promise.allSettled([
       sendCodexRequest("account/read", {
         refreshToken: false,
       }),
@@ -546,6 +551,7 @@ function startBridge({
         refreshToken: false,
       }),
       readBridgePackageVersionStatus(),
+      readLocalChatGPTAuthTokenFromDisk(),
     ]);
 
     return composeSanitizedAuthStatusFromSettledResults({
@@ -555,7 +561,7 @@ function startBridge({
           value: normalizeAccountRead(accountReadResult.value),
         }
         : accountReadResult,
-      authStatusResult,
+      authStatusResult: applyLocalAuthFallbackToSettledAuthStatus(authStatusResult, localAuthResult),
       loginInFlight: Boolean(pendingAuthLogin.loginId),
       bridgeVersionInfo: bridgeVersionInfoResult.status === "fulfilled"
         ? bridgeVersionInfoResult.value

package/src/daemon-state.js

@@ -1,5 +1,5 @@
 // FILE: daemon-state.js
-// Purpose: Persists macOS service config/runtime state outside the repo for the launchd bridge flow.
+// Purpose: Persists bridge service config/runtime state outside the repo for local daemon flows.
 // Layer: CLI helper
 // Exports: path resolvers plus read/write helpers for daemon config, pairing payloads, and service status.
 // Depends on: fs, os, path

package/src/index.js

@@ -1,14 +1,23 @@
 // FILE: index.js
 // Purpose: Small entrypoint wrapper for bridge lifecycle commands.
 // Layer: CLI entry
-// Exports: bridge lifecycle, pairing reset, thread resume/watch, and macOS service helpers.
-// Depends on: ./bridge, ./secure-device-state, ./session-state, ./rollout-watch, ./macos-launch-agent
+// Exports: bridge lifecycle, pairing reset, thread resume/watch, and platform service helpers.
+// Depends on: ./bridge, ./secure-device-state, ./session-state, ./rollout-watch, ./linux-systemd, ./macos-launch-agent
 
 const { startBridge } = require("./bridge");
 const { resetBridgeDeviceState } = require("./secure-device-state");
 const { openLastActiveThread } = require("./session-state");
 const { watchThreadRollout } = require("./rollout-watch");
 const { readBridgeConfig } = require("./codex-desktop-refresher");
+const {
+  getLinuxBridgeServiceStatus,
+  printLinuxBridgePairingQr,
+  printLinuxBridgeServiceStatus,
+  resetLinuxBridgePairing,
+  runLinuxBridgeService,
+  startLinuxBridgeService,
+  stopLinuxBridgeService,
+} = require("./linux-systemd");
 const {
   getMacOSBridgeServiceStatus,
   printMacOSBridgePairingQr,
@@ -20,14 +29,21 @@ const {
 } = require("./macos-launch-agent");
 
 module.exports = {
+  getLinuxBridgeServiceStatus,
   getMacOSBridgeServiceStatus,
+  printLinuxBridgePairingQr,
   printMacOSBridgePairingQr,
+  printLinuxBridgeServiceStatus,
   printMacOSBridgeServiceStatus,
   readBridgeConfig,
+  resetLinuxBridgePairing,
   resetMacOSBridgePairing,
+  runLinuxBridgeService,
   startBridge,
   runMacOSBridgeService,
+  startLinuxBridgeService,
   startMacOSBridgeService,
+  stopLinuxBridgeService,
   stopMacOSBridgeService,
   resetBridgePairing: resetBridgeDeviceState,
   openLastActiveThread,

package/src/linux-systemd.js

@@ -0,0 +1,435 @@
+// FILE: linux-systemd.js
+// Purpose: Owns Linux-only systemd user-service install/start/stop/status helpers for the background Remodex bridge.
+// Layer: CLI helper
+// Exports: start/stop/status helpers plus the systemd service runner used by `remodex up`.
+// Depends on: child_process, fs, os, path, ./bridge, ./daemon-state, ./codex-desktop-refresher, ./qr, ./secure-device-state
+
+const { execFileSync } = require("child_process");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { startBridge } = require("./bridge");
+const { readBridgeConfig } = require("./codex-desktop-refresher");
+const { printQR } = require("./qr");
+const { resetBridgeDeviceState } = require("./secure-device-state");
+const {
+  clearBridgeStatus,
+  clearPairingSession,
+  ensureRemodexLogsDir,
+  ensureRemodexStateDir,
+  readBridgeStatus,
+  readDaemonConfig,
+  readPairingSession,
+  resolveBridgeStderrLogPath,
+  resolveBridgeStdoutLogPath,
+  resolveRemodexStateDir,
+  writeBridgeStatus,
+  writeDaemonConfig,
+  writePairingSession,
+} = require("./daemon-state");
+
+const SERVICE_NAME = "com.remodex.bridge.service";
+const DEFAULT_PAIRING_WAIT_TIMEOUT_MS = 10_000;
+const DEFAULT_PAIRING_WAIT_INTERVAL_MS = 200;
+
+function runLinuxBridgeService({ env = process.env, platform = process.platform } = {}) {
+  assertLinuxPlatform(platform);
+  const config = readDaemonConfig({ env });
+  if (!config?.relayUrl) {
+    const message = "No relay URL configured for the Linux bridge service.";
+    clearPairingSession({ env });
+    writeBridgeStatus({
+      state: "error",
+      connectionStatus: "error",
+      pid: process.pid,
+      lastError: message,
+    }, { env });
+    console.error(`[remodex] ${message}`);
+    return;
+  }
+
+  startBridge({
+    config,
+    printPairingQr: false,
+    onPairingPayload(pairingPayload) {
+      writePairingSession(pairingPayload, { env });
+    },
+    onBridgeStatus(status) {
+      writeBridgeStatus(status, { env });
+    },
+  });
+}
+
+async function startLinuxBridgeService({
+  env = process.env,
+  platform = process.platform,
+  fsImpl = fs,
+  execFileSyncImpl = execFileSync,
+  osImpl = os,
+  nodePath = process.execPath,
+  cliPath = path.resolve(__dirname, "..", "bin", "remodex.js"),
+  waitForPairing = false,
+  pairingTimeoutMs = DEFAULT_PAIRING_WAIT_TIMEOUT_MS,
+  pairingPollIntervalMs = DEFAULT_PAIRING_WAIT_INTERVAL_MS,
+} = {}) {
+  assertLinuxPlatform(platform);
+  const config = readBridgeConfig({ env });
+  assertRelayConfigured(config);
+  const startedAt = Date.now();
+
+  writeDaemonConfig(config, { env, fsImpl });
+  clearPairingSession({ env, fsImpl });
+  clearBridgeStatus({ env, fsImpl });
+  ensureRemodexStateDir({ env, fsImpl, osImpl });
+  ensureRemodexLogsDir({ env, fsImpl, osImpl });
+
+  const unitPath = writeUserServiceUnit({
+    env,
+    fsImpl,
+    osImpl,
+    nodePath,
+    cliPath,
+  });
+
+  runSystemctl(["--user", "daemon-reload"], { execFileSyncImpl });
+  runSystemctl(["--user", "enable", SERVICE_NAME], { execFileSyncImpl });
+  runSystemctl(["--user", "restart", SERVICE_NAME], { execFileSyncImpl });
+
+  if (!waitForPairing) {
+    return {
+      unitPath,
+      pairingSession: null,
+    };
+  }
+
+  const pairingSession = await waitForFreshPairingSession({
+    env,
+    fsImpl,
+    startedAt,
+    timeoutMs: pairingTimeoutMs,
+    intervalMs: pairingPollIntervalMs,
+  });
+  return {
+    unitPath,
+    pairingSession,
+  };
+}
+
+function stopLinuxBridgeService({
+  env = process.env,
+  platform = process.platform,
+  execFileSyncImpl = execFileSync,
+  fsImpl = fs,
+} = {}) {
+  assertLinuxPlatform(platform);
+  try {
+    runSystemctl(["--user", "disable", "--now", SERVICE_NAME], {
+      execFileSyncImpl,
+    });
+  } catch (error) {
+    if (!isMissingSystemdUnitError(error)) {
+      throw error;
+    }
+  }
+  clearPairingSession({ env, fsImpl });
+  clearBridgeStatus({ env, fsImpl });
+}
+
+function resetLinuxBridgePairing({
+  env = process.env,
+  platform = process.platform,
+  execFileSyncImpl = execFileSync,
+  fsImpl = fs,
+  resetBridgePairingImpl = resetBridgeDeviceState,
+} = {}) {
+  assertLinuxPlatform(platform);
+  stopLinuxBridgeService({
+    env,
+    platform,
+    execFileSyncImpl,
+    fsImpl,
+  });
+  return resetBridgePairingImpl();
+}
+
+function getLinuxBridgeServiceStatus({
+  env = process.env,
+  platform = process.platform,
+  execFileSyncImpl = execFileSync,
+  fsImpl = fs,
+  osImpl = os,
+} = {}) {
+  assertLinuxPlatform(platform);
+  const unitPath = resolveUserServiceUnitPath({ env, osImpl });
+  const serviceState = readSystemdServiceState({
+    execFileSyncImpl,
+    missingAsStopped: true,
+  });
+  return {
+    label: SERVICE_NAME,
+    manager: "systemd-user",
+    platform: "linux",
+    installed: fsImpl.existsSync(unitPath),
+    unitPath,
+    unitLoaded: serviceState.loadState === "loaded",
+    activeState: serviceState.activeState,
+    subState: serviceState.subState,
+    servicePid: serviceState.execMainPid,
+    unitFileState: serviceState.unitFileState,
+    daemonConfig: readDaemonConfig({ env, fsImpl }),
+    bridgeStatus: readBridgeStatus({ env, fsImpl }),
+    pairingSession: readPairingSession({ env, fsImpl }),
+    stdoutLogPath: resolveBridgeStdoutLogPath({ env }),
+    stderrLogPath: resolveBridgeStderrLogPath({ env }),
+  };
+}
+
+function printLinuxBridgeServiceStatus(options = {}) {
+  const status = getLinuxBridgeServiceStatus(options);
+  const bridgeState = status.bridgeStatus?.state || "unknown";
+  const connectionStatus = status.bridgeStatus?.connectionStatus || "unknown";
+  const pairingCreatedAt = status.pairingSession?.createdAt || "none";
+  console.log(`[remodex] Service label: ${status.label}`);
+  console.log("[remodex] Service manager: systemd --user");
+  console.log(`[remodex] Installed: ${status.installed ? "yes" : "no"}`);
+  console.log(`[remodex] Loaded: ${status.unitLoaded ? "yes" : "no"}`);
+  console.log(`[remodex] Active state: ${status.activeState}`);
+  console.log(`[remodex] Sub-state: ${status.subState}`);
+  console.log(`[remodex] PID: ${status.servicePid || status.bridgeStatus?.pid || "unknown"}`);
+  console.log(`[remodex] Bridge state: ${bridgeState}`);
+  console.log(`[remodex] Connection: ${connectionStatus}`);
+  console.log(`[remodex] Pairing payload: ${pairingCreatedAt}`);
+  console.log(`[remodex] Unit file: ${status.unitPath}`);
+  console.log(`[remodex] Stdout log: ${status.stdoutLogPath}`);
+  console.log(`[remodex] Stderr log: ${status.stderrLogPath}`);
+}
+
+function printLinuxBridgePairingQr({ pairingSession = null, env = process.env, fsImpl = fs } = {}) {
+  const nextPairingSession = pairingSession || readPairingSession({ env, fsImpl });
+  const pairingPayload = nextPairingSession?.pairingPayload;
+  if (!pairingPayload) {
+    throw new Error("The Linux bridge service did not publish a pairing payload yet.");
+  }
+
+  printQR(pairingPayload);
+}
+
+function writeUserServiceUnit({
+  env = process.env,
+  fsImpl = fs,
+  osImpl = os,
+  nodePath = process.execPath,
+  cliPath = path.resolve(__dirname, "..", "bin", "remodex.js"),
+} = {}) {
+  const unitPath = resolveUserServiceUnitPath({ env, osImpl });
+  const stateDir = resolveRemodexStateDir({ env, osImpl });
+  const stdoutLogPath = resolveBridgeStdoutLogPath({ env, osImpl });
+  const stderrLogPath = resolveBridgeStderrLogPath({ env, osImpl });
+  const homeDir = env.HOME || osImpl.homedir();
+  const workingDirectory = path.resolve(__dirname, "..");
+  const serialized = buildUserServiceUnit({
+    homeDir,
+    pathEnv: env.PATH || "",
+    stateDir,
+    stdoutLogPath,
+    stderrLogPath,
+    workingDirectory,
+    nodePath,
+    cliPath,
+  });
+
+  fsImpl.mkdirSync(path.dirname(unitPath), { recursive: true });
+  fsImpl.writeFileSync(unitPath, serialized, "utf8");
+  return unitPath;
+}
+
+function buildUserServiceUnit({
+  homeDir,
+  pathEnv,
+  stateDir,
+  stdoutLogPath,
+  stderrLogPath,
+  workingDirectory,
+  nodePath,
+  cliPath,
+}) {
+  return `[Unit]
+Description=Remodex bridge
+After=default.target
+
+[Service]
+Type=simple
+WorkingDirectory=${quoteSystemdPath(workingDirectory)}
+ExecStart=${quoteSystemdExec(nodePath, cliPath, "run-service")}
+Restart=on-failure
+RestartSec=2
+Environment=${quoteSystemdEnv("HOME", homeDir)}
+Environment=${quoteSystemdEnv("PATH", pathEnv)}
+Environment=${quoteSystemdEnv("REMODEX_DEVICE_STATE_DIR", stateDir)}
+StandardOutput=append:${quoteSystemdPath(stdoutLogPath)}
+StandardError=append:${quoteSystemdPath(stderrLogPath)}
+
+[Install]
+WantedBy=default.target
+`;
+}
+
+function resolveUserServiceUnitPath({ env = process.env, osImpl = os } = {}) {
+  const configHome = normalizeNonEmptyString(env.XDG_CONFIG_HOME)
+    || path.join(env.HOME || osImpl.homedir(), ".config");
+  return path.join(configHome, "systemd", "user", SERVICE_NAME);
+}
+
+function readSystemdServiceState({
+  execFileSyncImpl = execFileSync,
+  missingAsStopped = false,
+} = {}) {
+  try {
+    const output = runSystemctl([
+      "--user",
+      "show",
+      "--property=LoadState,ActiveState,SubState,ExecMainPID,UnitFileState",
+      SERVICE_NAME,
+    ], {
+      execFileSyncImpl,
+      encoding: "utf8",
+    });
+    return parseSystemdShowOutput(output);
+  } catch (error) {
+    if (missingAsStopped && isMissingSystemdUnitError(error)) {
+      return {
+        loadState: "not-found",
+        activeState: "inactive",
+        subState: "dead",
+        execMainPid: null,
+        unitFileState: "disabled",
+      };
+    }
+    throw error;
+  }
+}
+
+function runSystemctl(args, {
+  execFileSyncImpl = execFileSync,
+  encoding = "utf8",
+} = {}) {
+  try {
+    return execFileSyncImpl("systemctl", args, {
+      encoding,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      throw new Error("`systemctl --user` is required for Linux bridge service management.");
+    }
+    throw error;
+  }
+}
+
+function parseSystemdShowOutput(output) {
+  const values = Object.create(null);
+  for (const line of String(output || "").split(/\r?\n/)) {
+    if (!line || !line.includes("=")) {
+      continue;
+    }
+    const separatorIndex = line.indexOf("=");
+    const key = line.slice(0, separatorIndex);
+    const value = line.slice(separatorIndex + 1);
+    values[key] = value;
+  }
+
+  const pidValue = Number.parseInt(values.ExecMainPID || "", 10);
+  return {
+    loadState: values.LoadState || "unknown",
+    activeState: values.ActiveState || "unknown",
+    subState: values.SubState || "unknown",
+    execMainPid: Number.isFinite(pidValue) && pidValue > 0 ? pidValue : null,
+    unitFileState: values.UnitFileState || "unknown",
+  };
+}
+
+async function waitForFreshPairingSession({
+  env = process.env,
+  fsImpl = fs,
+  startedAt,
+  timeoutMs,
+  intervalMs,
+} = {}) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const pairingSession = readPairingSession({ env, fsImpl });
+    const createdAt = Date.parse(pairingSession?.createdAt || "");
+    if (pairingSession?.pairingPayload && Number.isFinite(createdAt) && createdAt >= startedAt) {
+      return pairingSession;
+    }
+    await sleep(intervalMs);
+  }
+
+  throw new Error(
+    `Timed out waiting for the Linux bridge service to publish a pairing QR. `
+    + `Check ${resolveBridgeStdoutLogPath({ env })} and ${resolveBridgeStderrLogPath({ env })}.`
+  );
+}
+
+function isMissingSystemdUnitError(error) {
+  const combined = [
+    error?.message,
+    error?.stderr?.toString?.("utf8"),
+    error?.stdout?.toString?.("utf8"),
+  ].filter(Boolean).join("\n").toLowerCase();
+  return combined.includes("unit com.remodex.bridge.service could not be found")
+    || combined.includes("unit com.remodex.bridge.service not found")
+    || combined.includes("not loaded");
+}
+
+function assertLinuxPlatform(platform = process.platform) {
+  if (platform !== "linux") {
+    throw new Error("Linux bridge service management is only available on Linux.");
+  }
+}
+
+function assertRelayConfigured(config) {
+  if (typeof config?.relayUrl === "string" && config.relayUrl.trim()) {
+    return;
+  }
+  throw new Error("No relay URL configured. Run ./run-local-remodex.sh or set REMODEX_RELAY before enabling the Linux bridge service.");
+}
+
+function quoteSystemdValue(value) {
+  return `"${String(value).replaceAll("\\", "\\\\").replaceAll("\"", "\\\"")}"`;
+}
+
+function quoteSystemdPath(value) {
+  return String(value)
+    .replaceAll("\\", "\\\\")
+    .replaceAll(" ", "\\x20")
+    .replaceAll(":", "\\:");
+}
+
+function quoteSystemdEnv(name, value) {
+  return `"${String(name)}=${String(value).replaceAll("\\", "\\\\").replaceAll("\"", "\\\"")}"`;
+}
+
+function quoteSystemdExec(...parts) {
+  return parts.map(quoteSystemdValue).join(" ");
+}
+
+function normalizeNonEmptyString(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : "";
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+module.exports = {
+  buildUserServiceUnit,
+  getLinuxBridgeServiceStatus,
+  printLinuxBridgePairingQr,
+  printLinuxBridgeServiceStatus,
+  resetLinuxBridgePairing,
+  resolveUserServiceUnitPath,
+  runLinuxBridgeService,
+  startLinuxBridgeService,
+  stopLinuxBridgeService,
+};

package/src/macos-launch-agent.js

@@ -33,8 +33,8 @@ const DEFAULT_PAIRING_WAIT_TIMEOUT_MS = 10_000;
 const DEFAULT_PAIRING_WAIT_INTERVAL_MS = 200;
 
 // Runs the bridge inside launchd while keeping QR rendering in the foreground CLI command.
-function runMacOSBridgeService({ env = process.env } = {}) {
-  assertDarwinPlatform();
+function runMacOSBridgeService({ env = process.env, platform = process.platform } = {}) {
+  assertDarwinPlatform(platform);
   const config = readDaemonConfig({ env });
   if (!config?.relayUrl) {
     const message = "No relay URL configured for the macOS bridge service.";

package/src/voice-handler.js

@@ -4,6 +4,10 @@
 // Exports: createVoiceHandler
 // Depends on: global fetch/FormData/Blob, local codex app-server auth via sendCodexRequest
 
+const fs = require("fs/promises");
+const os = require("os");
+const path = require("path");
+
 const CHATGPT_TRANSCRIPTIONS_URL = "https://chatgpt.com/backend-api/transcribe";
 const MAX_AUDIO_BYTES = 10 * 1024 * 1024;
 const MAX_DURATION_MS = 60_000;
@@ -13,6 +17,7 @@ function createVoiceHandler({
   fetchImpl = globalThis.fetch,
   FormDataImpl = globalThis.FormData,
   BlobImpl = globalThis.Blob,
+  readLocalAuthToken = readLocalChatGPTAuthTokenFromDisk,
   logPrefix = "[remodex]",
 } = {}) {
   function handleVoiceRequest(rawMessage, sendResponse) {
@@ -36,6 +41,7 @@ function createVoiceHandler({
       fetchImpl,
       FormDataImpl,
       BlobImpl,
+      readLocalAuthToken,
     })
       .then((result) => {
         sendResponse(JSON.stringify({ id, result }));
@@ -67,7 +73,7 @@ function createVoiceHandler({
 // Validates iPhone-owned audio input and proxies it to the official transcription endpoint.
 async function transcribeVoice(
   params,
-  { sendCodexRequest, fetchImpl, FormDataImpl, BlobImpl }
+  { sendCodexRequest, fetchImpl, FormDataImpl, BlobImpl, readLocalAuthToken }
 ) {
   if (typeof sendCodexRequest !== "function") {
     throw voiceError("bridge_not_ready", "Voice transcription is not available right now.");
@@ -99,7 +105,7 @@ async function transcribeVoice(
     throw voiceError("audio_too_large", "Voice messages are limited to 10 MB.");
   }
 
-  const authContext = await loadAuthContext(sendCodexRequest);
+  const authContext = await loadAuthContext(sendCodexRequest, { readLocalAuthToken });
   return requestTranscription({
     authContext,
     audioBuffer,
@@ -108,6 +114,7 @@ async function transcribeVoice(
     FormDataImpl,
     BlobImpl,
     sendCodexRequest,
+    readLocalAuthToken,
   });
 }
 
@@ -119,6 +126,7 @@ async function requestTranscription({
   FormDataImpl,
   BlobImpl,
   sendCodexRequest,
+  readLocalAuthToken,
 }) {
   const makeAttempt = async (activeAuthContext) => {
     const formData = new FormDataImpl();
@@ -137,7 +145,10 @@ async function requestTranscription({
 
   let response = await makeAttempt(authContext);
   if (response.status === 401) {
-    const refreshedAuthContext = await loadAuthContext(sendCodexRequest);
+    const refreshedAuthContext = await loadAuthContext(sendCodexRequest, {
+      forceRefresh: true,
+      readLocalAuthToken,
+    });
     response = await makeAttempt(refreshedAuthContext);
   }
 
@@ -170,8 +181,17 @@ async function requestTranscription({
 }
 
 // Reads the current bridge-owned auth state from the local codex app-server and refreshes if needed.
-async function loadAuthContext(sendCodexRequest) {
-  const { authMethod, token, isChatGPT } = await resolveCurrentOrRefreshedAuthStatus(sendCodexRequest);
+async function loadAuthContext(
+  sendCodexRequest,
+  {
+    forceRefresh = false,
+    readLocalAuthToken = readLocalChatGPTAuthTokenFromDisk,
+  } = {}
+) {
+  const { authMethod, token, isChatGPT } = await resolveCurrentOrRefreshedAuthStatus(sendCodexRequest, {
+    forceRefresh,
+    readLocalAuthToken,
+  });
 
   if (!token) {
     throw voiceError("not_authenticated", "Sign in with ChatGPT before using voice transcription.");
@@ -277,8 +297,15 @@ function voiceError(errorCode, userMessage) {
 
 // Returns an ephemeral ChatGPT token so the phone can call the transcription API directly.
 // Uses its own token resolution instead of loadAuthContext so errors are specific and actionable.
-async function resolveVoiceAuth(sendCodexRequest) {
+async function resolveVoiceAuth(
+  sendCodexRequest,
+  params = null,
+  { readLocalAuthToken = readLocalChatGPTAuthTokenFromDisk } = {}
+) {
+  const forceRefresh = Boolean(params?.forceRefresh);
   const { authMethod, token, isChatGPT, requiresOpenaiAuth } = await resolveCurrentOrRefreshedAuthStatus(sendCodexRequest, {
+    forceRefresh,
+    readLocalAuthToken,
     rpcErrorCode: "auth_unavailable",
     rpcErrorMessage: "Could not read ChatGPT session from the Mac runtime. Is the bridge running?",
   });
@@ -301,25 +328,82 @@ async function resolveVoiceAuth(sendCodexRequest) {
 async function resolveCurrentOrRefreshedAuthStatus(
   sendCodexRequest,
   {
+    forceRefresh = false,
+    readLocalAuthToken = readLocalChatGPTAuthTokenFromDisk,
     rpcErrorCode = "not_authenticated",
     rpcErrorMessage = "Sign in with ChatGPT before using voice transcription.",
   } = {}
 ) {
-  const currentStatus = await readAuthStatus(sendCodexRequest, {
-    refreshToken: false,
-    rpcErrorCode,
-    rpcErrorMessage,
-  });
+  if (forceRefresh) {
+    const refreshedStatus = await readAuthStatus(sendCodexRequest, {
+      refreshToken: true,
+      rpcErrorCode,
+      rpcErrorMessage,
+    });
+    return withLocalAuthFallback(refreshedStatus, readLocalAuthToken);
+  }
+
+  const currentStatus = await withLocalAuthFallback(
+    await readAuthStatus(sendCodexRequest, {
+      refreshToken: false,
+      rpcErrorCode,
+      rpcErrorMessage,
+    }),
+    readLocalAuthToken
+  );
 
   if (currentStatus.token) {
     return currentStatus;
   }
 
-  return readAuthStatus(sendCodexRequest, {
+  const refreshedStatus = await readAuthStatus(sendCodexRequest, {
     refreshToken: true,
     rpcErrorCode,
     rpcErrorMessage,
   });
+
+  return withLocalAuthFallback(refreshedStatus, readLocalAuthToken);
+}
+
+async function withLocalAuthFallback(status, readLocalAuthToken) {
+  if (status?.token || typeof readLocalAuthToken !== "function") {
+    return status;
+  }
+
+  const localAuthStatus = await readLocalAuthToken().catch(() => null);
+  if (!localAuthStatus?.token || !localAuthStatus?.isChatGPT) {
+    return status;
+  }
+
+  return {
+    authMethod: localAuthStatus.authMethod || status.authMethod || "chatgpt",
+    token: localAuthStatus.token,
+    isChatGPT: true,
+    requiresOpenaiAuth: localAuthStatus.requiresOpenaiAuth ?? status.requiresOpenaiAuth,
+  };
+}
+
+async function readLocalChatGPTAuthTokenFromDisk({
+  readFileImpl = fs.readFile,
+  codexHome = process.env.CODEX_HOME || path.join(os.homedir(), ".codex"),
+} = {}) {
+  const authFile = path.join(codexHome, "auth.json");
+  const contents = await readFileImpl(authFile, "utf8");
+  const auth = JSON.parse(contents);
+  const authMethod = readString(auth?.auth_mode);
+  const tokenContainer = auth?.tokens && typeof auth.tokens === "object" ? auth.tokens : auth;
+  const token = readString(tokenContainer?.access_token);
+  const isChatGPT = token != null
+    && authMethod !== "apikey"
+    && authMethod !== "api_key"
+    && authMethod !== "apiKey";
+
+  return {
+    authMethod: authMethod || (isChatGPT ? "chatgpt" : null),
+    token,
+    isChatGPT,
+    requiresOpenaiAuth: isChatGPT,
+  };
 }
 
 async function readAuthStatus(
@@ -348,5 +432,6 @@ async function readAuthStatus(
 
 module.exports = {
   createVoiceHandler,
+  readLocalChatGPTAuthTokenFromDisk,
   resolveVoiceAuth,
 };