@codeyam-editor/codeyam-editor 0.1.5 → 0.1.7

package/npm/fleet-prewarm.js

@@ -25,6 +25,14 @@ const MARKER_PUBLISH_SKIPPED = 'CY_BINARY_PUBLISH_SKIPPED'; // pacer will NOT pu
 const MARKER_PATH_PULL = 'CY_PROVISION_PATH pull'; // this VM pulled a prebuilt image (~2 min fast path)
 const MARKER_PATH_COMPILE = 'CY_PROVISION_PATH compile'; // this VM compiled from source (~10 min slow path)
 
+// Markers scripts/cloud-refresh-binary.sh emits into the between-session
+// refresh log (/tmp/dash-refresh-binary-vm-<n>.log, or the systemd journal when
+// the timer runs it unattended). Same stable-contract rule as the four above.
+const MARKER_REFRESHED = 'CY_BINARY_REFRESHED'; // pulled + swapped a newer published binary, container restarted
+const MARKER_REFRESH_CURRENT = 'CY_BINARY_CURRENT'; // already on the newest published binary; nothing to do
+const MARKER_REFRESH_DEFERRED = 'CY_BINARY_REFRESH_DEFERRED'; // newer binary exists but a session is live (or state unknown)
+const MARKER_REFRESH_DEGRADED = 'CY_DEGRADED binary-refresh'; // the refresh could NOT complete — this VM may be running stale
+
 // Mirror scripts/gcp-bootstrap.sh's BRANCH_SLUG: '/' → '-', lowercased, capped
 // at 128 chars. The dashboard and the VM MUST agree on the slug or the probe
 // checks different tags than the bootstrap pulls. Empty / missing branch → the
@@ -53,7 +61,7 @@ function usableImageTags({ registry, branch } = {}) {
   return tags;
 }
 
-// The core verdict: should a batch add pace one VM ahead of the rest?
+// The core verdict: should a cold add pace one VM to compile+publish first?
 //
 //   count           how many VMs the operator asked to add
 //   hasUsableImage  the probe result — true (image present), false (definitely
@@ -61,24 +69,46 @@ function usableImageTags({ registry, branch } = {}) {
 //   hasPushToken    a write:packages token is present, so the pacer CAN publish
 //
 // Pace ONLY when it strictly pays AND can work:
-//   - count > 1            — a single add is never serialized (never slower)
-//   - hasUsableImage === false — known-absent; an existing image means all N can
-//                                pull concurrently, and `null` (unknown) falls
-//                                back to today's fan-out rather than risk a
-//                                10-min serialization that buys nothing
+//   - count >= 1           — a batch (k>1) serializes ONE ahead so the rest pull;
+//                            a single cold add (k==1) still paces so it PUBLISHES
+//                            the branch image, making every FUTURE add (single or
+//                            batch) pull instead of source-building. Gating the
+//                            publish behind k>1 was a bug: adding VMs one at a time
+//                            bypassed the pacer entirely, so no image was ever
+//                            produced and every single add recompiled.
+//   - hasUsableImage !== true — a usable image lets all N pull concurrently, so
+//                               only pace when one is NOT known to exist. Both
+//                               `false` (known-absent) AND `null` (undetermined)
+//                               pace: publishing is cheap + idempotent, and pacing
+//                               is the ONLY path that bootstraps self-feeding.
+//                               Fanning out on `null` is exactly what permanently
+//                               wedges a docker-less operator host whose probe can
+//                               never confirm absence (see
+//                               npm/cloud.js::probeUsableEditorImage) — republishing
+//                               an image that already existed is the harmless worst
+//                               case.
 //   - hasPushToken         — without it the pacer can't publish, so pacing would
 //                            just serialize N source compiles for no gain
-// Any miss → fan out all N immediately (today's behavior, strictly additive).
+// Fan out immediately only when a usable image is KNOWN to exist, or there is no
+// push token (today's behavior for those two cases, strictly additive).
 function decideBatchPrewarm({ count, hasUsableImage, hasPushToken } = {}) {
   const k = Math.round(Number(count) || 0);
-  if (k <= 1) return { pace: false, reason: 'single add — never serialized' };
+  if (k < 1) return { pace: false, reason: 'no VMs requested' };
   if (hasUsableImage === true)
     return { pace: false, reason: 'usable prebuilt image exists — all pull concurrently' };
-  if (hasUsableImage !== false)
-    return { pace: false, reason: 'image presence undetermined — fan out (no worse than today)' };
   if (!hasPushToken)
     return { pace: false, reason: 'no push token — pacer could not publish, fan out' };
-  return { pace: true, reason: `pacing 1 of ${k} — branch image absent, will publish for the rest` };
+  // hasUsableImage is `false` (known-absent) or `null` (undetermined); with a push
+  // token, pace either way to bootstrap self-feeding.
+  const basis = hasUsableImage === false
+    ? 'branch image absent'
+    : 'image presence undetermined — publishing to bootstrap self-feeding';
+  return {
+    pace: true,
+    reason: k > 1
+      ? `pacing 1 of ${k} — ${basis}, will publish for the rest`
+      : `single cold add — ${basis}, will compile and publish so future adds pull`,
+  };
 }
 
 // Has the pacer's add log settled to a definite publish outcome the held batch
@@ -149,11 +179,57 @@ function pushTokenDiagnostic({ hasPushToken } = {}) {
   };
 }
 
+// What did the last between-session binary refresh do? Parsed from the refresh
+// log for the VM card, so an operator can tell "up to date" from "could not
+// update" without opening a log.
+//
+// Returns 'refreshed' | 'current' | 'deferred' | 'degraded' | null (no refresh
+// has reported yet).
+//
+// The LAST marker wins, for the same reason provisionPath() takes the last one:
+// a tick that defers and a later tick that refreshes must read as refreshed,
+// not stay stuck on the older verdict. Ordering — not precedence between marker
+// kinds — is what makes this correct across repeated timer runs.
+//
+// `degraded` is deliberately a distinct state from `deferred`. Deferring is the
+// mechanism working as designed (a session is live, so we wait). Degraded means
+// the VM wanted a newer binary and could NOT get one — the silent-staleness
+// case this whole mechanism exists to make visible, and the only one that
+// warrants an operator's attention.
+function binaryRefreshState(logText) {
+  if (!logText || typeof logText !== 'string') return null;
+  const at = (marker) => logText.lastIndexOf(marker);
+  const candidates = [
+    ['refreshed', at(MARKER_REFRESHED)],
+    ['current', at(MARKER_REFRESH_CURRENT)],
+    ['deferred', at(MARKER_REFRESH_DEFERRED)],
+    ['degraded', at(MARKER_REFRESH_DEGRADED)],
+  ].filter(([, idx]) => idx >= 0);
+  if (!candidates.length) return null;
+  return candidates.reduce((best, cur) => (cur[1] > best[1] ? cur : best))[0];
+}
+
+// Operator-facing one-liner for a refresh state, for the VM card. null state →
+// null (render nothing — a VM that has never run a refresh is not a problem).
+function binaryRefreshLabel(state) {
+  if (state === 'refreshed') return 'editor binary refreshed to the newest published build';
+  if (state === 'current') return 'editor binary up to date';
+  if (state === 'deferred') return 'newer editor binary available — waiting for the session to end';
+  if (state === 'degraded') return 'could NOT refresh the editor binary — may be running stale';
+  return null;
+}
+
 module.exports = {
   MARKER_PUBLISHED,
   MARKER_PUBLISH_SKIPPED,
   MARKER_PATH_PULL,
   MARKER_PATH_COMPILE,
+  MARKER_REFRESHED,
+  MARKER_REFRESH_CURRENT,
+  MARKER_REFRESH_DEFERRED,
+  MARKER_REFRESH_DEGRADED,
+  binaryRefreshState,
+  binaryRefreshLabel,
   branchSlug,
   usableImageTags,
   decideBatchPrewarm,

package/npm/fleet-probe-transport.js

@@ -0,0 +1,155 @@
+'use strict';
+// The fleet dashboard's two LB-path HTTP probe transports, extracted from
+// scripts/operator/fleet-dashboard/server.js so their SOCKET LIFETIME is
+// testable.
+//
+// The undici contract, which is the whole reason this module exists: a `fetch`
+// response body is a stream that holds its connection open until it is read to
+// completion or explicitly cancelled. IGNORING `res.body` is NOT the same as
+// releasing it — the socket stays checked out of the agent's pool, and once the
+// peer sends FIN it parks in CLOSE-WAIT forever. Node's `http` module is the
+// opposite (an unread response pauses the socket, hence the `res.resume(); //
+// drain so the socket can close` in server.js's localGetJson), and that
+// asymmetry is what got missed when the fetch path was added.
+//
+// On 2026-08-01 that leaked 10,749 CLOSE-WAIT sockets to the fleet LB
+// (8.228.227.92:443) holding 128MB of unread IAP-login HTML in kernel receive
+// queues — ~460 sockets/hour, a ~1-day fuse — driving the dashboard cgroup into
+// swap-thrash until the node event loop stalled in `D` state and dashboard-bes
+// went UNHEALTHY while systemd still reported the unit active.
+//
+// So: EVERY return path here consumes or cancels the body. `fetch` is injected
+// rather than closed over, so a test can drive every branch with a body that
+// records whether it was cancelled.
+
+const fpt = require('./fleet-vm-probe-target');
+
+/** Release the connection behind a response we are not going to read.
+ *
+ *  Swallows its own failure deliberately. `cancel()` rejects when the body was
+ *  already consumed or already errored — in both cases the connection is
+ *  released anyway, so there is nothing to recover from and nothing to report.
+ *  Letting it throw would be actively harmful: these calls sit inside the
+ *  transports' `try`, so a rejection would be caught by the transport's own
+ *  catch and misclassify a perfectly good HTTP response as `unreachable`.
+ */
+async function disposeBody(res) {
+  try {
+    await res.body?.cancel();
+  } catch {
+    // Already consumed, already errored, or no body at all — connection is
+    // released either way.
+  }
+}
+
+/** GET JSON from a resolved LB target.
+ *
+ *  Uses redirect:'manual' so IAP's 302→accounts.google.com surfaces as a
+ *  classifiable response instead of the fetch silently following it and handing
+ *  us a login page that fails JSON parsing — which would read as "VM is down"
+ *  when the real fault is our token. That 302 carries a full HTML login page,
+ *  which is exactly why the non-ok return below must dispose of the body.
+ *
+ *  `deps` injects the transport's collaborators for tests: `fetchImpl` (default
+ *  global fetch) and `warn` (default console.warn).
+ */
+async function lbGetJson(target, timeout, deps = {}) {
+  const { fetchImpl = globalThis.fetch, warn = console.warn } = deps;
+  const ctl = new AbortController();
+  const timer = setTimeout(() => ctl.abort(), timeout);
+  try {
+    const res = await fetchImpl(target.url, {
+      headers: target.headers,
+      redirect: 'manual',
+      signal: ctl.signal,
+    });
+    const outcome = fpt.classifyProbeResponse({
+      status: res.status,
+      location: res.headers.get('location'),
+    });
+    if (outcome !== 'ok') {
+      // 401 and 403 share one outcome but have opposite fixes (OAuth client vs
+      // IAM grant). Name which one we hit, so the next misconfig is diagnosable
+      // from the log instead of a live curl against the backend.
+      const why = fpt.describeAuthMisconfig(res.status);
+      if (why) warn(`probe ${target.url}: HTTP ${res.status} — ${why}`);
+      await disposeBody(res);
+      return { outcome, json: null, status: res.status };
+    }
+    // `status` rides on every return so a caller can NAME the HTTP status in a
+    // fault warning. Without it a reachable-but-unusable body was indiscernible
+    // from a dead VM in the log — see probeBodyFault.
+    //
+    // Both branches below are body-safe without an explicit cancel: `res.text()`
+    // reads the stream to completion, so the connection is already released by
+    // the time JSON.parse runs or throws.
+    try { return { outcome: 'ok', json: JSON.parse(await res.text()), status: res.status }; }
+    catch { return { outcome: 'unreachable', json: null, error: 'bad-json', status: res.status }; }
+  } catch (err) {
+    // No response to dispose of — the request never produced one.
+    return {
+      outcome: 'unreachable',
+      json: null,
+      error: err && err.name === 'AbortError' ? 'timeout' : 'error',
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** Reachability-only transport for the PUBLIC preview ingress over the IAP-LB
+ *  seam.
+ *
+ *  Unlike lbGetJson it does not PARSE a body — the preview root returns HTML, so
+ *  routing it through lbGetJson would fail-close on the non-JSON parse. It must
+ *  still DISPOSE of that body on every path; "does not parse" was historically
+ *  written as "does not touch", and that is precisely what leaked.
+ *
+ *  Classifies purely on the HTTP response:
+ *    any non-auth HTTP response (200, or even 404/502 — the LB routed to a
+ *                                backend that answered) → true (ingress wired);
+ *    auth-misconfigured (302→Google login / 401 / 403) → null (UNKNOWN, never
+ *                        false): the preview backend is a SEPARATE IAP backend
+ *                        service whose audience/accessor may differ from the
+ *                        editor backend the operator token is minted for, so an
+ *                        auth challenge here proves nothing about the URL wiring;
+ *    transport error / timeout                          → false (nothing answered).
+ *
+ *  Uses redirect:'manual' so an IAP login 302 surfaces as classifiable instead
+ *  of fetch silently following it to a login page.
+ */
+async function lbProbeReachable(target, timeout, deps = {}) {
+  const { fetchImpl = globalThis.fetch, warn = console.warn } = deps;
+  const ctl = new AbortController();
+  const timer = setTimeout(() => ctl.abort(), timeout);
+  try {
+    const res = await fetchImpl(target.url, {
+      headers: target.headers,
+      redirect: 'manual',
+      signal: ctl.signal,
+    });
+    const outcome = fpt.classifyProbeResponse({
+      status: res.status,
+      location: res.headers.get('location'),
+    });
+    if (outcome === 'auth-misconfigured') {
+      const why = fpt.describeAuthMisconfig(res.status);
+      if (why) warn(`preview ingress ${target.url}: HTTP ${res.status} — ${why}`);
+      await disposeBody(res);
+      return null;
+    }
+    await disposeBody(res);
+    return true;
+  } catch {
+    // No response to dispose of — the request never produced one.
+    return false;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+module.exports = {
+  disposeBody,
+  lbGetJson,
+  lbProbeReachable,
+};

package/npm/fleet-project-drift.js

@@ -0,0 +1,58 @@
+'use strict';
+
+// npm/fleet-project-drift.js — pure classifier for the fleet dashboard's
+// "project-dir-drift" surface: does a VM's LIVE project identity conflict with
+// the identity the operator asked for at Add time?
+//
+// The drift surface exists to catch a genuine misprovision — a VM whose
+// /workspace checked out the WRONG repo, so its live project name no longer
+// matches the expected one. But a brand-new GREENFIELD project (added with
+// --new-project / newProjectName, no clientRepo) has no origin remote and, on a
+// cloud VM, is always bind-mounted at /workspace. Before the editor seeds its
+// projectTitle, the live identity falls back to the bare mount basename
+// "workspace", which never equals the expected newProjectName — a PERMANENT
+// FALSE drift that made every healthy greenfield add read amber and then get
+// misclassified as "Add failed". This module suppresses drift for exactly that
+// un-onboarded greenfield shape while leaving every true-positive intact.
+//
+// Pure like fleet-add-failure.js: server.js is the thin I/O shell that gathers
+// the poll state and renders the returned reasons; the decision is unit-tested
+// here without a live VM.
+
+// The bare basename of the cloud-VM bind mount. Every fleet VM mounts the
+// client project at /workspace (see server.js's in-container gather and the
+// `-w /workspace` exec target), so an un-onboarded greenfield project with no
+// origin resolves its live name to this literal string until the editor seeds a
+// real projectTitle.
+const MOUNT_BASENAME = 'workspace';
+
+// Decide the project-dir-drift reasons for one VM.
+//
+//   expectedName   the identity the operator asked for: repoBasename(clientRepo)
+//                  for a clone, else newProjectName for greenfield, else null
+//   liveName       the VM's live clientProject.name (null when unreachable)
+//   liveRepo       the VM's live clientProject.repo — null for a project with no
+//                  origin remote (always the case for a fresh greenfield add)
+//   hasClientRepo  whether the Add was configured with a clientRepo (a clone);
+//                  false for a --new-project greenfield add
+//
+// Returns { drifted, reasons }. `reasons` is [] when not drifted so the caller
+// can spread it into the card's reason list unconditionally.
+function classifyProjectDrift({ expectedName, liveName, liveRepo, hasClientRepo } = {}) {
+  // Un-onboarded greenfield: no configured clientRepo, no live origin remote,
+  // and the live name is still the bare mount basename. This is a healthy fresh
+  // project that simply has not been wired to a remote yet — never real drift.
+  // Note the live-origin check: once a greenfield project DOES gain an origin
+  // whose basename conflicts with expected, `liveRepo` is non-null and this
+  // suppression no longer applies, so a genuine later misprovision still drifts.
+  const greenfieldUnonboarded =
+    !hasClientRepo && !liveRepo && liveName === MOUNT_BASENAME;
+  const drifted =
+    !greenfieldUnonboarded && !!(expectedName && liveName && expectedName !== liveName);
+  const reasons = drifted
+    ? [`project-dir-drift (expected: ${expectedName}, running: ${liveName})`]
+    : [];
+  return { drifted, reasons };
+}
+
+module.exports = { classifyProjectDrift, MOUNT_BASENAME };

package/npm/fleet-public-url.js

@@ -24,6 +24,12 @@
 // as the scripts it backstops. A project that never joins the fleet never sets
 // FLEET_DOMAIN and never reaches this probe.
 
+// The IAP members probe parses the same `value(bindings.members)` gcloud shape
+// the per-VM access sidecar already reads, so it reuses that parser rather than
+// growing a second one. fleet-vm-access requires only utils + vm-urls, so this
+// edge introduces no cycle.
+const { parseProjectMembers } = require('./fleet-vm-access');
+
 // The Google HTTPS-LB "no backend answered" body signature: GFE emits this when
 // a host rule routes nowhere (or to a backendless default). A single source so
 // the classifier and any future log line agree on the string.
@@ -59,6 +65,202 @@ function classifyPublicUrlHealth({ statusCode, body, error } = {}) {
   return 'unknown';
 }
 
+/** Classify a public-URL WebSocket-UPGRADE probe result into the same ingress-
+ *  wiring vocabulary classifyPublicUrlHealth uses (vm: Readiness Verifies Real
+ *  Usability). The plain GET proves the host rule ROUTES, but says NOTHING about
+ *  whether the ingress carries a WebSocket UPGRADE — the exact VM5-class
+ *  blindness: the editor answered HTTP 200 (its `101` even succeeded) while the
+ *  LB severed the socket every 30s, so the Build tab looped "Reconnecting…" on a
+ *  VM every readiness signal called healthy. server.js gathers a `101`-asserting
+ *  upgrade against `<publicUrl>/ws/health` (the auth-free liveness endpoint that
+ *  completes the upgrade, sends one frame, and closes — no broker, no PTY) and
+ *  hands the result here. Follows the same absence-of-evidence contract:
+ *
+ *    'unknown' — a network / TLS / timeout error (no statusCode), OR a 3xx
+ *                auth/IAP login redirect: the probe couldn't reach a verdict.
+ *                NEVER a fault, exactly like classifyPublicUrlHealth's 'unknown'
+ *                — a transient blip, or an IAP that bounced an un-authenticated
+ *                probe to a login page, must never yank a healthy VM out of the
+ *                roster. (An IAP-fronted VM whose browser WS works fine returns a
+ *                302 to a probe that carries no IAP credential — proof of nothing
+ *                about the editor, so it cannot be 'unwired'.)
+ *    'wired'   — the upgrade completed (HTTP 101). The WS path carries frames.
+ *    'unwired' — the LB/editor answered PAST auth and REFUSED the upgrade (a
+ *                non-101, non-3xx code): a host/LB rule that doesn't carry
+ *                WebSocket at all (the OTHER WS failure mode, distinct from the
+ *                timeout guillotine below). This is the only definitive fault,
+ *                so 'ws-dead' fires on it but never on the ambiguous 'unknown'.
+ */
+function classifyPublicWsHealth({ statusCode, error } = {}) {
+  if (error || statusCode == null) return 'unknown';
+  const code = Number(statusCode);
+  if (code === 101) return 'wired';
+  // A 3xx is an auth/IAP login redirect — the probe carries no IAP credential,
+  // so it can never complete the handshake. Absence of evidence, never a fault
+  // (mirrors classifyPublicUrlHealth's 3xx-is-'wired'/never-unwired treatment).
+  if (code >= 300 && code < 400) return 'unknown';
+  // A non-101, non-redirect response is the editor answering past auth and
+  // refusing the upgrade — the genuine WS-unwired signal.
+  return 'unwired';
+}
+
+/** The IAP role that actually authorizes opening a VM's public URL. A policy can
+ *  carry any number of other bindings; only this one decides the verdict, and
+ *  only its members are real IAP principals. */
+const IAP_ACCESSOR_ROLE = 'roles/iap.httpsResourceAccessor';
+
+/** Classify a gcloud IAP get-iam-policy result for a backend service. PURE —
+ * takes `{ error, stdout }` and returns `{ verdict, members }`.
+ *
+ * `verdict` is the unchanged three-value vocabulary the ingress rendering and
+ * fleet-vm-readiness already depend on:
+ *    'unknown'     — the gcloud read itself errored (absence of evidence, never
+ *                    manufactured as a fault; mirrors the gather probes).
+ *    'granted'     — at least one binding carries roles/iap.httpsResourceAccessor,
+ *                    so someone can actually open the VM's public URL.
+ *    'no-accessor' — the policy read cleanly but names no accessor role, i.e. the
+ *                    VM is wired but nobody is granted (the public URL 51s in the
+ *                    browser).
+ *
+ * `members` is the list of principals holding the accessor role — the fact the
+ * old bare-verdict shape was structurally incapable of reporting. Because
+ * `domain:codeyam.com` always holds the role, "is anyone granted?" was always
+ * true, so a specific collaborator's MISSING binding could never be detected;
+ * that blindness is what let the dashboard render a failed grant as access for
+ * hours (VM-10, 2026-07-30). `members` is `[]` on a read error and on
+ * 'no-accessor' — an empty list is never evidence of a gap by itself, the verdict
+ * carries that.
+ *
+ * Input is `--format=value(bindings.role,bindings.members)`: one line per
+ * binding, fields TAB-separated, members within a binding `;`-separated. Only
+ * the accessor binding's members are returned — a roles/owner binding does not
+ * grant IAP web access, so listing its members as IAP principals would be a
+ * different flavor of the same lie.
+ */
+function classifyIapAccess({ error, stdout } = {}) {
+  if (error) return { verdict: 'unknown', members: [] };
+  const lines = String(stdout || '')
+    .split('\n')
+    .map((l) => l.trim())
+    .filter(Boolean);
+  const accessorLines = lines.filter((l) => l.split('\t')[0].trim() === IAP_ACCESSOR_ROLE);
+  if (accessorLines.length === 0) return { verdict: 'no-accessor', members: [] };
+  // Reuse the members parser written for exactly this gcloud output shape
+  // (`;`/newline split, trim, dedupe preserving first appearance, drop `deleted:`
+  // tombstones) rather than growing a second one that would drift from it.
+  const members = parseProjectMembers(
+    accessorLines.map((l) => l.split('\t').slice(1).join('\t')).join('\n'),
+  );
+  return { verdict: 'granted', members };
+}
+
+/** Aggregate the per-surface IAP verdicts (editor + preview) into a single fleet
+ *  verdict. PURE — takes `{ editor, preview }`, each a `classifyIapAccess`
+ *  result, and returns:
+ *    'unknown'             — either surface's read errored (absence of evidence,
+ *                            never manufactured as a fault).
+ *    'no-accessor'         — the EDITOR backend has no accessor: the URL the
+ *                            operator opens 51s for everyone. The primary gap
+ *                            (dominates a preview gap — the editor is unusable).
+ *    'preview-no-accessor' — the editor grants access but the PREVIEW backend has
+ *                            no accessor. The exact shape that hid this bug: the
+ *                            editor loads, but the framed Live Preview (served
+ *                            from the separate preview host) is blank for every
+ *                            authorized user because nobody is granted there.
+ *    'granted'             — BOTH surfaces authorize someone.
+ *
+ *  The preview verdict is optional: an older dashboard that only gathered the
+ *  editor surface passes `preview === undefined`, and the result collapses to the
+ *  single-surface classification (never a phantom preview gap).
+ *
+ *  Accepts each surface as either a bare verdict string or a full
+ *  `classifyIapAccess` result `{ verdict, members }`, and RETURNS A STRING either
+ *  way. The string return is load-bearing, not laziness: `deriveVmReadiness`
+ *  compares `v.iapAccess` against 'no-accessor' / 'preview-no-accessor' directly
+ *  (npm/fleet-vm-readiness.js), and the card's readiness-badge CSS keys off those
+ *  same values. Members are aggregated separately by `aggregateIapMembers` so the
+ *  verdict contract stays byte-identical. */
+function aggregateIapAccess({ editor, preview } = {}) {
+  // Unwrap the `{ verdict, members }` shape; a bare string passes through, and
+  // undefined/null stay undefined/null so the single-surface fallback below and
+  // the 'unknown' guard both keep working.
+  const v = (s) => (s && typeof s === 'object' ? s.verdict : s);
+  editor = v(editor);
+  preview = v(preview);
+  // Absence of evidence on either surface is never a fault.
+  if (editor === 'unknown' || preview === 'unknown') return 'unknown';
+  // The editor is the URL the operator opens; if IT lacks an accessor, that is
+  // the primary gap and dominates any preview verdict.
+  if (editor !== 'granted') return 'no-accessor';
+  // Editor granted. With no preview verdict gathered, fall back to the
+  // editor-only 'granted' (backward-compatible with single-surface dashboards).
+  if (preview === undefined || preview === null) return 'granted';
+  // Editor granted but the preview host authorizes nobody — the framed preview
+  // is blank for authorized users even though the editor works.
+  if (preview !== 'granted') return 'preview-no-accessor';
+  return 'granted';
+}
+
+/** Aggregate the per-surface IAP MEMBER lists into the card's display truth.
+ *  PURE — takes the same `{ editor, preview }` map of `classifyIapAccess`
+ *  results `aggregateIapAccess` consumes, and returns
+ *  `{ editor, preview, all, partial }`:
+ *
+ *    editor / preview — that surface's accessor members ([] when the surface
+ *                       reported no accessor, or was not gathered).
+ *    all              — the union across surfaces, first-appearance order. This
+ *                       is what the card renders as "who actually has access".
+ *    partial          — true when a principal holds the role on SOME but not all
+ *                       gathered surfaces. That is the editor-works /
+ *                       preview-blank shape, visible per-principal rather than
+ *                       only as the coarse 'preview-no-accessor' verdict.
+ *
+ *  Returns `null` when either gathered surface errored ('unknown'): a partial
+ *  read would render a live principal as missing, which is the same class of lie
+ *  in the opposite direction. Absence of evidence is not a member list. */
+function aggregateIapMembers({ editor, preview } = {}) {
+  const surfaces = [editor, preview].filter((s) => s !== undefined && s !== null);
+  if (surfaces.some((s) => (typeof s === 'object' ? s.verdict : s) === 'unknown')) return null;
+  const listOf = (s) => (s && typeof s === 'object' && Array.isArray(s.members) ? s.members : []);
+  const e = listOf(editor);
+  const p = listOf(preview);
+  const all = [];
+  for (const m of [...e, ...p]) if (!all.includes(m)) all.push(m);
+  // A principal is "partial" when it is absent from at least one surface that was
+  // actually gathered. With only one surface gathered nothing can be partial.
+  const gathered = [];
+  if (editor !== undefined && editor !== null) gathered.push(e);
+  if (preview !== undefined && preview !== null) gathered.push(p);
+  const partial = gathered.length > 1
+    && all.some((m) => gathered.some((list) => !list.includes(m)));
+  return { editor: e, preview: p, all, partial };
+}
+
+// The fleet minimum backend-service `timeoutSec` a WebSocket needs to survive
+// behind the External HTTPS LB. The LB severs a backend connection at
+// `timeoutSec` regardless of liveness, so the default 30s guillotines the Build
+// tab's terminal every 30s (the VM5 symptom). scripts/gcp/vm-ingress.sh sets —
+// and always converges existing BES to — 86400 (24h); readiness asserts the
+// same floor so a BES that drifted below it reads `ws-dead` instead of healthy.
+// A single source so the classifier and any future log line agree on the number.
+const FLEET_WS_TIMEOUT_MIN_SEC = 86400;
+
+/** Classify a backend-service `timeoutSec` against the fleet WS minimum. PURE —
+ *  server.js reads the value via `gcloud backend-services describe` and hands
+ *  the number in, so the threshold logic is unit-testable without gcloud.
+ *  Absence of evidence is never a fault (mirrors classifyBackendHealth):
+ *
+ *    'unknown'            — not a usable positive number (describe errored /
+ *                           empty): no verdict, never a problem state.
+ *    'ws-timeout-too-low' — a real value BELOW the minimum: the LB WILL sever
+ *                           the socket (the VM5 guillotine). The only fault.
+ *    'ok'                 — timeoutSec ≥ the fleet minimum: long enough for WS. */
+function classifyWsTimeout(backendTimeoutSec, minSec = FLEET_WS_TIMEOUT_MIN_SEC) {
+  const t = Number(backendTimeoutSec);
+  if (!Number.isFinite(t) || t <= 0) return 'unknown';
+  return t >= Number(minSec) ? 'ok' : 'ws-timeout-too-low';
+}
+
 /** The sticky `ingress-unwired` degraded-reason string — the single source for
  *  both the dashboard card reason and any log line. Embeds the advertised URL
  *  and the EXACT re-wire command an operator runs to fix it, so the amber card
@@ -152,9 +354,41 @@ function classifyBackendAttachment(err, stdout) {
   return String(stdout == null ? '' : stdout).trim() === '' ? 'backendless' : 'attached';
 }
 
+/** Collapse a VM's raw wiring signals into the single URL-state vocabulary the
+ *  card renders (vm--add-time-url-wiring-converges-reliably), so "the link is
+ *  converging" is DISTINCT from "the link is dead" — the operator is never shown
+ *  a "ready" card over an unwired URL, nor left to infer state from an absent
+ *  link. PURE — the dashboard reads the live facts (the public-URL probe verdict,
+ *  the inflight marker, the failed marker: all I/O at the edge) and passes them
+ *  in. Precedence:
+ *    - `publicUrlHealth === 'wired'` → 'wired'. A real 2xx/3xx wins over any
+ *      stale marker; the URL genuinely serves.
+ *    - else `inflight` → 'wiring'. The add-tail converge loop is still running;
+ *      the card reads a calm "wiring public URL…", not a false failure.
+ *    - else `failed` → 'wiring-failed'. The converge loop exhausted its deadline
+ *      without reaching `wired` — a real attention reason with a re-run command,
+ *      never a silent `partial`.
+ *    - else `null`. No wiring signal (legacy quick-tunnel, or a transient probe
+ *      miss with no markers) — the caller falls back to its existing
+ *      unwired/unknown handling rather than inventing a state. */
+function classifyUrlWiringState({ publicUrlHealth, inflight, failed } = {}) {
+  if (publicUrlHealth === 'wired') return 'wired';
+  if (inflight) return 'wiring';
+  if (failed) return 'wiring-failed';
+  return null;
+}
+
 module.exports = {
   classifyPublicUrlHealth,
+  classifyPublicWsHealth,
+  classifyIapAccess,
+  aggregateIapAccess,
+  aggregateIapMembers,
+  IAP_ACCESSOR_ROLE,
+  classifyWsTimeout,
+  FLEET_WS_TIMEOUT_MIN_SEC,
   ingressUnwiredReason,
   shouldAutoRewireIngress,
   classifyBackendAttachment,
+  classifyUrlWiringState,
 };