@codeyam-editor/codeyam-editor 0.1.4 → 0.1.6

package/npm/fleet-public-url.js

@@ -0,0 +1,394 @@
+'use strict';
+// Pure classification + reason-string derivation for the dashboard's public-URL
+// reachability probe (vm: Dashboard validates the public ingress URL, not just
+// the tunnel).
+//
+// The fleet dashboard probes each VM's editor through the local SSH tunnel and,
+// in Google-LB mode, the per-VM backend SERVICE health (gcloud get-health) —
+// but never the public `<slug>.editor.<domain>` URL the card advertises. VM5
+// (2026-06-19) sat "healthy" on every one of those signals while the advertised
+// URL returned 503 "no healthy upstream" for hours: a reused-slug Add aborted on
+// a `Duplicate path matcher` collision before binding the host rule, so the
+// hostname fell through to the default backend. A backend-health probe is
+// structurally blind to a missing host rule; only an end-to-end GET of the
+// advertised hostname catches it.
+//
+// This module is the PURE half — parsing + string derivation, no network —
+// mirroring classifyBackendHealth's `absent|unknown|unhealthy|healthy`
+// contract. The HTTPS GET I/O lives in server.js's gatherPublicUrlHealth, the
+// same split gatherBackendHealth / classifyBackendHealth already follow. Unit-
+// tested in npm/fleet-public-url.test.js.
+//
+// Stack note: this is fleet-operator infrastructure (the GCE fleet that runs
+// codeyam-editor itself), GCP / HTTPS-LB-specific by design — the same posture
+// 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.
+const NO_HEALTHY_UPSTREAM_RE = /no healthy upstream/i;
+
+/** Classify a public-URL probe result into the ingress-wiring vocabulary,
+ *  following classifyBackendHealth's contract — absence of evidence is never a
+ *  problem state:
+ *
+ *    'unknown' — a network / TLS / timeout / DNS error (no statusCode): the
+ *                probe couldn't reach a verdict. NEVER a degraded state, exactly
+ *                like classifyBackendHealth's 'unknown'. Also covers an
+ *                unexpected non-503 HTTP error (a 404/500 from the editor
+ *                itself) — that means the host rule DID route, just not to a
+ *                happy response, so it is neither 'unwired' nor a clean 'wired'.
+ *    'unwired' — the LB answered but no backend is bound to the advertised host:
+ *                a 503, or a recognizable "no healthy upstream" default-backend
+ *                body. THIS is the missing-host-rule signal a backend-health
+ *                probe cannot see (the VM5 case).
+ *    'wired'   — any 2xx / 3xx: the editor answered (a 200, or its login 302
+ *                redirect — the real VM5-healthy shape). The host rule routes.
+ */
+function classifyPublicUrlHealth({ statusCode, body, error } = {}) {
+  if (error || statusCode == null) return 'unknown';
+  const code = Number(statusCode);
+  if (code === 503) return 'unwired';
+  if (NO_HEALTHY_UPSTREAM_RE.test(String(body || ''))) return 'unwired';
+  if (code >= 200 && code < 400) return 'wired';
+  // Any other 4xx/5xx is the editor answering with an error of its own — the
+  // host rule routes, so it is NOT 'unwired'; but it is not a clean success
+  // either. Treat as 'unknown' (absence of the unwired signal) so we never raise
+  // a false ingress-unwired reason on it.
+  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
+ *  is self-documenting (the surface VM5 should have shown for hours instead of
+ *  reading healthy). */
+function ingressUnwiredReason({ url, domain, slug, n } = {}) {
+  const target = url || `(vm-${n} editor URL)`;
+  const slugEnv = slug ? ` VM_SLUG=${slug}` : '';
+  const rewire = `FLEET_DOMAIN=${domain}${slugEnv} bash scripts/gcp/vm-ingress.sh ${n} up`;
+  return `ingress-unwired: ${target} returns 503 (host rule missing). Re-wire: ${rewire}`;
+}
+
+/** Decide whether a just-landed public-URL verdict warrants an auto-rewire
+ *  self-heal. PURE — the dashboard reads the live VM state (I/O at the edge) and
+ *  passes the facts in; the gate logic itself is unit-testable without network
+ *  or server state. Fires only for a GENUINE missing-host-rule case:
+ *    - `verdict` is 'unwired' (the URL 503s), AND
+ *    - `reachable` (the tunnel is up — a down VM is not a missing-host-rule
+ *      case; re-wiring it accomplishes nothing), AND
+ *    - `backendEditorHealth` is 'healthy' (the backend SERVICE is fine, so only
+ *      the host rule is missing — the VM5 host-rule-drift case) OR 'absent' (the
+ *      per-VM backend service was NEVER created — the interrupted-add VM-4 case,
+ *      where a SIGTERM killed `backend-services create` mid-wiring) OR
+ *      'unhealthy' *with* `backendEditorBackendless` true (the BES EXISTS but has
+ *      ZERO NEG backends attached — the concurrent-add editor-band race, where the
+ *      backend slipped its NEG attachment but the BES object landed). All three
+ *      are recoverable by a single `vm-ingress.sh up`, which is
+ *      describe-before-create idempotent and creates/attaches only the missing
+ *      pieces. A backendless BES classifies as 'unhealthy' (get-health returns
+ *      empty, indistinguishable from a still-cold backend) yet will NEVER converge
+ *      on its own — it has no endpoint to become healthy — so it MUST re-wire, not
+ *      wait. 'unknown' (a transient gcloud/auth error — absence of evidence must
+ *      never trigger a re-wire storm) and a GENUINELY-converging 'unhealthy' (a
+ *      backend IS attached, health still flipping — `backendEditorBackendless`
+ *      false: let it converge, don't churn the LB) stay EXCLUDED, AND
+ *    - no re-wire is already `inFlight` (one per VM), AND
+ *    - the debounce window has elapsed since `lastRewireAt`.
+ *  The debounce is load-bearing: GCP host-rule changes take minutes to roll out
+ *  to all GFEs (VM5's CORRECT rule 503'd for ~minutes before flipping), so a
+ *  per-cycle re-fire would storm the LB while a good change is still
+ *  propagating. A missing/0 `lastRewireAt` means "never re-wired" → the window
+ *  is satisfied. */
+function shouldAutoRewireIngress({
+  verdict,
+  reachable,
+  backendEditorHealth,
+  backendEditorBackendless,
+  inFlight,
+  lastRewireAt,
+  now,
+  debounceMs,
+} = {}) {
+  if (verdict !== 'unwired') return false;
+  if (!reachable) return false;
+  // 'healthy' = host-rule drift (VM5); 'absent' = backend never created
+  // (interrupted-add VM-4); 'unhealthy' + backendless = BES exists with zero NEG
+  // backends (concurrent-add editor-band race) — it can't converge unaided, so it
+  // re-wires too. A genuinely-converging 'unhealthy' (backend attached, health
+  // flipping → backendless false) and 'unknown' stay excluded.
+  const rewirable =
+    backendEditorHealth === 'healthy' ||
+    backendEditorHealth === 'absent' ||
+    (backendEditorHealth === 'unhealthy' && backendEditorBackendless === true);
+  if (!rewirable) return false;
+  if (inFlight) return false;
+  return (Number(now) - (Number(lastRewireAt) || 0)) >= Number(debounceMs);
+}
+
+/** Classify a `gcloud compute backend-services describe --format=value(backends[].group)`
+ *  result into the attachment vocabulary — the signal `get-health` cannot give,
+ *  because an empty health result is ambiguous between "no backend attached" and
+ *  "a backend attached but still health-pending":
+ *
+ *    'backendless' — the BES EXISTS but has ZERO NEG backends attached (the
+ *                    describe printed empty / whitespace-only output). This BES
+ *                    will NEVER converge on its own — there is no endpoint to
+ *                    become healthy — so it is re-wirable, feeding
+ *                    shouldAutoRewireIngress's `backendEditorBackendless` branch
+ *                    (the concurrent-add editor-band slip).
+ *    'attached'    — the describe printed at least one backend group, OR it
+ *                    ERRORED. An error is treated as 'attached' (absence of
+ *                    evidence): a NotFound is the 'absent' case classifyBackendHealth
+ *                    already owns, and a transient gcloud/auth failure must NEVER
+ *                    manufacture a 'backendless' verdict that storms the LB with a
+ *                    re-wire. Pure (no I/O), so the empty-backends classification is
+ *                    unit-testable without gcloud — the I/O lives in server.js's
+ *                    gatherEditorBackendless, the same split classifyPublicUrlHealth
+ *                    follows. */
+function classifyBackendAttachment(err, stdout) {
+  if (err) return 'attached';
+  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

@@ -37,4 +37,98 @@ function decideAutoReleaseGoneHead({ queue, vms, jobs, orphans }) {
   return { release: true, uuid: head.uuid, vm: n, reason: `owning VM-${n} left the fleet` };
 }
 
-module.exports = { decideAutoReleaseGoneHead };
+/** Compute the set-priority writes a reorder requires.
+ *
+ *  A reorder POSTs a desired uuid order; the queue's priority convention is
+ *  first=N … last=1 (higher priority sorts earlier). This maps the desired
+ *  order onto target priorities, drops the entries already at their target
+ *  priority (no-ops — no `set-priority` shell-out needed), and sorts the
+ *  remaining writes intended-HEAD-first so the head lands first even if a
+ *  later write fails. `current` is the authoritative queue ([{uuid,priority}]);
+ *  `order` is the desired uuid sequence.
+ *
+ *  Returns one of:
+ *    { ok: false, reason: 'empty' }           — no order supplied
+ *    { ok: false, reason: 'stale' }           — order doesn't match current set
+ *    { ok: true, targets: [{uuid, prio}] }    — writes to apply (possibly [])
+ *  Pure; no I/O.
+ */
+function computeReorderTargets({ order, current }) {
+  const ord = (order || []).map((s) => String(s).trim()).filter(Boolean);
+  const cur = current || [];
+  const curUuids = cur.map((e) => e.uuid);
+  if (!ord.length) return { ok: false, reason: 'empty' };
+  // Same membership, same length — a reorder, not an add/remove. Anything else
+  // means the queue changed underneath the operator since they last saw it.
+  if (ord.length !== curUuids.length || !ord.every((u) => curUuids.includes(u))) {
+    return { ok: false, reason: 'stale' };
+  }
+  const N = ord.length;
+  const targets = ord
+    .map((uuid, i) => ({ uuid, prio: N - i }))                     // first=N … last=1
+    .filter(({ uuid, prio }) => {
+      const e = cur.find((x) => x.uuid === uuid);
+      return !e || e.priority !== prio;                            // skip no-ops
+    })
+    .sort((a, b) => b.prio - a.prio);                              // intended HEAD first
+  return { ok: true, targets };
+}
+
+/** 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 };

package/npm/fleet-reachability.js

@@ -0,0 +1,80 @@
+'use strict';
+
+// The three-state reachability contract for the Fleet Dashboard.
+//
+// A VM's reachability has THREE states, not two:
+//   true  — a probe reached the VM's editor
+//   false — a probe RAN and FAILED (a confirmed outage)
+//   null  — no verdict at all (never polled, or held inconclusive)
+//
+// `npm/fleet-auth-health.js::classifyReachability` has always modelled this
+// correctly, deliberately returning `{ reachable: null }` for the inconclusive
+// case. Every consumer between it and the browser then coerced that care away
+// with `!!v.reachable` and `{ n, reachable: false }` placeholders, so the null
+// never survived to anyone who could act on it.
+//
+// On 2026-07-30 that collapse served all 13 rostered VMs as `reachable: false`
+// with NO `reachableSource`, while each card's own `backendHealth` read
+// `healthy` and operator auth read clean — a self-contradicting fleet-wide
+// "outage" that had never been probed. It blocked both sanctioned refresh paths
+// (`refresh-client-vm-editor.sh` exits 1, `fleet-advance-to.sh` classifies
+// SKIP-unreachable) and, in a storm, is the signal that has driven reconcile
+// into hard-rebooting healthy VMs.
+//
+// This module is the single home for that vocabulary so the distinction is
+// stated once and grepped, rather than re-derived inline at each consumer. Pure:
+// no I/O, no clock, no state.
+
+// The `reachableSource` value for a record carrying no reachability verdict.
+// `reachableSource` otherwise names the signal that DECIDED a verdict ('lb' |
+// 'backend' | 'local' | 'iap', from classifyReachability), which is what makes a
+// card self-diagnosing — a `reachable: false` with a missing source is exactly
+// the fingerprint that identified the 2026-07-30 incident as manufactured by the
+// serializer rather than reported by a probe. 'unpolled' extends that same
+// self-diagnosis to the no-verdict case instead of leaving a silent gap.
+const REACHABILITY_UNPOLLED = 'unpolled';
+
+// Does this VM have a DEFINITE reachability verdict — did anyone actually ask?
+// Only a real boolean counts; null/undefined (and any malformed value) read as
+// "no verdict". Consumers use this to tell "never asked" from "asked and got an
+// answer", which is the distinction the whole three-state contract exists for.
+function hasReachabilityVerdict(reachable) {
+  return reachable === true || reachable === false;
+}
+
+// Is this VM CONFIRMED unreachable — probed, and the probe failed?
+//
+// Safety-critical. Reboot, reconcile, and destroy paths must gate on THIS, never
+// on a falsy check: `!reachable` is also true for an unknown, so a `!reachable`
+// guard lets a VM nobody has polled walk into a path that ends in a hard reset.
+// An unknown is not evidence, and evidence is the bar for a destructive action.
+function isConfirmedUnreachable(reachable) {
+  return reachable === false;
+}
+
+// Normalize a raw poll record's reachability into the pair the wire envelope
+// carries: `{ reachable, reachableSource }`.
+//
+// This is the seam where the bug lived. `reachable` is preserved as a genuine
+// tri-state — an ABSENT verdict stays absent rather than being coerced to a
+// definite false — and `reachableSource` falls back to 'unpolled' so a card with
+// no verdict says so out loud instead of looking like an unexplained outage.
+//
+// `v` is the merged poll state (`state.vms[n]`), or a placeholder standing in
+// for a VM with no poll state at all.
+function normalizeReachability(v) {
+  const raw = v ? v.reachable : null;
+  const reachable = hasReachabilityVerdict(raw) ? raw : null;
+  return {
+    reachable,
+    reachableSource: (v && v.reachableSource)
+      || (reachable === null ? REACHABILITY_UNPOLLED : null),
+  };
+}
+
+module.exports = {
+  REACHABILITY_UNPOLLED,
+  hasReachabilityVerdict,
+  isConfirmedUnreachable,
+  normalizeReachability,
+};