heyspex 0.1.0

package/scripts/dev-server-status.mjs

@@ -0,0 +1,722 @@
+#!/usr/bin/env node
+/**
+ * dev-server-status — ground-truth answer to "is the spex-console dev server
+ * running, and on what port(s)?"
+ *
+ * Why this exists: the only prior signal was `.heyspex/dev-server.lock.json`,
+ * and that file can LIE — a stale lock (the launcher died uncleanly), an
+ * untracked server (someone ran bare `next dev` with no wrapper, so no lock),
+ * a port conflict, or two servers at once. An agent that trusts the file can
+ * start a database migration "while the server is down" when it is actually
+ * up — which strands the running server's in-memory schema and forces a
+ * restart. (That incident is what this capability prevents.)
+ *
+ * The fix: derive truth from the OS, never from the lockfile alone.
+ *   1. HTTP-probe candidate ports — liveness is the authoritative "is it up?".
+ *   2. OS-scan the same ports (Get-NetTCPConnection on Windows, lsof/ss on
+ *      Unix — the read-only half of the kill-ports skill) for pid/name.
+ *   3. Read the lockfile + .heyspex/console-url ONLY as hints to attribute a
+ *      pid/url and to detect disagreement.
+ *   4. Emit explicit discrepancy flags (stale_lock, untracked_server,
+ *      multiple_servers, port_mismatch) so every way the file could be wrong
+ *      is surfaced, not hidden.
+ *
+ * The `running` verdict comes from the HTTP probe, so the answer is grounded
+ * in what is actually listening — it cannot be a false positive off a stale
+ * file, nor a false negative when an untracked server is up.
+ *
+ * Three faces share this core (per the "capability = core → MCP + CLI" rule):
+ *   - MCP tool   heyspex_dev_server_status   (vendor/heyspex-mcp/cli.mjs)
+ *   - hs CLI     hs server status            (bin/hs.mjs → runs this file)
+ *   - PreToolUse hook reminder               (scripts/claude-hooks/…)
+ *
+ * Run directly:  node scripts/dev-server-status.mjs [--json]
+ * Import:        import { getDevServerStatus } from './dev-server-status.mjs'
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import http from 'node:http';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+// `/api/version` is the spex-console liveness endpoint (cheap JSON, no page
+// render). Probing `/` false-negatives during Next dev JIT compiles — the full
+// app shell can exceed 2s while API routes the UI already uses keep returning
+// 200. See HS-EPIC-OBSV.
+const HTTP_PROBE_TIMEOUT_MS = 4000;
+const PROBE_PATH = '/api/version';
+// HS-09JU: a single 4s probe can miss a live-but-cold-compiling server (Next
+// dev JIT-compiling the /api/version route) and false-flag it dead
+// (running:false, stale_lock) — the exact false positive that made agents
+// start a duplicate server against an already-live one. One retry after a
+// backoff is enough to ride out a cold compile without materially slowing
+// down the common "genuinely nothing there" case (connection refused/reset
+// returns near-instantly, so the retry+delay path is only paid when a real
+// TCP timeout occurred on the first attempt).
+const PROBE_RETRY_ATTEMPTS = 2;
+const PROBE_RETRY_DELAY_MS = 1500;
+// HS-D4O9-DIAG: API routes answering is NOT proof the console is usable — a
+// missing dependency (the incident: @clerk/nextjs declared but not installed)
+// left every PAGE route throwing "Cannot find module" while API handlers kept
+// returning 200, so the API-only probe reported a dead UI as healthy. A SECOND
+// probe against a real page route catches this — the broken layout.tsx sat
+// ABOVE every route, so any page route would have caught the incident. /sign-in
+// specifically because it's the route the HS-D4O9-DIAG fix was verified against
+// (confirmed 200 post-fix; the diagnosis's own AC4 recommendation names it) —
+// prefer a route that renders REAL content over one that may 404 (a 404 still
+// proves the framework compiled/routed, but a 200 is stronger positive
+// evidence). `ok` below still treats any non-5xx as healthy, so an environment
+// where /sign-in genuinely doesn't exist degrades to "route not found", never
+// a false failure. Longer timeout than the API probe — a page render can be
+// slower than a JSON handler, especially on the first post-restart compile.
+const PAGE_PROBE_PATH = '/sign-in';
+const PAGE_PROBE_TIMEOUT_MS = 6000;
+const OS_SCAN_TIMEOUT_MS = 2500;
+// Default candidate ports: Next dev defaults plus a few it bumps to when 3000
+// is taken (3000 → 3001 → … ). Kept small on purpose — a wide range would slow
+// the probe and is rarely needed; the lockfile / console-url ports are added on
+// top so an auto-bumped server is still found.
+const DEFAULT_PORTS = [3000, 3001, 3002, 3003, 3004, 3005];
+
+function defaultVaultRoot() {
+  // Honor the same override the hs CLI uses; otherwise fall back to this file's
+  // own location (it lives at <vaultRoot>/scripts/, so one level up is the root).
+  if (process.env.HS_VAULT_ROOT) return process.env.HS_VAULT_ROOT;
+  return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+}
+
+function readLockfile(vaultRoot) {
+  const file = path.join(vaultRoot, '.heyspex', 'dev-server.lock.json');
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (parsed && typeof parsed === 'object') {
+      return {
+        present: true,
+        pid: typeof parsed.pid === 'number' ? parsed.pid : null,
+        url: typeof parsed.url === 'string' ? parsed.url : null,
+        startedAt: typeof parsed.startedAt === 'string' ? parsed.startedAt : null,
+        // Bind host, recorded by ensure-next-dev.mjs. `host` is the interface
+        // passed to `next dev -H`; `lan` says whether that interface is
+        // reachable from off this machine. null on a lock written by an older
+        // launcher — UNKNOWN, which readers must not read as "loopback".
+        host: typeof parsed.host === 'string' ? parsed.host : null,
+        lan: typeof parsed.lan === 'boolean' ? parsed.lan : null,
+      };
+    }
+  } catch {
+    // Missing or malformed — no lock.
+  }
+  return { present: false, pid: null, url: null, startedAt: null, host: null, lan: null };
+}
+
+function readConsoleUrlFile(vaultRoot) {
+  for (const name of ['console-url', 'cockpit-url']) { // legacy-cockpit fallback
+    try {
+      const raw = fs.readFileSync(path.join(vaultRoot, '.heyspex', name), 'utf8').trim();
+      if (raw.length > 0) return raw.replace(/\/+$/, '');
+    } catch {
+      // try next candidate
+    }
+  }
+  return null;
+}
+
+/**
+ * Atomically publish the live console origin for MCP + hooks ([[HS-EPIC-PT8A]]).
+ * Called by ensure-next-dev on bind and by the MCP transport recovery path when
+ * a port scan finds the console on a port the stale discovery file missed.
+ */
+export function writeConsoleUrlFile(vaultRoot, url) {
+  const root = vaultRoot || defaultVaultRoot();
+  const dir = path.join(root, '.heyspex');
+  fs.mkdirSync(dir, { recursive: true });
+  const file = path.join(dir, 'console-url');
+  const tmp = `${file}.${process.pid}.tmp`;
+  const normalized = String(url).trim().replace(/\/+$/, '');
+  fs.writeFileSync(tmp, `${normalized}\n`, 'utf8');
+  fs.renameSync(tmp, file);
+  try {
+    fs.writeFileSync(path.join(dir, 'cockpit-url'), `${normalized}\n`, 'utf8'); // legacy-cockpit shadow
+  } catch {
+    // Best-effort — canonical console-url above is authoritative.
+  }
+  return normalized;
+}
+
+// Signal-0 liveness probe — mirrors pidAlive() in ensure-next-dev.mjs. EPERM
+// means the process exists but is owned by another user, so it is still alive.
+function pidAlive(pid) {
+  if (!pid || typeof pid !== 'number') return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === 'EPERM';
+  }
+}
+
+function portFromUrl(url) {
+  if (typeof url !== 'string') return null;
+  try {
+    const u = new URL(url);
+    if (u.port) return Number(u.port);
+    return u.protocol === 'https:' ? 443 : 80;
+  } catch {
+    return null;
+  }
+}
+
+function candidatePorts(vaultRoot, override) {
+  if (Array.isArray(override) && override.length > 0) {
+    return [...new Set(override.map(Number).filter((n) => Number.isInteger(n) && n > 0))];
+  }
+  const lock = readLockfile(vaultRoot);
+  const fromLock = portFromUrl(lock.url);
+  const fromConsole = portFromUrl(readConsoleUrlFile(vaultRoot));
+  const ports = [...DEFAULT_PORTS];
+  if (fromLock) ports.push(fromLock);
+  if (fromConsole) ports.push(fromConsole);
+  return [...new Set(ports)];
+}
+
+// ---- OS-level listener scan (pid attribution; best-effort) -----------------
+
+function scanListenersWindows(ports) {
+  // Read-only twin of kill-ports.ps1's Get-PortListeners. PowerShell 5.1's
+  // ConvertTo-Json emits a bare object for a single row, so we force an array
+  // and parse defensively below.
+  const portList = ports.join(',');
+  const script =
+    `$ports=@(${portList});` +
+    `$rows=@(Get-NetTCPConnection -State Listen -LocalPort $ports -ErrorAction SilentlyContinue|` +
+    `ForEach-Object{$p=Get-Process -Id $_.OwningProcess -ErrorAction SilentlyContinue;` +
+    `[pscustomobject]@{port=[int]$_.LocalPort;pid=[int]$_.OwningProcess;name=if($p){$p.ProcessName}else{''}}});` +
+    `ConvertTo-Json -InputObject $rows -Compress`;
+  const res = spawnSync(
+    'powershell',
+    ['-NoProfile', '-NonInteractive', '-Command', script],
+    { encoding: 'utf8', timeout: OS_SCAN_TIMEOUT_MS },
+  );
+  if (res.status !== 0 || !res.stdout) return [];
+  let parsed;
+  try {
+    parsed = JSON.parse(res.stdout.trim());
+  } catch {
+    return [];
+  }
+  const rows = Array.isArray(parsed) ? parsed : [parsed];
+  return rows
+    .filter((r) => r && Number.isInteger(r.port))
+    .map((r) => ({ port: r.port, pid: Number.isInteger(r.pid) ? r.pid : null, name: r.name || '' }));
+}
+
+function scanListenersUnix(ports) {
+  const rows = [];
+  const haveLsof = spawnSync('sh', ['-c', 'command -v lsof'], { encoding: 'utf8' }).status === 0;
+  for (const port of ports) {
+    let pids = [];
+    if (haveLsof) {
+      const res = spawnSync('lsof', ['-t', '-nP', `-iTCP:${port}`, '-sTCP:LISTEN'], {
+        encoding: 'utf8',
+        timeout: OS_SCAN_TIMEOUT_MS,
+      });
+      if (res.stdout) pids = res.stdout.split('\n').map((s) => Number(s.trim())).filter(Boolean);
+    } else {
+      const res = spawnSync('ss', ['-ltnp', `sport = :${port}`], {
+        encoding: 'utf8',
+        timeout: OS_SCAN_TIMEOUT_MS,
+      });
+      if (res.stdout) {
+        for (const m of res.stdout.matchAll(/pid=(\d+)/g)) pids.push(Number(m[1]));
+      }
+    }
+    for (const pid of [...new Set(pids)]) {
+      let name = '';
+      const ps = spawnSync('ps', ['-p', String(pid), '-o', 'comm='], { encoding: 'utf8' });
+      if (ps.stdout) name = ps.stdout.trim();
+      rows.push({ port, pid, name });
+    }
+  }
+  return rows;
+}
+
+function scanListeners(ports) {
+  try {
+    return process.platform === 'win32' ? scanListenersWindows(ports) : scanListenersUnix(ports);
+  } catch {
+    // OS scan is best-effort — HTTP probe still establishes liveness without it.
+    return [];
+  }
+}
+
+// A spex-console dev server (however it was started — wrapper, bare `next
+// dev`, a manual `-p 8080`) is always a `node` process. Filtering the wide
+// scan to this name keeps it from ballooning into probing every unrelated
+// listener on the machine (browsers, Docker, print spooler, …) the way an
+// unfiltered machine-wide scan would.
+function isNodeLikeListenerName(name) {
+  return /^node(\.exe)?$/i.test(name || '');
+}
+
+// ---- Wide OS scan (no port filter) — HS-09JU ------------------------------
+//
+// `scanListeners(ports)` above only ever confirms ports ALREADY in the
+// candidate set (DEFAULT_PORTS + lockfile/console-url hints). A live console
+// server that Next auto-bumped past 3005, or that someone started with a
+// manual `-p`, is invisible to it — the exact "off-candidate-port live server
+// reported dead" false positive from the diagnosis. This scan has NO port
+// filter, so it sees every listener on the machine, then narrows to node-like
+// process names before returning — the discovered ports get folded into the
+// HTTP probe list by getDevServerStatus, not returned as candidates on their
+// own (an unrelated node process squatting some other port must still fail
+// the API-probe 'console' classification before it counts as a hit).
+function scanWideListenersWindows() {
+  const script =
+    `$rows=@(Get-NetTCPConnection -State Listen -ErrorAction SilentlyContinue|` +
+    `ForEach-Object{$p=Get-Process -Id $_.OwningProcess -ErrorAction SilentlyContinue;` +
+    `[pscustomobject]@{port=[int]$_.LocalPort;pid=[int]$_.OwningProcess;name=if($p){$p.ProcessName}else{''}}});` +
+    `ConvertTo-Json -InputObject $rows -Compress`;
+  const res = spawnSync(
+    'powershell',
+    ['-NoProfile', '-NonInteractive', '-Command', script],
+    { encoding: 'utf8', timeout: OS_SCAN_TIMEOUT_MS },
+  );
+  if (res.status !== 0 || !res.stdout) return [];
+  let parsed;
+  try {
+    parsed = JSON.parse(res.stdout.trim());
+  } catch {
+    return [];
+  }
+  const rows = Array.isArray(parsed) ? parsed : [parsed];
+  return rows
+    .filter((r) => r && Number.isInteger(r.port) && isNodeLikeListenerName(r.name))
+    .map((r) => ({ port: r.port, pid: Number.isInteger(r.pid) ? r.pid : null, name: r.name || '' }));
+}
+
+function scanWideListenersUnix() {
+  const haveLsof = spawnSync('sh', ['-c', 'command -v lsof'], { encoding: 'utf8' }).status === 0;
+  const rows = [];
+  if (haveLsof) {
+    const res = spawnSync('lsof', ['-iTCP', '-sTCP:LISTEN', '-nP'], {
+      encoding: 'utf8',
+      timeout: OS_SCAN_TIMEOUT_MS,
+    });
+    if (!res.stdout) return [];
+    for (const line of res.stdout.split('\n').slice(1)) { // header row first
+      const cols = line.trim().split(/\s+/);
+      if (cols.length < 9) continue;
+      const name = cols[0];
+      const pid = Number(cols[1]);
+      const addr = cols[8];
+      const portMatch = addr && addr.match(/:(\d+)$/);
+      if (!portMatch || !isNodeLikeListenerName(name)) continue;
+      rows.push({ port: Number(portMatch[1]), pid: Number.isInteger(pid) ? pid : null, name });
+    }
+    return rows;
+  }
+  const res = spawnSync('ss', ['-ltnp'], { encoding: 'utf8', timeout: OS_SCAN_TIMEOUT_MS });
+  if (!res.stdout) return [];
+  for (const line of res.stdout.split('\n')) {
+    const portMatch = line.match(/:(\d+)\s/);
+    const nameMatch = line.match(/users:\(\("([^"]+)"/);
+    if (!portMatch || !nameMatch || !isNodeLikeListenerName(nameMatch[1])) continue;
+    const pidMatch = line.match(/pid=(\d+)/);
+    rows.push({ port: Number(portMatch[1]), pid: pidMatch ? Number(pidMatch[1]) : null, name: nameMatch[1] });
+  }
+  return rows;
+}
+
+function scanWideListeners() {
+  try {
+    return process.platform === 'win32' ? scanWideListenersWindows() : scanWideListenersUnix();
+  } catch {
+    // Best-effort discovery only — the base candidatePorts scan still covers
+    // the common case without this.
+    return [];
+  }
+}
+
+// ---- HTTP liveness + identity probe (authoritative "is it up?") ------------
+
+function probePort(port) {
+  return new Promise((resolve) => {
+    const req = http.request(
+      // Probe `localhost` (not a hardcoded 127.0.0.1) so resolution matches how
+      // Next bound — on Windows `localhost` often resolves to ::1 (IPv6), and a
+      // hardcoded IPv4 connect would miss a server listening only on ::1.
+      { host: 'localhost', port, path: PROBE_PATH, method: 'GET', timeout: HTTP_PROBE_TIMEOUT_MS },
+      (res) => {
+        const poweredBy = String(res.headers['x-powered-by'] || '');
+        const chunks = [];
+        let bytes = 0;
+        res.on('data', (chunk) => {
+          if (bytes < 512) chunks.push(chunk);
+          bytes += chunk.length;
+        });
+        res.on('end', () => {
+          const body = Buffer.concat(chunks).toString('utf8');
+          const isConsole =
+            /next/i.test(poweredBy) ||
+            (res.statusCode === 200 &&
+              String(res.headers['content-type'] || '').includes('application/json') &&
+              (() => {
+                try {
+                  return typeof JSON.parse(body).buildId === 'string';
+                } catch {
+                  return false;
+                }
+              })());
+          resolve({
+            port,
+            responded: true,
+            httpStatus: res.statusCode ?? null,
+            probe: isConsole ? 'console' : 'unknown',
+          });
+        });
+      },
+    );
+    req.on('timeout', () => {
+      req.destroy();
+      resolve({ port, responded: false, httpStatus: null, probe: 'no-response' });
+    });
+    req.on('error', () => {
+      resolve({ port, responded: false, httpStatus: null, probe: 'no-response' });
+    });
+    req.end();
+  });
+}
+
+// HS-09JU: retry probePort with backoff before concluding a port is dead.
+// A single 4s attempt can land squarely inside a cold Next dev compile and
+// miss it; a retry after PROBE_RETRY_DELAY_MS gives the compile a second
+// window. Returns as soon as any attempt responds — this only adds latency to
+// the "actually not there" case, never to the "it's live" case.
+async function probePortWithRetry(port) {
+  let last = { port, responded: false, httpStatus: null, probe: 'no-response' };
+  for (let attempt = 0; attempt < PROBE_RETRY_ATTEMPTS; attempt++) {
+    last = await probePort(port);
+    if (last.responded) return last;
+    if (attempt < PROBE_RETRY_ATTEMPTS - 1) {
+      await new Promise((resolve) => setTimeout(resolve, PROBE_RETRY_DELAY_MS));
+    }
+  }
+  return last;
+}
+
+// HS-D4O9-DIAG: the PAGE-render probe — a second, independent liveness check
+// against a real page ROUTE (not an API handler). A 5xx response or a timeout
+// means the root layout/page cannot compile; 2xx/3xx/4xx all mean the
+// framework itself is up and routing (a 404 is a routing miss, not a compile
+// failure; a 3xx is a legitimate auth-middleware redirect, e.g. Clerk sending
+// an unauthenticated request to /sign-in — neither should be misread as
+// "broken"). Mirrors probePort's { responded, httpStatus } shape but adds
+// `ok` (the pass/fail verdict this probe exists to produce) instead of a
+// console/unknown classification, which only the API probe needs.
+function probePage(port, pagePath = PAGE_PROBE_PATH) {
+  return new Promise((resolve) => {
+    const req = http.request(
+      { host: 'localhost', port, path: pagePath, method: 'GET', timeout: PAGE_PROBE_TIMEOUT_MS },
+      (res) => {
+        res.resume(); // drain the body — only the status code matters here
+        res.on('end', () => {
+          const httpStatus = res.statusCode ?? null;
+          resolve({
+            path: pagePath,
+            responded: true,
+            httpStatus,
+            timedOut: false,
+            ok: typeof httpStatus === 'number' && httpStatus < 500,
+          });
+        });
+      },
+    );
+    req.on('timeout', () => {
+      req.destroy();
+      resolve({ path: pagePath, responded: false, httpStatus: null, timedOut: true, ok: false });
+    });
+    req.on('error', () => {
+      resolve({ path: pagePath, responded: false, httpStatus: null, timedOut: false, ok: false });
+    });
+    req.end();
+  });
+}
+
+// ---- Discrepancy guidance (HS-09JU) -----------------------------------------
+//
+// Every discrepancy flag below fires ONLY in the presence of some server
+// evidence (a live console server the lockfile doesn't vouch for, a lock
+// pointing at the wrong port, a page-render failure on an otherwise-live
+// server, …) — none of them mean "nothing is running, go ahead and start
+// one". Pre-fix, callers (the SessionStart awareness hook, agents reading
+// this tool's output) read "trust the verdict and any discrepancy flags" as
+// license to treat a flag as a restart TRIGGER; the flags are diagnostic
+// information about WHY the lockfile disagreed with reality, not a verdict
+// that no server exists. This table is additive — `discrepancies` (the plain
+// string codes) is unchanged for existing consumers; `discrepancyGuidance`
+// is the new field that spells out the correct reading for each code.
+const DISCREPANCY_GUIDANCE_TEXT = {
+  stale_lock:
+    'The lockfile looks stale (its recorded launcher pid is dead, or it claims a server that is not answering) — this is NOT proof no server is running. A launcher can die on Windows while the `next dev` it started keeps running. Check `running`/`servers` in THIS SAME response first: if a console server is listed, do NOT start a new one — reuse it. Only treat the server as actually down when `running` is false and no server entry answers.',
+  untracked_server:
+    'A live spex-console server is answering that no lockfile/console-url vouches for (started outside the wrapper with a bare `next dev`, or the discovery file was cleaned). This means a server IS running right now — do NOT start a second one; two servers compiling into the same .next corrupts it. Reuse the server shown in `servers`; only stop-then-relaunch via `npm run dev` if you specifically need it wrapper-managed.',
+  port_mismatch:
+    'The lockfile points at one port but the live console server is answering on a different one. A server IS running (see `servers`) — do not start a new one; use the port shown in `servers`, not the lockfile\'s port.',
+  multiple_servers:
+    'More than one console server is answering at once — this is the corrupted-.next state two concurrent `next dev` processes cause. Do NOT start another. Stop the extras first (`hs server stop` / `npm run console:stop`).',
+  page_probe_failed:
+    'The API probe answered but a real page route failed to render (HS-D4O9-DIAG: e.g. a missing dependency leaves every page throwing while API handlers keep answering 200). The server is up but likely broken — check server logs / reinstall deps. Restarting the dev server will usually NOT fix this on its own, so do not treat this flag as "not running".',
+};
+
+/**
+ * Expand `discrepancies` (plain string codes, unchanged for backward
+ * compatibility) into the guidance objects new callers should read instead of
+ * inferring meaning from the bare code. Every known code is restart-blocking
+ * by construction (see the table's own comment above) — an unrecognized
+ * future code still gets a safe generic message rather than being silently
+ * dropped.
+ */
+function buildDiscrepancyGuidance(discrepancies) {
+  return discrepancies.map((code) => ({
+    code,
+    restartBlocking: true,
+    message:
+      DISCREPANCY_GUIDANCE_TEXT[code] ||
+      'Diagnostic flag — verify `running`/`servers` above before treating this as license to start a server.',
+  }));
+}
+
+/**
+ * Ground-truth dev-server status. Returns a structured verdict whose `running`
+ * field is derived from the HTTP probe (never from the lockfile alone), plus
+ * the discrepancy flags that name every way the lockfile disagreed with reality.
+ */
+export async function getDevServerStatus({ vaultRoot, ports, pagePath } = {}) {
+  const root = vaultRoot || defaultVaultRoot();
+  const basePorts = candidatePorts(root, ports);
+
+  // HS-09JU: fold in any node-like listener the wide OS scan finds outside
+  // `basePorts` (DEFAULT_PORTS + lockfile/console-url hints) — a live console
+  // server that Next auto-bumped past 3005, or that was started with a manual
+  // `-p`, must still be found and probed, not reported dead just because it's
+  // off the well-known range. Skipped when the caller passed an explicit
+  // `ports` override (tests, a narrowed `hs server status` check) — that's
+  // "check exactly these ports", so widening would defeat the point.
+  const explicitPorts = Array.isArray(ports) && ports.length > 0;
+  const wideRows = explicitPorts ? [] : scanWideListeners();
+  const discoveredPorts = wideRows.map((r) => r.port).filter((p) => !basePorts.includes(p));
+  const portsToCheck = [...new Set([...basePorts, ...discoveredPorts])];
+
+  const [probes, baseOsRows] = await Promise.all([
+    Promise.all(portsToCheck.map((p) => probePortWithRetry(p))),
+    Promise.resolve(scanListeners(basePorts)),
+  ]);
+
+  const osByPort = new Map();
+  for (const row of baseOsRows) {
+    if (!osByPort.has(row.port)) osByPort.set(row.port, row);
+  }
+  // Ports the wide scan discovered aren't in `basePorts`, so the exact-match
+  // scan above never attributed them — attribute them from the wide scan's
+  // own pid/name data instead (it already has it; no third OS call needed).
+  for (const row of wideRows) {
+    if (!osByPort.has(row.port)) osByPort.set(row.port, row);
+  }
+  const osRows = [...osByPort.values()];
+
+  // A server entry exists for any port that EITHER answered HTTP OR the OS
+  // reports as listening — so an OS-listening-but-HTTP-dead port is still shown.
+  const ports_seen = new Set([
+    ...probes.filter((p) => p.responded).map((p) => p.port),
+    ...osRows.map((r) => r.port),
+  ]);
+
+  // HS-D4O9-DIAG: the page probe only makes sense against a port the API probe
+  // already identified as spex-console — probing an 'unknown'/'no-response' port
+  // for a page render would just add noise, and a port with no server at all has
+  // nothing to probe. Run these in parallel with everything above already
+  // resolved so we know exactly which ports qualify.
+  const consolePorts = [...ports_seen].filter(
+    (port) => (probes.find((p) => p.port === port) || {}).probe === 'console',
+  );
+  const pageProbes = await Promise.all(consolePorts.map((port) => probePage(port, pagePath)));
+  const pageProbeByPort = new Map(consolePorts.map((port, i) => [port, pageProbes[i]]));
+
+  const servers = [...ports_seen]
+    .sort((a, b) => a - b)
+    .map((port) => {
+      const probe = probes.find((p) => p.port === port) || { responded: false, httpStatus: null, probe: 'no-response' };
+      const os = osByPort.get(port) || { pid: null, name: '' };
+      return {
+        port,
+        pid: os.pid,
+        name: os.name,
+        url: `http://localhost:${port}`,
+        listening: true,
+        responded: probe.responded,
+        httpStatus: probe.httpStatus,
+        probe: probe.probe, // 'console' | 'unknown' | 'no-response'
+        // Additive (HS-D4O9-DIAG): null for any port the API probe didn't call
+        // 'console' — the page probe never runs against those.
+        pageProbe: pageProbeByPort.get(port) ?? null,
+      };
+    });
+
+  const consoleServers = servers.filter((s) => s.probe === 'console');
+  const running = consoleServers.length > 0;
+  // Additive top-level summary (HS-D4O9-DIAG): true only when every identified
+  // console server's page probe also succeeded; null when there is no console
+  // server to judge (distinct from false — "not applicable" vs "checked and
+  // failed"). Deliberately NOT folded into `running` — that field's existing
+  // API-probe-only meaning stays backward compatible for callers already keyed
+  // off it; this is the new, stricter "is the UI actually usable" signal.
+  const uiHealthy = consoleServers.length === 0 ? null : consoleServers.every((s) => s.pageProbe?.ok === true);
+
+  const lock = readLockfile(root);
+  const lockfile = {
+    present: lock.present,
+    pid: lock.pid,
+    url: lock.url,
+    startedAt: lock.startedAt,
+    // Bind host as the launcher recorded it. null ⇒ UNKNOWN (no lock, or a lock
+    // written before the loopback-default change) — never read null as loopback.
+    host: lock.host,
+    lan: lock.lan,
+    pidAlive: lock.present ? pidAlive(lock.pid) : null,
+  };
+  const consoleUrlFile = readConsoleUrlFile(root);
+
+  // ---- Reconcile: surface every disagreement ----
+  //
+  // Reconcile by PORT, not pid. The lock records the LAUNCHER pid
+  // (ensure-next-dev.mjs), while the OS reports the listening pid (its child
+  // `next dev`) — they never match, so a pid comparison would false-flag every
+  // properly-wrapped server as untracked. The port the lock points at is the
+  // stable join key.
+  const discrepancies = [];
+  const lockPort = portFromUrl(lock.url);
+  // Ports the lockfile / console-url file vouch for (a console server here is
+  // "tracked"). console-url alone is a weaker signal (it isn't cleared as
+  // reliably as the lock), so it only widens the tracked set, never narrows it.
+  const trackedPorts = new Set([lockPort, portFromUrl(consoleUrlFile)].filter((p) => p != null));
+
+  if (lock.present) {
+    if (!lockfile.pidAlive) {
+      // Launcher process is gone but the lock file survives → stale.
+      discrepancies.push('stale_lock');
+    } else if (consoleServers.length === 0) {
+      // Lock claims a live server (launcher alive) but nothing console-like is
+      // actually answering → the lock is lying about "running".
+      discrepancies.push('stale_lock');
+    }
+    if (lockPort != null && consoleServers.length > 0 && !consoleServers.some((s) => s.port === lockPort)) {
+      // Lock points at one port; the live console server is on another.
+      discrepancies.push('port_mismatch');
+    }
+  }
+
+  if (consoleServers.some((s) => !trackedPorts.has(s.port))) {
+    // A live console server on a port no lock/console-url vouches for — a bare
+    // `next dev` started outside the wrapper, with no lock to record it.
+    discrepancies.push('untracked_server');
+  }
+
+  if (consoleServers.length > 1) discrepancies.push('multiple_servers');
+
+  // HS-D4O9-DIAG: the API probe answering is NOT proof the console is usable —
+  // surface the page-compile failure as its own discrepancy so a caller that
+  // already inspects `discrepancies` (the existing extension point for "the
+  // lockfile/API signal disagrees with reality") picks this up for free,
+  // without needing to know about the new `uiHealthy`/`pageProbe` fields.
+  if (consoleServers.some((s) => s.pageProbe && s.pageProbe.ok === false)) {
+    discrepancies.push('page_probe_failed');
+  }
+
+  return {
+    running,
+    // Additive (HS-D4O9-DIAG): the stricter "does the UI actually render"
+    // signal — see the field's own comment above for why it's separate from
+    // `running` rather than folded into it. null = no console server to judge.
+    uiHealthy,
+    servers,
+    lockfile,
+    consoleUrlFile,
+    candidatePorts: portsToCheck,
+    discrepancies: [...new Set(discrepancies)],
+    // Additive (HS-09JU): the corrected reading of `discrepancies` — every
+    // entry is restart-BLOCKING (evidence a server exists), never a restart
+    // trigger. See DISCREPANCY_GUIDANCE_TEXT above for the per-code rationale.
+    discrepancyGuidance: buildDiscrepancyGuidance([...new Set(discrepancies)]),
+    platform: process.platform,
+    checkedAt: new Date().toISOString(),
+  };
+}
+
+// ---- Human-readable one-liner (for the CLI + hook reminders) ---------------
+
+export function summarizeStatus(status) {
+  if (!status.running && status.servers.length === 0) {
+    return 'Dev server: NOT running (no listener on candidate ports).';
+  }
+  const parts = status.servers.map((s) => {
+    const who = s.pid ? ` pid ${s.pid}${s.name ? ` (${s.name})` : ''}` : '';
+    const tag =
+      s.probe === 'console' ? 'spex-console' : s.probe === 'unknown' ? 'non-console process' : 'listening, no HTTP response';
+    // HS-D4O9-DIAG: name the page-probe failure right on the server line — the
+    // discrepancy list below already carries `page_probe_failed`, but a human
+    // scanning per-server lines should see it without cross-referencing.
+    const pageNote =
+      s.pageProbe && s.pageProbe.ok === false
+        ? ` — ⚠ PAGE PROBE FAILED (${s.pageProbe.timedOut ? 'timeout' : `HTTP ${s.pageProbe.httpStatus ?? 'no response'}`} on ${s.pageProbe.path})`
+        : '';
+    return `:${s.port} — ${tag}${who}${pageNote}`;
+  });
+  // running=true (API answered) but uiHealthy===false (page compile failed) is
+  // exactly the HS-D4O9-DIAG false-positive this fix closes — the headline must
+  // say so instead of a flat "RUNNING" that reads as "everything is fine".
+  const head = !status.running
+    ? 'Dev server: port(s) occupied (no console identified)'
+    : status.uiHealthy === false
+      ? 'Dev server: RUNNING but UI NOT rendering (API up, page compile FAILED)'
+      : 'Dev server: RUNNING';
+  // HS-09JU: discrepancies are diagnostic, not restart triggers — a flag next
+  // to a RUNNING headline still means "a server exists"; spell that out here
+  // so a human (or an agent) reading only this line, not the JSON, doesn't
+  // misread the flag list as "start a new one".
+  const flags = status.discrepancies.length
+    ? `\n⚠ discrepancies (diagnostic — do NOT restart because of these; see \`running\`/\`servers\` above): ${status.discrepancies.join(', ')}`
+    : '';
+  // Bind host: only worth a line when the launcher recorded one. LAN mode is
+  // called out because it is the state that exposes the console off-machine.
+  const lock = status.lockfile;
+  const bind = !lock?.present
+    ? ''
+    : lock.lan === true
+      ? `\n  bind: ${lock.host ?? '?'} — ⚠ LAN MODE (reachable from your network; only /api/env-vault/join needs this)`
+      : lock.lan === false
+        ? `\n  bind: ${lock.host ?? '?'} — loopback only`
+        : '';
+  return `${head}\n  ${parts.join('\n  ')}${bind}${flags}`;
+}
+
+// ---- CLI entrypoint --------------------------------------------------------
+
+const invokedDirectly = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (invokedDirectly) {
+  const asJson = process.argv.includes('--json');
+  getDevServerStatus()
+    .then((status) => {
+      if (asJson) {
+        process.stdout.write(JSON.stringify(status, null, 2) + '\n');
+      } else {
+        process.stdout.write(summarizeStatus(status) + '\n');
+      }
+      process.exit(0);
+    })
+    .catch((err) => {
+      // Even on failure, print a usable message and exit 0 — callers (hook, CLI)
+      // should never be broken by a status check.
+      process.stdout.write(`Dev server status check failed: ${err?.message ?? err}\n`);
+      process.exit(0);
+    });
+}