@threadcrumbs/threadgauge 0.0.0-stage → 0.1.0

package/dist/favicon.svg

@@ -0,0 +1,17 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="-53 -53 106 106">
+  <defs>
+    <linearGradient id="fav-shell" x1="0" y1="-50" x2="0" y2="50" gradientUnits="userSpaceOnUse"><stop offset="0" stop-color="#ffffff"/><stop offset="1" stop-color="#d9dfe8"/></linearGradient>
+    <radialGradient id="fav-face" cx="-9.7" cy="-17.3" r="55" gradientUnits="userSpaceOnUse"><stop offset="0" stop-color="#2f4466"/><stop offset="0.6" stop-color="#141e33"/><stop offset="1" stop-color="#0b1120"/></radialGradient>
+    <linearGradient id="fav-arc" x1="0" y1="-50" x2="0" y2="50" gradientUnits="userSpaceOnUse"><stop offset="0" stop-color="#d27d60"/><stop offset="1" stop-color="#b1583a"/></linearGradient>
+    <filter id="fav-glow" x="-1" y="-1" width="3" height="3"><feGaussianBlur stdDeviation="3.2"/></filter>
+  </defs>
+  <circle r="50" fill="url(#fav-shell)" stroke="#121319" stroke-width="3" paint-order="stroke"/>
+  <circle r="44.5" fill="#c3cbd8" stroke="#121319" stroke-width="2.4"/>
+  <circle r="42.5" fill="url(#fav-face)"/>
+  <path d="M-34.3,-12.48 A36.5,36.5 0 0 1 -15.43,-33.08" fill="none" stroke="#fff" stroke-opacity="0.28" stroke-width="4.4" stroke-linecap="round"/>
+  <path d="M-21.21,21.21 A30,30 0 1 1 21.21,21.21" fill="none" stroke="#2f4466" stroke-width="8" stroke-linecap="round"/>
+  <path d="M-21.21,21.21 A30,30 0 0 1 21.21,-21.21" fill="none" stroke="url(#fav-arc)" stroke-width="8" stroke-linecap="round"/>
+  <path d="M0,0 L16.26,-16.26" stroke="#7fcfff" stroke-width="5.5" stroke-linecap="round" filter="url(#fav-glow)" opacity="0.9"/>
+  <path d="M0,0 L16.26,-16.26" stroke="#eef8ff" stroke-width="5.5" stroke-linecap="round"/>
+  <circle r="7" fill="#e8ecf2" stroke="#121319" stroke-width="2.4" paint-order="stroke"/>
+</svg>

package/dist/index.html

@@ -0,0 +1,16 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
+    <meta name="color-scheme" content="dark" />
+    <meta name="theme-color" content="#0a0b0f" />
+    <title>Threadgauge</title>
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg?app=threadgauge" />
+    <script type="module" crossorigin src="/assets/index-DGQBjXpa.js"></script>
+    <link rel="modulepreload" crossorigin href="/assets/preload-helper-BXl3LOEh.js">
+  </head>
+  <body>
+    <div id="app"></div>
+  </body>
+</html>

package/package.json

@@ -1,6 +1,75 @@
-{
-  "name": "@threadcrumbs/threadgauge",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "@threadcrumbs/threadgauge",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "A live dashboard of every coding agent working on your machine: what it is doing, how full its context is, and what it has cost.",
+  "license": "SEE LICENSE IN LICENSE.md",
+  "author": "Threadcrumbs LLC",
+  "homepage": "https://threadgauge.io",
+  "bugs": {
+    "url": "https://threadgauge.io/#contact",
+    "email": "hello@threadcrumbs.io"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "claude-code",
+    "coding-agent",
+    "telemetry",
+    "dashboard",
+    "developer-tools"
+  ],
+  "engines": {
+    "node": ">=22.13"
+  },
+  "packageManager": "pnpm@11.9.0",
+  "bin": {
+    "threadgauge": "bin/threadgauge.mjs"
+  },
+  "files": [
+    "bin/",
+    "dist/",
+    "NOTICES.md",
+    "server/",
+    "src/tiers.js"
+  ],
+  "os": [
+    "darwin",
+    "win32",
+    "linux"
+  ],
+  "scripts": {
+    "dev": "vite",
+    "dev:demo": "vite --mode demo",
+    "build": "vite build",
+    "start": "vite build && node server/serve.mjs",
+    "serve": "node server/serve.mjs",
+    "test": "node --test \"test/**/*.test.mjs\"",
+    "check:layout": "node tools/layout-audit.mjs",
+    "prepack": "pnpm run build",
+    "auto-publish": "node ../common/tools/release.mjs"
+  },
+  "dependencies": {
+    "@threadcrumbs/common": "^0.1.5"
+  },
+  "devDependencies": {
+    "@fontsource-variable/atkinson-hyperlegible-mono": "^5.3.0",
+    "@fontsource-variable/atkinson-hyperlegible-next": "^5.3.0",
+    "@fontsource-variable/fira-code": "^5.3.0",
+    "@fontsource-variable/inconsolata": "^5.3.0",
+    "@fontsource-variable/inter": "^5.3.0",
+    "@fontsource-variable/inter-tight": "^5.3.0",
+    "@fontsource-variable/jetbrains-mono": "^5.3.0",
+    "@fontsource-variable/source-code-pro": "^5.3.1",
+    "@fontsource-variable/source-sans-3": "^5.3.1",
+    "@fontsource/barlow": "^5.3.0",
+    "@fontsource/barlow-semi-condensed": "^5.3.0",
+    "@fontsource/fira-sans": "^5.3.0",
+    "@fontsource/fira-sans-condensed": "^5.3.0",
+    "@fontsource/ibm-plex-mono": "^5.3.0",
+    "@fontsource/ibm-plex-sans": "^5.3.0",
+    "@fontsource/ibm-plex-sans-condensed": "^5.3.0",
+    "vite": "^7.3.7"
+  }
+}

package/server/api.mjs

@@ -0,0 +1,188 @@
+import fsp from 'node:fs/promises'
+import { createDetails } from './details.mjs'
+import { createHistory } from './history.mjs'
+import { createMonitor } from './monitor.mjs'
+import { createOpener } from './open.mjs'
+import { createPathOpener } from './paths.mjs'
+import { createThreadCache } from './threads.mjs'
+import { findThreadnauts as probeThreadnauts } from './threadnauts.mjs'
+import { isLocalRequest } from './lib/local-request.mjs'
+import { createLicensing } from './license.mjs'
+
+const { version } = JSON.parse(await fsp.readFile(new URL('../package.json', import.meta.url), 'utf8'))
+const KEEPALIVE_MS = 20000
+const BODY_LIMIT = 16 * 1024
+
+function readJson(req) {
+  return new Promise((resolve, reject) => {
+    let body = ''
+    req.setEncoding('utf8')
+    req.on('data', (chunk) => {
+      body += chunk
+      if (body.length > BODY_LIMIT) {
+        reject(new Error('Request body too large'))
+        req.destroy()
+      }
+    })
+    req.on('end', () => {
+      try {
+        resolve(body ? JSON.parse(body) : {})
+      } catch {
+        reject(new Error('Request body is not JSON'))
+      }
+    })
+    req.on('error', reject)
+  })
+}
+
+function refusePost(req) {
+  if (req.method !== 'POST') return [405, { error: 'Method not allowed' }]
+  if (!/^application\/json\s*(;|$)/i.test(req.headers['content-type'] || '')) return [415, { error: 'Threadgauge only takes JSON' }]
+  return null
+}
+
+function send(res, status, body) {
+  const payload = JSON.stringify(body)
+  res.writeHead(status, {
+    'Content-Type': 'application/json',
+    'Cache-Control': 'no-store',
+    'Content-Length': Buffer.byteLength(payload),
+    'X-Content-Type-Options': 'nosniff',
+  })
+  res.end(payload)
+}
+
+function stream(req, res, monitor) {
+  res.writeHead(200, {
+    'Content-Type': 'text/event-stream; charset=utf-8',
+    'Cache-Control': 'no-store',
+    Connection: 'keep-alive',
+    'X-Content-Type-Options': 'nosniff',
+  })
+  const emit = (event, data) => res.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`)
+  res.write('retry: 2000\n\n')
+  emit('snapshot', monitor.snapshot())
+  const unsubscribe = monitor.subscribe((update) => emit('update', update))
+  const keepalive = setInterval(() => res.write(': keepalive\n\n'), KEEPALIVE_MS)
+  req.on('close', () => {
+    clearInterval(keepalive)
+    unsubscribe()
+  })
+}
+
+const SESSION_PATH = /^\/api\/sessions\/([^/]+)(?:\/subagents\/([^/]+)|\/(hunks))?$/
+
+export function apiMiddleware(
+  getMonitor,
+  {
+    threadsOf = createThreadCache({ ttl: 60_000 }),
+    open = createOpener({ threadsOf }),
+    openPath = createPathOpener(),
+    licensing = createLicensing(),
+    findThreadnauts = probeThreadnauts,
+    details = createDetails({ getMonitor, resume: open.resume }),
+    history = createHistory({ threads: threadsOf }),
+  } = {},
+) {
+  return async function middleware(req, res, next) {
+    const url = new URL(req.url, 'http://localhost')
+    if (!url.pathname.startsWith('/api/')) return next ? next() : send(res, 404, { error: 'Not found' })
+
+    if (!isLocalRequest(req)) {
+      return send(res, 403, { error: 'Threadgauge only answers its own page on this machine' })
+    }
+
+    try {
+      if (url.pathname === '/api/open') {
+        const refused = refusePost(req)
+        if (refused) return send(res, ...refused)
+        const body = await readJson(req)
+        const listed = (await getMonitor()).snapshot().sessions.find((s) => s.id === body.id)
+        const session = listed || (typeof body.id === 'string' ? await history.find(body.id) : null)
+        if (!session) return send(res, 404, { ok: false, error: "Threadgauge can't find that thread anymore" })
+        const shown = await open(session, body.via === 'terminal' ? 'terminal' : 'app')
+        return send(res, shown.ok ? 200 : 400, shown)
+      }
+
+      if (url.pathname === '/api/open-path') {
+        const refused = refusePost(req)
+        if (refused) return send(res, ...refused)
+        const body = await readJson(req)
+        const agent = typeof body.agent === 'string' && body.agent ? { subagent: body.agent } : {}
+        const found = typeof body.id === 'string' ? await (await getMonitor()).detail(body.id, agent) : null
+        if (!found) return send(res, 404, { ok: false, error: "Threadgauge can't find that thread anymore" })
+        const { status = 200, ...result } = await openPath({ session: found.session, detail: found.detail, path: body.path, line: body.line, editor: body.editor })
+        return send(res, status, result)
+      }
+
+      if (url.pathname === '/api/license') {
+        const refused = refusePost(req)
+        if (refused) return send(res, ...refused)
+        const body = await readJson(req)
+        const result = await licensing.activate(body.key)
+        return send(res, result.ok ? 200 : 400, result)
+      }
+
+      if (req.method !== 'GET') return send(res, 405, { error: 'Method not allowed' })
+
+      if (url.pathname === '/api/about') {
+        return send(res, 200, { app: 'threadgauge', version })
+      }
+
+      if (url.pathname === '/api/entitlements') {
+        return send(res, 200, await licensing.entitlements())
+      }
+
+      if (url.pathname === '/api/sessions') {
+        return send(res, 200, (await getMonitor()).snapshot())
+      }
+
+      if (url.pathname === '/api/history') {
+        const shown = new Set((await getMonitor()).snapshot().sessions.map((s) => s.id))
+        return send(res, 200, { sessions: await history.list(shown) })
+      }
+
+      if (url.pathname === '/api/stream') {
+        return stream(req, res, await getMonitor())
+      }
+
+      if (url.pathname === '/api/threadnauts') {
+        return send(res, 200, { url: await findThreadnauts() })
+      }
+
+      const one = SESSION_PATH.exec(url.pathname)
+      if (one) {
+        let id
+        let agent
+        try {
+          id = decodeURIComponent(one[1])
+          agent = one[2] ? decodeURIComponent(one[2]) : null
+        } catch {
+          return send(res, 400, { error: 'Bad session id' })
+        }
+        if (one[3]) {
+          const found = await details.hunks(id, url.searchParams.get('path') || '', url.searchParams.get('agent'))
+          return found ? send(res, 200, found) : send(res, 404, { error: 'Unknown file' })
+        }
+        const found = agent ? await details.subagent(id, agent) : await details.panel(id)
+        return found ? send(res, 200, found) : send(res, 404, { error: agent ? 'Unknown subagent' : 'Unknown session' })
+      }
+
+      return send(res, 404, { error: 'Unknown endpoint' })
+    } catch (err) {
+      return send(res, 500, { error: String(err?.message || err) })
+    }
+  }
+}
+
+let sharedMonitor = null
+
+async function defaultMonitor() {
+  sharedMonitor ??= createMonitor()
+  await sharedMonitor.start()
+  return sharedMonitor
+}
+
+export const middleware = apiMiddleware(defaultMonitor)
+
+export const createDevMiddleware = () => apiMiddleware(defaultMonitor, { licensing: createLicensing({ development: true }) })

package/server/details.mjs

@@ -0,0 +1,64 @@
+import path from 'node:path'
+
+const SIBLING_TTL_MS = 5000
+
+export function withoutHunks(detail) {
+  if (!detail?.files) return detail
+  return { ...detail, files: detail.files.map(({ hunks, ...file }) => ({ ...file, diff: hunks == null ? null : hunks.length })) }
+}
+
+const fullPath = (session, file) => path.resolve(session.cwd || session.projectPath || '', file)
+const keyOf = (file, platform) => (platform === 'win32' ? file.toLowerCase() : file)
+
+export function createDetails({ getMonitor, resume = async () => null, now = Date.now, platform = process.platform } = {}) {
+  const siblings = new Map()
+
+  async function siblingFiles(monitor, session) {
+    const hit = siblings.get(session.id)
+    if (hit && hit.lastActivityAt === session.lastActivityAt && now() - hit.at < SIBLING_TTL_MS) return hit.files
+    const found = await monitor.detail(session.id, { filesOnly: true }).catch(() => null)
+    const files = new Set((found?.detail?.files || []).map((f) => keyOf(fullPath(session, f.path), platform)))
+    siblings.set(session.id, { at: now(), lastActivityAt: session.lastActivityAt, files })
+    return files
+  }
+
+  async function overlapsFor(monitor, session, detail) {
+    if (!detail?.files?.length || !(session.cwd || session.projectPath)) return {}
+    const others = monitor.snapshot().sessions.filter((s) => s.id !== session.id && (s.cwd || s.projectPath))
+    const overlaps = {}
+    for (const other of others) {
+      const files = await siblingFiles(monitor, other)
+      for (const file of detail.files) {
+        if (!files.has(keyOf(fullPath(session, file.path), platform))) continue
+        overlaps[file.path] = [...(overlaps[file.path] || []), { id: other.id, title: other.title, status: other.status }]
+      }
+    }
+    return overlaps
+  }
+
+  async function panel(id) {
+    const monitor = await getMonitor()
+    const found = await monitor.detail(id)
+    if (!found) return null
+    const [command, overlaps] = await Promise.all([
+      resume(found.session).catch(() => null),
+      overlapsFor(monitor, found.session, found.detail),
+    ])
+    return { session: found.session, detail: withoutHunks(found.detail), resume: command, overlaps }
+  }
+
+  async function subagent(id, agentId) {
+    const found = await (await getMonitor()).detail(id, { subagent: agentId })
+    if (!found?.detail) return null
+    return { session: found.session, detail: withoutHunks(found.detail) }
+  }
+
+  async function hunks(id, file, agentId = null) {
+    const found = await (await getMonitor()).detail(id, agentId ? { subagent: agentId } : {})
+    const entry = found?.detail?.files?.find((f) => f.path === file)
+    if (!entry) return null
+    return { path: entry.path, line: entry.line ?? null, hunks: entry.hunks ?? null }
+  }
+
+  return { panel, subagent, hunks }
+}

package/server/history.mjs

@@ -0,0 +1,65 @@
+import { HARNESSES } from '@threadcrumbs/common/harnesses'
+import { organizationReader } from '@threadcrumbs/common/orgs'
+import { createThreadCache } from './threads.mjs'
+
+const ERROR_MS = 3 * 24 * 60 * 60 * 1000
+const MAX_OLDER = 300
+
+export function olderStatus(thread, now) {
+  if (thread.needsInput) return 'asking'
+  if (thread.hasError && now - thread.lastActivityAt <= ERROR_MS) return 'error'
+  if (thread.unread) return 'done'
+  return 'idle'
+}
+
+export function olderSession(thread, harness, now) {
+  return {
+    id: thread.id,
+    harness,
+    title: thread.title || 'Untitled session',
+    project: thread.project || 'unknown',
+    projectPath: thread.projectPath || '',
+    worktree: thread.worktree || '',
+    cwd: thread.cwd || '',
+    gitBranch: thread.gitBranch || '',
+    model: thread.model || '',
+    effort: thread.effort || '',
+    status: olderStatus(thread, now),
+    live: false,
+    startedAt: thread.createdAt || 0,
+    lastActivityAt: thread.lastActivityAt || 0,
+    tool: null,
+    tokens: null,
+    context: null,
+    costUsd: null,
+    lines: null,
+    plan: null,
+    subagents: 0,
+    prompts: null,
+    older: true,
+  }
+}
+
+export function createHistory({ now = Date.now, harnesses = HARNESSES, threads = createThreadCache({ ttl: 60_000, now }), organizations = organizationReader() } = {}) {
+  async function olderThreads() {
+    const found = []
+    for (const harness of harnesses) {
+      if (!(await Promise.resolve(harness.detect()).catch(() => false))) continue
+      for (const thread of await threads(harness)) {
+        if (!thread.archived) found.push(olderSession(thread, harness.id, now()))
+      }
+    }
+    return found
+  }
+
+  async function list(shown = new Set()) {
+    const older = (await olderThreads()).filter((s) => !shown.has(s.id)).sort((a, b) => b.lastActivityAt - a.lastActivityAt).slice(0, MAX_OLDER)
+    return organizations(older).catch(() => older)
+  }
+
+  async function find(id) {
+    return (await olderThreads()).find((s) => s.id === id) || null
+  }
+
+  return { list, find }
+}

package/server/http-server.mjs

@@ -0,0 +1,87 @@
+import http from 'node:http'
+import fsp from 'node:fs/promises'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { middleware } from './api.mjs'
+
+const here = path.dirname(fileURLToPath(import.meta.url))
+const DIST = path.join(here, '..', 'dist')
+
+const CSP = [
+  "default-src 'self'",
+  "script-src 'self'",
+  "style-src 'self'",
+  "img-src 'self' data:",
+  "font-src 'self'",
+  "connect-src 'self'",
+  "object-src 'none'",
+  "base-uri 'none'",
+  "form-action 'none'",
+  "frame-ancestors 'none'",
+].join('; ')
+
+export const SECURITY_HEADERS = {
+  'Content-Security-Policy': CSP,
+  'X-Content-Type-Options': 'nosniff',
+  'Referrer-Policy': 'no-referrer',
+  'X-Frame-Options': 'DENY',
+}
+
+const TYPES = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.ico': 'image/x-icon',
+  '.woff2': 'font/woff2',
+}
+
+function resolveInDist(pathname) {
+  const rel = decodeURIComponent(pathname).replace(/^\/+/, '')
+  const file = path.resolve(DIST, rel || 'index.html')
+  return file === DIST || file.startsWith(DIST + path.sep) ? file : null
+}
+
+async function serveRequest(req, res) {
+  const url = new URL(req.url, 'http://localhost')
+
+  if (url.pathname.startsWith('/api/')) {
+    return middleware(req, res, null)
+  }
+
+  let file = resolveInDist(url.pathname)
+  if (!file) {
+    res.writeHead(403, SECURITY_HEADERS).end('Forbidden')
+    return
+  }
+  try {
+    if ((await fsp.stat(file)).isDirectory()) file = path.join(file, 'index.html')
+  } catch {
+    file = path.join(DIST, 'index.html')
+  }
+
+  try {
+    const body = await fsp.readFile(file)
+    const type = TYPES[path.extname(file)] || 'application/octet-stream'
+    const cache = file.includes(`${path.sep}assets${path.sep}`)
+      ? 'public, max-age=31536000, immutable'
+      : 'no-cache'
+    res.writeHead(200, { ...SECURITY_HEADERS, 'Content-Type': type, 'Content-Length': body.length, 'Cache-Control': cache })
+    res.end(body)
+  } catch {
+    res.writeHead(404, { ...SECURITY_HEADERS, 'Content-Type': 'text/plain' }).end('Not found')
+  }
+}
+
+export function startServer({ port, host }) {
+  const server = http.createServer(serveRequest)
+  return new Promise((resolve, reject) => {
+    server.once('error', reject)
+    server.listen(port, host, () => {
+      server.off('error', reject)
+      resolve(server)
+    })
+  })
+}

package/server/lib/local-request.mjs

@@ -0,0 +1,41 @@
+import os from 'node:os'
+
+export const LOCAL_HOSTS = new Set(['localhost', '127.0.0.1', '::1'])
+
+for (const addrs of Object.values(os.networkInterfaces())) {
+  for (const a of addrs || []) {
+    if (a && a.family === 'IPv4' && !a.internal && a.address) LOCAL_HOSTS.add(a.address)
+  }
+}
+
+for (const extra of (process.env.THREADGAUGE_ALLOWED_HOSTS || '').split(',')) {
+  const entry = extra.trim()
+  const host = hostnameOf(entry) || hostnameOf(`[${entry}]`)
+  if (host) LOCAL_HOSTS.add(host)
+}
+
+export function hostnameOf(value) {
+  if (!value) return ''
+  const raw = String(value).includes('://') ? value : `http://${value}`
+  try {
+    return new URL(raw).hostname.replace(/^\[|\]$/g, '')
+  } catch {
+    return ''
+  }
+}
+
+export function isOwnOrigin(origin, host) {
+  try {
+    const page = new URL(origin)
+    return page.protocol === 'http:' && page.host === new URL(`http://${host}`).host
+  } catch {
+    return false
+  }
+}
+
+export function isLocalRequest(req) {
+  if (!LOCAL_HOSTS.has(hostnameOf(req.headers.host))) return false
+  const origin = req.headers.origin
+  if (origin && origin !== 'null') return isOwnOrigin(origin, req.headers.host)
+  return req.method === 'GET' || req.method === 'HEAD'
+}

package/server/lib/open-url.mjs

@@ -0,0 +1,16 @@
+import { spawn } from 'node:child_process'
+
+const OPENERS = {
+  darwin: ['open'],
+  win32: ['rundll32', 'url.dll,FileProtocolHandler'],
+  linux: ['xdg-open'],
+}
+
+export function openUrl(url) {
+  const opener = OPENERS[process.platform]
+  if (!opener) return
+  const [cmd, ...args] = opener
+  const child = spawn(cmd, [...args, url], { stdio: 'ignore', detached: true })
+  child.on('error', () => {})
+  child.unref()
+}

package/server/lib/ports.mjs

@@ -0,0 +1,54 @@
+import net from 'node:net'
+
+export const DEFAULT_PORT = 5274
+export const PORTS_TO_TRY = 20
+
+const LOOPBACKS = ['127.0.0.1', '::1']
+
+export const originOf = (host, port) => `http://${host.includes(':') ? `[${host}]` : host}:${port}`
+
+export function answers(host, port, timeoutMs = 2000) {
+  return new Promise((resolve) => {
+    const socket = net.connect({ host, port })
+    const settle = (ok) => {
+      socket.destroy()
+      resolve(ok)
+    }
+    socket.setTimeout(timeoutMs, () => settle(false))
+    socket.once('connect', () => settle(true))
+    socket.once('error', () => settle(false))
+  })
+}
+
+export async function loopbackHolder(port) {
+  const answered = await Promise.all(LOOPBACKS.map((host) => answers(host, port)))
+  return LOOPBACKS[answered.indexOf(true)] ?? null
+}
+
+export async function listenOnFirstFreePort({ first, tries = PORTS_TO_TRY, listen, isOurs, holderOf = loopbackHolder }) {
+  const last = Math.min(first + tries - 1, 65535)
+  for (let port = first; port <= last; port++) {
+    const holder = await holderOf(port)
+    if (holder) {
+      const origin = originOf(holder, port)
+      if (await isOurs(origin)) return { port, server: null, existing: true, origin }
+      continue
+    }
+    try {
+      return { port, server: await listen(port), existing: false }
+    } catch (err) {
+      if (err.code !== 'EADDRINUSE') throw err
+    }
+  }
+  return { port: 0, server: null, existing: false, last }
+}
+
+export async function answersAsThreadgauge(origin, timeoutMs = 2000) {
+  try {
+    const res = await fetch(`${origin}/api/about`, { signal: AbortSignal.timeout(timeoutMs) })
+    const body = await res.json()
+    return body?.app === 'threadgauge'
+  } catch {
+    return false
+  }
+}