ocremote 1.3.0

package/oc-remote.mjs

@@ -0,0 +1,2390 @@
+#!/usr/bin/env node
+import http from 'node:http'
+import https from 'node:https'
+import net from 'node:net'
+import os from 'node:os'
+import fs from 'node:fs'
+import path from 'node:path'
+import zlib from 'node:zlib'
+import crypto from 'node:crypto'
+import { spawn, execFile } from 'node:child_process'
+import { createRequire } from 'node:module'
+import { fileURLToPath } from 'node:url'
+import { Identity } from './lib/identity.mjs'
+import { RelayClient } from './lib/relay.mjs'
+import { RpcAdapter } from './lib/rpc.mjs'
+import { b64 } from './lib/crypto.mjs'
+
+const require = createRequire(import.meta.url)
+const NAME = 'oc-remote'
+const VERSION = '1.3.0'
+const LAUNCH_LABEL = 'com.raul.ocremote'
+const LOG_PATH = path.join(os.homedir(), 'Library', 'Logs', 'oc-remote.log')
+const STARTED_AT = Date.now()
+const HERE = path.dirname(fileURLToPath(import.meta.url))
+const LOOPBACK = '127.0.0.1'
+
+let qrcode = null
+try {
+  qrcode = require(path.join(HERE, 'vendor', 'qrcode.js'))
+} catch {
+  qrcode = null
+}
+
+function augmentPath() {
+  const extras = [
+    '/opt/homebrew/bin',
+    '/usr/local/bin',
+    '/usr/bin',
+    path.join(os.homedir(), '.local', 'bin'),
+    path.join(os.homedir(), '.opencode', 'bin'),
+  ]
+  const current = (process.env.PATH || '').split(':').filter(Boolean)
+  const missing = extras.filter((dir) => dir && !current.includes(dir) && fs.existsSync(dir))
+  if (missing.length) process.env.PATH = [...current, ...missing].join(':')
+}
+augmentPath()
+
+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 --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
+  oc-remote restart                Restart the installed LaunchAgent
+  oc-remote logs                   Show the daemon log path and last lines
+  oc-remote funnel on|off|status   Enable/disable the stable Tailscale Funnel URL
+  oc-remote pair                   Print a fresh pairing QR for OpenCode Remote v2
+  oc-remote relay-status           Relay identity, connection and paired devices
+  oc-remote unpair <pairID>        Revoke a paired device (relay + local)
+  oc-remote version                Print the version
+
+Options:
+  --dir <path>              Project directory used by opencode (default: cwd)
+  --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
+  --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
+                            funnel     Tailscale Funnel: stable public HTTPS URL (one-time approval)
+                            cloudflare quick tunnel, downloads cloudflared if needed (zero setup)
+                            tailscale  advertise the Tailscale IP (stable, needs Tailscale app)
+                            none       LAN only (default when nothing else is available)
+  --host <ip>               Bind address for the companion (default: 0.0.0.0)
+  --token <str>             Set the pairing token (persisted in config.json)
+  --new-token               Rotate the pairing token (only way to rotate)
+  --ntfy <topic|url>        Enable ntfy push notifications and endpoint beacons
+  --public-url <url>        Public base URL to advertise (skips --tunnel)
+  --no-auth                 Disable token auth (DANGEROUS, LAN becomes open)
+  --opencode <path>         opencode binary (default: ~/.opencode/bin/opencode)
+  --no-mdns                 Do not publish _ocremote._tcp via Bonjour
+  --print-qr                Print pairing QR at startup (default)
+  --no-print-qr             Do not print the pairing QR
+  --help                    Show this help
+`
+
+const SUBCOMMANDS = new Set(['doctor', 'status', 'restart', 'logs', 'version', 'funnel', 'pair', 'relay-status', 'unpair'])
+
+const VALUE_FLAGS = new Set([
+  'dir',
+  'port',
+  'opencode-port',
+  'utility-port',
+  'host',
+  'token',
+  'ntfy',
+  'public-url',
+  'opencode',
+  'tunnel',
+  'relay',
+  'device-name',
+])
+const BOOL_FLAGS = new Set(['new-token', 'no-auth', 'no-mdns', 'print-qr', 'no-print-qr', 'help', 'pair', 'daemon'])
+const TUNNEL_MODES = new Set(['auto', 'funnel', 'cloudflare', 'tailscale', 'none'])
+const ALLOWED_METHODS = new Set(['GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'])
+
+let shuttingDown = false
+let server = null
+let child = null
+let mdnsChild = null
+let restartTimer = null
+let restartAttempts = 0
+let activeClients = 0
+let allUrls = []
+let primaryUrl = ''
+let remoteToken = ''
+let internalPassword = ''
+let internalAuth = ''
+let tunnelChild = null
+let tunnelTimer = null
+let tunnelUrl = ''
+let tunnelProvider = null
+let tunnelAttempts = 0
+let quickTunnelUrl = ''
+let funnelMonitorTimer = null
+let transportTimer = null
+let cachedTailscaleIp = null
+let endpointTimer = null
+let lastBeaconKey = ''
+let watchdogTimer = null
+let watchdogFailures = 0
+const sockets = new Set()
+
+const AUTH_FAIL_LIMIT = 20
+const AUTH_FAIL_WINDOW = 60_000
+const AUTH_BLOCK_MS = 60_000
+const authFailures = new Map()
+
+function log(level, msg) {
+  process.stderr.write(`[oc-remote] ${new Date().toISOString()} ${level} ${msg}\n`)
+}
+const info = (m) => log('INFO', m)
+const warn = (m) => log('WARN', m)
+const error = (m) => log('ERROR', m)
+
+function randomHex(bytes) {
+  return crypto.randomBytes(bytes).toString('hex')
+}
+
+function safeEqual(a, b) {
+  const ab = Buffer.from(String(a))
+  const bb = Buffer.from(String(b))
+  if (ab.length !== bb.length) {
+    crypto.timingSafeEqual(bb, bb)
+    return false
+  }
+  return crypto.timingSafeEqual(ab, bb)
+}
+
+function authBlocked(ip) {
+  const now = Date.now()
+  const record = authFailures.get(ip)
+  if (!record) return false
+  if (record.blockedUntil && record.blockedUntil > now) return true
+  if (record.blockedUntil) {
+    authFailures.delete(ip)
+    return false
+  }
+  if (now - record.windowStart > AUTH_FAIL_WINDOW) {
+    authFailures.delete(ip)
+    return false
+  }
+  if (record.count >= AUTH_FAIL_LIMIT) {
+    record.blockedUntil = now + AUTH_BLOCK_MS
+    return true
+  }
+  return false
+}
+
+function noteAuthFailure(ip) {
+  const now = Date.now()
+  const record = authFailures.get(ip)
+  if (!record || now - record.windowStart > AUTH_FAIL_WINDOW) {
+    authFailures.set(ip, { count: 1, windowStart: now, blockedUntil: 0 })
+  } else {
+    record.count++
+  }
+  if (authFailures.get(ip).count >= AUTH_FAIL_LIMIT) {
+    authFailures.get(ip).blockedUntil = now + AUTH_BLOCK_MS
+    warn(`auth: too many failed attempts from ${ip}; blocking for ${AUTH_BLOCK_MS / 1000}s`)
+  }
+}
+
+function clearAuthFailures(ip) {
+  authFailures.delete(ip)
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+function ntfyTarget(raw) {
+  const text = String(raw || '').trim()
+  if (!text) return null
+  if (/^https?:\/\//i.test(text)) {
+    try {
+      const url = new URL(text)
+      const segments = url.pathname.split('/').filter(Boolean)
+      const topic = segments.pop() || ''
+      const base = `${url.origin}${segments.length ? `/${segments.join('/')}` : ''}`
+      return { base: base.replace(/\/+$/, ''), topic, query: url.search || '' }
+    } catch {
+      return null
+    }
+  }
+  return { base: 'https://ntfy.sh', topic: text, query: '' }
+}
+
+function publishNtfy(payload) {
+  const target = opts.ntfyTarget || (opts.ntfyTarget = ntfyTarget(opts.ntfy))
+  if (!target || !target.topic) {
+    warn('ntfy: no topic configured; skipping publish')
+    return Promise.resolve()
+  }
+  const url = `${target.base}/${target.query}`
+  return fetch(url, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ topic: target.topic, ...payload }),
+    signal: AbortSignal.timeout(5000),
+  })
+    .then((res) => {
+      if (!res.ok) warn(`ntfy: publish failed with HTTP ${res.status}`)
+    })
+    .catch((err) => warn(`ntfy: publish failed: ${err.message}`))
+}
+
+function parseArgs(argv) {
+  const flags = {}
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+    if (!arg.startsWith('--')) {
+      return { error: `unexpected argument: ${arg}` }
+    }
+    const eq = arg.indexOf('=')
+    const key = eq >= 0 ? arg.slice(2, eq) : arg.slice(2)
+    if (BOOL_FLAGS.has(key)) {
+      flags[key] = true
+      continue
+    }
+    if (!VALUE_FLAGS.has(key)) {
+      return { error: `unknown flag: --${key}` }
+    }
+    const value = eq >= 0 ? arg.slice(eq + 1) : argv[++i]
+    if (value === undefined) {
+      return { error: `missing value for --${key}` }
+    }
+    flags[key] = value
+  }
+  if (flags['no-print-qr']) flags['print-qr'] = false
+  return { flags }
+}
+
+function configPaths() {
+  const dir = process.env.OCREMOTE_CONFIG_DIR
+    ? path.resolve(process.env.OCREMOTE_CONFIG_DIR)
+    : path.join(os.homedir(), '.config', 'oc-remote')
+  return { dir, file: path.join(dir, 'config.json') }
+}
+
+function loadConfig() {
+  const { file } = configPaths()
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'))
+    return parsed && typeof parsed === 'object' ? parsed : {}
+  } catch {
+    return {}
+  }
+}
+
+function saveConfig(cfg) {
+  const { dir, file } = configPaths()
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 })
+  try {
+    fs.chmodSync(dir, 0o700)
+  } catch {}
+  const tmp = `${file}.tmp`
+  fs.writeFileSync(tmp, `${JSON.stringify(cfg, null, 2)}\n`, { mode: 0o600 })
+  fs.renameSync(tmp, file)
+  try {
+    fs.chmodSync(file, 0o600)
+  } catch {}
+}
+
+function resolveOpencodeBin(flagValue) {
+  if (flagValue) return flagValue
+  if (process.env.OPENCODE_BIN) return process.env.OPENCODE_BIN
+  const homeBin = path.join(os.homedir(), '.opencode', 'bin', 'opencode')
+  if (fs.existsSync(homeBin)) return homeBin
+  return 'opencode'
+}
+
+function locateBin(bin) {
+  if (bin.includes('/')) {
+    return fs.existsSync(bin) ? bin : null
+  }
+  for (const dir of (process.env.PATH || '').split(':')) {
+    if (!dir) continue
+    const candidate = path.join(dir, bin)
+    try {
+      fs.accessSync(candidate, fs.constants.X_OK)
+      return candidate
+    } catch {}
+  }
+  return null
+}
+
+function lanIPv4() {
+  const out = []
+  for (const [name, addrs] of Object.entries(os.networkInterfaces())) {
+    for (const addr of addrs || []) {
+      if (addr.family !== 'IPv4' || addr.internal) continue
+      if (addr.address.startsWith('169.254.')) continue
+      out.push({ name, address: addr.address })
+    }
+  }
+  return out
+}
+
+function tailscaleBin() {
+  return process.env.OCREMOTE_TAILSCALE || 'tailscale'
+}
+
+function execTailscale(args, timeout = 10_000) {
+  return new Promise((resolve) => {
+    execFile(tailscaleBin(), args, { timeout }, (err, stdout, stderr) => {
+      resolve({
+        ok: !err,
+        code: err && typeof err.code === 'number' ? err.code : err ? 1 : 0,
+        stdout: String(stdout || ''),
+        stderr: String(stderr || ''),
+      })
+    })
+  })
+}
+
+function tailscaleIp() {
+  return new Promise((resolve) => {
+    execFile(tailscaleBin(), ['ip', '-4'], { timeout: 1500 }, (err, stdout) => {
+      if (err) return resolve(null)
+      const ip = String(stdout)
+        .split('\n')
+        .map((line) => line.trim())
+        .filter(Boolean)[0]
+      resolve(ip && net.isIPv4(ip) ? ip : null)
+    })
+  })
+}
+
+async function tailscaleStatusJson() {
+  const result = await execTailscale(['status', '--json'], 5000)
+  if (!result.ok) return null
+  try {
+    return JSON.parse(result.stdout)
+  } catch {
+    return null
+  }
+}
+
+async function tailscaleRunning() {
+  const status = await tailscaleStatusJson()
+  if (!status) return false
+  return status.BackendState === 'Running'
+}
+
+async function tailscaleDnsName() {
+  const status = await tailscaleStatusJson()
+  const name = status && status.Self && status.Self.DNSName
+  if (typeof name !== 'string' || !name.length) return null
+  return name.replace(/\.$/, '')
+}
+
+async function funnelStatusJson() {
+  const result = await execTailscale(['funnel', 'status', '--json'], 5000)
+  if (!result.ok) return null
+  const text = result.stdout.trim()
+  if (!text || text === '{}') return {}
+  try {
+    return JSON.parse(text)
+  } catch {
+    return null
+  }
+}
+
+async function funnelProxyTarget(dnsName) {
+  const status = await funnelStatusJson()
+  if (!status || !status.Web || !dnsName) return null
+  const entry = status.Web[`${dnsName}:443`]
+  if (!entry || !entry.Handlers) return null
+  const root = entry.Handlers['/']
+  if (!root || typeof root.Proxy !== 'string') return null
+  return root.Proxy
+}
+
+function funnelProxyMatches(proxy) {
+  if (!proxy) return false
+  return new RegExp(`(?:127\\.0\\.0\\.1|localhost):${opts.port}(?:/|$)`).test(proxy)
+}
+
+async function funnelUrlIfActive() {
+  if (!(await tailscaleRunning())) return null
+  const dnsName = await tailscaleDnsName()
+  if (!dnsName) return null
+  const proxy = await funnelProxyTarget(dnsName)
+  if (!funnelProxyMatches(proxy)) return null
+  return `https://${dnsName}`
+}
+
+async function enableFunnel() {
+  if (!(await tailscaleRunning())) {
+    info('tailscale is not running; trying `tailscale up`...')
+    await execTailscale(['up'], 15_000)
+    if (!(await tailscaleRunning())) {
+      error('tailscale is not connected. Open the Tailscale app and sign in, then retry')
+      return null
+    }
+  }
+  const dnsName = await tailscaleDnsName()
+  if (!dnsName) {
+    error('could not read the Tailscale DNS name (is MagicDNS enabled?)')
+    return null
+  }
+  const active = await funnelUrlIfActive()
+  if (active) return active
+
+  info(`enabling Tailscale Funnel on https://${dnsName} -> http://${LOOPBACK}:${opts.port}`)
+  const result = await execTailscale(
+    ['funnel', '--bg', '--https=443', `http://${LOOPBACK}:${opts.port}`],
+    20_000
+  )
+  const output = `${result.stdout}\n${result.stderr}`
+  const approval = /https:\/\/login\.tailscale\.com\/[^\s]+/.exec(output)
+  if (approval) {
+    warn('Funnel needs a one-time approval. Open this URL, approve Funnel, then restart oc-remote:')
+    warn(`  ${approval[0]}`)
+    return null
+  }
+  if (!result.ok) {
+    error(`could not enable Tailscale Funnel: ${(result.stderr || result.stdout).trim() || 'unknown error'}`)
+    return null
+  }
+  for (let attempt = 0; attempt < 5; attempt++) {
+    const url = await funnelUrlIfActive()
+    if (url) return url
+    await sleep(1000)
+  }
+  const url = await tailscaleDnsName()
+  return url ? `https://${url}` : null
+}
+
+async function disableFunnel() {
+  const dnsName = await tailscaleDnsName()
+  const proxy = await funnelProxyTarget(dnsName)
+  if (!funnelProxyMatches(proxy)) return
+  info('disabling Tailscale Funnel (it pointed at this companion)')
+  await execTailscale(['funnel', '--https=443', 'off'], 10_000)
+}
+
+function startFunnelMonitor() {
+  clearInterval(funnelMonitorTimer)
+  funnelMonitorTimer = setInterval(async () => {
+    if (shuttingDown || opts.tunnel !== 'funnel') return
+    if (await funnelUrlIfActive()) return
+    warn('Tailscale Funnel is no longer serving this companion; re-applying')
+    const url = await enableFunnel()
+    if (url && url !== tunnelUrl) {
+      tunnelUrl = url
+      rebuildUrls()
+      info(`funnel restored: ${tunnelUrl}`)
+      printPairing()
+    }
+  }, 30_000)
+  funnelMonitorTimer.unref?.()
+}
+
+function isLoopback(req) {
+  const addr = req.socket.remoteAddress || ''
+  return addr === '127.0.0.1' || addr === '::1' || addr === '::ffff:127.0.0.1'
+}
+
+function extractToken(req, url) {
+  const header = req.headers.authorization
+  if (header) {
+    const bearer = /^Bearer\s+(.+)$/i.exec(header)
+    if (bearer) return bearer[1].trim()
+    const basic = /^Basic\s+(.+)$/i.exec(header)
+    if (basic) {
+      try {
+        const decoded = Buffer.from(basic[1], 'base64').toString('utf8')
+        const idx = decoded.indexOf(':')
+        if (idx >= 0) return decoded.slice(idx + 1)
+      } catch {}
+    }
+  }
+  const authToken = url.searchParams.get('auth_token')
+  if (authToken) {
+    try {
+      const decoded = Buffer.from(authToken, 'base64').toString('utf8')
+      const idx = decoded.indexOf(':')
+      if (idx >= 0) return decoded.slice(idx + 1)
+    } catch {}
+  }
+  const plain = url.searchParams.get('token')
+  if (plain) return plain
+  return null
+}
+
+function authorized(req, url) {
+  if (opts.noAuth) return true
+  return safeEqual(extractToken(req, url) || '', remoteToken)
+}
+
+function sendJson(req, res, status, payload, extraHeaders) {
+  const body = JSON.stringify(payload)
+  const headers = {
+    'content-type': 'application/json; charset=utf-8',
+    'content-length': Buffer.byteLength(body),
+    'cache-control': 'no-store',
+    ...(extraHeaders || {}),
+  }
+  res.writeHead(status, headers)
+  if (req.method === 'HEAD') return res.end()
+  res.end(body)
+}
+
+function filterRequestHeaders(headers) {
+  const drop = new Set([
+    'host',
+    'authorization',
+    'connection',
+    'proxy-connection',
+    'keep-alive',
+    'upgrade',
+    'transfer-encoding',
+    'te',
+    'trailer',
+    'proxy-authorization',
+    'expect',
+  ])
+  const out = {}
+  for (const [key, value] of Object.entries(headers)) {
+    if (!drop.has(key.toLowerCase())) out[key] = value
+  }
+  return out
+}
+
+function filterResponseHeaders(headers) {
+  const drop = new Set([
+    'connection',
+    'proxy-connection',
+    'keep-alive',
+    'upgrade',
+    'transfer-encoding',
+    'trailer',
+    'proxy-authenticate',
+    'proxy-authorization',
+  ])
+  const out = {}
+  for (const [key, value] of Object.entries(headers)) {
+    if (!drop.has(key.toLowerCase())) out[key] = value
+  }
+  return out
+}
+
+function handleProxy(req, res, url) {
+  if (!ALLOWED_METHODS.has(req.method)) {
+    sendJson(req, res, 405, { error: 'method_not_allowed', method: req.method })
+    return
+  }
+
+  const params = new URLSearchParams(url.searchParams)
+  params.delete('token')
+  params.delete('auth_token')
+  const qs = params.toString()
+  const targetPath = url.pathname + (qs ? `?${qs}` : '')
+
+  const headers = filterRequestHeaders(req.headers)
+  headers.authorization = internalAuth
+
+  const isEvent =
+    url.pathname === '/event' || url.pathname === '/global/event' || url.pathname === '/api/event'
+
+  activeClients++
+  let counted = false
+  const release = () => {
+    if (counted) return
+    counted = true
+    activeClients = Math.max(0, activeClients - 1)
+  }
+  res.on('close', release)
+
+  const upstream = http.request(
+    {
+      host: LOOPBACK,
+      port: opts.opencodePort,
+      method: req.method,
+      path: targetPath,
+      headers,
+    },
+    (upstreamRes) => {
+      const outHeaders = filterResponseHeaders(upstreamRes.headers)
+      if (isEvent) outHeaders['x-accel-buffering'] = 'no'
+      const status = upstreamRes.statusCode || 502
+      if (upstreamRes.statusMessage) {
+        res.writeHead(status, upstreamRes.statusMessage, outHeaders)
+      } else {
+        res.writeHead(status, outHeaders)
+      }
+      res.flushHeaders()
+      upstreamRes.on('data', (chunk) => {
+        if (!res.write(chunk)) {
+          upstreamRes.pause()
+          res.once('drain', () => upstreamRes.resume())
+        }
+      })
+      upstreamRes.on('end', () => res.end())
+      upstreamRes.on('error', () => res.destroy())
+    }
+  )
+
+  upstream.setNoDelay(true)
+  upstream.setTimeout(0)
+  upstream.on('error', (err) => {
+    release()
+    if (res.headersSent) {
+      res.destroy()
+      return
+    }
+    sendJson(req, res, 502, {
+      error: 'bad_gateway',
+      message:
+        err.code === 'ECONNREFUSED'
+          ? 'opencode upstream is not running'
+          : err.code === 'ECONNRESET'
+            ? 'opencode upstream closed the connection'
+            : err.message || String(err),
+    })
+  })
+  req.on('error', () => upstream.destroy())
+  res.on('close', () => {
+    if (!res.writableEnded) upstream.destroy()
+  })
+  req.pipe(upstream)
+}
+
+function statusPayload() {
+  return {
+    name: NAME,
+    version: VERSION,
+    directory: opts.dir,
+    uptime: Math.round((Date.now() - STARTED_AT) / 1000),
+    port: opts.port,
+    opencodePort: opts.opencodePort,
+    clients: activeClients,
+    tunnel: remoteUrl(),
+    tunnelProvider,
+    auth: !opts.noAuth,
+    utilityPort: opts.utilityPort,
+    relay: opts.relay || null,
+    deviceID: identity ? identity.deviceID() : null,
+  }
+}
+
+function remoteUrl() {
+  return opts.publicUrl || tunnelUrl || null
+}
+
+const CRC_TABLE = (() => {
+  const table = new Int32Array(256)
+  for (let n = 0; n < 256; n++) {
+    let c = n
+    for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1
+    table[n] = c
+  }
+  return table
+})()
+
+function crc32(buf) {
+  let c = 0xffffffff
+  for (let i = 0; i < buf.length; i++) c = CRC_TABLE[(c ^ buf[i]) & 0xff] ^ (c >>> 8)
+  return (c ^ 0xffffffff) >>> 0
+}
+
+function pngChunk(type, data) {
+  const len = Buffer.alloc(4)
+  len.writeUInt32BE(data.length, 0)
+  const typeBuf = Buffer.from(type, 'latin1')
+  const crc = Buffer.alloc(4)
+  crc.writeUInt32BE(crc32(Buffer.concat([typeBuf, data])), 0)
+  return Buffer.concat([len, typeBuf, data, crc])
+}
+
+function qrPng(qr, scale = 8, margin = 4) {
+  const count = qr.getModuleCount()
+  const size = (count + margin * 2) * scale
+  const raw = Buffer.alloc(size * (size + 1), 0xff)
+  for (let y = 0; y < size; y++) raw[y * (size + 1)] = 0
+  for (let my = 0; my < count; my++) {
+    for (let mx = 0; mx < count; mx++) {
+      if (!qr.isDark(my, mx)) continue
+      for (let py = 0; py < scale; py++) {
+        const row = (margin + my) * scale + py
+        const start = row * (size + 1) + 1 + (margin + mx) * scale
+        raw.fill(0x00, start, start + scale)
+      }
+    }
+  }
+  const ihdr = Buffer.alloc(13)
+  ihdr.writeUInt32BE(size, 0)
+  ihdr.writeUInt32BE(size, 4)
+  ihdr[8] = 8
+  ihdr[9] = 0
+  const signature = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])
+  return Buffer.concat([
+    signature,
+    pngChunk('IHDR', ihdr),
+    pngChunk('IDAT', zlib.deflateSync(raw)),
+    pngChunk('IEND', Buffer.alloc(0)),
+  ])
+}
+
+function buildQr(text) {
+  const qr = qrcode(0, 'L')
+  qr.addData(text)
+  qr.make()
+  return qr
+}
+
+function pairLink() {
+  const host = os.hostname()
+  const params = [
+    'v=1',
+    `name=${encodeURIComponent(host)}`,
+    `url=${encodeURIComponent(primaryUrl)}`,
+    `token=${encodeURIComponent(remoteToken)}`,
+  ]
+  if (opts.ntfy) params.push(`ntfy=${encodeURIComponent(String(opts.ntfy))}`)
+  if (allUrls.length > 1) {
+    params.push(`urls=${encodeURIComponent(allUrls.map((entry) => entry.url).join(','))}`)
+  }
+  return `ocremote://pair?${params.join('&')}`
+}
+
+function escapeHtml(value) {
+  return String(value)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;')
+}
+
+let identity = null
+let relayClient = null
+let adapter = null
+let utilityServer = null
+let lastInvite = null
+
+async function createInvitePayload() {
+  if (!relayClient) {
+    return { relay: false, url: pairLink(), token: remoteToken }
+  }
+  const invite = await relayClient.createInvite()
+  const url = relayClient.inviteURL(invite)
+  lastInvite = { url, expiresAt: invite.expiresAt }
+  return {
+    relay: true,
+    url,
+    expiresAt: invite.expiresAt,
+    deviceID: relayClient.identity.deviceID(),
+    name: relayClient.identity.name(),
+  }
+}
+
+function currentInviteLink() {
+  if (lastInvite && lastInvite.expiresAt > Date.now()) return lastInvite.url
+  return null
+}
+
+function pairPage() {
+  const v2Link = currentInviteLink()
+  const link = v2Link || pairLink()
+  let qrBlock = '<p class="warn">qrcode.js vendor missing: re-download companion/vendor/qrcode.js</p>'
+  if (qrcode) {
+    const png = qrPng(buildQr(link))
+    qrBlock = `<img class="qr" alt="Pairing QR" src="data:image/png;base64,${png.toString('base64')}">`
+  }
+  const v2Block = v2Link
+    ? `<div class="card"><div class="row"><span class="k">relay</span><code class="v" id="rl">${escapeHtml(opts.relay)}</code></div>
+<div class="row"><span class="k">device</span><code class="v" id="dv">${escapeHtml(relayClient ? relayClient.identity.deviceID() : '')}</code><button onclick="cp('dv')">copy</button></div>
+<div class="row"><span class="k">deep link</span><code class="v" id="dl2">${escapeHtml(v2Link)}</code><button onclick="cp('dl2')">copy</button></div>
+<p>Scan with the app. The invite is single-use and expires in 5 minutes; reload this page for a new one.</p></div>`
+    : ''
+  const rows = allUrls
+    .map(
+      (entry) =>
+        `<div class="row"><span class="k">${escapeHtml(entry.label)}</span><code class="v" id="u${escapeHtml(entry.label)}">${escapeHtml(entry.url)}</code><button onclick="cp('u${escapeHtml(entry.label)}')">copy</button></div>`
+    )
+    .join('\n')
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="robots" content="noindex">
+<title>oc-remote pairing</title>
+<style>
+  :root { color-scheme: dark; }
+  body { margin: 0; padding: 32px 20px; background: #0a0a0a; color: #e5e5e5;
+         font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace; }
+  .wrap { max-width: 560px; margin: 0 auto; }
+  h1 { font-size: 16px; font-weight: 600; letter-spacing: .08em; text-transform: uppercase; color: #a3a3a3; }
+  .qr { width: 288px; height: 288px; display: block; margin: 24px auto; background: #fff; border-radius: 8px; padding: 12px; image-rendering: pixelated; }
+  .card { border: 1px solid #262626; border-radius: 8px; padding: 16px; margin: 16px 0; background: #111; }
+  .row { display: flex; align-items: center; gap: 12px; padding: 6px 0; }
+  .k { color: #737373; min-width: 76px; font-size: 12px; }
+  .v { flex: 1; overflow-wrap: anywhere; color: #e5e5e5; }
+  button { background: #1f1f1f; color: #d4d4d4; border: 1px solid #333; border-radius: 6px;
+           padding: 4px 10px; font: inherit; font-size: 12px; cursor: pointer; }
+  button:hover { background: #262626; color: #fff; }
+  .warn { color: #fbbf24; }
+  p { color: #a3a3a3; line-height: 1.5; }
+  code { font-family: inherit; font-size: 13px; }
+</style>
+</head>
+<body>
+<div class="wrap">
+  <h1>oc-remote &middot; pairing</h1>
+  ${qrBlock}
+  <p>Scan with the OpenCode Remote iOS app, or copy the values below.</p>
+  ${v2Block}
+  <div class="card">
+    <div class="row"><span class="k">token</span><code class="v" id="tk">${escapeHtml(remoteToken)}</code><button onclick="cp('tk')">copy</button></div>
+${rows}
+  </div>
+  <div class="card"><div class="row"><span class="k">deep link</span><code class="v" id="dl">${escapeHtml(pairLink())}</code><button onclick="cp('dl')">copy</button></div></div>
+  <p>Served on a loopback-only port that is never exposed through tunnels or the relay.</p>
+</div>
+<script>
+function cp(id) {
+  var el = document.getElementById(id);
+  var text = el.textContent;
+  var done = function () { var b = el.parentNode.querySelector('button'); if (b) { b.textContent = 'copied'; setTimeout(function(){ b.textContent = 'copy'; }, 1200); } };
+  if (navigator.clipboard && navigator.clipboard.writeText) { navigator.clipboard.writeText(text).then(done, fallback); }
+  else { fallback(); }
+  function fallback() {
+    var ta = document.createElement('textarea');
+    ta.value = text; document.body.appendChild(ta); ta.select();
+    try { document.execCommand('copy'); } catch (e) {}
+    document.body.removeChild(ta); done();
+  }
+}
+</script>
+</body>
+</html>`
+}
+
+function handleRequest(req, res) {
+  let url
+  try {
+    url = new URL(req.url, `http://${LOOPBACK}`)
+  } catch {
+    sendJson(req, res, 400, { error: 'bad_request' })
+    return
+  }
+
+  const pathname = url.pathname
+
+  if (pathname === '/_ocremote/health') {
+    if (req.method !== 'GET' && req.method !== 'HEAD') {
+      sendJson(req, res, 405, { error: 'method_not_allowed' })
+      return
+    }
+    sendJson(req, res, 200, { ok: true })
+    return
+  }
+
+  {
+    const clientIp = req.socket.remoteAddress || 'unknown'
+    if (authorized(req, url)) {
+      clearAuthFailures(clientIp)
+    } else if (authBlocked(clientIp)) {
+      sendJson(
+        req,
+        res,
+        429,
+        { error: 'too_many_requests', message: 'too many failed auth attempts; retry in a minute' },
+        { 'retry-after': '60' }
+      )
+      return
+    } else {
+      noteAuthFailure(clientIp)
+      sendJson(req, res, 401, { error: 'unauthorized', message: 'missing or invalid token' })
+      return
+    }
+  }
+
+  if (pathname === '/_ocremote/status') {
+    if (req.method !== 'GET' && req.method !== 'HEAD') {
+      sendJson(req, res, 405, { error: 'method_not_allowed' })
+      return
+    }
+    sendJson(req, res, 200, statusPayload())
+    return
+  }
+
+  if (pathname === '/_ocremote/pair' || pathname === '/_ocremote/invite') {
+    sendJson(req, res, 404, { error: 'not_found', message: 'pairing endpoints live on the loopback-only utility port' })
+    return
+  }
+
+  handleProxy(req, res, url)
+}
+
+function handleUtilityRequest(req, res) {
+  let url
+  try {
+    url = new URL(req.url, 'http://127.0.0.1')
+  } catch {
+    sendJson(req, res, 400, { error: 'bad_request' })
+    return
+  }
+  if (url.pathname === '/_ocremote/health') {
+    sendJson(req, res, 200, { ok: true })
+    return
+  }
+  if (url.pathname === '/_ocremote/invite') {
+    if (req.method !== 'GET' && req.method !== 'POST') {
+      sendJson(req, res, 405, { error: 'method_not_allowed' })
+      return
+    }
+    createInvitePayload()
+      .then((payload) => sendJson(req, res, 200, payload))
+      .catch((err) => sendJson(req, res, 500, { error: 'invite_failed', message: err.message }))
+    return
+  }
+  if (url.pathname === '/_ocremote/pair') {
+    if (req.method !== 'GET' && req.method !== 'HEAD') {
+      sendJson(req, res, 405, { error: 'method_not_allowed' })
+      return
+    }
+    const ready = relayClient && !currentInviteLink() ? createInvitePayload() : Promise.resolve(null)
+    ready
+      .then(() => {
+        const html = pairPage()
+        res.writeHead(200, {
+          'content-type': 'text/html; charset=utf-8',
+          'content-length': Buffer.byteLength(html),
+          'cache-control': 'no-store',
+        })
+        if (req.method === 'HEAD') return res.end()
+        res.end(html)
+      })
+      .catch((err) => sendJson(req, res, 500, { error: 'page_failed', message: err.message }))
+    return
+  }
+  sendJson(req, res, 404, { error: 'not_found' })
+}
+
+async function createUtilityServer() {
+  const preferred = opts.utilityPort ?? opts.port + 1
+  for (let candidate = preferred; candidate < preferred + 20; candidate++) {
+    if (candidate === opts.port || candidate === opts.opencodePort) continue
+    if (candidate > 65535) break
+    if (!(await portFree(candidate))) continue
+    const srv = http.createServer(handleUtilityRequest)
+    const ok = await new Promise((resolve) => {
+      srv.once('error', (err) => {
+        warn(`utility port ${candidate} failed: ${err.message}`)
+        resolve(false)
+      })
+      srv.listen(candidate, LOOPBACK, () => {
+        opts.utilityPort = candidate
+        resolve(true)
+      })
+    })
+    if (!ok) continue
+    info(`pairing page (loopback only): http://${LOOPBACK}:${opts.utilityPort}/_ocremote/pair`)
+    return srv
+  }
+  error('could not start the loopback utility listener; pairing pages are unavailable')
+  return null
+}
+
+function createProxyServer() {
+  const srv = http.createServer(handleRequest)
+  srv.requestTimeout = 0
+  srv.headersTimeout = 60000
+  srv.keepAliveTimeout = 65000
+  srv.timeout = 0
+  srv.on('connection', (socket) => {
+    sockets.add(socket)
+    socket.on('close', () => sockets.delete(socket))
+  })
+  srv.on('clientError', (err, socket) => {
+    try {
+      socket.end('HTTP/1.1 400 Bad Request\r\nconnection: close\r\ncontent-length: 0\r\n\r\n')
+    } catch {}
+  })
+  srv.on('upgrade', (req, socket) => {
+    rejectUpgrade(socket)
+  })
+  srv.on('connect', (req, socket) => {
+    rejectUpgrade(socket)
+  })
+  srv.on('error', (err) => {
+    error(`server error: ${err.message}`)
+  })
+  return srv
+}
+
+function rejectUpgrade(socket) {
+  const body = JSON.stringify({
+    error: 'not_implemented',
+    message: 'WebSocket/Upgrade is not supported by oc-remote (PTY is out of scope)',
+  })
+  try {
+    socket.write(
+      `HTTP/1.1 501 Not Implemented\r\ncontent-type: application/json; charset=utf-8\r\nconnection: close\r\ncontent-length: ${Buffer.byteLength(body)}\r\n\r\n${body}`
+    )
+  } catch {}
+  socket.destroy()
+}
+
+function pipePrefixed(stream, prefix) {
+  let buffer = ''
+  stream.setEncoding('utf8')
+  stream.on('data', (chunk) => {
+    buffer += chunk
+    let idx
+    while ((idx = buffer.indexOf('\n')) >= 0) {
+      process.stderr.write(prefix + buffer.slice(0, idx) + '\n')
+      buffer = buffer.slice(idx + 1)
+    }
+  })
+  stream.on('end', () => {
+    if (buffer.length) process.stderr.write(prefix + buffer + '\n')
+  })
+  stream.on('error', () => {})
+}
+
+function launchOpencode() {
+  const args = [
+    'serve',
+    '--hostname',
+    LOOPBACK,
+    '--port',
+    String(opts.opencodePort),
+    '--print-logs',
+    '--log-level',
+    'INFO',
+  ]
+  info(`starting opencode: ${opts.opencodeBin} ${args.join(' ')} (cwd: ${opts.dir})`)
+  child = spawn(opts.opencodeBin, args, {
+    cwd: opts.dir,
+    env: {
+      ...process.env,
+      OPENCODE_SERVER_USERNAME: 'opencode',
+      OPENCODE_SERVER_PASSWORD: internalPassword,
+    },
+    stdio: ['ignore', 'pipe', 'pipe'],
+  })
+  child.on('error', (err) => {
+    error(`failed to spawn opencode: ${err.message}`)
+  })
+  child.on('exit', (code, signal) => {
+    child = null
+    if (shuttingDown) return
+    scheduleRestart(signal ? `signal ${signal}` : `code ${code}`)
+  })
+  if (child.stdout) pipePrefixed(child.stdout, '[opencode] ')
+  if (child.stderr) pipePrefixed(child.stderr, '[opencode] ')
+}
+
+function scheduleRestart(reason) {
+  restartAttempts++
+  const delay = Math.min(15000, 1000 * 2 ** Math.min(restartAttempts - 1, 4))
+  warn(`opencode exited (${reason}); restarting in ${delay}ms (attempt ${restartAttempts})`)
+  restartTimer = setTimeout(async () => {
+    if (shuttingDown) return
+    launchOpencode()
+    const health = await waitHealthy(30000)
+    if (health) {
+      restartAttempts = 0
+      info(`opencode restarted (v${health.version})`)
+    }
+  }, delay)
+}
+
+function waitHealthy(timeoutMs) {
+  const deadline = Date.now() + timeoutMs
+  const attempt = () =>
+    new Promise((resolve) => {
+      const req = http.request(
+        {
+          host: LOOPBACK,
+          port: opts.opencodePort,
+          path: '/global/health',
+          method: 'GET',
+          headers: { authorization: internalAuth },
+          timeout: 2000,
+        },
+        (res) => {
+          let data = ''
+          res.setEncoding('utf8')
+          res.on('data', (chunk) => {
+            data += chunk
+          })
+          res.on('end', () => {
+            try {
+              const parsed = JSON.parse(data)
+              resolve(parsed && parsed.healthy ? parsed : null)
+            } catch {
+              resolve(null)
+            }
+          })
+        }
+      )
+      req.on('error', () => resolve(null))
+      req.on('timeout', () => {
+        req.destroy()
+        resolve(null)
+      })
+      req.end()
+    })
+
+  return (async () => {
+    while (Date.now() < deadline) {
+      if (shuttingDown) return null
+      const health = await attempt()
+      if (health) return health
+      await sleep(400)
+    }
+    return null
+  })()
+}
+
+function portFree(port) {
+  return new Promise((resolve) => {
+    const probe = net.createServer()
+    probe.once('error', () => resolve(false))
+    probe.once('listening', () => probe.close(() => resolve(true)))
+    probe.listen(port, LOOPBACK)
+  })
+}
+
+function configBinDir() {
+  return path.join(configPaths().dir, 'bin')
+}
+
+function cloudflaredLocalBin() {
+  return path.join(configBinDir(), process.platform === 'win32' ? 'cloudflared.exe' : 'cloudflared')
+}
+
+function findCloudflared() {
+  if (process.env.OCREMOTE_CLOUDFLARED) {
+    const override = process.env.OCREMOTE_CLOUDFLARED
+    return fs.existsSync(override) ? override : null
+  }
+  const local = cloudflaredLocalBin()
+  if (fs.existsSync(local)) return local
+  return locateBin('cloudflared')
+}
+
+function downloadFile(url, dest, redirects = 0) {
+  return new Promise((resolve, reject) => {
+    if (redirects > 5) return reject(new Error('too many redirects'))
+    const req = https.get(url, { headers: { 'user-agent': `${NAME}/${VERSION}` } }, (res) => {
+      const status = res.statusCode || 0
+      if (status >= 300 && status < 400 && res.headers.location) {
+        res.resume()
+        resolve(downloadFile(new URL(res.headers.location, url).toString(), dest, redirects + 1))
+        return
+      }
+      if (status !== 200) {
+        res.resume()
+        reject(new Error(`download failed with HTTP ${status}`))
+        return
+      }
+      const file = fs.createWriteStream(dest, { mode: 0o755 })
+      res.pipe(file)
+      file.on('finish', () => file.close(() => resolve()))
+      file.on('error', reject)
+      res.on('error', reject)
+    })
+    req.on('error', reject)
+    req.setTimeout(120000, () => req.destroy(new Error('download timed out')))
+  })
+}
+
+async function ensureCloudflared() {
+  const existing = findCloudflared()
+  if (existing) return existing
+  const arch = process.arch === 'arm64' ? 'arm64' : 'amd64'
+  if (process.platform !== 'darwin' && process.platform !== 'linux') {
+    throw new Error(`automatic cloudflared install is not supported on ${process.platform}; install it manually`)
+  }
+  const asset = process.platform === 'darwin' ? `cloudflared-darwin-${arch}.tgz` : `cloudflared-linux-${arch}`
+  const url = `https://github.com/cloudflare/cloudflared/releases/latest/download/${asset}`
+  info(`downloading cloudflared (${asset}) ...`)
+  fs.mkdirSync(configBinDir(), { recursive: true, mode: 0o700 })
+  const tmp = path.join(os.tmpdir(), `oc-remote-cloudflared-${Date.now()}`)
+  await downloadFile(url, tmp)
+  if (asset.endsWith('.tgz')) {
+    await new Promise((resolve, reject) => {
+      execFile('tar', ['-xzf', tmp, '-C', configBinDir()], (err) => (err ? reject(err) : resolve()))
+    })
+  } else {
+    fs.copyFileSync(tmp, cloudflaredLocalBin())
+  }
+  fs.chmodSync(cloudflaredLocalBin(), 0o755)
+  try {
+    fs.unlinkSync(tmp)
+  } catch {}
+  const bin = findCloudflared()
+  if (!bin) throw new Error('cloudflared install failed')
+  return bin
+}
+
+function readLines(stream, onLine) {
+  let buffer = ''
+  stream.setEncoding('utf8')
+  stream.on('data', (chunk) => {
+    buffer += chunk
+    let idx
+    while ((idx = buffer.indexOf('\n')) >= 0) {
+      onLine(buffer.slice(0, idx))
+      buffer = buffer.slice(idx + 1)
+    }
+  })
+}
+
+async function startTunnel() {
+  if (opts.publicUrl) {
+    info('--public-url set; skipping tunnel startup')
+    return
+  }
+  if (opts.tunnel === 'none') return
+
+  if (opts.tunnel === 'funnel') {
+    const url = await enableFunnel()
+    if (!url) {
+      warn('funnel unavailable; staying on LAN/Tailscale candidates')
+      return
+    }
+    tunnelProvider = 'funnel'
+    tunnelUrl = url
+    cachedTailscaleIp = await tailscaleIp()
+    rebuildUrls()
+    info(`stable remote URL via Tailscale Funnel: ${tunnelUrl}`)
+    printPairing()
+    startFunnelMonitor()
+    return
+  }
+
+  if (opts.tunnel === 'tailscale') {
+    const ip = await tailscaleIp()
+    if (!ip) {
+      warn('--tunnel tailscale: tailscale is not installed or not connected; falling back to LAN')
+      return
+    }
+    tunnelProvider = 'tailscale'
+    tunnelUrl = `http://${ip}:${opts.port}`
+    rebuildUrls()
+    info(`remote access via Tailscale: ${tunnelUrl}`)
+    printPairing()
+    return
+  }
+
+  if (opts.tunnel === 'auto') {
+    const activeFunnel = await funnelUrlIfActive()
+    if (activeFunnel) {
+      tunnelProvider = 'funnel'
+      tunnelUrl = activeFunnel
+      rebuildUrls()
+      info(`stable remote URL via existing Tailscale Funnel: ${tunnelUrl}`)
+      printPairing()
+      return
+    }
+  }
+
+  const installed = findCloudflared()
+  if (!installed && opts.tunnel === 'auto') {
+    if (cachedTailscaleIp) {
+      tunnelProvider = 'tailscale'
+      tunnelUrl = `http://${cachedTailscaleIp}:${opts.port}`
+      rebuildUrls()
+      info(`remote access via Tailscale: ${tunnelUrl}`)
+      printPairing()
+      return
+    }
+    info('remote access: LAN only - run `oc-remote --tunnel funnel` (stable URL) or --tunnel cloudflare')
+    return
+  }
+
+  let bin = installed
+  if (!bin) {
+    try {
+      bin = await ensureCloudflared()
+      info(`cloudflared ready: ${bin}`)
+    } catch (err) {
+      error(`could not install cloudflared: ${err.message}`)
+      return
+    }
+  }
+
+  tunnelProvider = 'cloudflare'
+  spawnCloudflared(bin)
+}
+
+function spawnCloudflared(bin) {
+  if (shuttingDown) return
+  info('starting cloudflare quick tunnel...')
+  tunnelChild = spawn(bin, ['tunnel', '--url', `http://${LOOPBACK}:${opts.port}`, '--no-autoupdate'], {
+    stdio: ['ignore', 'pipe', 'pipe'],
+  })
+  const onLine = (line) => {
+    const match = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/i.exec(line)
+    if (!match) return
+    const url = match[0]
+    quickTunnelUrl = url
+    if (url === tunnelUrl) return
+    if (tunnelProvider === 'funnel') {
+      rebuildUrls()
+      return
+    }
+    tunnelUrl = url
+    tunnelAttempts = 0
+    rebuildUrls()
+    info(`cloudflare quick tunnel ready: ${tunnelUrl}`)
+    printPairing()
+  }
+  if (tunnelChild.stdout) readLines(tunnelChild.stdout, onLine)
+  if (tunnelChild.stderr) readLines(tunnelChild.stderr, onLine)
+  tunnelChild.on('error', (err) => error(`cloudflared failed to start: ${err.message}`))
+  tunnelChild.on('exit', (code, signal) => {
+    tunnelChild = null
+    if (shuttingDown || opts.tunnel === 'none') return
+    tunnelUrl = tunnelProvider === 'funnel' ? tunnelUrl : ''
+    quickTunnelUrl = ''
+    rebuildUrls()
+    tunnelAttempts++
+    const delay = Math.min(30000, 2000 * 2 ** Math.min(tunnelAttempts - 1, 4))
+    warn(`cloudflared exited (${signal || code}); restarting in ${delay}ms`)
+    tunnelTimer = setTimeout(() => spawnCloudflared(bin), delay)
+  })
+}
+
+function stopTunnel() {
+  clearTimeout(tunnelTimer)
+  tunnelTimer = null
+  if (tunnelChild) {
+    try {
+      tunnelChild.kill('SIGTERM')
+    } catch {}
+    tunnelChild = null
+  }
+}
+
+async function computeUrls() {
+  cachedTailscaleIp = await tailscaleIp()
+  rebuildUrls()
+}
+
+function rebuildUrls() {
+  const urls = []
+  if (opts.publicUrl) urls.push({ url: opts.publicUrl, label: 'public' })
+  if (tunnelUrl && !opts.publicUrl) {
+    urls.push({ url: tunnelUrl, label: tunnelProvider === 'tailscale' ? 'tailscale' : 'tunnel' })
+  }
+  if (quickTunnelUrl && quickTunnelUrl !== tunnelUrl) {
+    urls.push({ url: quickTunnelUrl, label: 'tunnel' })
+  }
+  if (cachedTailscaleIp && !urls.some((entry) => entry.url.includes(cachedTailscaleIp))) {
+    urls.push({ url: `http://${cachedTailscaleIp}:${opts.port}`, label: 'tailscale' })
+  }
+  const seen = new Set()
+  for (const entry of lanIPv4()) {
+    if (seen.has(entry.address)) continue
+    seen.add(entry.address)
+    if (urls.some((existing) => existing.url.includes(entry.address))) continue
+    urls.push({ url: `http://${entry.address}:${opts.port}`, label: entry.name })
+  }
+  urls.push({ url: `http://${LOOPBACK}:${opts.port}`, label: 'loopback' })
+  allUrls = urls
+  const next = urls[0].url.replace(/\/+$/, '')
+  const changed = next !== primaryUrl
+  primaryUrl = next
+  if (changed) {
+    writeEndpointFile()
+    publishBeacon()
+  }
+}
+
+function endpointId() {
+  return crypto.createHash('sha256').update(`oc-remote:${remoteToken}`).digest('hex').slice(0, 12)
+}
+
+function endpointPayload() {
+  return {
+    type: 'endpoint',
+    id: endpointId(),
+    name: os.hostname(),
+    version: VERSION,
+    url: primaryUrl,
+    urls: allUrls.map((entry) => ({ url: entry.url, label: entry.label })),
+    provider: opts.publicUrl ? 'public' : tunnelProvider || 'lan',
+    auth: !opts.noAuth,
+    port: opts.port,
+    ts: Date.now(),
+  }
+}
+
+function writeEndpointFile() {
+  try {
+    const { dir } = configPaths()
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 })
+    const file = path.join(dir, 'endpoint.json')
+    const tmp = `${file}.tmp`
+    fs.writeFileSync(tmp, `${JSON.stringify(endpointPayload(), null, 2)}\n`, { mode: 0o600 })
+    fs.renameSync(tmp, file)
+  } catch (err) {
+    warn(`could not write endpoint.json: ${err.message}`)
+  }
+}
+
+function publishBeacon() {
+  if (!opts.ntfyUrl || shuttingDown) return
+  const payload = endpointPayload()
+  const key = payload.url
+  if (key === lastBeaconKey) return
+  lastBeaconKey = key
+  info(`beacon: publishing ${payload.url} [${payload.provider}] to ntfy`)
+  publishNtfy({
+    title: 'oc-remote endpoint',
+    message: JSON.stringify(payload),
+    tags: ['ocremote-endpoint'],
+    priority: 1,
+  })
+}
+
+function startEndpointBeacon() {
+  writeEndpointFile()
+  publishBeacon()
+  clearInterval(endpointTimer)
+  endpointTimer = setInterval(() => {
+    if (shuttingDown) return
+    computeUrls()
+    writeEndpointFile()
+    lastBeaconKey = ''
+    publishBeacon()
+  }, 5 * 60_000)
+  endpointTimer.unref?.()
+}
+
+function startTransportWatcher() {
+  clearInterval(transportTimer)
+  transportTimer = setInterval(async () => {
+    if (shuttingDown || opts.publicUrl || opts.tunnel !== 'auto') return
+    const active = await funnelUrlIfActive()
+    if (active && active !== tunnelUrl) {
+      tunnelProvider = 'funnel'
+      tunnelUrl = active
+      rebuildUrls()
+      info(`stable remote URL via existing Tailscale Funnel: ${tunnelUrl}`)
+      printPairing()
+      return
+    }
+    if (!active && tunnelProvider === 'funnel') {
+      tunnelProvider = quickTunnelUrl ? 'cloudflare' : null
+      tunnelUrl = quickTunnelUrl
+      rebuildUrls()
+      warn(
+        tunnelUrl
+          ? `Tailscale Funnel went away; falling back to ${tunnelUrl}`
+          : 'Tailscale Funnel went away; falling back to LAN/Tailscale candidates'
+      )
+      printPairing()
+    }
+  }, 60_000)
+  transportTimer.unref?.()
+}
+
+function startWatchdog() {
+  clearInterval(watchdogTimer)
+  watchdogTimer = setInterval(() => {
+    if (shuttingDown || !child || child.exitCode !== null) return
+    const req = http.request(
+      {
+        host: LOOPBACK,
+        port: opts.opencodePort,
+        path: '/global/health',
+        method: 'GET',
+        headers: { authorization: internalAuth },
+        timeout: 3000,
+      },
+      (res) => {
+        res.resume()
+        if (res.statusCode && res.statusCode < 500) {
+          watchdogFailures = 0
+          return
+        }
+        noteWatchdogFailure()
+      }
+    )
+    req.on('timeout', () => req.destroy(new Error('timeout')))
+    req.on('error', () => noteWatchdogFailure())
+    req.end()
+  }, 30_000)
+  watchdogTimer.unref?.()
+}
+
+function noteWatchdogFailure() {
+  watchdogFailures++
+  warn(`watchdog: opencode health check failed (${watchdogFailures}/3)`)
+  if (watchdogFailures < 3) return
+  watchdogFailures = 0
+  if (!child || child.exitCode !== null) return
+  error('watchdog: opencode is unresponsive; restarting it')
+  try {
+    child.kill('SIGKILL')
+  } catch {}
+}
+
+function printPairing() {
+  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')
+  if (publicEntry) {
+    const stable = tunnelProvider === 'funnel' || publicEntry.label === 'public'
+    info(
+      `remote access: ${publicEntry.url} (${stable ? 'stable, reachable from anywhere' : 'reachable from anywhere; the URL changes when the tunnel restarts'})`
+    )
+  } else if (tunnelProvider === 'tailscale') {
+    info('remote access: Tailscale IP above (needs the Tailscale app on your phone)')
+  } else {
+    info('remote access: LAN only - run `oc-remote --tunnel funnel` (stable URL) or --tunnel cloudflare')
+  }
+  info(`pairing deep link: ${pairLink()}`)
+  if (!opts.printQr) return
+  if (!qrcode) {
+    warn('QR unavailable: companion/vendor/qrcode.js not found')
+    return
+  }
+  const ascii = buildQr(pairLink()).createASCII(1, 4)
+  process.stderr.write(`${ascii}\n`)
+}
+
+function printInviteQr(link) {
+  if (!opts.printQr || !qrcode) return
+  process.stderr.write(`${buildQr(link).createASCII(1, 4)}\n`)
+}
+
+function handleRelayEvent(event) {
+  if (event.type === 'relay_connected') return
+  if (event.type === 'relay_disconnected') return
+  if (event.type === 'paired') {
+    info(`relay: paired ${event.clientID}${event.name ? ` (${event.name})` : ''}`)
+    return
+  }
+  if (event.type === 'session_open') {
+    info(`relay: client session ${event.session} (${event.clientID})`)
+    return
+  }
+}
+
+async function startRelay() {
+  if (!opts.relay) return
+  identity = new Identity(configPaths().dir).ensure(opts.deviceName || os.hostname().replace(/\.local$/i, ''))
+  adapter = new RpcAdapter({
+    baseUrl: `http://${LOOPBACK}:${opts.opencodePort}`,
+    authHeader: internalAuth,
+    logger: warn,
+  })
+  relayClient = new RelayClient({
+    relayUrl: opts.relay,
+    identity,
+    adapter,
+    logger: info,
+    invites: new Map(),
+    onEvent: handleRelayEvent,
+  })
+  try {
+    await relayClient.registerDevice(VERSION)
+    info(`relay: registered device ${identity.deviceID()} (${identity.name()})`)
+  } catch (err) {
+    error(`relay registration failed: ${err.message}`)
+  }
+  relayClient.start()
+  const payload = await createInvitePayload()
+  info(`relay: ${opts.relay}`)
+  info(`pairing v2 link: ${payload.url}`)
+  printInviteQr(payload.url)
+}
+
+function printBanner(health) {
+  const hostname = os.hostname()
+  info(`${NAME} v${VERSION} on ${hostname} (${os.platform()} ${os.release()})`)
+  info(`project directory: ${opts.dir}`)
+  info(`opencode: ${opts.opencodeBin} v${health.version} -> http://${LOOPBACK}:${opts.opencodePort} (loopback only)`)
+  info(`proxy listening: ${opts.host}:${opts.port}`)
+  if (opts.noAuth) warn('AUTH DISABLED: anyone who can reach this port controls opencode')
+  for (const line of opts.noAuth
+    ? ['pair page: disabled (--no-auth)']
+    : [`pair page (loopback): http://${LOOPBACK}:${opts.port}/_ocremote/pair`])
+    info(line)
+  if (opts.relay) info(`relay: ${opts.relay} (device ${opts.deviceName || os.hostname()})`)
+  info('self-check: oc-remote doctor')
+  printPairing()
+}
+
+function startMdns() {
+  if (!opts.mdns) return
+  const dnsSd = '/usr/bin/dns-sd'
+  if (!fs.existsSync(dnsSd)) {
+    warn('mDNS: /usr/bin/dns-sd not found; skipping Bonjour registration')
+    return
+  }
+  const hostLabel = os.hostname().replace(/\.local\.?$/i, '')
+  const serviceName = `${NAME} (${hostLabel})`
+  mdnsChild = spawn(dnsSd, ['-R', serviceName, '_ocremote._tcp', 'local', String(opts.port), 'v=1'], {
+    stdio: ['ignore', 'pipe', 'pipe'],
+  })
+  mdnsChild.on('error', (err) => warn(`mDNS: ${err.message}`))
+  mdnsChild.on('exit', (code, signal) => {
+    mdnsChild = null
+    if (!shuttingDown && code !== 0) warn(`mDNS registration exited (${signal || code})`)
+  })
+  if (mdnsChild.stdout) pipePrefixed(mdnsChild.stdout, '[dns-sd] ')
+  if (mdnsChild.stderr) pipePrefixed(mdnsChild.stderr, '[dns-sd] ')
+  info(`mDNS: publishing "_ocremote._tcp.local" as "${serviceName}" on port ${opts.port}`)
+}
+
+function startNtfy() {
+  if (!opts.ntfy) return
+  const busy = new Set()
+  const publish = (payload) => publishNtfy(payload)
+
+  const onEvent = (event) => {
+    const props = event.properties || {}
+    if (event.type === 'permission.asked') {
+      const patterns = Array.isArray(props.patterns) ? props.patterns.join(', ') : ''
+      const message = `${props.permission || 'permission'} ${patterns}`.trim()
+      info(`ntfy: permission.asked -> push notification`)
+      publish({
+        title: 'opencode: permission required',
+        message: message || 'permission required',
+        tags: ['warning'],
+        priority: 4,
+        ...(primaryUrl ? { click: primaryUrl } : {}),
+      })
+      return
+    }
+    if (event.type === 'session.status') {
+      const status = props.status && props.status.type
+      if (status === 'busy') busy.add(props.sessionID)
+      else busy.delete(props.sessionID)
+      return
+    }
+    if (event.type === 'session.idle') {
+      if (busy.delete(props.sessionID)) {
+        info(`ntfy: session.idle after busy -> push notification`)
+        publish({
+          title: 'opencode: task finished',
+          message: `session ${props.sessionID} is idle`,
+          tags: ['white_check_mark'],
+          priority: 3,
+          ...(primaryUrl ? { click: primaryUrl } : {}),
+        })
+      }
+      return
+    }
+    if (event.type === 'session.deleted') busy.delete(props.sessionID)
+  }
+
+  const connect = () => {
+    if (shuttingDown) return
+    const req = http.request(
+      {
+        host: LOOPBACK,
+        port: opts.opencodePort,
+        path: '/event',
+        method: 'GET',
+        headers: { authorization: internalAuth, accept: 'text/event-stream' },
+      },
+      (res) => {
+        if (res.statusCode !== 200) {
+          warn(`ntfy: event stream returned HTTP ${res.statusCode}; retrying in 5s`)
+          res.resume()
+          setTimeout(connect, 5000)
+          return
+        }
+        info(`ntfy: subscribed to opencode events (topic ${opts.ntfyUrl})`)
+        let buffer = ''
+        res.setEncoding('utf8')
+        res.on('data', (chunk) => {
+          buffer += chunk
+          let idx
+          while ((idx = buffer.indexOf('\n\n')) >= 0) {
+            const block = buffer.slice(0, idx)
+            buffer = buffer.slice(idx + 2)
+            for (const line of block.split('\n')) {
+              if (!line.startsWith('data:')) continue
+              try {
+                onEvent(JSON.parse(line.slice(5).trim()))
+              } catch {}
+            }
+          }
+        })
+        res.on('end', () => {
+          if (!shuttingDown) setTimeout(connect, 5000)
+        })
+        res.on('error', () => {})
+      }
+    )
+    req.on('error', (err) => {
+      if (shuttingDown) return
+      warn(`ntfy: event stream error: ${err.message}; retrying in 5s`)
+      setTimeout(connect, 5000)
+    })
+    req.end()
+  }
+  connect()
+}
+
+function shutdown(signal) {
+  if (shuttingDown) return
+  shuttingDown = true
+  info(`received ${signal}; shutting down`)
+  clearTimeout(restartTimer)
+  clearInterval(endpointTimer)
+  clearInterval(watchdogTimer)
+  clearInterval(funnelMonitorTimer)
+  clearInterval(transportTimer)
+  stopTunnel()
+  if (relayClient) {
+    try {
+      relayClient.stop()
+    } catch {}
+    relayClient = null
+  }
+  if (utilityServer) {
+    try {
+      utilityServer.close()
+    } catch {}
+    utilityServer = null
+  }
+  if (mdnsChild) {
+    try {
+      mdnsChild.kill('SIGTERM')
+    } catch {}
+    mdnsChild = null
+  }
+  for (const socket of sockets) {
+    try {
+      socket.destroy()
+    } catch {}
+  }
+  const finish = () => process.exit(0)
+  if (server) {
+    server.close(finish)
+  } else {
+    setTimeout(finish, 0)
+  }
+  if (child && child.exitCode === null) {
+    try {
+      child.kill('SIGTERM')
+    } catch {}
+    const killer = setTimeout(() => {
+      try {
+        child?.kill('SIGKILL')
+      } catch {}
+      finish()
+    }, 3000)
+    killer.unref()
+  }
+  setTimeout(finish, 4000).unref()
+}
+
+let opts = {
+  dir: process.cwd(),
+  port: 4190,
+  opencodePort: 4191,
+  utilityPort: null,
+  host: '0.0.0.0',
+  publicUrl: null,
+  tunnel: 'auto',
+  ntfy: null,
+  ntfyUrl: null,
+  noAuth: false,
+  mdns: true,
+  printQr: true,
+  opencodeBin: null,
+  relay: null,
+  deviceName: null,
+}
+
+function abort(msg) {
+  process.stderr.write(`${HELP}\n`)
+  error(msg)
+  process.exit(2)
+}
+
+function readEndpointFile() {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(configPaths().dir, 'endpoint.json'), 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+function maskToken(token) {
+  if (!token) return '(none)'
+  const text = String(token)
+  return text.length <= 8 ? '****' : `${text.slice(0, 4)}...${text.slice(-4)}`
+}
+
+function execCommand(bin, args, timeout = 5000) {
+  return new Promise((resolve) => {
+    execFile(bin, args, { timeout }, (err, stdout, stderr) => {
+      resolve({ ok: !err, stdout: String(stdout || ''), stderr: String(stderr || '') })
+    })
+  })
+}
+
+async function probeUrl(url, headers = {}, timeout = 5000) {
+  try {
+    const res = await fetch(url, { headers, signal: AbortSignal.timeout(timeout) })
+    const text = await res.text()
+    return { ok: res.ok, status: res.status, text }
+  } catch (err) {
+    return { ok: false, status: 0, text: err.message }
+  }
+}
+
+function postLocal(port, path, timeout = 2500) {
+  return new Promise((resolve) => {
+    const req = http.request(
+      { host: LOOPBACK, port, path, method: 'POST', timeout },
+      (res) => {
+        let text = ''
+        res.setEncoding('utf8')
+        res.on('data', (chunk) => {
+          text += chunk
+        })
+        res.on('end', () => resolve({ status: res.statusCode, text }))
+      }
+    )
+    req.on('timeout', () => req.destroy(new Error('timeout')))
+    req.on('error', () => resolve(null))
+    req.end()
+  })
+}
+
+function probeLocal(path, headers = {}, timeout = 3000) {
+  return new Promise((resolve) => {
+    const req = http.request(
+      { host: LOOPBACK, port: opts.port, path, method: 'GET', headers, timeout },
+      (res) => {
+        let text = ''
+        res.setEncoding('utf8')
+        res.on('data', (chunk) => {
+          text += chunk
+        })
+        res.on('end', () => resolve({ ok: res.statusCode >= 200 && res.statusCode < 300, status: res.statusCode, text }))
+      }
+    )
+    req.on('timeout', () => req.destroy(new Error('timeout')))
+    req.on('error', (err) => resolve({ ok: false, status: 0, text: err.message }))
+    req.end()
+  })
+}
+
+async function launchAgentState() {
+  const result = await execCommand('launchctl', ['print', `gui/${process.getuid()}/${LAUNCH_LABEL}`], 5000)
+  if (!result.ok) return 'not loaded'
+  const match = /state = ([a-z]+)/.exec(result.stdout)
+  return match ? match[1] : 'loaded'
+}
+
+async function runSubcommand(name, argv) {
+  const parsed = parseArgs(argv)
+  const flags = parsed.error ? {} : parsed.flags
+  const cfg = loadConfig()
+  const port = flags.port !== undefined ? Number(flags.port) : Number(cfg.port ?? 4190)
+  const token = flags.token !== undefined ? String(flags.token) : cfg.token
+  opts.port = port
+  const out = (line) => process.stdout.write(`${line}\n`)
+  const authHeader = token ? { authorization: `Bearer ${token}` } : {}
+
+  if (name === 'funnel') {
+    const action = (argv[0] || 'status').toLowerCase()
+    opts.port = port
+    if (action === 'off') {
+      await disableFunnel()
+      out('tailscale funnel disabled')
+      return 0
+    }
+    if (action === 'status') {
+      const active = await funnelUrlIfActive()
+      out(active ? `funnel active: ${active}` : 'funnel not active')
+      return active ? 0 : 1
+    }
+    if (action !== 'on') {
+      out('usage: oc-remote funnel on|off|status')
+      return 2
+    }
+    const enabled = await enableFunnel()
+    if (enabled) {
+      out(`funnel active: ${enabled}`)
+      out('the companion will adopt it automatically (auto mode watches for it)')
+      return 0
+    }
+    out('funnel not enabled yet: approve the link printed above, then run `oc-remote funnel on` again')
+    return 1
+  }
+
+  if (name === 'version') {
+    out(VERSION)
+    return 0
+  }
+
+  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)
+    let payload = null
+    for (const port of ports) {
+      const res = await postLocal(port, '/_ocremote/invite')
+      if (!res || res.status !== 200) continue
+      try {
+        payload = JSON.parse(res.text)
+        break
+      } catch {}
+    }
+    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 ...`')
+      return 1
+    }
+    out(payload.url)
+    if (payload.expiresAt) out(`expires: ${new Date(payload.expiresAt).toISOString()} (single use)`)
+    if (!payload.relay) out('note: no relay configured; this is the legacy LAN/tunnel pairing link')
+    if (qrcode) process.stdout.write(`${buildQr(payload.url).createASCII(1, 4)}\n`)
+    return 0
+  }
+
+  if (name === 'relay-status') {
+    const relay = opts.relay ?? cfg.relay
+    if (!relay) {
+      out('relay: not configured (add --relay wss://relay.example)')
+      return 1
+    }
+    const identityStore = new Identity(configPaths().dir).load()
+    if (!identityStore) {
+      out('identity: missing (start the companion once to create it)')
+      return 1
+    }
+    out(`relay: ${relay}`)
+    out(`device: ${identityStore.deviceID()} (${identityStore.name()})`)
+    const pairs = identityStore.pairs()
+    out(`paired devices: ${pairs.length}`)
+    for (const item of pairs) out(`  - ${item.pairID}  ${item.clientID}  ${item.name || ''}`)
+    const httpBase = relay.replace(/^ws/, 'http').replace(/\/+$/, '')
+    const probe = await probeUrl(`${httpBase}/v1/devices/${identityStore.deviceID()}`, {}, 5000)
+    if (probe.ok) {
+      try {
+        const device = JSON.parse(probe.text)
+        const seen = device.lastSeen ? new Date(device.lastSeen * 1000).toISOString() : 'never'
+        out(`companion online: ${device.online}  lastSeen: ${seen}`)
+      } catch {}
+    } else {
+      out(`relay unreachable (HTTP ${probe.status})`)
+    }
+    return 0
+  }
+
+  if (name === 'unpair') {
+    const pairID = argv.find((value) => !value.startsWith('--'))
+    if (!pairID) {
+      out('usage: oc-remote unpair <pairID>')
+      return 2
+    }
+    const identityStore = new Identity(configPaths().dir).load()
+    const pair = identityStore ? identityStore.pair(pairID) : null
+    if (!pair) {
+      error(`unknown pair: ${pairID}`)
+      return 1
+    }
+    const relay = opts.relay ?? cfg.relay
+    if (relay) {
+      try {
+        const client = new RelayClient({ relayUrl: relay, identity: identityStore, adapter: null, logger: () => {} })
+        await client.revokePair(pairID)
+        out(`relay: revoked ${pairID}`)
+      } catch (err) {
+        error(`relay revoke failed: ${err.message}`)
+        return 1
+      }
+    }
+    identityStore.removePair(pairID)
+    out(`local pair removed: ${pairID}`)
+    return 0
+  }
+
+  if (name === 'logs') {
+    out(LOG_PATH)
+    if (fs.existsSync(LOG_PATH)) {
+      const lines = fs.readFileSync(LOG_PATH, 'utf8').trimEnd().split('\n')
+      out(lines.slice(-40).join('\n'))
+    } else {
+      out('(no log file yet)')
+    }
+    return 0
+  }
+
+  if (name === 'restart') {
+    const result = await execCommand('launchctl', ['kickstart', '-k', `gui/${process.getuid()}/${LAUNCH_LABEL}`], 8000)
+    if (!result.ok) {
+      error(`could not restart ${LAUNCH_LABEL}: ${result.stderr.trim() || 'agent not loaded'}`)
+      out('hint: bash companion/install.sh --dir <project> --tunnel <mode>')
+      return 1
+    }
+    out(`restarted ${LAUNCH_LABEL}`)
+    return 0
+  }
+
+  if (name === 'status') {
+    const endpoint = readEndpointFile()
+    const state = await launchAgentState()
+    const health = await probeLocal('/_ocremote/health')
+    const authenticated = token
+      ? await probeLocal('/_ocremote/status', authHeader)
+      : { ok: false, status: 0, text: 'no token' }
+    out(`oc-remote v${VERSION}`)
+    out(`config: ${configPaths().file}`)
+    out(`token: ${maskToken(token)}`)
+    out(`launch agent: ${state}`)
+    out(`companion: ${health.ok ? `reachable on 127.0.0.1:${port}` : `NOT reachable on 127.0.0.1:${port}`}`)
+    out(`auth: ${authenticated.ok ? 'token accepted' : `token rejected (HTTP ${authenticated.status})`}`)
+    if (endpoint) {
+      const age = Math.round((Date.now() - Number(endpoint.ts || 0)) / 1000)
+      out(`endpoint: ${endpoint.url} [${endpoint.provider}] published ${age}s ago`)
+      for (const entry of endpoint.urls || []) out(`  - ${entry.url}  [${entry.label}]`)
+      out(`beacon id: ${endpoint.id}`)
+    } else {
+      out('endpoint: (no endpoint.json yet)')
+    }
+    return health.ok ? 0 : 1
+  }
+
+  if (name === 'doctor') {
+    out(`oc-remote doctor v${VERSION}`)
+    let critical = 0
+    const check = (ok, label, fix) => {
+      out(`${ok ? ' ok ' : 'FAIL'}  ${label}`)
+      if (!ok && fix) out(`         fix: ${fix}`)
+      if (!ok) critical++
+    }
+    const note = (label, hint) => {
+      out(`  -   ${label}`)
+      if (hint) out(`         hint: ${hint}`)
+    }
+
+    const bin = locateBin(resolveOpencodeBin(flags.opencode))
+    if (bin) {
+      const version = await execCommand(bin, ['--version'], 8000)
+      check(true, `opencode binary: ${bin}${version.ok ? ` (${version.stdout.trim()})` : ''}`)
+    } else {
+      check(false, 'opencode binary not found', 'install opencode or pass --opencode <path>')
+    }
+
+    check(Boolean(token), `pairing token stored in ${configPaths().file}`, 'run `oc-remote` once to generate one')
+
+    const health = await probeLocal('/_ocremote/health')
+    check(
+      health.ok,
+      `companion reachable on 127.0.0.1:${port}`,
+      'start it (`oc-remote --dir <project>`) or `bash companion/install.sh --dir <project>`'
+    )
+
+    if (health.ok) {
+      const status = await probeLocal('/_ocremote/status', authHeader)
+      check(status.ok, `token accepted by the companion (HTTP ${status.status})`, 'rotate the token with `oc-remote --new-token`')
+      const upstream = await probeLocal('/global/health', authHeader, 5000)
+      check(upstream.ok, `opencode upstream healthy (HTTP ${upstream.status})`, 'restart with `oc-remote restart`')
+    }
+
+    const state = await launchAgentState()
+    if (state === 'running' || state === 'loaded') {
+      check(true, `LaunchAgent ${LAUNCH_LABEL}: ${state}`)
+    } else {
+      note(
+        `LaunchAgent ${LAUNCH_LABEL}: ${state}`,
+        'install it for always-on access: `bash companion/install.sh --dir <project> --tunnel auto`'
+      )
+    }
+
+    const lan = lanIPv4()
+    if (lan.length) {
+      check(true, `LAN address${lan.length === 1 ? '' : 'es'}: ${lan.map((e) => e.address).join(', ')}`)
+    } else {
+      note('no LAN address (Wi-Fi or Ethernet off?)', 'the phone can still connect through the tunnel')
+    }
+
+    const tsInstalled = (await execCommand(tailscaleBin(), ['version'], 4000)).ok
+    if (tsInstalled) {
+      const running = await tailscaleRunning()
+      const dnsName = running ? await tailscaleDnsName() : null
+      if (running) {
+        check(true, `tailscale: running (${dnsName || 'no DNS name'})`)
+        if (dnsName) {
+          const proxy = await funnelProxyTarget(dnsName)
+          const active = funnelProxyMatches(proxy)
+          if (active) {
+            check(true, `tailscale funnel -> ${proxy}`)
+          } else {
+            note(
+              'tailscale funnel: not serving this companion',
+              'stable URL with a one-time approval: `oc-remote --tunnel funnel`'
+            )
+          }
+        }
+      } else {
+        note('tailscale: stopped', 'open the Tailscale app for the stable Funnel URL / tailnet access')
+      }
+    } else {
+      note('tailscale CLI not found', 'optional: stable Funnel URL / tailnet access')
+    }
+
+    const endpoint = readEndpointFile()
+    if (endpoint && endpoint.url) {
+      const endpointProbe = await probeUrl(`${endpoint.url}/_ocremote/health`, {}, 8000)
+      check(
+        endpointProbe.ok,
+        `endpoint reachable: ${endpoint.url} (HTTP ${endpointProbe.status})`,
+        'check the tunnel: `oc-remote logs` or restart with `oc-remote restart`'
+      )
+    } else {
+      note('no endpoint published yet (LAN/tailscale only)', 'run the companion once to publish endpoint.json')
+    }
+
+    if (opts.ntfy || cfg.ntfy) {
+      const raw = String(cfg.ntfy || '')
+      let base = 'https://ntfy.sh'
+      if (/^https?:\/\//i.test(raw)) {
+        try {
+          base = new URL(raw).origin
+        } catch {
+          base = 'https://ntfy.sh'
+        }
+      }
+      const ntfy = await probeUrl(`${base}/v1/health`, {}, 5000)
+      check(ntfy.ok, `ntfy reachable (${base})`, 'check your network or use a self-hosted ntfy URL')
+    } else {
+      note('ntfy not configured', 'optional: push notifications + endpoint beacons')
+    }
+
+    out(critical === 0 ? 'all checks passed' : `${critical} check${critical === 1 ? '' : 's'} failed`)
+    return critical === 0 ? 0 : 1
+  }
+
+  return 0
+}
+
+async function main() {
+  const argv = process.argv.slice(2)
+  if (argv[0] && SUBCOMMANDS.has(argv[0])) {
+    const code = await runSubcommand(argv[0], argv.slice(1))
+    return code
+  }
+  const parsed = parseArgs(argv)
+  if (parsed.error) abort(parsed.error)
+  const flags = parsed.flags
+  if (flags.help) {
+    process.stdout.write(HELP)
+    return 0
+  }
+
+  const cfg = loadConfig()
+
+  opts.port = flags.port !== undefined ? Number(flags.port) : Number(cfg.port ?? 4190)
+  opts.opencodePort =
+    flags['opencode-port'] !== undefined ? Number(flags['opencode-port']) : Number(cfg.opencodePort ?? 4191)
+  opts.host = flags.host !== undefined ? flags.host : (cfg.host ?? '0.0.0.0')
+  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.deviceName = flags['device-name'] !== undefined ? String(flags['device-name']) : (cfg.deviceName ?? null)
+  opts.utilityPort =
+    flags['utility-port'] !== undefined
+      ? Number(flags['utility-port'])
+      : Number(cfg.utilityPort ?? 0) || null
+  opts.noAuth = Boolean(flags['no-auth'])
+  opts.mdns = !flags['no-mdns']
+  opts.printQr = flags['print-qr'] !== false
+
+  if (!TUNNEL_MODES.has(opts.tunnel)) {
+    abort(`invalid --tunnel: ${opts.tunnel} (expected ${[...TUNNEL_MODES].join(' | ')})`)
+  }
+
+  if (!Number.isInteger(opts.port) || opts.port < 1 || opts.port > 65535) abort(`invalid --port: ${flags.port ?? cfg.port}`)
+  if (!Number.isInteger(opts.opencodePort) || opts.opencodePort < 1 || opts.opencodePort > 65535)
+    abort(`invalid --opencode-port: ${flags['opencode-port'] ?? cfg.opencodePort}`)
+  if (opts.port === opts.opencodePort) abort('--port and --opencode-port must differ')
+  if (opts.utilityPort !== null && (!Number.isInteger(opts.utilityPort) || opts.utilityPort < 1 || opts.utilityPort > 65535))
+    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://...)`)
+
+  const dir = path.resolve(flags.dir !== undefined ? flags.dir : process.cwd())
+  let stat
+  try {
+    stat = fs.statSync(dir)
+  } catch {
+    abort(`directory does not exist: ${dir}`)
+  }
+  if (!stat.isDirectory()) abort(`not a directory: ${dir}`)
+  opts.dir = dir
+
+  if (flags.daemon) {
+    const installer = path.join(HERE, 'install.sh')
+    if (!fs.existsSync(installer)) abort(`install.sh not found next to oc-remote.mjs`)
+    const args = [installer, '--dir', dir, '--port', String(opts.port)]
+    if (opts.tunnel) args.push('--tunnel', opts.tunnel)
+    if (opts.relay) args.push('--relay', opts.relay)
+    if (opts.ntfy) args.push('--ntfy', String(opts.ntfy))
+    if (opts.deviceName) args.push('--device-name', opts.deviceName)
+    const child = spawn('bash', args, { stdio: 'inherit' })
+    return await new Promise((resolve) => child.on('exit', (code) => resolve(code ?? 0)))
+  }
+
+  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('  2. Sign in:      opencode auth login')
+      say('  3. Run again:    npx ocremote --pair')
+      return 1
+    }
+    abort(`opencode binary not found: ${flags.opencode || 'opencode'}`)
+  }
+
+  if (flags.pair) {
+    info('first run: starting opencode and preparing the pairing QR')
+    info('keep this terminal open while you pair; for an always-on service use --daemon')
+  }
+
+  if (opts.ntfy) {
+    const topic = String(opts.ntfy)
+    opts.ntfyUrl = /^https?:\/\//i.test(topic)
+      ? topic
+      : `https://ntfy.sh/${encodeURIComponent(topic)}`
+    opts.ntfyTarget = ntfyTarget(opts.ntfy)
+  }
+
+  const storedToken = typeof cfg.token === 'string' && cfg.token.length ? cfg.token : null
+  let token
+  let tokenChanged = false
+  if (flags['new-token']) {
+    token = randomHex(16)
+    tokenChanged = true
+    info('rotating pairing token (--new-token)')
+  } else if (flags.token !== undefined) {
+    token = String(flags.token)
+    tokenChanged = token !== storedToken
+  } else if (storedToken) {
+    token = storedToken
+  } else {
+    token = randomHex(16)
+    tokenChanged = true
+    info('generated a new pairing token')
+  }
+  remoteToken = token
+
+  const nextConfig = {
+    version: 1,
+    token,
+    port: opts.port,
+    opencodePort: opts.opencodePort,
+    host: opts.host,
+    publicUrl: opts.publicUrl,
+    tunnel: opts.tunnel,
+    ntfy: opts.ntfy,
+    relay: opts.relay,
+    deviceName: opts.deviceName,
+    utilityPort: flags['utility-port'] !== undefined ? opts.utilityPort : (cfg.utilityPort ?? null),
+    updatedAt: new Date().toISOString(),
+  }
+  const configChanged =
+    tokenChanged ||
+    cfg.port !== nextConfig.port ||
+    cfg.opencodePort !== nextConfig.opencodePort ||
+    cfg.host !== nextConfig.host ||
+    cfg.publicUrl !== nextConfig.publicUrl ||
+    cfg.tunnel !== nextConfig.tunnel ||
+    cfg.ntfy !== nextConfig.ntfy ||
+    cfg.relay !== nextConfig.relay ||
+    cfg.deviceName !== nextConfig.deviceName ||
+    cfg.utilityPort !== nextConfig.utilityPort
+  if (configChanged) {
+    try {
+      saveConfig(nextConfig)
+      info(`config saved: ${configPaths().file} (0600)`)
+    } catch (err) {
+      warn(`could not save config: ${err.message}`)
+    }
+  }
+
+  internalPassword = randomHex(16)
+  internalAuth = `Basic ${Buffer.from(`opencode:${internalPassword}`, 'utf8').toString('base64')}`
+
+  if (!(await portFree(opts.opencodePort))) {
+    error(`port ${opts.opencodePort} is already in use; pick another with --opencode-port`)
+    return 1
+  }
+
+  await computeUrls()
+
+  launchOpencode()
+  const health = await waitHealthy(30000)
+  if (!health) {
+    error('opencode did not become healthy within 30s; aborting')
+    if (child && child.exitCode === null) child.kill('SIGKILL')
+    return 1
+  }
+  info(`opencode is healthy (v${health.version})`)
+
+  server = createProxyServer()
+  await new Promise((resolve, reject) => {
+    server.once('error', reject)
+    server.listen(opts.port, opts.host, () => {
+      server.off('error', reject)
+      resolve()
+    })
+  }).catch((err) => {
+    error(
+      err.code === 'EADDRINUSE'
+        ? `port ${opts.port} is already in use; pick another with --port`
+        : `could not listen on ${opts.host}:${opts.port}: ${err.message}`
+    )
+    if (child && child.exitCode === null) child.kill('SIGKILL')
+    return 1
+  })
+
+  printBanner(health)
+  utilityServer = await createUtilityServer()
+  startMdns()
+  startNtfy()
+  startEndpointBeacon()
+  startTransportWatcher()
+  startWatchdog()
+  await startTunnel()
+  await startRelay()
+  return 0
+}
+
+process.on('SIGINT', () => shutdown('SIGINT'))
+process.on('SIGTERM', () => shutdown('SIGTERM'))
+process.on('uncaughtException', (err) => error(`uncaught exception: ${err.stack || err.message}`))
+process.on('unhandledRejection', (err) => error(`unhandled rejection: ${err?.stack || err}`))
+
+main()
+  .then((code) => {
+    if (code !== 0) process.exit(code)
+  })
+  .catch((err) => {
+    error(`fatal: ${err.stack || err.message}`)
+    process.exit(1)
+  })