flowviant 0.52.0 → 0.54.0

package/bin/lib/instance.mjs

@@ -1,11 +1,24 @@
 /**
- * ONE DAEMON PER CREDENTIAL, refused at startup.
+ * ONE DAEMON PER REPO (and per credential), ARBITRATED at startup — a second
+ * run in the same repo takes the first one's place rather than being turned
+ * away. See "WHAT A SECOND RUN DOES" below for the whole rule.
  *
- * WHY THIS EXISTS. Nothing stopped two daemons before, and the server hands
- * work out by READING, never claiming: `listWorkTurnJobs` selects every pending
- * turn for the fleet token, `listShipJobs` reads a flag. So two daemons on one
- * credential are offered the SAME turn — and the ProjectRoom nudges every
- * connected daemon socket at once, so they do not even drift out of phase.
+ * WHY THIS EXISTS. Nothing stopped two daemons before, and the server USED to
+ * hand work out by READING, never claiming: `listWorkTurnJobs` selected every
+ * pending turn for the machine credential, `listShipJobs` read a flag. So two
+ * daemons on one credential were offered the SAME turn — and the ProjectRoom
+ * nudges every connected daemon socket at once, so they did not even drift out
+ * of phase.
+ *
+ * That half is fixed on the server now: since 0.53.0 each SESSION is leased to
+ * one daemon INSTANCE nonce — `di`, regenerated every start (config.mjs) and
+ * sent on every poll beside `ws`, the list of sessions this daemon holds a
+ * worktree for — so a turn is handed to the instance holding that session and
+ * to no one else. It does NOT retire this lock. The lease fails OPEN when no
+ * instance is reported (an older daemon cannot name itself), and it arbitrates
+ * only what rides a session: the wiki sweep, env materialization, previews,
+ * deploys and every worktree operation the server never sees are still first
+ * come, first served.
  *
  * The per-worktree `flowviant-turn.lock` cannot save it. That lock is written
  * AFTER the work token is minted and the attachments are fetched — a window
@@ -14,27 +27,70 @@
  * (its own comment says so, work.mjs), where the holder is already live when
  * the successor looks; it was never a concurrency primitive.
  *
- * What the duplicate run costs, all of it invisible in the tab: two Claudes
- * editing one worktree, two cards from one `file_card` (no idempotency key),
- * the session write budget spent twice, quota spent twice — and then exactly
- * ONE answer survives, because `settleWorkTurn` is atomic. The side effects
- * land twice and the transcript shows one turn.
+ * What a duplicate run cost before the session lease, all of it invisible in
+ * the tab: two Claudes editing one worktree, two cards from one `file_card` (no
+ * idempotency key), the session write budget spent twice, quota spent twice —
+ * and then exactly ONE answer surviving, because `settleWorkTurn` is atomic.
+ * The side effects landed twice and the transcript showed one turn. Two daemons
+ * in one checkout still cost the un-leased half of that: two `git fetch`, two
+ * worktree sweeps, and the collisions listed under ONE DAEMON PER REPO below.
  *
- * KEYED ON THE CREDENTIAL, NOT THE REPO. The credential is stored once, at
+ * KEYED ON THE CREDENTIAL — and, as the next paragraph adds, on the REPO as
+ * well; both checks run, and either one is enough. The credential is stored once, at
  * ~/.flowviant/credentials.json, so `flowviant` in two DIFFERENT checkouts is
  * still one project served twice — and that case is strictly worse, because the
  * two daemons have different worktree roots and the turn lock cannot even see
  * across them. Keying on the token catches both, and still lets a second
  * credential run a second project on the same machine.
  *
+ * ...AND ONE DAEMON PER REPO, which is NOT the same statement. The lock above
+ * is keyed on the credential, and the two coincide only while one credential
+ * serves one project — which is the product's law but not a thing this file can
+ * assume. Two DIFFERENT credentials pointing at one checkout both acquired
+ * happily (measured), giving two daemons in one working tree: two `git fetch`,
+ * two worktree sweeps, `retireWorkSessions` in one removing directories the
+ * other is serving, and a ship in one racing a rebase in the other. No server
+ * lease can arbitrate any of that, because the server never sees a directory.
+ * So the repo is checked too, across every credential's lock.
+ *
+ * WHAT A SECOND RUN DOES, and this is the whole rule:
+ *
+ *   SAME REPO      -> the new run WINS. The holder is asked to stand down and
+ *                     this daemon takes its place. Re-running `flowviant` in a
+ *                     directory you are working in means "serve this repo", and
+ *                     the process already serving it is by definition the one
+ *                     you are replacing. That is a restart, and a restart
+ *                     should not require you to go and find a pid.
+ *
+ *   DIFFERENT REPO -> REFUSED, and nothing is signalled. That daemon is serving
+ *                     other work; killing it because you happened to run this
+ *                     command elsewhere is not a restart, it is collateral.
+ *                     `--takeover` overrides, deliberately explicitly.
+ *
+ * One rule, and it is the invariant stated as behaviour: one daemon per repo.
+ * `--no-takeover` (or FLOWVIANT_NO_TAKEOVER=1) makes even the same-repo case
+ * refuse, for anyone who wants the old ceremony.
+ *
  * IT FAILS OPEN. A home directory we cannot write to is not a reason to refuse
  * to start; it is a reason to say so and carry on unguarded.
  */
 
-import { closeSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync, writeSync } from 'node:fs';
-import { homedir } from 'node:os';
+import { execFileSync } from 'node:child_process';
+import {
+  closeSync,
+  mkdirSync,
+  openSync,
+  readdirSync,
+  readFileSync,
+  realpathSync,
+  rmSync,
+  writeFileSync,
+  writeSync,
+} from 'node:fs';
+import { homedir, platform } from 'node:os';
 import { join } from 'node:path';
 import { createHash } from 'node:crypto';
+import { VERSION } from './config.mjs';
 
 /** Deliberately a HASH: a credential must never become a filename. */
 export function instanceLockPath(fleetToken) {
@@ -42,6 +98,20 @@ export function instanceLockPath(fleetToken) {
   return join(homedir(), '.flowviant', `daemon-${key}.lock`);
 }
 
+/** Numeric dotted compare, -1/0/1. Unparsable compares EQUAL, so a version we
+ *  cannot read never silently authorises a downgrade. */
+function cmpVersion(a, b) {
+  const x = String(a).split('.').map((n) => Number.parseInt(n, 10));
+  const y = String(b).split('.').map((n) => Number.parseInt(n, 10));
+  for (let i = 0; i < Math.max(x.length, y.length); i++) {
+    const p = x[i] ?? 0;
+    const q = y[i] ?? 0;
+    if (Number.isNaN(p) || Number.isNaN(q)) return 0;
+    if (p !== q) return p > q ? 1 : -1;
+  }
+  return 0;
+}
+
 /** Signal 0 — a liveness probe, not a kill. EPERM means alive and not ours. */
 function alive(pid) {
   if (!Number.isInteger(pid) || pid <= 0) return false;
@@ -63,7 +133,192 @@ function readHolder(path) {
 }
 
 const record = (repoRoot) =>
-  JSON.stringify({ pid: process.pid, repoRoot, startedAt: new Date().toISOString() });
+  JSON.stringify({
+    pid: process.pid,
+    repoRoot,
+    startedAt: new Date().toISOString(),
+    // The script we were started from, and what we are. A takeover matches the
+    // live command line against `entry` before signalling anything — a lock
+    // records a PID, and a crashed daemon's PID can be reused by anything.
+    entry: process.argv[1] || '',
+    version: VERSION,
+  });
+
+/** Same directory, whatever it is spelled as — symlinks and trailing slashes
+ *  included. A repo compared by string would let `/repo` and `/repo/` past. */
+function samePath(a, b) {
+  if (!a || !b) return false;
+  const norm = (v) => {
+    try {
+      return realpathSync(v);
+    } catch {
+      return String(v).replace(/\/+$/, '');
+    }
+  };
+  return norm(a) === norm(b);
+}
+
+/**
+ * A LIVE daemon in this same checkout, under a DIFFERENT credential.
+ *
+ * The lock above cannot see one: it is keyed on the credential, so a second
+ * token in the same directory opens its own file and takes it. Every other
+ * lock file on this machine is ours to read, so read them.
+ *
+ * Returns the holder, or null. A stale file never blocks — it is cleared by
+ * whichever acquire owns it, and blocking on a corpse would be worse than the
+ * thing this prevents.
+ */
+/** Which lock file a neighbour holder was read from — takeOverFrom waits on it. */
+const NEIGHBOUR_PATHS = new WeakMap();
+function neighbourLockPath(holder, fallback) {
+  return NEIGHBOUR_PATHS.get(holder) ?? fallback;
+}
+
+export function daemonInSameRepo(repoRoot, ownPath) {
+  const dir = join(homedir(), '.flowviant');
+  let files;
+  try {
+    files = readdirSync(dir).filter((f) => /^daemon-[0-9a-f]{12}\.lock$/.test(f));
+  } catch {
+    return null;
+  }
+  for (const f of files) {
+    const path = join(dir, f);
+    if (path === ownPath) continue; // our own credential — the lock above owns that question
+    const holder = readHolder(path);
+    if (!holder || !alive(holder.pid)) continue;
+    if (holder.pid === process.ppid) continue; // ourselves mid self-update re-exec
+    if (samePath(holder.repoRoot, repoRoot)) {
+      NEIGHBOUR_PATHS.set(holder, path);
+      return holder;
+    }
+  }
+  return null;
+}
+
+/**
+ * IS THIS PID STILL THE DAEMON THAT TOOK THE LOCK?
+ *
+ * `process.kill(pid, 0)` says "a process exists", which is not the same claim,
+ * and the difference matters the moment we are about to signal it. Matched on
+ * the holder's own recorded ENTRYPOINT, never on the word "flowviant": a
+ * command line merely CONTAINING it matches a shell, an editor, or a test
+ * runner living under a `…-flowviant/` directory. That last one is not
+ * hypothetical — a looser version of this check SIGTERMed one.
+ *
+ * A lock with no `entry` predates this and is never signalled.
+ */
+function stillTheHolder(holder) {
+  const want = typeof holder?.entry === 'string' ? holder.entry : null;
+  if (!want) return false;
+  try {
+    if (platform() === 'linux') {
+      return readFileSync(`/proc/${holder.pid}/cmdline`, 'utf8').replace(/\0/g, ' ').includes(want);
+    }
+    return execFileSync('ps', ['-o', 'command=', '-p', String(holder.pid)], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 3000,
+    }).includes(want);
+  } catch {
+    return false; // gone, or unreadable — not something we signal
+  }
+}
+
+/** Blocking, because this runs before there is an event loop worth yielding to
+ *  and the caller cannot proceed until it knows whether the holder is gone. */
+const sleep = (ms) => {
+  try {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+  } catch {
+    /* no SharedArrayBuffer — check again immediately */
+  }
+};
+
+/** How long the outgoing daemon gets to stand down cleanly. Its SIGTERM handler
+ *  kills the CLI children it spawned and stops its preview tunnels; both are
+ *  why we ask before we insist. */
+const TAKEOVER_GRACE_MS = 20_000;
+
+/**
+ * Ask the holder to stand down, then take its place.
+ *
+ * SIGTERM FIRST, and not out of politeness: the daemon's handler runs its
+ * teardown — it kills the CLI children it spawned and stops its preview
+ * tunnels, which are DETACHED and would otherwise keep a public hostname
+ * serving a worktree until the box reboots.
+ *
+ * WAIT ON THE LOCK FILE, not the pid. A departing daemon's release() removes it
+ * on exit, so the file changing IS the handover. `kill(pid, 0)` cannot see it:
+ * a process that exited but has not been reaped is a ZOMBIE and answers signal
+ * 0 exactly like a living one — measured, a peer that exited cleanly still read
+ * as alive for the full grace window.
+ *
+ * And "gone" is NOT "the file stopped naming our pid". It can stop naming it
+ * because the holder SELF-UPDATED: update.mjs re-execs and the successor adopts
+ * this same lock through the ppid branch. Treating that as free steals a live
+ * daemon's lock and leaves it running unguarded — measured doing exactly that.
+ */
+function takeOverFrom(holder, path, log, { allowDowngrade = false } = {}) {
+  if (!holder?.pid || !alive(holder.pid)) return null; // already gone
+  if (!stillTheHolder(holder)) {
+    return { failed: `pid ${holder.pid} is no longer the daemon that took this lock — refusing to signal it` };
+  }
+  if (!allowDowngrade && holder.version && cmpVersion(VERSION, holder.version) < 0) {
+    return {
+      failed: `the running daemon is ${holder.version} and this one is ${VERSION} — refusing to replace a newer daemon with an older one (--takeover-downgrade if you mean it)`,
+    };
+  }
+
+  log?.(`asking daemon pid ${holder.pid} to stand down…`);
+  try {
+    process.kill(holder.pid, 'SIGTERM');
+  } catch {
+    return { failed: `could not signal pid ${holder.pid}` };
+  }
+
+  const standing = () => {
+    const now = readHolder(path);
+    if (!now || !alive(now.pid)) return null;
+    return now;
+  };
+  const deadline = Date.now() + TAKEOVER_GRACE_MS;
+  for (;;) {
+    const now = standing();
+    if (!now) break;
+    if (now.pid !== holder.pid) {
+      return {
+        failed: `the daemon handed over to pid ${now.pid}${now.version ? ` (${now.version})` : ''} while we waited — it is mid-update, so try again in a moment`,
+      };
+    }
+    if (Date.now() >= deadline) {
+      log?.(`pid ${holder.pid} did not stand down within ${TAKEOVER_GRACE_MS / 1000}s — forcing it.`);
+      try {
+        process.kill(holder.pid, 'SIGKILL');
+      } catch {
+        /* exited in the gap */
+      }
+      sleep(600);
+      const after = standing();
+      if (after && after.pid !== holder.pid) {
+        return { failed: `the daemon handed over to pid ${after.pid} — try again in a moment` };
+      }
+      if (after) return { failed: `pid ${holder.pid} would not stop` };
+      break;
+    }
+    sleep(400);
+  }
+
+  // A SIGKILLed daemon never ran its release(), so clear what it left.
+  try {
+    rmSync(path, { force: true });
+  } catch {
+    return { failed: 'could not clear the lock file' };
+  }
+  log?.(`daemon pid ${holder.pid} stopped — taking over.`);
+  return null;
+}
 
 /**
  * Take the lock, or report who holds it.
@@ -75,7 +330,8 @@ const record = (repoRoot) =>
  * `wx` is the whole guarantee: create-exclusive is one atomic syscall, which is
  * the property the turn lock's check-then-write does not have.
  */
-export function acquireInstanceLock(fleetToken, repoRoot) {
+export function acquireInstanceLock(fleetToken, repoRoot, opts = {}) {
+  const { takeover: force = false, noTakeover = false, allowDowngrade = false, log } = opts;
   if (process.env.FLOWVIANT_ALLOW_MULTI === '1') return { ok: true, release: () => {} };
   const path = instanceLockPath(fleetToken);
   try {
@@ -84,6 +340,20 @@ export function acquireInstanceLock(fleetToken, repoRoot) {
     return { ok: true, release: () => {}, unguarded: true };
   }
 
+  // ONE DAEMON PER REPO, checked across every credential — see the header. This
+  // runs BEFORE we take our own lock, so a refusal leaves nothing behind.
+  const neighbour = daemonInSameRepo(repoRoot, path);
+  if (neighbour) {
+    // Same working tree, another credential. Under "one daemon per repo" the
+    // new run wins here too — but it is signalling a process that belongs to a
+    // DIFFERENT project, so it is worth saying out loud rather than doing
+    // quietly.
+    if (noTakeover) return { ok: false, holder: neighbour, sameRepo: true };
+    log?.(`another project's daemon is serving this repo (pid ${neighbour.pid}).`);
+    const bad = takeOverFrom(neighbour, neighbourLockPath(neighbour, path), log);
+    if (bad) return { ok: false, holder: neighbour, sameRepo: true, takeoverFailed: bad.failed };
+  }
+
   // Two passes at most: one to clear a stale holder, one to take the lock. A
   // loop here would spin against a peer that keeps re-taking it.
   for (let attempt = 0; attempt < 2; attempt++) {
@@ -118,7 +388,16 @@ export function acquireInstanceLock(fleetToken, repoRoot) {
         }
         return { ok: true, release: makeRelease(path) };
       }
-      return { ok: false, holder };
+      // THE RULE. Same repo -> this run replaces it; different repo -> refuse
+      // and signal nothing, unless --takeover says otherwise. See the header.
+      const here = samePath(holder.repoRoot, repoRoot);
+      const wanted = force || (here && !noTakeover);
+      if (wanted) {
+        const bad = takeOverFrom(holder, path, log, { allowDowngrade });
+        if (bad) return { ok: false, holder, takeoverFailed: bad.failed, sameRepo: here };
+        continue; // the file is gone — the next pass takes it
+      }
+      return { ok: false, holder, sameRepo: here };
     }
     try {
       writeSync(fd, record(repoRoot));

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));
+  });
+}

package/bin/lib/login.mjs

@@ -56,7 +56,11 @@ export async function runLogin({ thenStart = false } = {}) {
   }
   const { deviceCode, userCode, intervalSeconds = 5, expiresInSeconds = 600 } = start;
   const pretty = `${userCode.slice(0, 4)}-${userCode.slice(4)}`;
-  console.log(`  1. Open ${c.cyan(APP_URL)} → your project → the ${c.bold('Agents')} panel → ${c.bold('Connect a machine')}.`);
+  // Where the control ACTUALLY is. It was "the Agents panel", a settings
+  // section deleted 2026-08-17; connecting a machine is offered on the surface
+  // you are on when it matters, and for a new operator that is the Workbench —
+  // the project's empty state says so before it can show you any sessions.
+  console.log(`  1. Open ${c.cyan(APP_URL)} → your project → the ${c.bold('Workbench')} → ${c.bold('Connect a machine')}.`);
   console.log(`  2. Enter this code:   ${c.bold(c.green(pretty))}\n`);
   info('waiting for you to approve…');