@codeyam-editor/codeyam-editor 0.1.4 → 0.1.5

package/npm/fleet-live-status.js

@@ -0,0 +1,123 @@
+'use strict';
+// Pure session/broker live-status derivation for the Fleet Dashboard's per-VM
+// status LABEL (scripts/operator/fleet-dashboard/server.js requires this). This
+// is the trailing decision of deriveStatus, after every heavy-job / orphan /
+// failed-badge branch has been ruled out: given the reachable VM's session and
+// broker signals, is it building, waiting, or genuinely idle?
+//
+// The bug this fixes (observed live 2026-06-20, VM-1): the label was derived
+// SOLELY from `hasSession` — the editor server's own in-process build-session
+// flag. But a Claude agent's lifetime is owned by the PTY broker, deliberately
+// DECOUPLED from the editor-server lifetime (see docs/process-model.md). After a
+// server restart, or for a broker-resumed/detached agent the server didn't spawn
+// itself, `hasSession` is false while a fully-live agent keeps working in the
+// broker. The card fell through to 'idle' even though the broker dot — driven by
+// the same `brokerStatus` — already showed 'agent-live'. The label and the dot
+// disagreed.
+//
+// The fix consults the already-debounced broker tri-state (from
+// fleet-broker-status.js, threaded in by the caller) so a broker-held live agent
+// reads as working, not idle. `awaitingUserInput` is honored independent of
+// `hasSession`, so a broker-live agent blocked on input reads 'waiting'.
+//
+// The terminal-done refinement (observed live 2026-06-21): a broker-live agent
+// whose WORKFLOW reached its terminal step is parked alive at its prompt but is
+// NOT building — the editor masks the feature and reports `needsCleanup: true`
+// (session_info_response.rs). Without this signal the card showed an active-green
+// "Building" border on a finished, idle VM. We discriminate on `needsCleanup`
+// (a positive terminal signal) rather than feature-emptiness (also briefly true
+// at session START, which would mislabel a just-starting agent as done). This
+// only ever DOWNGRADES a would-be-'building' verdict to 'session-done'; a
+// mid-feature post-restart agent is not terminal (`needsCleanup` falsy) and stays
+// 'building', preserving the 2026-06-20 decoupled-agent fix above.
+//
+// Returns 'waiting' | 'building' | 'session-done' | 'idle' for a reachable VM, or
+// `null` when the VM is unreachable — the caller maps null to its own
+// asleep/unreachable verdict (it owns the running-fleet snapshot this module
+// deliberately does not touch) and otherwise passes the verdict through verbatim
+// as the card's `status`, so 'session-done' must match the card's status class.
+// Precedence is preserved: an unreachable VM returns null regardless of a stale
+// 'agent-live', so the broker branch only ever upgrades a would-be-idle verdict.
+function liveSessionStatus(v, brokerStatus) {
+  // Unreachable: we polled nothing reliable. Defer to the caller's
+  // asleep/unreachable mapping — a stale broker signal must not mask it.
+  if (!v.reachable) return null;
+  if (v.hasSession && v.awaitingUserInput) return 'waiting';
+  if (v.hasSession) return 'building';
+  // No editor-owned session, but a live agent may still be working in the PTY
+  // broker (decoupled lifetime — see docs/process-model.md). The broker
+  // tri-state is already debounced upstream; agent-live ⇒ working, not idle.
+  if (brokerStatus === 'agent-live') {
+    if (v.awaitingUserInput) return 'waiting';
+    // The agent is parked alive in the broker's build slot, but its workflow
+    // reached the terminal step (editor reports needsCleanup) — finished and
+    // idle, not building. A mid-feature post-restart agent is NOT terminal and
+    // still reads 'building' (preserves the 2026-06-20 decoupled-agent fix).
+    if (v.needsCleanup) return 'session-done';
+    return 'building';
+  }
+  return 'idle';
+}
+
+// Distinguish a freshly-rostered VM whose editor is still STARTING UP — a normal
+// cold boot that hasn't bound :14199 yet, or (the VM-2 case) the ~10–15-min
+// self-host `rebuild-self --force-in-container` compile that recompiles the
+// editor binary from source before the server can listen — from a genuinely DEAD
+// one. deriveStatus (scripts/operator/fleet-dashboard/server.js) calls this only
+// after it has already established the VM is rostered, unreachable, and GCP still
+// lists it RUNNING — i.e. exactly the case that otherwise falls through to the
+// red 'unreachable' that made a successful Add look like a failure.
+//
+// Returns 'editor-starting' when EITHER the VM was launched within the grace
+// window (`recentlyLaunched` — the cheap common case, no SSH needed) OR an
+// in-container probe has CONFIRMED a first-run build is still running
+// (`probeBuilding === true`), which lets the long self-host compile keep reading
+// "Starting editor…" past the window with no fragile fixed timeout. Returns null
+// otherwise so deriveStatus runs its existing unreachable path unchanged — an
+// honest red card the moment the grace window lapses with no confirmed build. A
+// DISTINCT key from the wake-path 'starting' (fleet-sleep-status.js) so the two
+// in-progress states never collide. Pure; the caller owns the time + SSH I/O.
+function classifyStartingVsUnreachable({ recentlyLaunched = false, probeBuilding = null } = {}) {
+  if (recentlyLaunched || probeBuilding === true) return 'editor-starting';
+  return null;
+}
+
+// Classify the in-container startup probe (server.js's editorStartingInContainer
+// one-IAP-SSH round-trip) into the tri-state the verdict cache stores and
+// classifyStartingVsUnreachable consumes. Mirrors fleet-cleanup.js's
+// classifyProjectWiring shape: takes the raw `{ stdout, err }` and parses the
+// three `---CY---`-separated segments the probe emits — the `docker ps` status
+// line, the count of listeners on :14199, and the count of live first-run build
+// processes (`rebuild-self` / `cargo build`):
+//   true  — container up, :14199 NOT yet bound, and a build process is alive ⇒
+//           still building (keeps the card calm-blue past the grace window).
+//   false — container up but :14199 already bound (the normal reachable path
+//           will win) OR up-and-idle with no build process (let the card flip to
+//           honest 'unreachable'); also a clean response with the container down.
+//   null  — an ssh/docker blip (`err`) ⇒ inconclusive; never upgrades a
+//           past-window card (stays honest), re-probed next poll.
+function classifyStartupProbe({ stdout, err } = {}) {
+  if (err) return null;
+  const parts = String(stdout == null ? '' : stdout).split('---CY---').map((s) => s.trim());
+  const containerUp = /^Up\b/m.test(parts[0] || '');
+  const portBound = (Number((parts[1] || '0').trim()) || 0) > 0;
+  const buildProcAlive = (Number((parts[2] || '0').trim()) || 0) > 0;
+  if (!containerUp) return false; // clean response, container down → not building
+  if (portBound) return false; // already serving — the reachable path owns it
+  return buildProcAlive ? true : false;
+}
+
+// Pure gate deciding whether pollStartupProbes should fire the (costly) IAP-SSH
+// build probe for a given VM this tick. We only probe a VM that is PLAUSIBLY
+// still starting — present, unreachable, GCP still lists it RUNNING, NOT already
+// owned by an active heavy job, and either recently launched OR already confirmed
+// building on a prior tick (so a ~15-min self-host compile keeps being probed
+// past the grace window with no fixed cap). A healthy/reachable VM, an
+// asleep/vanished one, or a long-idle one that simply went unreachable is never
+// probed. Pure so pollStartupProbes stays a thin SSH loop and this decision
+// matrix is exhaustively unit-testable without booting the server.
+function shouldProbeStartup({ vmPresent = false, reachable = false, gcpRunning = false, jobActive = false, recentlyLaunched = false, wasBuilding = false } = {}) {
+  return vmPresent && !reachable && gcpRunning && !jobActive && (recentlyLaunched || wasBuilding);
+}
+
+module.exports = { liveSessionStatus, classifyStartingVsUnreachable, classifyStartupProbe, shouldProbeStartup };

package/npm/fleet-plans.js

@@ -88,9 +88,144 @@ const REQUIRED_PLAN_ROW_FIELDS = [
   'slug', 'title', 'mode', 'order', 'prefix', 'blockedBy', 'claim'
 ];
 
+/**
+ * Decides which data source a project's Queued Plans panel should read from.
+ * The dashboard's own project (codeyam-editor) reads plans fresh from origin
+ * via the laptop checkout; every other project keeps the VM probe.
+ * @param {Object} params
+ * @param {string} params.project The project name for the panel.
+ * @param {?string} params.selfHostProject The dashboard's own project name.
+ * @returns {'origin'|'vm'} The source to use.
+ */
+function planSourceForProject({ project, selfHostProject }) {
+  return selfHostProject && project === selfHostProject ? 'origin' : 'vm';
+}
+
+/**
+ * Builds the static (non-ticking) part of a Queued Plans panel header label so
+ * the data source and its staleness risk are always visible. Origin-sourced
+ * panels name the branch + short sha; VM-sourced panels carry the "may lag
+ * origin" caveat. The relative age ("· 8s ago") is appended by the frontend's
+ * own ago ticker, so this returns the static prefix only.
+ * @param {Object} params
+ * @param {'origin'|'vm'} params.source Where the panel's data came from.
+ * @param {?string} params.ref The git ref (e.g. "origin/<branch>") for origin.
+ * @param {?string} params.sha The full commit sha for origin.
+ * @param {?number} params.fromVm The representative VM number for vm source.
+ * @param {?('stale-binary'|'fetch-failed'|'parse-error'|'unknown')} params.originError
+ *   When the self-host origin path was *attempted* and failed, the classified
+ *   reason it fell back to the VM probe. Absent/null for ordinary VM-sourced
+ *   projects (which were never meant to read origin).
+ * @returns {string} The static header annotation.
+ */
+function planPanelSourceLabel({ source, ref, sha, fromVm, originError }) {
+  if (source === 'origin') {
+    const shortSha = sha ? String(sha).slice(0, 7) : '?';
+    const where = ref || 'origin';
+    return `${where} @ ${shortSha}`;
+  }
+  // VM-sourced: surface the residual lag risk the origin path eliminates.
+  const vm = (fromVm !== null && fromVm !== undefined) ? `VM-${fromVm}` : 'VM';
+  if (originError) {
+    // The origin path was attempted and failed: this is a *degraded* panel, not
+    // a normal VM-sourced one. Name the failure class so it is self-diagnosing.
+    return `via ${vm} · origin unavailable: ${originErrorPhrase(originError)}`;
+  }
+  return `via ${vm} · may lag origin`;
+}
+
+/**
+ * Maps a classified origin-failure bucket to a short operator-facing phrase for
+ * the panel header. Mirrors the bucket set of classifyOriginError; an unknown
+ * bucket degrades to the generic "origin read failed" phrase.
+ * @param {string} originError The classified bucket.
+ * @returns {string} A short human-readable phrase.
+ */
+function originErrorPhrase(originError) {
+  switch (originError) {
+    case 'stale-binary':
+      return 'stale editor binary';
+    case 'fetch-failed':
+      return 'git fetch failed';
+    case 'parse-error':
+      return 'bad snapshot output';
+    default:
+      return 'origin read failed';
+  }
+}
+
+/**
+ * Classifies a caught origin-path error message into a small, stable set of
+ * buckets the operator can act on, rather than surfacing a noisy raw error
+ * (which can carry paths/branch names) in the panel header. Pure so it is
+ * unit-testable.
+ *   - `unrecognized subcommand`        → 'stale-binary'  (CLI predates the command)
+ *   - leading `git fetch origin`       → 'fetch-failed'  (couldn't reach origin)
+ *   - no-JSON / malformed snapshot     → 'parse-error'   (plans-snapshot output)
+ *   - anything else                    → 'unknown'
+ * @param {?string} message The caught error's message text.
+ * @returns {'stale-binary'|'fetch-failed'|'parse-error'|'unknown'}
+ */
+function classifyOriginError(message) {
+  const msg = typeof message === 'string' ? message : '';
+  if (msg.includes('unrecognized subcommand')) return 'stale-binary';
+  if (/^git fetch origin\b/.test(msg)) return 'fetch-failed';
+  if (msg.includes('plans-snapshot produced no JSON') ||
+      msg.includes('plans-snapshot JSON parse')) return 'parse-error';
+  return 'unknown';
+}
+
+/**
+ * True when an origin-fetch error means the branch no longer exists on the
+ * remote — it was merged and deleted, so `git fetch origin <branch>` fails with
+ * git's `couldn't find remote ref <branch>`. This is NOT a transient fetch
+ * failure (network / auth): the branch is *gone*, so re-fetching it every poll
+ * cycle is pure noise. The dashboard uses this to record the branch as gone,
+ * fall back to the VM probe quietly, and stop logging an error every cycle —
+ * the difference between a healthy fleet that *reads* broken in the log and one
+ * that reads calm. Pure so it is unit-testable.
+ * @param {?string} message The caught fetch-error message text.
+ * @returns {boolean}
+ */
+function isRemoteRefGone(message) {
+  const msg = typeof message === 'string' ? message : '';
+  return /couldn't find remote ref/i.test(msg);
+}
+
+/**
+ * Parses the stdout of `editor plans-snapshot --format json` into the snapshot
+ * envelope the dashboard consumes. The pure half of snapshotPlansFromOrigin:
+ * extracts the JSON object (the CLI may prefix a dev-build banner), parses it,
+ * and normalizes missing arrays to []. Throws a descriptive error on no-JSON
+ * or malformed-JSON so the caller can fall back to the VM probe.
+ * @param {string} stdout The plans-snapshot CLI stdout.
+ * @returns {{ref: string, sha: string, plans: Object[], completedSlugs: string[]}}
+ */
+function parsePlansSnapshotStdout(stdout) {
+  const m = stdout && stdout.match(/\{[\s\S]*\}/);
+  if (!m) throw new Error('plans-snapshot produced no JSON');
+  let data;
+  try {
+    data = JSON.parse(m[0]);
+  } catch (e) {
+    throw new Error(`plans-snapshot JSON parse: ${e.message}`);
+  }
+  return {
+    ref: data.ref,
+    sha: data.sha,
+    plans: data.plans || [],
+    completedSlugs: data.completedSlugs || [],
+  };
+}
+
 module.exports = {
   indexVmsBySessionId,
   unsatisfiedDeps,
   resolvePlanRows,
+  planSourceForProject,
+  planPanelSourceLabel,
+  classifyOriginError,
+  isRemoteRefGone,
+  parsePlansSnapshotStdout,
   REQUIRED_PLAN_ROW_FIELDS
 };

package/npm/fleet-prewarm.js

@@ -0,0 +1,165 @@
+'use strict';
+
+// npm/fleet-prewarm.js — pure verdicts for the fleet dashboard's concurrent
+// cold-add pre-warm (vm--concurrent-add-prewarm-branch-image).
+//
+// When several VMs are added at once on a branch whose prebuilt image is not yet
+// published, EVERY VM compiles the editor from source (~10 min each) in
+// parallel — none has finished compiling-and-publishing before its siblings
+// start, so the self-feeding fast path (publish_compiled_binary in
+// scripts/gcp-bootstrap.sh) never gets a chance to prime. The fix is to bring up
+// ONE "pacer" VM first, wait until it has published the branch binary (or
+// settled on a definite won't-publish), then release the rest so they pull it.
+//
+// This module holds the *decisions* — pace-or-fan-out, which tags constitute a
+// usable image, parsing the bootstrap's machine markers, and the push-token
+// diagnostic — so each case is unit-tested without a live VM or registry. The
+// I/O (the manifest probe, reading the add log, threading the held queue) lives
+// in the server / cloud.js shells that call these.
+
+// Machine-detectable markers gcp-bootstrap.sh emits into the cloud:up add log
+// (streamed to /tmp/dash-add-vm-<n>.log). They are stable contracts the
+// dashboard greps for — keep them in sync with scripts/gcp-bootstrap.sh.
+const MARKER_PUBLISHED = 'CY_BINARY_PUBLISHED'; // pacer published the branch binary; held adds can pull it
+const MARKER_PUBLISH_SKIPPED = 'CY_BINARY_PUBLISH_SKIPPED'; // pacer will NOT publish (no token / no branch / failure)
+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)
+
+// 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
+// universal "main" slug, matching the bootstrap's detached-HEAD fallback.
+function branchSlug(branch) {
+  if (!branch || typeof branch !== 'string') return 'main';
+  const slug = branch.replace(/\//g, '-').toLowerCase().slice(0, 128);
+  return slug || 'main';
+}
+
+// The tag chain that constitutes a "usable" prebuilt editor image, in the same
+// precedence the dev bootstrap pulls (build_editor_image in gcp-bootstrap.sh):
+//   1. cloud-smoke:<slug>-latest   — the branch base image
+//   2. cloud-smoke:main-latest     — the universal CI fallback (skipped when
+//                                    the branch already IS main, no duplicate)
+//   3. binary:<slug>-latest        — the branch binary overlay
+// If a manifest HEAD on ANY of these succeeds, a cold add can pull instead of
+// compiling, so no pacer is needed. Registry defaults to the same
+// CODEYAM_REGISTRY the bootstrap reads.
+function usableImageTags({ registry, branch } = {}) {
+  const reg = registry || 'ghcr.io/codeyam-ai';
+  const slug = branchSlug(branch);
+  const tags = [`${reg}/codeyam-editor-cloud-smoke:${slug}-latest`];
+  if (slug !== 'main') tags.push(`${reg}/codeyam-editor-cloud-smoke:main-latest`);
+  tags.push(`${reg}/codeyam-editor-binary:${slug}-latest`);
+  return tags;
+}
+
+// The core verdict: should a batch add pace one VM ahead of the rest?
+//
+//   count           how many VMs the operator asked to add
+//   hasUsableImage  the probe result — true (image present), false (definitely
+//                   absent), or null (couldn't determine: no token, probe error)
+//   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
+//   - 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).
+function decideBatchPrewarm({ count, hasUsableImage, hasPushToken } = {}) {
+  const k = Math.round(Number(count) || 0);
+  if (k <= 1) return { pace: false, reason: 'single add — never serialized' };
+  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` };
+}
+
+// Has the pacer's add log settled to a definite publish outcome the held batch
+// can act on? Returns 'published' (binary is now pullable — release and pull),
+// 'skipped' (pacer will NOT publish — release; they recompile, today's
+// behavior), or null (still in flight — keep waiting). A SKIPPED that is later
+// followed by a PUBLISHED still reports published (the success wins), so marker
+// ordering can't strand the batch on a transient earlier skip.
+function detectPublishSettled(logText) {
+  if (!logText || typeof logText !== 'string') return null;
+  if (logText.includes(MARKER_PUBLISHED)) return 'published';
+  if (logText.includes(MARKER_PUBLISH_SKIPPED)) return 'skipped';
+  return null;
+}
+
+// The pure release decision for the pre-warm hold (startPrewarmWatch's per-tick
+// verdict): given the pacer's current signals, should the held batch be released
+// now, and why? Returns a human reason string to release, or null to keep
+// waiting. Releases on the FIRST of: a settled publish marker, the pacer job
+// terminating without one, or the bounded timeout — so a publish failure or a
+// stuck pacer can never strand the batch.
+//
+//   settled     detectPublishSettled() result: 'published' | 'skipped' | null
+//   pacerJob    the pacer add job record ({ state, ... }) or null/undefined
+//   elapsedMs   ms since the watch started
+//   timeoutMs   the bounded fallback after which the batch releases regardless
+function prewarmReleaseDecision({ settled, pacerJob, elapsedMs, timeoutMs } = {}) {
+  if (settled) return `pacer ${settled}`;
+  const st = pacerJob && pacerJob.state;
+  if (st === 'done' || st === 'error') return `pacer ${st}`;
+  if (Number(elapsedMs) > Number(timeoutMs)) return 'timeout';
+  return null;
+}
+
+// Which provision path did a VM take, parsed from its add log's path marker?
+// Returns 'pull' (~2 min prebuilt pull), 'compile' (~10 min source compile), or
+// null (not yet determined). The LAST marker wins — a VM that tries a pull,
+// misses, then falls back to a compile correctly reads 'compile'.
+function provisionPath(logText) {
+  if (!logText || typeof logText !== 'string') return null;
+  const pull = logText.lastIndexOf(MARKER_PATH_PULL);
+  const compile = logText.lastIndexOf(MARKER_PATH_COMPILE);
+  if (pull < 0 && compile < 0) return null;
+  return compile > pull ? 'compile' : 'pull';
+}
+
+// Operator-facing one-liner for a provision path, for the add card sub-status.
+// null path → null (render nothing).
+function provisionPathLabel(path) {
+  if (path === 'pull') return 'pulling prebuilt image (~2 min)';
+  if (path === 'compile') return 'compiling from source (~10 min)';
+  return null;
+}
+
+// The push-token diagnostic surfaced on the dashboard. Without a write:packages
+// token the self-feeding publish is silently off, so EVERY cold add recompiles
+// (~10 min) and the pacer can't help either — a state the operator must see, not
+// discover from a buried per-VM log line.
+function pushTokenDiagnostic({ hasPushToken } = {}) {
+  if (hasPushToken) return { warn: false, message: null };
+  return {
+    warn: true,
+    message:
+      'Self-feeding disabled: no CODEYAM_GHCR_PUSH_TOKEN (write:packages). ' +
+      'Cold adds will always recompile the editor from source (~10 min each) ' +
+      'and concurrent batches cannot pre-warm. Install a write-scoped token and ' +
+      'reinstall the fleet agents to enable the fast path.',
+  };
+}
+
+module.exports = {
+  MARKER_PUBLISHED,
+  MARKER_PUBLISH_SKIPPED,
+  MARKER_PATH_PULL,
+  MARKER_PATH_COMPILE,
+  branchSlug,
+  usableImageTags,
+  decideBatchPrewarm,
+  detectPublishSettled,
+  prewarmReleaseDecision,
+  provisionPath,
+  provisionPathLabel,
+  pushTokenDiagnostic,
+};

package/npm/fleet-public-url.js

@@ -0,0 +1,160 @@
+'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 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';
+}
+
+/** 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';
+}
+
+module.exports = {
+  classifyPublicUrlHealth,
+  ingressUnwiredReason,
+  shouldAutoRewireIngress,
+  classifyBackendAttachment,
+};

package/npm/fleet-queue.js

@@ -37,4 +37,41 @@ 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 };
+}
+
+module.exports = { decideAutoReleaseGoneHead, computeReorderTargets };