wherdr 1.3.0 → 1.3.2

package/bin/lib/commands.mjs

@@ -7,10 +7,11 @@ import net from 'node:net'
 import os from 'node:os'
 import path from 'node:path'
 import { pathToFileURL } from 'node:url'
-import { BIN, CliError, SERVER, VERSION, bad, c, localUrl, ok, portTaken, probe, row, say, serverEnv, settingsFile, warn, wherdrDir, withSettings } from './core.mjs'
+import { BIN, CliError, SERVER, VERSION, bad, c, homebrewInstall, localUrl, ok, portTaken, probe, row, say, serverEnv, settingsFile, warn, wherdrDir, withSettings } from './core.mjs'
 import { RUNTIME_HELP, findRuntime, isBun, runtimeOk, runtimeVersion, temporaryInstall } from './runtime.mjs'
+import { brewDoctor, brewRedirect, brewService, brewStatusRows } from './brew.mjs'
 import { controlService, installService, serviceFile, servicePlatform, serviceState, uninstallService } from './service.mjs'
-import { LINKS, inspect, reachable } from './tailnet.mjs'
+import { LINKS, inspect, publishCommand, reachable } from './tailnet.mjs'
 
 export const HELP = `${'wherdr'}: your Herdr agents from your phone and browser.
 
@@ -139,6 +140,13 @@ export async function run(opts) {
 export async function start(opts) {
   needServer()
   const ctx = context(opts)
+  const brew = brewService()
+  if (brew) {
+    const redirect = brewRedirect('start', brew)
+    if (redirect) throw new CliError(redirect)
+    ok(`wherdr already runs as a Homebrew service: ${c.cyan(ctx.url)}`)
+    return
+  }
   const svc = serviceState()
   if (svc.installed) {
     if (svc.running && await probe(ctx.port, ctx.host)) { ok(`wherdr already runs as a login service: ${c.cyan(ctx.url)}`); return }
@@ -187,6 +195,12 @@ async function waitUp(ctx, alive, seconds = 45) {
 // ------------------------------------------------------------------ stop
 export async function stop(opts, { quiet = false } = {}) {
   const ctx = context(opts)
+  const brew = brewService()
+  const redirect = brewRedirect('stop', brew)
+  if (redirect) {
+    if (quiet) return false
+    throw new CliError(redirect)
+  }
   const svc = serviceState()
   if (svc.installed && svc.running) {
     controlService('stop')
@@ -213,6 +227,8 @@ export async function stop(opts, { quiet = false } = {}) {
 }
 
 export async function restart(opts) {
+  const redirect = brewRedirect('restart', brewService())
+  if (redirect) throw new CliError(redirect)
   const svc = serviceState()
   if (svc.installed) {
     const ctx = context(opts)
@@ -231,20 +247,22 @@ export async function status(opts) {
   const answer = await probe(ctx.port, ctx.host)
   const pid = livePid(ctx.files.pid)
   const svc = serviceState()
+  const brew = brewService()
+  const hb = brew && brewStatusRows(brew)
   say(`${c.bold('wherdr')} ${VERSION}`)
   row('Address', answer === 'wherdr' ? `${c.green('●')} ${c.cyan(ctx.url)} answers` : answer ? `${c.yellow('●')} port ${ctx.port} is taken by another program` : `${c.dim('○')} port ${ctx.port} free: not running`)
-  row('Process', svc.running ? 'login service' : pid ? `pid ${pid} (wherdr start)` : answer === 'wherdr' ? 'started another way (Docker, plugin, a terminal…)' : 'none')
-  row('Service', svc.installed ? `installed (${serviceFile()})${svc.running ? '' : ', not running'}` : 'not installed · wherdr service install')
+  row('Process', hb?.process ? hb.process : svc.running ? 'login service' : pid ? `pid ${pid} (wherdr start)` : answer === 'wherdr' ? 'started another way (Docker, plugin, a terminal…)' : 'none')
+  row('Service', hb ? hb.service : svc.installed ? `installed (${serviceFile()})${svc.running ? '' : ', not running'}` : 'not installed · wherdr service install')
   row('Data', ctx.env.DATA_DIR)
-  row('Log', ctx.files.log)
+  row('Log', hb ? hb.log : ctx.files.log)
   if (ctx.env.HERDR_WEB_SESSION) row('Session', ctx.env.HERDR_WEB_SESSION)
-  if (!answer) say(c.dim('\n  Start it: wherdr start (background) or wherdr (foreground).'))
+  if (!answer) say(c.dim(hb ? hb.hint : '\n  Start it: wherdr start (background) or wherdr (foreground).'))
 }
 
 // ------------------------------------------------------------------ logs
 export async function logs(opts) {
   const ctx = context(opts)
-  const log = ctx.files.log
+  const log = brewService()?.log ?? ctx.files.log
   if (!existsSync(log)) { say(`No log yet (${log}).`); if (!opts.follow) return }
   const text = tailText(log, Number(opts.lines ?? 50))
   if (text) say(text)
@@ -271,16 +289,39 @@ export function openUrl(url) {
   return r.status === 0
 }
 
+// Does the published address answer? 'host' means wherdr answers but does not
+// know that name yet (`tailscale serve` run a moment ago): a local request to
+// /api/phone makes it read Tailscale again and adopt the address
+// (server/utils/phone.ts), then it is asked again. `reach` / `allow` are
+// injectable for the tests.
+export async function phoneReach(localUrl, phoneUrl, { reach = reachable, allow = url => fetch(`${url}/api/phone`).catch(() => {}), timeoutMs = 8000 } = {}) {
+  let r = await reach(phoneUrl, timeoutMs)
+  if (r === 'host') { await allow(localUrl); r = await reach(phoneUrl, timeoutMs) }
+  return r
+}
+
+// The address to open: the tailnet one when wherdr is already published there
+// and it answers (passkeys are tied to the address they were created on),
+// else the local one.
+export async function openAddress(localUrl, port, { net = inspect, ...probes } = {}) {
+  const phone = (await net(port)).phone
+  if (!phone?.served) return localUrl
+  return await phoneReach(localUrl, phone.url, { timeoutMs: 5000, ...probes }) === 'ok' ? phone.url.replace(/\/$/, '') : localUrl
+}
+
 export async function open(opts) {
   const ctx = context(opts)
   if (await probe(ctx.port, ctx.host) !== 'wherdr') warn(`wherdr does not answer on port ${ctx.port}: run \`wherdr start\` first.`)
-  if (openUrl(ctx.url)) ok(`opened ${c.cyan(ctx.url)}`)
-  else say(ctx.url)
+  const url = await openAddress(ctx.url, ctx.port)
+  if (openUrl(url)) ok(`opened ${c.cyan(url)}`)
+  else say(url)
 }
 
 // ----------------------------------------------------------------- phone
 // The phone setup lives in the app (Settings › Phone: publish on the tailnet,
-// live check, APP_URL, QR code). Here: the real state, the link to that page,
+// live check, APP_URL, QR code). Here: the real state, the command that
+// publishes wherdr when it is not (a server without a screen has no browser
+// for that page; wherdr adopts the address by itself), the link to the page,
 // and the QR code only when the address answers.
 export const phoneSetupUrl = url => `${url}/#/settings?section=phone`
 
@@ -293,6 +334,13 @@ async function qr(text) {
   } catch { return null }
 }
 
+// Why a published address is not usable yet, for `wherdr phone`.
+export function phoneRefusal(reach, phone, running) {
+  if (reach !== 'host') return running ? 'does not answer yet (the HTTPS certificate can take a minute)' : 'wherdr is not running'
+  if (phone.funnel) return 'also open to the Internet by `tailscale funnel`, which wherdr never enables: turn the funnel off'
+  return 'wherdr refuses it: it could not read `tailscale serve status` itself (is `tailscale` on the PATH of the wherdr server?)'
+}
+
 export async function phone(opts) {
   const ctx = context(opts)
   const setup = phoneSetupUrl(ctx.url)
@@ -305,17 +353,21 @@ export async function phone(opts) {
   let reach = null
   if (!net.installed) warn(`Tailscale is not installed: ${c.cyan(LINKS.download)}`)
   else if (!net.connected || !net.phone) warn('Tailscale is not connected on this machine.')
-  else if (!net.phone.served) warn(`${c.bold('Not reachable from your phone yet')}: wherdr is not published on your tailnet.`)
-  else {
-    reach = await reachable(net.phone.url)
+  else if (!net.phone.served) {
+    warn(`${c.bold('Not reachable from your phone yet')}: wherdr is not published on your tailnet.`)
+    say(`    Publish it (private, only your Tailscale devices): ${c.cyan(publishCommand(ctx.port))}`)
+    say('    wherdr enables that address by itself; run `wherdr phone` again for its QR code.')
+  } else {
+    reach = await phoneReach(ctx.url, net.phone.url)
     if (reach === 'ok') ok(`${c.cyan(net.phone.url)} answers`)
-    else warn(`${c.bold('Not reachable from your phone yet')}: ${net.phone.url} is published but ${reach === 'host' ? 'refused (APP_URL)' : 'does not answer'}.`)
+    else warn(`${c.bold('Not reachable from your phone yet')}: ${net.phone.url} is published but ${phoneRefusal(reach, net.phone, local === 'wherdr')}.`)
   }
   if (reach === 'ok') {
     const code = await qr(net.phone.url)
     if (code) { say(); say(code.split('\n').map(l => `  ${l}`).join('\n')) }
     say(`  ${code ? 'Scan it with the iPhone camera' : `Open ${c.cyan(net.phone.url)} on the iPhone`}, then Share → Add to Home Screen.`)
     say('  In the app: Settings → Enable notifications, then Security → Enable passkey lock.')
+    say(`  Enable the lock on ${c.cyan(net.phone.url)}, not on localhost: a passkey is tied to its address.`)
   }
   say()
   say(`  Set up your phone in the app, on this computer: ${c.cyan(setup)}`)
@@ -342,6 +394,8 @@ export async function service(opts) {
     npm install -g wherdr      (or: bun add -g wherdr, pnpm add -g wherdr)
     wherdr service install`)
   }
+  // A LaunchAgent pointing into Cellar/wherdr/<version> would break at the next `brew upgrade`.
+  if (homebrewInstall(bin)) throw new CliError(brewRedirect('service', {}))
   const runtime = findRuntime(ctx.env)
   if (!runtime) throw new CliError(RUNTIME_HELP)
   // The background server of `wherdr start` would hold the port.
@@ -409,10 +463,14 @@ export async function doctor(opts) {
   const taken = answer ? null : await portTaken(ctx.port, ctx.host)
   if (answer === 'wherdr') ok(`Port ${ctx.port}: wherdr answers (${ctx.url})`)
   else if (answer || taken) fail(`Port ${ctx.port}: ${taken?.error || 'taken by another program'}. Use --port.`)
-  else warn(`Port ${ctx.port}: free, wherdr is not running (wherdr start).`)
+  else warn(`Port ${ctx.port}: free, wherdr is not running (${homebrewInstall(BIN) ? 'brew services start wherdr' : 'wherdr start'}).`)
 
   const svc = serviceState()
-  if (!servicePlatform()) warn(`Login service: not available on ${process.platform}.`)
+  const brew = brewService()
+  if (brew) {
+    const [level, text] = brewDoctor(brew)
+    ;({ ok, warn, fail })[level](text)
+  } else if (!servicePlatform()) warn(`Login service: not available on ${process.platform}.`)
   else if (!svc.installed) warn('Login service: not installed (wherdr service install starts wherdr at login).')
   else if (svc.running) ok(`Login service: running (${serviceFile()})`)
   else fail(`Login service: installed but not running (${serviceFile()}). See wherdr logs.`)

package/bin/lib/core.mjs

@@ -12,6 +12,23 @@ export const BIN = path.join(ROOT, 'bin', 'wherdr.mjs')
 export const VERSION = JSON.parse(readFileSync(path.join(ROOT, 'package.json'), 'utf8')).version
 export const DEFAULT_PORT = '7683'
 
+// Installed by the Homebrew formula: the package lives in <prefix>/Cellar/wherdr/<version>/libexec.
+export function homebrewInstall(file) {
+  return /[\\/]Cellar[\\/]wherdr[\\/]/.test(file)
+}
+
+// How this copy of wherdr was installed (shared/updates.ts InstallMode), from
+// the path of its bin/wherdr.mjs: the Homebrew Cellar; the copy the Herdr
+// plugin keeps in <wherdr dir>/app; `npm i -g` (<prefix>/lib/node_modules/wherdr,
+// never a temporary npx folder); otherwise a temporary package (npx, bunx, pnpm dlx).
+export function installKind(bin, dir) {
+  if (homebrewInstall(bin)) return 'brew'
+  const root = path.resolve(bin, '..', '..')
+  if (root === path.join(dir, 'app')) return 'plugin'
+  if (/[\\/]lib[\\/]node_modules[\\/]wherdr$/.test(root) && !/[\\/]_npx[\\/]/.test(root)) return 'npm-global'
+  return 'npm'
+}
+
 export const COMMANDS = ['run', 'start', 'stop', 'restart', 'status', 'logs', 'open', 'phone', 'panel', 'service', 'doctor', 'help', 'version']
 const VALUE_OPTIONS = { '--port': 'port', '--host': 'host', '--data-dir': 'dataDir', '--session': 'session', '--lines': 'lines', '-n': 'lines' }
 const FLAGS = { '-h': 'help', '--help': 'help', '-v': 'version', '--version': 'version', '-f': 'follow', '--follow': 'follow' }
@@ -83,7 +100,7 @@ export function withSettings(env, dir) {
 }
 
 // Environment of the server: options win over the environment, which wins over the defaults.
-export function serverEnv(opts, env, home = os.homedir()) {
+export function serverEnv(opts, env, home = os.homedir(), bin = BIN) {
   const out = { ...env }
   const dir = wherdrDir(env, home)
   out.PORT = opts.port ?? env.PORT ?? DEFAULT_PORT
@@ -93,8 +110,11 @@ export function serverEnv(opts, env, home = os.homedir()) {
   out.NODE_ENV = 'production'
   // Open WebSockets do not hold Ctrl+C for 30 s; clients reconnect on their own.
   out.NITRO_SHUTDOWN_TIMEOUT ??= '1500'
-  // Update command offered in the app (shared/updates.ts).
-  out.WHERDR_INSTALL = 'npm'
+  // Update command, or one-tap update, offered in the app (shared/updates.ts):
+  // the package to replace and the folder of its state and log (server/utils/selfupdate.ts).
+  out.WHERDR_INSTALL = installKind(bin, dir)
+  out.WHERDR_ROOT = path.resolve(bin, '..', '..')
+  out.WHERDR_DIR = dir
   // Nitro reads NITRO_PORT / NITRO_HOST before PORT / HOST.
   delete out.NITRO_PORT
   delete out.NITRO_HOST

package/bin/lib/tailnet.d.mts

@@ -1,13 +1,18 @@
 // Types of tailnet.mjs, for the server (server/utils/phone.ts).
-export interface PhoneAddress { url: string, served: boolean, httpsPort: string }
+// funnel: also published on the Internet by `tailscale funnel` (never adopted).
+export interface PhoneAddress { url: string, served: boolean, httpsPort: string, funnel?: boolean }
 export interface Tailnet {
   installed: boolean
-  bin?: string
+  bin?: string | null
+  // Tailscale's socket, when the state was read there (no CLI: Docker).
+  socket?: string | null
   name?: string | null
   connected?: boolean
   https?: boolean
   phone?: PhoneAddress | null
   taken?: boolean
+  // Addresses published for wherdr's port; null when they could not be read.
+  served?: string[] | null
 }
 export type Reach = 'ok' | 'host' | 'other' | 'unreachable'
 export type ReachCause = 'dns' | 'refused' | 'timeout' | 'cert' | 'tls' | 'network'
@@ -15,18 +20,22 @@ export interface Probe { reach: Reach, cause?: ReachCause, status?: number }
 export type ServeErrorCode = 'operator' | 'https' | 'offline'
 
 export const LINKS: { download: string, https: string, operator: string }
+export const TAILSCALED_SOCKET: string
+export function tailscaledSocket(env?: Record<string, string | undefined>, exists?: (p: string) => boolean): string | null
 export function tailscaleBin(env?: Record<string, string | undefined>, exists?: (p: string) => boolean): string | null
 export function tailnetStatus(statusJson: string): { name: string | null, connected: boolean, https: boolean }
 export function phoneAddress(name: string | null, port: string | number, serveJson: string): PhoneAddress | null
+export function servedAddresses(name: string | null, port: string | number, serveJson: string): string[] | null
 export function servedPorts(serveJson: string): string[]
 export function publishCommand(port: string | number, httpsPort?: string | number): string
 export function publishArgs(port: string | number): string[]
 export function unpublishArgs(httpsPort: string): string[]
 export function tailnetUrl(text: unknown): string | null
 export function serveError(output: string): { code: ServeErrorCode, link: string } | null
-export function inspect(port: string | number, bin?: string | null): Promise<Tailnet>
+export function inspect(port: string | number, bin?: string | null, socket?: string | null): Promise<Tailnet>
 export function tailnetDomain(resolvConf: string): string | null
 export function reachable(url: string, timeoutMs?: number): Promise<Reach>
+export function healthReach(status: number, text: string): 'ok' | 'host' | null
 export function probe(url: string, timeoutMs?: number): Promise<Probe>
 export function failureCause(err: unknown): ReachCause
 export function runTailscale(bin: string, args: string[], timeoutMs?: number): Promise<{ code: number, output: string }>

package/bin/lib/tailnet.mjs

@@ -7,6 +7,7 @@
 import { execFile } from 'node:child_process'
 import dns from 'node:dns'
 import { existsSync } from 'node:fs'
+import http from 'node:http'
 import https from 'node:https'
 import path from 'node:path'
 import { promisify } from 'node:util'
@@ -26,6 +27,32 @@ export function tailscaleBin(env = process.env, exists = existsSync) {
   return dirs.find(p => exists(p)) || null
 }
 
+// Tailscale's own socket on Linux. Its local API answers the same JSON as the
+// CLI: a Docker container has no `tailscale` command, but docker-compose.yml
+// mounts this folder, so wherdr reads the state there. Anyone may read; the
+// API also accepts changes from Tailscale's operator, but wherdr only ever
+// sends GET requests to it (localApi below).
+export const TAILSCALED_SOCKET = '/var/run/tailscale/tailscaled.sock'
+export function tailscaledSocket(env = process.env, exists = existsSync) {
+  const file = env.WHERDR_TAILSCALED_SOCKET || TAILSCALED_SOCKET
+  return exists(file) ? file : null
+}
+
+// GET on Tailscale's local API → the body, '' on any failure.
+function localApi(socketPath, route, timeoutMs = 4000) {
+  const { promise, resolve } = Promise.withResolvers()
+  const req = http.get({ socketPath, path: `/localapi/v0/${route}`, headers: { host: 'local-tailscaled.sock' }, timeout: timeoutMs }, (res) => {
+    let text = ''
+    res.setEncoding('utf8')
+    res.on('data', (c) => { if (text.length < 1 << 20) text += c })
+    res.on('end', () => resolve(res.statusCode === 200 ? text : ''))
+    res.on('error', () => resolve(''))
+  })
+  req.on('timeout', () => req.destroy())
+  req.on('error', () => resolve(''))
+  return promise
+}
+
 // `tailscale status --json` → { name, connected, https }: this machine's
 // tailnet name (machine.tailnet.ts.net) or null, whether Tailscale is up,
 // and whether the tailnet issues HTTPS certificates.
@@ -40,22 +67,51 @@ export function tailnetStatus(statusJson) {
   }
 }
 
+// The HTTPS entries of a serve configuration that proxy to wherdr's local
+// port on this machine's own name: [{ hostPort, httpsPort, funnel }], or null
+// when the configuration could not be read (Tailscale stopped, not JSON).
+// Background entries (`--bg`) and those of a `tailscale serve` still running
+// in a terminal (Foreground) both count. `funnel`: also open to the Internet.
+function wherdrEntries(name, port, serveJson) {
+  let config = null
+  try { config = JSON.parse(serveJson) } catch {}
+  if (!name || !config || typeof config !== 'object' || Array.isArray(config)) return null
+  const target = new RegExp(`^(https?://)?(127\\.0\\.0\\.1|localhost):${port}/?$`)
+  const out = []
+  for (const part of [config, ...Object.values(config.Foreground || {})]) {
+    for (const [hostPort, entry] of Object.entries(part?.Web || {})) {
+      const colon = hostPort.lastIndexOf(':')
+      if (hostPort.slice(0, colon).toLowerCase() !== name.toLowerCase()) continue
+      if (!Object.values(entry?.Handlers || {}).some(h => target.test(h?.Proxy || ''))) continue
+      out.push({ hostPort, httpsPort: hostPort.slice(colon + 1), funnel: Boolean(part.AllowFunnel?.[hostPort]) })
+    }
+  }
+  return out
+}
+
+const addressOf = (name, httpsPort) => `https://${name}${httpsPort === '443' ? '' : `:${httpsPort}`}/`
+
 // Phone address: the `tailscale serve` entry whose proxy targets wherdr's
 // local port (served on any HTTPS port), else the address publishing would
 // give (same port) with served: false. Null without a tailnet name.
 export function phoneAddress(name, port, serveJson) {
   if (!name) return null
-  let web = {}
-  try { web = JSON.parse(serveJson || '{}')?.Web || {} } catch {}
-  const target = new RegExp(`^(https?://)?(127\\.0\\.0\\.1|localhost):${port}/?$`)
-  for (const [hostPort, entry] of Object.entries(web)) {
-    if (!Object.values(entry?.Handlers || {}).some(h => target.test(h?.Proxy || ''))) continue
-    const servedPort = hostPort.slice(hostPort.lastIndexOf(':') + 1)
-    return { url: `https://${name}${servedPort === '443' ? '' : `:${servedPort}`}/`, served: true, httpsPort: servedPort }
-  }
+  const entries = wherdrEntries(name, port, serveJson) || []
+  const hit = entries.find(e => !e.funnel) || entries[0]
+  if (hit) return { url: addressOf(name, hit.httpsPort), served: true, httpsPort: hit.httpsPort, ...(hit.funnel ? { funnel: true } : {}) }
   return { url: `https://${name}:${port}/`, served: false, httpsPort: String(port) }
 }
 
+// The addresses wherdr adopts by itself (server/utils/phone.ts): what
+// `tailscale serve` publishes for its port on this machine's name, read from
+// Tailscale, which only the owner of the machine configures. null: unknown
+// (nothing is changed then); []: nothing is published. An address that
+// `tailscale funnel` also opens to the Internet is never adopted.
+export function servedAddresses(name, port, serveJson) {
+  const entries = wherdrEntries(name, port, serveJson)
+  return entries && entries.filter(e => !e.funnel).map(e => addressOf(name, e.httpsPort))
+}
+
 // HTTPS ports already published by `tailscale serve` (for anything).
 export function servedPorts(serveJson) {
   try {
@@ -92,16 +148,18 @@ export function serveError(output) {
   return null
 }
 
-// Tailscale's state for wherdr's port: { installed, bin, connected, https, name, phone, taken }.
-export async function inspect(port, bin = tailscaleBin()) {
-  if (!bin) return { installed: false }
+// Tailscale's state for wherdr's port: { installed, bin, socket, connected,
+// https, name, phone, taken, served }. Read with the CLI, or without one
+// (Docker) from Tailscale's socket.
+export async function inspect(port, bin = tailscaleBin(), socket = bin ? null : tailscaledSocket()) {
+  if (!bin && !socket) return { installed: false }
   const run = args => exec(bin, args, { encoding: 'utf8', timeout: 8000 }).then(r => r.stdout, () => '')
-  const status = tailnetStatus(await run(['status', '--json']))
-  const serve = status.name ? await run(['serve', 'status', '--json']) : ''
+  const status = tailnetStatus(bin ? await run(['status', '--json']) : await localApi(socket, 'status?peers=false'))
+  const serve = !status.name ? '' : bin ? await run(['serve', 'status', '--json']) : await localApi(socket, 'serve-config')
   const phone = phoneAddress(status.name, port, serve)
   // Publishing on wherdr's port would replace whatever else is served there.
   const taken = Boolean(phone && !phone.served && servedPorts(serve).includes(String(port)))
-  return { installed: true, bin, ...status, phone, taken }
+  return { installed: true, bin, socket, ...status, phone, taken, served: servedAddresses(status.name, port, serve) }
 }
 
 // The tailnet's DNS suffix (tailnet.ts.net) from /etc/resolv.conf's search
@@ -152,29 +210,49 @@ export function failureCause(err) {
   return 'network'
 }
 
-// reachable() with the details: { reach, cause?, status? }: `cause` when
-// unreachable (failureCause), `status` the HTTP code when something answered.
-export function probe(url, timeoutMs = 8000) {
+// GET of `route` on the address → { status, text }, or { cause } when it failed.
+function fetchText(url, route, timeoutMs) {
   const { promise, resolve } = Promise.withResolvers()
   let u
-  try { u = new URL('manifest.webmanifest', url) } catch { return Promise.resolve({ reach: 'unreachable', cause: 'network' }) }
+  try { u = new URL(route, url) } catch { return Promise.resolve({ cause: 'network' }) }
   // Accept JSON: a refused host then answers { code: 'host' }, not the HTML page.
   const req = https.get(u, { lookup, timeout: timeoutMs, headers: { accept: 'application/json' } }, (res) => {
     let text = ''
     res.setEncoding('utf8')
     res.on('data', (c) => { if (text.length < 65536) text += c })
-    res.on('end', () => {
-      const status = res.statusCode || 0
-      if (status >= 200 && status < 300) resolve({ reach: text.includes('wherdr') ? 'ok' : 'other', status })
-      else resolve({ reach: status === 403 && /"code"\s*:\s*"host"/.test(text) ? 'host' : 'other', status })
-    })
-    res.on('error', e => resolve({ reach: 'unreachable', cause: failureCause(e) }))
+    res.on('end', () => resolve({ status: res.statusCode || 0, text }))
+    res.on('error', e => resolve({ cause: failureCause(e) }))
   })
   req.on('timeout', () => req.destroy(new Error('timeout')))
-  req.on('error', e => resolve({ reach: 'unreachable', cause: failureCause(e) }))
+  req.on('error', e => resolve({ cause: failureCause(e) }))
   return promise
 }
 
+// What an answer of /api/health means: 'ok' (wherdr, and it accepts this
+// address), 'host' (wherdr's host check refused it), or null: not a wherdr
+// that has this route (versions up to 1.3.1, or another program).
+export function healthReach(status, text) {
+  if (status >= 200 && status < 300 && /"name"\s*:\s*"wherdr"/.test(text)) return 'ok'
+  if (status === 403 && /"code"\s*:\s*"host"/.test(text)) return 'host'
+  return null
+}
+
+// reachable() with the details: { reach, cause?, status? }: `cause` when
+// unreachable (failureCause), `status` the HTTP code when something answered.
+// /api/health is asked first: it goes through wherdr's host check, which the
+// static manifest does not (it answers for any host name). The manifest only
+// recognizes an older wherdr without that route.
+export async function probe(url, timeoutMs = 8000) {
+  const health = await fetchText(url, 'api/health', timeoutMs)
+  if (health.cause) return { reach: 'unreachable', cause: health.cause }
+  const reach = healthReach(health.status, health.text)
+  if (reach) return { reach, status: health.status }
+  const manifest = await fetchText(url, 'manifest.webmanifest', timeoutMs)
+  if (manifest.cause) return { reach: 'unreachable', cause: manifest.cause }
+  const ok = manifest.status >= 200 && manifest.status < 300 && manifest.text.includes('wherdr')
+  return { reach: ok ? 'ok' : 'other', status: ok ? manifest.status : health.status }
+}
+
 // Runs `tailscale <args>` without a terminal → { code, output }. On a tailnet
 // without HTTPS, `tailscale serve` prints a link and waits: the timeout ends it.
 export function runTailscale(bin, args, timeoutMs = 30_000) {