ocremote 1.3.3 → 2.0.0

package/README.md

@@ -1,6 +1,6 @@
 # oc-remote
 
-> **Plataformas.** El companion es Node puro (>= 20) y funciona en macOS, Linux y
+> **Plataformas.** El companion requiere Node >= 22.13 y soporta macOS, Linux y
 > Windows: `npx ocremote --pair` en cualquiera de los tres. Solo en macOS:
 > `--daemon` (LaunchAgent) y mDNS (`--no-mdns` lo desactiva; en otros sistemas ni
 > se intenta). En Linux, para tenerlo siempre activo usa una unidad de usuario de
@@ -8,7 +8,30 @@
 > de tareas al iniciar sesión. Los túneles (`--tunnel cloudflare`) descargan
 > `cloudflared` para la plataforma correcta. Windows está corregido en código
 > (rutas, `.exe`, `;` en PATH, cloudflared .exe) pero no verificado en una máquina
-> Windows real. companion
+> Windows real.
+
+## Primer arranque (2.0.0, preparado para publicar)
+
+```bash
+npm install -g opencode-ai
+opencode auth login
+npx ocremote --pair
+```
+
+`--pair` selecciona el relay alojado por defecto y no necesita VPN ni descubrimiento
+de red local. El proxy queda en loopback. El QR sólo se muestra cuando la invitación
+está registrada: abre la app, escanéalo y conserva la terminal abierta mientras la
+usas. Caduca en 15 minutos y es de un solo uso. Para mostrar otro QR de una instancia
+en marcha: `npx ocremote pair`. En macOS, `npx ocremote --daemon` instala el servicio.
+
+La nueva app comprueba la firma del ordenador contra la clave fijada por el QR. Es
+necesario actualizar app, companion y relay juntos y volver a emparejar las entradas
+antiguas que no tengan esa clave. La versión publicada no cambia hasta publicar el
+paquete; este repositorio prepara 2.0.0.
+
+Las secciones de proxy/túneles de abajo describen también el modo directo opcional.
+Con `--relay` o `--pair`, el valor predeterminado de `--host` es `127.0.0.1`, el túnel
+queda desactivado y Bonjour no se anuncia salvo petición explícita.
 
 Proceso Node sin dependencias externas (solo APIs nativas de Node 22+) que
 convierte un Mac en un host de **opencode** accesible desde la app iOS
@@ -34,7 +57,7 @@ push opcionales.
 
 ## Requisitos
 
-- macOS con Node 22 o superior (`node --version`).
+- Node 22.13 o superior (`node --version`).
 - El binario `opencode` (por defecto `~/.opencode/bin/opencode`).
 - Opcional: `tailscale` (acceso remoto), `ntfy` (push, no requiere instalar
   nada en el Mac), `dns-sd` (viene con macOS).

package/install.sh

@@ -175,6 +175,7 @@ ln -sfn "$ENTRY" "$BIN_DIR/oc-remote"
   echo '  <array>'
   echo "    <string>$(xml_escape "$NODE_BIN")</string>"
   echo "    <string>$(xml_escape "$BIN_DIR/oc-remote")</string>"
+  echo '    <string>--no-print-qr</string>'
   echo '    <string>--dir</string>'
   echo "    <string>$(xml_escape "$PROJECT_DIR")</string>"
   echo '    <string>--port</string>'

package/lib/crypto.mjs

@@ -102,6 +102,7 @@ export function openWire(key, expectedDir, payload, minCounter = -1n) {
   if (dir !== expectedDir) throw new Error('bad direction')
   let counter = 0n
   for (const byte of payload.subarray(1, 12)) counter = (counter << 8n) | BigInt(byte)
+  if (counter > BigInt(Number.MAX_SAFE_INTEGER)) throw new Error('counter out of range')
   if (counter <= minCounter) throw new Error('replayed counter')
   const plaintext = open(key, dir, counter, payload.subarray(12))
   return { counter: Number(counter), plaintext }

package/lib/identity.mjs

@@ -31,8 +31,13 @@ export class Identity {
         privateKey: privateKeyFromSeed(unb64(parsed.privateKey)),
         createdAt: parsed.createdAt,
       }
+      const publicRaw = exportRawPublic(crypto.createPublicKey(this.identity.privateKey))
+      if (this.identity.id !== deviceIDFromPublic(publicRaw) || !publicRaw.equals(this.identity.publicRaw)) {
+        throw new Error('Identity keys do not match')
+      }
       return this
-    } catch {
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw new Error(`Cannot read identity: ${error.message}`)
       this.identity = null
       return null
     }
@@ -100,6 +105,7 @@ export class Identity {
   }
 
   pairFile(pairID) {
+    if (typeof pairID !== 'string' || !/^[A-Za-z0-9_-]{1,80}$/.test(pairID)) throw new Error('Invalid pair ID')
     return path.join(this.pairsDir, `${pairID}.json`)
   }
 

package/lib/relay.mjs

@@ -33,7 +33,7 @@ export class RelayClient {
     this.identity = identity
     this.adapter = adapter
     this.logger = logger
-    this.invites = invites
+    this.invites = invites ?? new Map()
     this.onEvent = onEvent || (() => {})
     this.ws = null
     this.sessions = new Map()
@@ -42,6 +42,7 @@ export class RelayClient {
     this.lastMessageAt = 0
     this.pingTimer = null
     this.reconnectTimer = null
+    this.ready = false
   }
 
   log(message) {
@@ -91,7 +92,7 @@ export class RelayClient {
   async registerPair(pair) {
     const ts = Math.floor(Date.now() / 1000)
     const deviceID = this.identity.deviceID()
-    const message = `ocremote-pair-v1|${deviceID}|${pair.pairID}|${pair.clientID}|${ts}`
+    const message = `ocremote-pair-v2|${deviceID}|${pair.pairID}|${pair.clientID}|${pair.clientPK}|${pair.name || ''}|${ts}`
     await this.api('/v1/pairs', {
       body: {
         deviceID,
@@ -133,23 +134,31 @@ export class RelayClient {
   }
 
   async createInvite() {
+    await this.waitReady()
+    const now = Date.now()
     const invite = {
       pairID: `p_${randomBytes(6).toString('hex')}`,
       secret: randomBytes(32),
-      createdAt: Date.now(),
-      expiresAt: Date.now() + 5 * 60_000,
+      createdAt: now,
+      expiresAt: now + 15 * 60_000,
     }
+    await this.registerInvite(invite)
+    if (!this.ready) throw new Error('Relay disconnected. Try pairing again once connected.')
     this.invites.set(invite.pairID, invite)
-    if (this.ws && this.ws.readyState === 1) {
-      try {
-        await this.registerInvite(invite)
-      } catch (err) {
-        this.log(`could not register invite with the relay: ${err.message}`)
-      }
+    for (const [id, previous] of [...this.invites]) {
+      if (previous.expiresAt <= now) this.invites.delete(id)
     }
     return invite
   }
 
+  async waitReady(timeout = 15_000) {
+    const deadline = Date.now() + timeout
+    while (!this.ready && !this.stopped && Date.now() < deadline) {
+      await new Promise(resolve => setTimeout(resolve, 50))
+    }
+    if (!this.ready) throw new Error('Relay is unavailable. Check your internet connection and try again.')
+  }
+
   pruneInvites() {
     const now = Date.now()
     for (const [id, invite] of this.invites) {
@@ -178,6 +187,7 @@ export class RelayClient {
 
   stop() {
     this.stopped = true
+    this.ready = false
     clearTimeout(this.reconnectTimer)
     clearInterval(this.pingTimer)
     for (const session of this.sessions.values()) session.close('relay_stopped')
@@ -206,6 +216,7 @@ export class RelayClient {
       const challenge = await this.api('/v1/challenge', {
         body: { deviceID: this.identity.deviceID() },
       })
+      if (this.stopped) return
       const role = 'companion'
       const message = `ocremote-ws-v1|${role}|${this.identity.deviceID()}||${challenge.challenge}`
       const url = `${this.relayUrl}/v1/ws?role=${role}&device=${this.identity.deviceID()}`
@@ -235,11 +246,13 @@ export class RelayClient {
         }, PING_INTERVAL)
       })
       ws.addEventListener('message', (event) => {
+        if (this.ws !== ws || this.stopped) return
         this.lastMessageAt = Date.now()
         this.handleMessage(event.data)
       })
       ws.addEventListener('close', () => {
         if (this.ws !== ws) return
+        this.ready = false
         clearInterval(this.pingTimer)
         for (const session of this.sessions.values()) session.close('relay_disconnected')
         this.sessions.clear()
@@ -293,6 +306,7 @@ export class RelayClient {
       return
     }
     if (msg.t === 'session_open') {
+      this.sessions.get(msg.session)?.close('replaced')
       const session = new RelaySession({
         id: msg.session,
         clientID: msg.clientID,
@@ -317,6 +331,7 @@ export class RelayClient {
     }
     if (msg.t === 'pong') return
     if (msg.t === 'hello') {
+      this.ready = true
       this.log(`relay hello: ${JSON.stringify(msg.device || {})}`)
       return
     }
@@ -353,6 +368,9 @@ export class RelaySession {
     if (this.closed) return
     this.closed = true
     this.adapter?.cancelAll(this)
+    if (!['relay_stopped', 'relay_disconnected', 'client_disconnected', 'replaced'].includes(reason)) {
+      this.relay.send(control({ t: 'session_close', session: this.id }))
+    }
     this.log(`session ${this.id} closed (${reason})`)
   }
 
@@ -369,44 +387,55 @@ export class RelaySession {
   }
 
   handleOpen(payload) {
+    if (this.closed || this.mode !== 'awaiting') return
     let msg = null
     try {
       msg = JSON.parse(payload.toString('utf8'))
     } catch {
       return
     }
-    if (msg.t !== 'hs1' || msg.v !== PROTOCOL_VERSION) return
+    if (!msg || msg.t !== 'hs1' || msg.v !== PROTOCOL_VERSION) return
     this.clientNonce = unb64(msg.nonce)
     if (this.clientNonce.length !== 32) {
       this.close('bad_nonce')
       return
     }
+    const clientPK = unb64(msg.clientPK)
+    const proof = `ocremote-client-v1|${this.identity.deviceID()}|${msg.pair}|${msg.clientPK}|${msg.nonce}`
+    if (clientPK.length !== 32 || !verify(clientPK, unb64(msg.sig), proof)) {
+      this.close('client_signature_invalid')
+      return
+    }
+    this.handshakeClientPK = msg.clientPK
     this.serverNonce = randomBytes(32)
     this.sendCounter = 0
     this.recvCounter = -1
     this.failures = 0
-    this.sendOpen({ t: 'hs2', v: PROTOCOL_VERSION, nonce: b64(this.serverNonce) })
 
     const pair = this.identity.pair(msg.pair)
     if (pair) {
+      if (pair.clientPK !== msg.clientPK || pair.pairKey.length !== 32) {
+        this.close('client_key_mismatch')
+        return
+      }
       this.mode = 'paired'
       this.pairID = pair.pairID
       this.clientID = pair.clientID
       this.key = sessionKey(pair.pairKey, this.clientNonce, this.serverNonce, pair.pairID)
       this.log(`session ${this.id} handshake ok (paired ${pair.clientID})`)
-      return
-    }
-
-    const invite = this.relay.invites.get(msg.pair)
-    if (!invite || Date.now() > invite.expiresAt) {
-      this.log(`session ${this.id} rejected: unknown or expired invite`)
-      this.close('invite_invalid')
-      return
+    } else {
+      const invite = this.relay.invites.get(msg.pair)
+      if (!invite || invite.claimed || Date.now() >= invite.expiresAt) {
+        this.close('invite_invalid')
+        return
+      }
+      this.mode = 'pairing'
+      this.pairID = invite.pairID
+      this.key = inviteSessionKey(invite.secret, this.clientNonce, this.serverNonce)
     }
-    this.mode = 'pairing'
-    this.pairID = invite.pairID
-    this.key = inviteSessionKey(invite.secret, this.clientNonce, this.serverNonce)
-    this.log(`session ${this.id} handshake ok (pairing invite ${invite.pairID})`)
+    const nonce = b64(this.serverNonce)
+    const transcript = `ocremote-channel-v1|${this.identity.deviceID()}|${this.pairID}|${msg.clientPK}|${msg.nonce}|${nonce}`
+    this.sendOpen({ t: 'hs2', v: PROTOCOL_VERSION, nonce, sig: b64(this.identity.sign(transcript)) })
   }
 
   handleSealed(payload) {
@@ -432,10 +461,12 @@ export class RelaySession {
   }
 
   handleMessage(msg) {
+    if (!msg || typeof msg !== 'object') return
     if (msg.t === 'pair' && this.mode === 'pairing') {
       this.completePairing(msg)
       return
     }
+    if (this.mode !== 'paired') return
     if (msg.t === 'ping') {
       this.sendSealed({ t: 'pong' })
       return
@@ -451,23 +482,19 @@ export class RelaySession {
 
   async completePairing(msg) {
     const invite = this.relay.invites.get(this.pairID)
-    if (!invite) {
+    if (!invite || invite.claimed || Date.now() >= invite.expiresAt) {
       this.close('invite_missing')
       return
     }
-    if (typeof msg.clientID !== 'string' || typeof msg.clientPK !== 'string') {
+    if (typeof msg.clientID !== 'string' || !/^[A-Za-z0-9_-]{1,80}$/.test(msg.clientID) ||
+        msg.clientPK !== this.handshakeClientPK || (msg.name !== undefined && (typeof msg.name !== 'string' || Buffer.byteLength(msg.name) > 64))) {
       this.close('bad_pair_request')
       return
     }
     const pairKey = pairKeyFromInvite(invite.secret, this.clientNonce, this.serverNonce)
+    invite.claimed = true
+    this.mode = 'registering'
     this.relay.invites.delete(this.pairID)
-    this.identity.savePairWithKey({
-      pairID: this.pairID,
-      clientID: msg.clientID,
-      clientPK: msg.clientPK,
-      name: msg.name,
-      pairKey,
-    })
     try {
       await this.relay.registerPair({
         pairID: this.pairID,
@@ -475,8 +502,14 @@ export class RelaySession {
         clientPK: msg.clientPK,
         name: msg.name,
       })
+      this.identity.savePairWithKey({
+        pairID: this.pairID, clientID: msg.clientID, clientPK: msg.clientPK, name: msg.name, pairKey,
+      })
     } catch (err) {
       this.log(`pair registration failed: ${err.message}`)
+      this.sendSealed({ t: 'pair_error', message: 'Pairing could not be saved. Show a new QR and try again.' })
+      this.close('pair_registration_failed')
+      return
     }
     this.mode = 'paired'
     this.clientID = msg.clientID

package/lib/rpc.mjs

@@ -2,6 +2,7 @@ import { b64 } from './crypto.mjs'
 
 const MAX_CONCURRENT = 8
 const MAX_UPLOAD = 24 << 20
+const MAX_RESPONSE = 700 * 1024
 
 export class RpcAdapter {
   constructor({ baseUrl, authHeader, logger }) {
@@ -9,6 +10,7 @@ export class RpcAdapter {
     this.authHeader = authHeader
     this.logger = logger
     this.active = new Map()
+    this.inFlight = 0
   }
 
   log(message) {
@@ -16,12 +18,12 @@ export class RpcAdapter {
   }
 
   sessionMap(session) {
-    if (!this.active.has(session.id)) this.active.set(session.id, new Map())
-    return this.active.get(session.id)
+    if (!this.active.has(session)) this.active.set(session, new Map())
+    return this.active.get(session)
   }
 
   cancel(session, id) {
-    const entry = this.sessionMap(session).get(id)
+    const entry = this.active.get(session)?.get(id)
     if (entry) {
       entry.controller.abort()
       this.log(`rpc ${id} cancelled`)
@@ -33,7 +35,7 @@ export class RpcAdapter {
   // server applied it. Better to let it finish on the computer and let the
   // client reconcile by inspecting state after reconnecting.
   cancelAll(session) {
-    const map = this.active.get(session.id)
+    const map = this.active.get(session)
     if (!map) return
     for (const entry of map.values()) {
       if (entry.mutating) continue
@@ -41,14 +43,14 @@ export class RpcAdapter {
         entry.controller.abort()
       } catch {}
     }
-    this.active.delete(session.id)
+    this.active.delete(session)
   }
 
   async handle(session, msg) {
     const id = msg.id
-    if (typeof id !== 'number' || typeof msg.path !== 'string') return
+    if (!Number.isSafeInteger(id) || typeof msg.path !== 'string' || session.closed) return
     const map = this.sessionMap(session)
-    if (map.size >= MAX_CONCURRENT) {
+    if (map.size >= MAX_CONCURRENT || this.inFlight >= 40 || map.has(id)) {
       session.sendSealed({ t: 'res', id, error: 'too_many_requests' })
       return
     }
@@ -58,10 +60,16 @@ export class RpcAdapter {
     }
 
     const controller = new AbortController()
-    const method = (msg.method || 'GET').toUpperCase()
+    const method = typeof msg.method === 'string' ? msg.method.toUpperCase() : 'GET'
+    if (!['GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'].includes(method)) {
+      session.sendSealed({ t: 'res', id, error: 'bad_method' })
+      return
+    }
     const mutating = method === 'POST' || method === 'PUT' || method === 'PATCH' || method === 'DELETE'
     map.set(id, { controller, mutating })
     const stream = msg.stream === true
+    this.inFlight++
+    const timer = stream ? null : setTimeout(() => controller.abort(), mutating ? 900_000 : 120_000)
     let opened = false
     try {
       const url = new URL(`${this.baseUrl}${msg.path}`)
@@ -72,7 +80,7 @@ export class RpcAdapter {
         }
       }
       const headers = { authorization: this.authHeader }
-      const init = { method, headers, signal: controller.signal }
+      const init = { method, headers, signal: controller.signal, redirect: 'error' }
       if (msg.body) {
         const body = Buffer.from(String(msg.body), 'base64')
         if (body.length > MAX_UPLOAD) {
@@ -85,7 +93,18 @@ export class RpcAdapter {
 
       const res = await fetch(url, init)
       if (!stream) {
-        const buffer = Buffer.from(await res.arrayBuffer())
+        const chunks = []
+        let size = 0
+        if (res.body) for await (const chunk of res.body) {
+          size += chunk.length
+          if (size > MAX_RESPONSE) {
+            controller.abort()
+            session.sendSealed({ t: 'res', id, error: 'Response exceeds the relay limit. Narrow the request and try again.' })
+            return
+          }
+          chunks.push(Buffer.from(chunk))
+        }
+        const buffer = Buffer.concat(chunks)
         session.sendSealed({
           t: 'res',
           id,
@@ -104,7 +123,9 @@ export class RpcAdapter {
       }
       for await (const chunk of res.body) {
         if (controller.signal.aborted) break
-        session.sendSealed({ t: 'chunk', id, data: b64(chunk) })
+        for (let offset = 0; offset < chunk.length; offset += 64 * 1024) {
+          session.sendSealed({ t: 'chunk', id, data: b64(chunk.subarray(offset, offset + 64 * 1024)) })
+        }
       }
       session.sendSealed({ t: 'end', id })
     } catch (err) {
@@ -115,7 +136,10 @@ export class RpcAdapter {
         session.sendSealed(opened ? { t: 'end', id, error: 'stream_failed' } : { t: 'res', id, error: 'opencode_unreachable' })
       }
     } finally {
+      clearTimeout(timer)
+      this.inFlight--
       map.delete(id)
+      if (map.size === 0 && this.active.get(session) === map) this.active.delete(session)
     }
   }
 }

package/oc-remote.mjs

@@ -17,7 +17,7 @@ import { b64 } from './lib/crypto.mjs'
 
 const require = createRequire(import.meta.url)
 const NAME = 'oc-remote'
-const VERSION = '1.3.3'
+const VERSION = '2.0.0'
 const LAUNCH_LABEL = 'com.raul.ocremote'
 const LOG_PATH =
   process.platform === 'darwin'
@@ -42,9 +42,9 @@ function augmentPath() {
     path.join(os.homedir(), '.local', 'bin'),
     path.join(os.homedir(), '.opencode', 'bin'),
   ]
-  const current = (process.env.PATH || '').split(':').filter(Boolean)
+  const current = (process.env.PATH || '').split(path.delimiter).filter(Boolean)
   const missing = extras.filter((dir) => dir && !current.includes(dir) && fs.existsSync(dir))
-  if (missing.length) process.env.PATH = [...current, ...missing].join(':')
+  if (missing.length) process.env.PATH = [...current, ...missing].join(path.delimiter)
 }
 augmentPath()
 
@@ -52,7 +52,7 @@ const HELP = `oc-remote v${VERSION} - remote companion for opencode
 
 Usage:
   oc-remote [options]              Start the companion (and the daemon entry point)
-  npx ocremote --pair              First run: check opencode, show the pairing QR
+  npx ocremote [--pair]            Start and show the pairing QR (Node 22.13+)
   npx ocremote --daemon            Install as a background service (LaunchAgent)
   oc-remote doctor                 Diagnose every link in the connection chain
   oc-remote status                 Show config, daemon state and live endpoint
@@ -69,7 +69,7 @@ Options:
   --port <n>                Companion HTTP/SSE proxy port (default: 4190)
   --opencode-port <n>       Loopback port for the internal opencode serve (default: 4191)
   --utility-port <n>        Loopback-only port for pairing/utility pages (default: port+1)
-  --relay <url>             Relay v2 URL (wss://relay.example) for anywhere access
+  --relay <url>             Custom relay URL; --pair uses the hosted relay by default
   --device-name <name>      Name shown on the phone (default: hostname)
   --tunnel <mode>           Remote access: auto | funnel | cloudflare | tailscale | none
                             auto       reuse an active funnel, else cloudflared, else Tailscale, else LAN
@@ -940,6 +940,14 @@ function handleRequest(req, res) {
 }
 
 function handleUtilityRequest(req, res) {
+  const localHost = `127.0.0.1:${opts.utilityPort}`
+  const allowedHosts = new Set([localHost, `localhost:${opts.utilityPort}`])
+  if (!allowedHosts.has(req.headers.host) ||
+      (req.headers.origin && req.headers.origin !== `http://${req.headers.host}`) ||
+      req.headers['sec-fetch-site'] === 'cross-site') {
+    sendJson(req, res, 403, { error: 'local_origin_required' })
+    return
+  }
   let url
   try {
     url = new URL(req.url, 'http://127.0.0.1')
@@ -1002,6 +1010,7 @@ async function createUtilityServer() {
       })
     })
     if (!ok) continue
+    saveConfig({ ...loadConfig(), utilityPort: opts.utilityPort })
     info(`pairing page (loopback only): http://${LOOPBACK}:${opts.utilityPort}/_ocremote/pair`)
     return srv
   }
@@ -1555,6 +1564,10 @@ function noteWatchdogFailure() {
 }
 
 function printPairing(options = {}) {
+  if (opts.relay) {
+    info('remote access: encrypted relay; no VPN or local-network discovery needed')
+    return
+  }
   for (const entry of allUrls) info(`url: ${entry.url}  [${entry.label}]`)
   info(`pairing token: ${remoteToken}`)
   const publicEntry = allUrls.find((entry) => entry.label === 'public' || entry.label === 'tunnel')
@@ -1568,10 +1581,6 @@ function printPairing(options = {}) {
   } else {
     info('remote access: LAN only - run `oc-remote --tunnel funnel` (stable URL) or --tunnel cloudflare')
   }
-  if (opts.relay) {
-    info('pairing: relay mode, the invite QR below is the one to scan')
-    return
-  }
   info(`pairing deep link: ${pairLink()}`)
   if (options.qr === false || !opts.printQr) return
   if (!qrcode) {
@@ -1620,23 +1629,31 @@ async function startRelay() {
     await relayClient.registerDevice(VERSION)
     info(`relay: registered device ${identity.deviceID()} (${identity.name()})`)
   } catch (err) {
-    error(`relay registration failed: ${err.message}`)
+    throw new Error(`Could not register with the relay: ${err.message}. Check your connection and run npx ocremote --pair again.`)
   }
   relayClient.start()
+  info('connecting to the relay…')
+  await relayClient.waitReady()
+  if (!opts.printQr) {
+    info('Ready. To pair your iPhone, run: npx ocremote pair')
+    return
+  }
   const payload = await createInvitePayload()
   info(`relay: ${opts.relay}`)
-  info(`pairing v2 link: ${payload.url}`)
+  process.stdout.write(`${payload.url}\n`)
   if (payload.expiresAt) {
     info(`invite expires at ${new Date(payload.expiresAt).toLocaleTimeString()} (15 minutes, single use)`)
   }
   printInviteQr(payload.url)
+  info('Open the iPhone app → Connect your computer → Scan QR. Keep this terminal open while using the app.')
   if (opts.pair) {
     clearInterval(inviteRefreshTimer)
     inviteRefreshTimer = setInterval(async () => {
       if (shuttingDown) return
       try {
         const fresh = await createInvitePayload()
-        info(`invite refreshed (previous one expired or about to): ${fresh.url}`)
+        info('New pairing QR ready. The previous QR stays valid until its expiry time.')
+        process.stdout.write(`${fresh.url}\n`)
         printInviteQr(fresh.url)
       } catch (err) {
         warn(`could not refresh the invite: ${err.message}`)
@@ -1973,15 +1990,11 @@ async function runSubcommand(name, argv) {
   }
 
   if (name === 'pair') {
-    const mainPort = Number(cfg.port ?? 4190)
-    const candidates = []
-    if (flags['utility-port'] !== undefined) candidates.push(Number(flags['utility-port']))
-    if (cfg.utilityPort) candidates.push(Number(cfg.utilityPort))
-    for (let offset = 1; offset <= 4; offset++) candidates.push(mainPort + offset)
-    const ports = [...new Set(candidates)].filter((port) => port > 0 && port <= 65535)
+    const utilityPort = Number(flags['utility-port'] ?? cfg.utilityPort)
+    const ports = Number.isInteger(utilityPort) && utilityPort > 0 && utilityPort <= 65535 ? [utilityPort] : []
     let payload = null
     for (const port of ports) {
-      const res = await postLocal(port, '/_ocremote/invite')
+      const res = await postLocal(port, '/_ocremote/invite', 25_000)
       if (!res || res.status !== 200) continue
       try {
         payload = JSON.parse(res.text)
@@ -1990,7 +2003,7 @@ async function runSubcommand(name, argv) {
     }
     if (!payload) {
       error('could not get an invite from the running companion')
-      out('hint: start it with `oc-remote --dir <project> --relay <wss://...>` or `bash companion/install.sh ...`')
+      out('Start it with: npx ocremote --pair')
       return 1
     }
     out(payload.url)
@@ -2223,6 +2236,8 @@ async function runSubcommand(name, argv) {
 }
 
 async function main() {
+  const [major, minor] = process.versions.node.split('.').map(Number)
+  if (major < 22 || (major === 22 && minor < 13)) abort('Node 22.13 or newer is required. Update Node, then run npx ocremote --pair again.')
   const argv = process.argv.slice(2)
   if (argv[0] && SUBCOMMANDS.has(argv[0])) {
     const code = await runSubcommand(argv[0], argv.slice(1))
@@ -2231,6 +2246,7 @@ async function main() {
   const parsed = parseArgs(argv)
   if (parsed.error) abort(parsed.error)
   const flags = parsed.flags
+  if (argv.length === 0) flags.pair = true
   if (flags.help) {
     process.stdout.write(HELP)
     return 0
@@ -2245,7 +2261,11 @@ async function main() {
   opts.publicUrl = flags['public-url'] !== undefined ? flags['public-url'] : (cfg.publicUrl ?? null)
   opts.tunnel = flags.tunnel !== undefined ? String(flags.tunnel) : (cfg.tunnel ?? 'auto')
   opts.ntfy = flags.ntfy !== undefined ? flags.ntfy : (cfg.ntfy ?? null)
-  opts.relay = flags.relay !== undefined ? String(flags.relay) : (cfg.relay ?? null)
+  opts.pair = Boolean(flags.pair)
+  opts.relay = flags.relay !== undefined ? String(flags.relay) :
+    (cfg.relay ?? ((flags.pair || flags.daemon) && flags.tunnel === undefined ? 'wss://relay-production-9c9b.up.railway.app' : null))
+  if (opts.relay && flags.tunnel === undefined) opts.tunnel = 'none'
+  if (opts.relay && flags.host === undefined) opts.host = LOOPBACK
   opts.deviceName = flags['device-name'] !== undefined ? String(flags['device-name']) : (cfg.deviceName ?? null)
   opts.utilityPort =
     flags['utility-port'] !== undefined
@@ -2253,6 +2273,7 @@ async function main() {
       : Number(cfg.utilityPort ?? 0) || null
   opts.noAuth = Boolean(flags['no-auth'])
   opts.mdns = flags.mdns === true || (!flags['no-mdns'] && process.platform === 'darwin')
+  if (opts.relay && flags.mdns !== true) opts.mdns = false
   opts.mdnsExplicit = flags.mdns === true
   opts.printQr = flags['print-qr'] !== false
 
@@ -2268,7 +2289,15 @@ async function main() {
     abort(`invalid --utility-port: ${flags['utility-port'] ?? cfg.utilityPort}`)
   if (opts.utilityPort !== null && (opts.utilityPort === opts.port || opts.utilityPort === opts.opencodePort))
     abort('--utility-port must differ from --port and --opencode-port')
-  if (opts.relay && !/^wss?:\/\//i.test(opts.relay)) abort(`invalid --relay: ${opts.relay} (expected wss://...)`)
+  if (opts.relay) {
+    let relayURL
+    try { relayURL = new URL(opts.relay) } catch { abort('Invalid --relay URL. Use wss://hostname.') }
+    const local = ['127.0.0.1', 'localhost', '[::1]'].includes(relayURL.hostname)
+    if (!(relayURL.protocol === 'wss:' || (relayURL.protocol === 'ws:' && local)) || relayURL.username || relayURL.password || relayURL.search || relayURL.hash || !['', '/'].includes(relayURL.pathname)) {
+      abort('Invalid --relay URL. Use wss://hostname (ws:// is allowed only for localhost).')
+    }
+    opts.relay = relayURL.origin
+  }
 
   const dir = path.resolve(flags.dir !== undefined ? flags.dir : process.cwd())
   let stat
@@ -2300,12 +2329,24 @@ async function main() {
     return await new Promise((resolve) => child.on('exit', (code) => resolve(code ?? 0)))
   }
 
+  if (flags.pair && cfg.token && !flags['new-token'] && flags.token === undefined && opts.port === Number(cfg.port)) {
+    const running = await probeLocal('/_ocremote/status', { authorization: `Bearer ${cfg.token}` })
+    if (running.ok) {
+      let status
+      try { status = JSON.parse(running.text) } catch {}
+      if (status?.name === NAME && status.relay === opts.relay && Number.isInteger(status.utilityPort)) {
+        info('Your companion is already running. Preparing a fresh pairing QR…')
+        return runSubcommand('pair', ['--utility-port', String(status.utilityPort)])
+      }
+    }
+  }
+
   opts.opencodeBin = locateBin(resolveOpencodeBin(flags.opencode))
   if (!opts.opencodeBin) {
     if (flags.pair) {
       const say = (line) => process.stdout.write(`${line}\n`)
       error('opencode is not installed on this computer.')
-      say('  1. Install it:  curl -fsSL https://opencode.ai/install | bash')
+      say('  1. Install it:  npm install -g opencode-ai')
       say('  2. Sign in:      opencode auth login')
       say('  3. Run again:    npx ocremote --pair')
       return 1
@@ -2345,6 +2386,12 @@ async function main() {
   }
   remoteToken = token
 
+  if (!(await portFree(opts.port)) || !(await portFree(opts.opencodePort))) {
+    error('A companion or another service is already running on these ports.')
+    info('To show its QR: npx ocremote pair. For another instance, choose --port and --opencode-port.')
+    return 1
+  }
+
   const nextConfig = {
     version: 1,
     token,
@@ -2440,6 +2487,8 @@ main()
     if (code !== 0) process.exit(code)
   })
   .catch((err) => {
-    error(`fatal: ${err.stack || err.message}`)
+    error(err.message)
+    relayClient?.stop()
+    if (child && child.exitCode === null) child.kill('SIGTERM')
     process.exit(1)
   })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ocremote",
-  "version": "1.3.3",
+  "version": "2.0.0",
   "description": "Control opencode on your computer from the OpenCode Remote iOS app: supervisor, pairing QR, relay and tunnel transports",
   "type": "module",
   "bin": {
@@ -13,7 +13,7 @@
     "install.sh"
   ],
   "engines": {
-    "node": ">=20"
+    "node": ">=22.13.0"
   },
   "keywords": [
     "opencode",
@@ -25,6 +25,6 @@
   ],
   "license": "MIT",
   "scripts": {
-    "test": "node --test test/proxy.test.mjs"
+    "test": "node --test test/*.test.mjs"
   }
 }