@codeyam-editor/codeyam-editor 0.1.5 → 0.1.6

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-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,
 };

package/npm/fleet-queue.js

@@ -74,4 +74,61 @@ function computeReorderTargets({ order, current }) {
   return { ok: true, targets };
 }
 
-module.exports = { decideAutoReleaseGoneHead, computeReorderTargets };
+/** Move one uuid within a desired order array.
+ *
+ *  The staged-draft panel shuffles a working uuid order before it is saved.
+ *  `delta > 0` raises priority (moves the entry TOWARD the head / index 0);
+ *  `delta < 0` lowers it (toward the tail). The target index is clamped to the
+ *  array bounds, so a nudge past an end is a no-op and a full-span negative
+ *  delta lands the entry at the very tail — which is exactly how Demote
+ *  (head → back of the line) is expressed: `nudgeQueueOrder(order, head, -(N-1))`.
+ *  Mirrors the editor UI's `useBranchQueueDraft.nudge` (arrayMove(from, from-delta)).
+ *
+ *  `order` is a uuid array; a uuid not present is returned unchanged. Pure — the
+ *  input array is never mutated.
+ */
+function nudgeQueueOrder(order, uuid, delta) {
+  const arr = (order || []).slice();
+  const from = arr.findIndex((u) => u === uuid);
+  if (from < 0 || !delta) return arr;
+  let to = from - delta;              // +delta → toward head; -delta → toward tail
+  if (to < 0) to = 0;
+  if (to > arr.length - 1) to = arr.length - 1;
+  if (to === from) return arr;
+  const [moved] = arr.splice(from, 1);
+  arr.splice(to, 0, moved);
+  return arr;
+}
+
+/** Merge a fresh poll's membership into a staged draft order without discarding
+ *  the operator's in-progress reorder.
+ *
+ *  - uuids still present live keep their DRAFT position (the working order wins);
+ *  - draft uuids that vanished upstream are dropped;
+ *  - live uuids not yet in the draft are appended at the tail so a sibling
+ *    session's newly-enqueued entry doesn't silently disappear.
+ *
+ *  Pure port of the editor UI's `reconcileDraft` order rule (uuid-only, no meta).
+ *  Both arguments are uuid arrays; returns the merged uuid array. Never mutates
+ *  its inputs.
+ */
+function reconcileQueueDraft(draftOrder, liveOrder) {
+  const live = liveOrder || [];
+  const liveSet = new Set(live);
+  const seen = new Set();
+  const out = [];
+  for (const u of draftOrder || []) {
+    if (liveSet.has(u) && !seen.has(u)) { out.push(u); seen.add(u); }
+  }
+  for (const u of live) {
+    if (!seen.has(u)) { out.push(u); seen.add(u); }
+  }
+  return out;
+}
+
+module.exports = {
+  decideAutoReleaseGoneHead,
+  computeReorderTargets,
+  nudgeQueueOrder,
+  reconcileQueueDraft,
+};

package/npm/fleet-reachability-debounce.js

@@ -0,0 +1,69 @@
+'use strict';
+// Pure consecutive-failure debounce for the Fleet Dashboard's per-VM top-level
+// reachability. Mirrors npm/fleet-broker-debounce.js exactly: server.js does the
+// polling and threads the state; this decides the reachability the card renders.
+//
+// The bug this fixes (observed live 2026-07-01, VM6): a healthy VM briefly
+// flashed 'unreachable' and surfaced a reset-client-error even though it was up
+// the whole time. The dashboard polls each VM's editor over a laptop-side
+// SSH/cloudflared forward with NO fast respawner, so a single one-poll hiccup
+// returned reachable:false and the card instantly read 'unreachable' — which
+// then invited the destructive "Reset client" action on a perfectly healthy VM.
+// The single probe is left as-is on the poller side; the right seam for
+// absorbing a one-poll blip is here at the aggregation layer, just like broker.
+//
+// Asymmetric by design: ONLY the flip to 'unreachable' is debounced (it requires
+// `threshold` consecutive failed polls). A reachable poll takes effect
+// immediately — we never DELAY clearing a false alarm, only delay raising one.
+//
+// Three display states the card renders:
+//   'reachable'    — the editor answered this poll.
+//   'reconnecting' — a sub-threshold failure streak (1..N-1), OR the GCP side
+//                    confirms the editor answers over IAP while the local port
+//                    is dark (a laptop tunnel fault, never a dead VM). Calm; the
+//                    watchdog respawns the forward. A one-poll hiccup lives here.
+//   'unreachable'  — N consecutive failures AND no GCP-side confirmation. The
+//                    honest sustained-outage state.
+//
+// State carried across polls: { display, failStreak, lastConfirmed }.
+//   display       — the debounced value the card renders this poll.
+//   failStreak    — how many consecutive raw failed polls we've seen.
+//   lastConfirmed — the last raw 'reachable' we proved (informational; the card
+//                   holds 'reconnecting' during a pending sub-threshold streak).
+
+// ~9s at the dashboard's 3s poll cadence, matching the broker debounce: enough
+// to absorb a transient forward hiccup while still surfacing a real outage
+// quickly. Named so retuning is a one-line edit.
+const UNREACHABLE_DEBOUNCE_THRESHOLD = 3;
+
+function debounceReachability(prev, rawReachable, opts) {
+  const threshold = (opts && opts.threshold) || UNREACHABLE_DEBOUNCE_THRESHOLD;
+  const gcpConfirmedReachable = !!(opts && opts.gcpConfirmedReachable);
+  const lastConfirmed = prev ? prev.lastConfirmed : undefined;
+
+  // Confirmed reachable: the editor answered now. Render immediately, reset the
+  // streak, remember this as the last-confirmed value.
+  if (rawReachable) {
+    return { display: 'reachable', failStreak: 0, lastConfirmed: 'reachable' };
+  }
+
+  // Raw failure: count the streak.
+  const failStreak = (prev ? prev.failStreak : 0) + 1;
+
+  // GCP-side confirmation: the editor answers over IAP while the local port is
+  // dark. That's a laptop tunnel fault, NOT a dead VM — never escalate to
+  // 'unreachable' no matter how long the local forward has been down; the
+  // watchdog respawns the forward. Hold the calm 'reconnecting' state.
+  if (gcpConfirmedReachable) {
+    return { display: 'reconnecting', failStreak, lastConfirmed };
+  }
+
+  // Sub-threshold failure: stay calm ('reconnecting'). Only a SUSTAINED failure
+  // past the threshold escalates to the honest 'unreachable'.
+  if (failStreak >= threshold) {
+    return { display: 'unreachable', failStreak, lastConfirmed };
+  }
+  return { display: 'reconnecting', failStreak, lastConfirmed };
+}
+
+module.exports = { debounceReachability, UNREACHABLE_DEBOUNCE_THRESHOLD };