flowviant 0.52.0 → 0.53.0

package/bin/lib/authproxy.mjs

@@ -1,44 +1,124 @@
 /**
- * Opt-in basic-auth reverse proxy for previews (`.flowviant/preview.json`
- * "auth": true). The public tunnel is otherwise a capability URL — anyone with
- * it reaches the running app. This gates it: cloudflared → this proxy → dev
- * server, with a generated password the app surfaces to the reviewer.
+ * The password gate in front of a shared preview. cloudflared → this proxy →
+ * the dev server the DRIVER started in their own worktree.
  *
- * Minimal + dependency-free: forwards HTTP, and pipes WS upgrades (HMR) — the
+ * MANDATORY, not opt-in (2026-08-21). It was `.flowviant/preview.json`
+ * "auth": true, defaulting OFF, and its caller logged "tunneling WITHOUT a
+ * password" to a console nobody reads and opened the tunnel anyway. A tunnel
+ * publishes a worktree holding the project's materialized dev secrets; there is
+ * no honest default but closed. `startAuthProxy` returning null now means the
+ * share is ABORTED and the machine says why.
+ *
+ * Minimal and dependency-free: forwards HTTP, and pipes WS upgrades (HMR) — the
  * browser re-sends the cached Basic-auth header on same-origin upgrades, so HMR
- * still authenticates. If a proxy request fails the page just 502s; it never
- * touches the default (no-auth) preview path.
+ * still authenticates.
+ *
+ * Three things this file gets wrong easily, all of them fixed here and all of
+ * them worth keeping fixed:
+ *  - the credential must NOT reach the origin. `headers: req.headers` forwarded
+ *    `authorization` verbatim, handing the gate password to whatever code the
+ *    branch happens to be running. It is stripped now.
+ *  - the comparison is over a secret, so it is constant-time over a digest
+ *    rather than `===` over a string.
+ *  - `stop()` was a bare `server.close()`, which refuses NEW connections and
+ *    leaves live ones alone — so a held HMR websocket kept the page alive for
+ *    the one most-engaged viewer after teardown. Live sockets are tracked and
+ *    destroyed.
  */
 
 import { createServer, request } from 'node:http';
-import { randomBytes } from 'node:crypto';
+import { randomBytes, createHash, timingSafeEqual } from 'node:crypto';
+
+/** Failed attempts before the proxy stops answering at all. A quick tunnel's
+ *  hostname is unguessable, so this is not the primary control — it is what
+ *  turns a discovered URL from an offline guessing target into a visible,
+ *  self-closing incident. */
+const MAX_FAILED = 25;
+
+const digest = (s) => createHash('sha256').update(String(s)).digest();
+
+/** Constant-time over sha256 digests, so length never leaks and a missing
+ *  header costs the same as a wrong one. */
+function sameSecret(a, b) {
+  try {
+    return timingSafeEqual(digest(a ?? ''), digest(b ?? ''));
+  } catch {
+    return false;
+  }
+}
 
-/** Start the proxy in front of a dev server on `targetPort`. Resolves
- *  { port, user, password, stop }. Binds loopback only (cloudflared connects
- *  locally); the password is what gates the public tunnel. */
-export function startAuthProxy({ targetPort, log }) {
+/**
+ * Start the gate in front of a dev server on `targetPort`. Resolves
+ * { port, user, password, stop } — or NULL, which the caller must treat as a
+ * hard failure. Binds loopback only; cloudflared connects locally, and the
+ * password is what gates the public hostname.
+ *
+ * `onAbuse` fires once, after MAX_FAILED rejected attempts, so the caller can
+ * tear the whole share down rather than leaving a URL under attack.
+ */
+export function startAuthProxy({ targetPort, log, onAbuse }) {
   const user = 'preview';
-  const password = randomBytes(9).toString('base64url'); // ~12 url-safe chars
+  // 24 bytes → 32 url-safe chars. It was 9 bytes, chosen when this was an
+  // opt-in convenience; it is the only thing between a public hostname and a
+  // worktree now.
+  const password = randomBytes(24).toString('base64url');
   const expected = 'Basic ' + Buffer.from(`${user}:${password}`).toString('base64');
-  const authed = (req) => req.headers['authorization'] === expected;
 
-  const forwardOpts = (req) => ({
-    host: '127.0.0.1',
-    port: targetPort,
-    method: req.method,
-    path: req.url,
-    headers: req.headers,
-  });
+  let failed = 0;
+  let abused = false;
+  const authed = (req) => {
+    if (abused) return false;
+    if (sameSecret(req.headers['authorization'], expected)) {
+      failed = 0;
+      return true;
+    }
+    // A bare GET with no header is the browser's first move on every load, and
+    // it is answered with a 401 challenge — it is not an attempt.
+    if (req.headers['authorization']) failed += 1;
+    if (failed >= MAX_FAILED && !abused) {
+      abused = true;
+      log?.(`preview gate: ${failed} failed attempts — closing the share.`);
+      try {
+        onAbuse?.();
+      } catch {
+        /* the caller's teardown is best-effort */
+      }
+    }
+    return false;
+  };
+
+  // The gate credential is OURS and stops here. Everything else is passed
+  // through untouched: the origin is the driver's own dev server and rewriting
+  // its request would be us editing their app's input.
+  const forwardOpts = (req) => {
+    const headers = { ...req.headers };
+    delete headers.authorization;
+    delete headers['proxy-authorization'];
+    return {
+      host: '127.0.0.1',
+      port: targetPort,
+      method: req.method,
+      path: req.url,
+      headers,
+    };
+  };
+
+  const challenge = (res) => {
+    res.writeHead(401, {
+      'WWW-Authenticate': 'Basic realm="Flowviant preview"',
+      'Content-Type': 'text/plain',
+      // A preview is a moving target by definition; nothing about it should sit
+      // in a cache the viewer cannot see.
+      'Cache-Control': 'no-store',
+    });
+    res.end('This preview is password-protected. Enter the password shown in Flowviant.');
+  };
+
+  // Every live socket, so stop() can actually end the ones already talking.
+  const sockets = new Set();
 
   const server = createServer((req, res) => {
-    if (!authed(req)) {
-      res.writeHead(401, {
-        'WWW-Authenticate': 'Basic realm="Flowviant preview"',
-        'Content-Type': 'text/plain',
-      });
-      res.end('This preview is password-protected. Enter the password shown in Flowviant.');
-      return;
-    }
+    if (!authed(req)) return challenge(res);
     const proxyReq = request(forwardOpts(req), (proxyRes) => {
       res.writeHead(proxyRes.statusCode || 502, proxyRes.headers);
       proxyRes.pipe(res);
@@ -50,8 +130,13 @@ export function startAuthProxy({ targetPort, log }) {
     req.pipe(proxyReq);
   });
 
+  server.on('connection', (socket) => {
+    sockets.add(socket);
+    socket.on('close', () => sockets.delete(socket));
+  });
+
   // WS upgrade (HMR). The browser resends the Basic-auth header on same-origin
-  // upgrades, so we can gate it too, then pipe the two sockets together.
+  // upgrades, so we gate it too, then pipe the two sockets together.
   server.on('upgrade', (req, socket, head) => {
     if (!authed(req)) {
       socket.write('HTTP/1.1 401 Unauthorized\r\nWWW-Authenticate: Basic realm="Flowviant preview"\r\n\r\n');
@@ -65,6 +150,8 @@ export function startAuthProxy({ targetPort, log }) {
       if (proxyHead && proxyHead.length) proxySocket.unshift(proxyHead);
       proxySocket.pipe(socket);
       socket.pipe(proxySocket);
+      sockets.add(proxySocket);
+      proxySocket.on('close', () => sockets.delete(proxySocket));
       proxySocket.on('error', () => socket.destroy());
       socket.on('error', () => proxySocket.destroy());
     });
@@ -74,10 +161,12 @@ export function startAuthProxy({ targetPort, log }) {
   });
 
   return new Promise((resolve) => {
-    server.on('error', () => resolve(null)); // couldn't bind → caller falls back to no proxy
+    // Could not bind → the caller ABORTS the share. There is no no-proxy path
+    // to fall back to any more.
+    server.on('error', () => resolve(null));
     server.listen(0, '127.0.0.1', () => {
       const port = server.address().port;
-      log?.(`auth proxy on :${port} — preview is password-gated`);
+      log?.(`preview gate on :${port}`);
       resolve({
         port,
         user,
@@ -88,6 +177,16 @@ export function startAuthProxy({ targetPort, log }) {
           } catch {
             /* already closed */
           }
+          // close() only stops NEW connections. An open HMR socket would keep
+          // serving the viewer who is still looking at it.
+          for (const s of sockets) {
+            try {
+              s.destroy();
+            } catch {
+              /* already gone */
+            }
+          }
+          sockets.clear();
         },
       });
     });

package/bin/lib/config.mjs

@@ -1,5 +1,6 @@
 /** Parsed configuration: env vars, CLI flags, and the chosen credentials. */
 
+import { randomBytes } from 'node:crypto';
 import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -168,6 +169,21 @@ export const ALLOW_PATCHES =
 // them (Node's default UA is treated as a bot). Claude Code sends its own UA.
 export const USER_AGENT = `flowviant/${VERSION}`;
 
+/**
+ * WHICH DAEMON PROCESS this is — not which credential.
+ *
+ * Two daemons legitimately share one fleet token (that is exactly what
+ * `machineDaemonsDisagree` reports, and the instance lock added in 0.51.2
+ * cannot see a peer OLDER than itself). So the token cannot identify a lease
+ * holder, and anything that must be done exactly once needs this instead.
+ *
+ * Regenerated every start, deliberately: a daemon that restarted is a daemon
+ * that lost whatever it was holding, and a stale lease should not follow it
+ * back. Sent on the poll as `di`; its ABSENCE is what an older daemon looks
+ * like, and the server hands preview work to nobody who cannot name themselves.
+ */
+export const DAEMON_INSTANCE = randomBytes(12).toString('hex');
+
 // The ONE credential. `tokens` (FLOWVIANT_TOKEN / FLOWVIANT_TOKENS / --token /
 // --tokens) stood beside it and carried WORKER tokens into the pre-daemon loop;
 // that principal owns zero tools since dispatch was deleted, and the kind can no

package/bin/lib/fleet.mjs

@@ -23,6 +23,7 @@ import {
   USER_AGENT,
   MCP_URL,
   SAFE,
+  DAEMON_INSTANCE,
   POLL_SECONDS,
   MAX_CONCURRENT,
   IDLE_SECONDS,
@@ -77,7 +78,7 @@ import { detectRuntimes, knownSkills, pickRuntimeFor, RUNTIMES } from './runtime
 import { createWorkManager } from './work.mjs';
 import { scanLocalSessions } from './localSessions.mjs';
 
-async function fetchRoster(haveIds) {
+async function fetchRoster(haveIds, livePreviewSessionIds = []) {
   const url = new URL(FLEET_URL);
   if (haveIds.length) url.searchParams.set('have', haveIds.join(','));
   // What this machine will run at once. The server grows lanes to meet waiting
@@ -98,6 +99,15 @@ async function fetchRoster(haveIds) {
   // so a team can see whether the shared box runs wide open, and enforces
   // nothing (membership is the consent boundary). Older servers ignore it.
   url.searchParams.set('safe', SAFE ? '1' : '0');
+  // WHICH PROCESS, so the server can lease preview work to exactly one of two
+  // daemons on one credential. Older servers ignore unknown params.
+  url.searchParams.set('di', DAEMON_INSTANCE);
+  // Which shares this machine is still serving. It rides the poll rather than
+  // taking an endpoint of its own: one beat, no floor, and the stale window is
+  // the reconcile interval instead of minutes — which matters, because a share
+  // the server still calls live is a 530 on somebody's phone. Always set, even
+  // empty: '' means "serving none", absent would mean "an older daemon".
+  url.searchParams.set('pv', livePreviewSessionIds.join(','));
   // WHICH CLIs this machine actually has, so the app can stop guessing.
   //
   // Until now every surface that listed Gemini or Codex said "not wired up yet"
@@ -374,6 +384,14 @@ export async function runFleetDaemon() {
   const nextByAgent = new Map();
   let leaseTtlSeconds = 24 * 60 * 60; // updated from each roster response
   let mcpUrl = MCP_URL;
+  // DEAD, and kept only because unpicking it is a rewire rather than a
+  // deletion: nothing calls `workers.set` anywhere in this tree. It held
+  // DISPATCH lanes, and the server has sent `agents: []` permanently since
+  // 2026-08-19, so every loop below iterates nothing. Two `stopPreview` calls
+  // hung off it until 2026-08-21 and read as live preview wiring; they were
+  // deleted, not rewired. When the Workbench preview lands, its teardown is
+  // keyed on sessionId and belongs beside retireWorkSessions in work.mjs —
+  // NOT here.
   const workers = new Map(); // agentId -> { state, promise, wt, label }
   let daemonAlive = true; // flipped false on shutdown so the stream stops reconnecting
   let stream = null; // push channel handle (set once the loop is set up)
@@ -413,15 +431,10 @@ export async function runFleetDaemon() {
       } catch {
         /* best-effort */
       }
-      // Stop the detached preview (dev server + cloudflared tunnel) — it's its
-      // own process group and survives our exit, otherwise leaking a port-bound
-      // server + a live tunnel serving a stale branch until reboot.
-      try {
-        w.state.stopPreview?.();
-      } catch {
-        /* best-effort */
-      }
     }
+    // Detached tunnels survive our exit by design, so leaving them would strand
+    // a public hostname until the box rebooted.
+    shutdownPreviews();
   };
   process.on('SIGINT', () => {
     console.log('');
@@ -593,6 +606,10 @@ export async function runFleetDaemon() {
     processWorkTurns,
     processShipJobs,
     processDiffJobs,
+    processPreviewJobs,
+    livePreviewIds,
+    retirePreviews,
+    shutdownPreviews,
     retireWorkSessions,
     reportWorktrees,
     shutdownWork,
@@ -1153,7 +1170,7 @@ export async function runFleetDaemon() {
   for (;;) {
     let roster;
     try {
-      roster = await fetchRoster(buildHave());
+      roster = await fetchRoster(buildHave(), livePreviewIds());
     } catch (e) {
       if (e.auth) {
         fail(`${e.message} — credential revoked or invalid. Shutting down.`);
@@ -1215,11 +1232,20 @@ export async function runFleetDaemon() {
     // AFTER the work/ship intake: retirement is the server saying which
     // sessions are LIVE, and the guards above (chains, shipping) are populated
     // by the intake this same tick.
+    // BEFORE retirement, and the order is load-bearing: `git worktree remove`
+    // under a running dev server leaves it serving bytes from open file handles
+    // in a directory that no longer exists — a human is shown the wrong thing
+    // and nothing errors anywhere.
+    retirePreviews(roster.activeWorkSessions);
     retireWorkSessions(roster.activeWorkSessions);
     // Diffs somebody has open and is waiting on. Project-scoped rather than
     // per-session: `git show` runs from the repo ROOT, which can see a closed
     // tab's branch and a shipped commit on main alike.
     processDiffJobs(roster.diffJobs);
+    // Shares to open or tear down. CLAIMED before acted on — two daemons on one
+    // credential are both handed this array, and both opening a tunnel strands
+    // a public hostname nobody can settle.
+    processPreviewJobs(roster.previewJobs);
     // …and what the SURVIVING ones hold: branch, ahead-of-base, diffstat.
     // Throttled inside, never awaited — a `git status` the human cannot run
     // themselves from a browser, relayed. After retirement so a directory that
@@ -1323,11 +1349,6 @@ export async function runFleetDaemon() {
         } catch {
           /* best-effort */
         }
-        try {
-          w.state.stopPreview?.();
-        } catch {
-          /* best-effort */
-        }
         // Only poll mode's per-lane tree dies with the lane. A live lane owns no
         // checkout: the task it was building has its own, which must SURVIVE —
         // removing a lane requeues its task, and the next lane to pick that task

package/bin/lib/listeners.mjs

@@ -0,0 +1,269 @@
+/**
+ * What is LISTENING inside a session's worktree.
+ *
+ * The Workbench preview never starts an app. The driver runs their own dev
+ * server in their own tab, exactly as they would in a terminal, and this file
+ * is how the machine NOTICES — a browser has no `ss -ltnp` to run, so the
+ * daemon runs it. That direction is the whole design: a control that can only
+ * exist once the machine has measured the thing it acts on cannot invent a
+ * state, cannot guess a port, and cannot time out waiting for a cold start.
+ *
+ * A listener is attributed to a session by the CWD OF THE PROCESS HOLDING THE
+ * SOCKET, never by the port number. Ports are global to the box; a worktree is
+ * not. Without that attribution `share_preview(5432)` tunnels Postgres and
+ * `share_preview(<a teammate's port>)` publishes somebody else's worktree — so
+ * this measurement is a security control, not a convenience, and it is why the
+ * MCP tool must not ship before it.
+ *
+ * Deliberately NOT a probe: nothing here connects to the port, sends bytes, or
+ * asks what is on the other end. It reads the kernel's own socket table. A
+ * daemon that spoke to whatever the driver happened to be running would be a
+ * second actor in their session.
+ *
+ * Linux (including WSL2) reads /proc. macOS shells out to lsof twice. Windows
+ * reports NOTHING and says so through the empty array — the same answer
+ * `stillOurs` gives, and the same rule the rest of the product keeps: an
+ * unmeasured thing renders nothing rather than rendering "none".
+ */
+
+import { execFileSync } from 'node:child_process';
+import { createConnection } from 'node:net';
+import { readFileSync, readdirSync, readlinkSync, realpathSync } from 'node:fs';
+import { platform } from 'node:os';
+import { sep } from 'node:path';
+
+/** A box with more processes than this is not one we walk per sweep. The scan
+ *  is one readlink per pid and runs every reconcile; this is the runaway
+ *  bound, not a capacity statement. */
+const MAX_PIDS = 4000;
+/** Rows reported per session. A dev server, its HMR socket and an API is three;
+ *  twenty is somebody's docker-compose and the extra rows say nothing. */
+const MAX_ROWS = 8;
+/** Longest process label we relay. */
+const MAX_LABEL = 24;
+
+// ── /proc/net/tcp parsing (linux) ──────────────────────────────────────────
+
+// local_address is "<hex addr>:<hex port>". The address is little-endian per
+// 4-byte word; the PORT is big-endian. Only the port and the coarse bind scope
+// are worth relaying — a browser cannot reach a loopback bind through a tunnel
+// any differently than an any-bind, but the operator can read the difference.
+function parseLocal(hex) {
+  const [addr, port] = String(hex).split(':');
+  if (!addr || !port) return null;
+  const p = parseInt(port, 16);
+  if (!Number.isInteger(p) || p <= 0 || p > 65535) return null;
+  const zeros = /^0+$/.test(addr);
+  const v4Loopback = addr.toUpperCase() === '0100007F';
+  // ::1 in /proc/net/tcp6 is 24 zeros then 01000000 (little-endian per word).
+  const v6Loopback = addr.toUpperCase() === '00000000000000000000000001000000';
+  return { port: p, bind: zeros ? 'any' : v4Loopback || v6Loopback ? 'loopback' : 'other' };
+}
+
+/** inode -> { port, bind } for every socket in LISTEN state. */
+function listeningByInode() {
+  const out = new Map();
+  for (const f of ['/proc/net/tcp', '/proc/net/tcp6']) {
+    let text;
+    try {
+      text = readFileSync(f, 'utf8');
+    } catch {
+      continue; // no ipv6 stack, or not linux
+    }
+    for (const line of text.split('\n').slice(1)) {
+      const c = line.trim().split(/\s+/);
+      if (c.length < 10) continue;
+      if (c[3] !== '0A') continue; // TCP_LISTEN
+      const local = parseLocal(c[1]);
+      if (!local) continue;
+      const inode = c[9];
+      if (inode && inode !== '0') out.set(inode, local);
+    }
+  }
+  return out;
+}
+
+function labelFor(pid) {
+  try {
+    const raw = readFileSync(`/proc/${pid}/cmdline`, 'utf8');
+    const first = raw.split('\0').filter(Boolean)[0] || '';
+    // The basename only. A full argv is the driver's command line, which can
+    // carry a token in an inline env assignment — and the whole argv is never
+    // what a reader needs to recognise their own dev server.
+    const base = first.split('/').pop() || first;
+    return base.slice(0, MAX_LABEL) || null;
+  } catch {
+    return null;
+  }
+}
+
+function scanLinux(worktree) {
+  const inodes = listeningByInode();
+  if (inodes.size === 0) return [];
+
+  let root;
+  try {
+    root = realpathSync(worktree);
+  } catch {
+    return []; // the directory is gone — retired under us
+  }
+  const prefix = root.endsWith(sep) ? root : root + sep;
+  const inside = (p) => p === root || p.startsWith(prefix);
+
+  let pids;
+  try {
+    pids = readdirSync('/proc').filter((d) => /^\d+$/.test(d));
+  } catch {
+    return [];
+  }
+  if (pids.length > MAX_PIDS) pids = pids.slice(0, MAX_PIDS);
+
+  const found = new Map(); // port -> row
+  for (const pid of pids) {
+    // Cheap filter FIRST: one readlink rejects almost every process on the box,
+    // and only survivors pay for a readdir of their fd table.
+    let cwd;
+    try {
+      cwd = readlinkSync(`/proc/${pid}/cwd`);
+    } catch {
+      continue; // not ours, or gone
+    }
+    if (!inside(cwd)) continue;
+
+    let fds;
+    try {
+      fds = readdirSync(`/proc/${pid}/fd`);
+    } catch {
+      continue;
+    }
+    for (const fd of fds) {
+      let link;
+      try {
+        link = readlinkSync(`/proc/${pid}/fd/${fd}`);
+      } catch {
+        continue;
+      }
+      const m = /^socket:\[(\d+)\]$/.exec(link);
+      if (!m) continue;
+      const hit = inodes.get(m[1]);
+      if (!hit) continue;
+      if (found.has(hit.port)) continue;
+      found.set(hit.port, { port: hit.port, bind: hit.bind, label: labelFor(pid) });
+    }
+  }
+  return [...found.values()];
+}
+
+// ── macOS ──────────────────────────────────────────────────────────────────
+
+function lsof(args) {
+  try {
+    return execFileSync('lsof', args, {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 5000,
+      maxBuffer: 4 * 1024 * 1024,
+    });
+  } catch {
+    return ''; // lsof absent or nothing matched — both are "no measurement"
+  }
+}
+
+function scanDarwin(worktree) {
+  // Pass 1: every listening socket, as pid → ports.
+  const byPid = new Map();
+  let pid = null;
+  for (const line of lsof(['-nP', '-iTCP', '-sTCP:LISTEN', '-F', 'pn']).split('\n')) {
+    if (line.startsWith('p')) pid = line.slice(1);
+    else if (line.startsWith('n') && pid) {
+      const m = /:(\d+)$/.exec(line.slice(1));
+      if (!m) continue;
+      const p = Number(m[1]);
+      const bind = /^n\*:/.test(line) ? 'any' : /^n(127\.0\.0\.1|\[::1\])/.test(line) ? 'loopback' : 'other';
+      if (!byPid.has(pid)) byPid.set(pid, []);
+      byPid.get(pid).push({ port: p, bind });
+    }
+  }
+  if (byPid.size === 0) return [];
+
+  let root;
+  try {
+    root = realpathSync(worktree);
+  } catch {
+    return [];
+  }
+  const prefix = root.endsWith(sep) ? root : root + sep;
+
+  // Pass 2: the cwd of exactly those pids, in ONE batched call.
+  const out = new Map();
+  let cur = null;
+  for (const line of lsof(['-a', '-d', 'cwd', '-F', 'pn', '-p', [...byPid.keys()].join(',')]).split('\n')) {
+    if (line.startsWith('p')) cur = line.slice(1);
+    else if (line.startsWith('n') && cur) {
+      const cwd = line.slice(1);
+      if (cwd !== root && !cwd.startsWith(prefix)) continue;
+      for (const row of byPid.get(cur) || []) {
+        if (!out.has(row.port)) out.set(row.port, { ...row, label: null });
+      }
+    }
+  }
+  return [...out.values()];
+}
+
+// ── public ─────────────────────────────────────────────────────────────────
+
+/**
+ * Every TCP port in LISTEN held by a process whose cwd is inside `worktree`.
+ * Smallest port first, capped. An empty array on an unsupported platform means
+ * "we did not look" — callers must not turn it into "nothing is running".
+ */
+export function listenersIn(worktree) {
+  if (!worktree) return [];
+  let rows;
+  try {
+    rows = platform() === 'linux' ? scanLinux(worktree) : platform() === 'darwin' ? scanDarwin(worktree) : [];
+  } catch {
+    return [];
+  }
+  return rows.sort((a, b) => a.port - b.port).slice(0, MAX_ROWS);
+}
+
+/** Does this platform measure listeners at all? The web must render no preview
+ *  affordance where the answer is no, rather than an empty one. */
+export function listenersSupported() {
+  return platform() === 'linux' || platform() === 'darwin';
+}
+
+/**
+ * Is something accepting connections on this loopback port RIGHT NOW?
+ *
+ * Used at two moments, both of them re-validation rather than discovery: the
+ * daemon re-checks a port the server told it to share, and a live share checks
+ * that its origin has not died under the tunnel. cloudflared happily outlives a
+ * dead dev server and the gate answers a dead origin with 502, so without this
+ * the product would print "live" over a 502 — which is Flowviant asserting a
+ * state it never measured.
+ *
+ * A TCP connect and an immediate close: no bytes sent, nothing read.
+ */
+export function isListening(port, timeoutMs = 1500) {
+  return new Promise((resolve) => {
+    if (!Number.isInteger(port) || port <= 0 || port > 65535) return resolve(false);
+    let done = false;
+    const finish = (v) => {
+      if (done) return;
+      done = true;
+      try {
+        sock.destroy();
+      } catch {
+        /* already gone */
+      }
+      resolve(v);
+    };
+    const sock = createConnection({ port, host: '127.0.0.1' });
+    sock.setTimeout(timeoutMs);
+    sock.once('connect', () => finish(true));
+    sock.once('timeout', () => finish(false));
+    sock.once('error', () => finish(false));
+  });
+}