@codeyam-editor/codeyam-editor 0.1.4 → 0.1.6

package/npm/fleet-vm-probe-target.js

@@ -0,0 +1,282 @@
+'use strict';
+// Where the fleet dashboard sends a per-VM editor-API probe, and how to read
+// the answer.
+//
+// The dashboard gets ALL per-VM live data — reachability, feature, step,
+// selectedPlan, credential health, preview — by probing each VM's editor API.
+// On a laptop that probe goes to `127.0.0.1:PORT_BASE+N`, which is fed by an SSH
+// `-L` forward the vm-watchdog creates. On the GCE operator host those forwards
+// cannot exist: the watchdog runs as root, the fleet VMs use metadata SSH keys
+// (OS Login is OFF) and refuse root login, so `gcloud compute ssh` fails
+// `Permission denied (publickey)`. No forwards ⇒ dead local ports ⇒ every card
+// reads "unreachable" with no progress.
+//
+// On GCE we therefore probe each VM through the LB hostname it is already wired
+// to (`https://vm-<N>.editor.<domain>`), authenticated with an IAP identity
+// token minted by the operator service account. Same paths, same downstream
+// parsing — only the transport changes.
+//
+// Pure logic only — no I/O, no env reads, no clock — so it stays unit-testable
+// in isolation (npm/fleet-vm-probe-target.test.js), exactly like vm-urls.js.
+
+// Loopback host for the laptop probe. The SSH `-L` forward binds here, so the
+// probe must too — 'localhost' could resolve to ::1 and miss an IPv4-only bind.
+const LOCAL_HOST = '127.0.0.1';
+
+/** Resolve where a per-VM editor-API probe should be sent.
+ *
+ *  Returns a descriptor the caller dispatches on:
+ *    { mode: 'lb',    url, headers, authMissing }  — GCE: absolute LB URL
+ *    { mode: 'local', host, port, path, headers }  — laptop: forwarded port
+ *
+ *  `authMissing` is true when a GCE probe has no IAP token to attach. The caller
+ *  must NOT treat the resulting response as reachable — an unauthenticated
+ *  request to an IAP-fronted backend gets a 302 to the Google login page, which
+ *  is "auth misconfigured", not "the VM is up". See classifyProbeResponse.
+ *
+ *  `sessionToken` (optional): the fail-closed editor requires each VM's own
+ *  editor session token in `Authorization` on every gated control-API request.
+ *  When one is supplied, it rides in `Authorization` and the IAP token moves to
+ *  `Proxy-Authorization` (IAP honors it there), so both credentials are present
+ *  without colliding on `Authorization`. When it is absent, header shape is
+ *  byte-for-byte today's behavior (IAP in `Authorization`), keeping the open
+ *  `/api/session-info` reachability probe unchanged.
+ */
+function resolveVmProbeTarget({ onGce, url, n, portBase, path, iapToken, sessionToken } = {}) {
+  const probePath = path == null ? '/' : String(path);
+  if (!probePath.startsWith('/')) {
+    throw new Error(`probe path must start with "/", got: ${probePath}`);
+  }
+
+  if (!onGce) {
+    const base = Number(portBase);
+    const num = Number(n);
+    if (!Number.isInteger(base) || !Number.isInteger(num)) {
+      throw new Error('local probe requires integer portBase and n');
+    }
+    return { mode: 'local', host: LOCAL_HOST, port: base + num, path: probePath, headers: {} };
+  }
+
+  // GCE: the LB URL is the ONLY way in. A VM with no derived URL (legacy
+  // quick-tunnel mode, or a roster entry the URL derivation skipped) has no
+  // reachable address on this host, so fail loud rather than silently falling
+  // back to a local port that is guaranteed dead.
+  const origin = url == null ? '' : String(url).trim().replace(/\/+$/, '');
+  if (origin === '') {
+    throw new Error(`VM-${n} has no LB URL to probe (FLEET_DOMAIN not configured?)`);
+  }
+
+  const token = iapToken == null ? '' : String(iapToken).trim();
+  const session = sessionToken == null ? '' : String(sessionToken).trim();
+  // With a session token the fail-closed editor's own credential owns
+  // `Authorization`; IAP still fronts the LB, so its token moves to
+  // `Proxy-Authorization`. Without one, keep exactly today's IAP-in-
+  // `Authorization` shape. `authMissing` stays keyed on the IAP token alone —
+  // IAP is still required to reach the LB even when a session token is present.
+  let headers;
+  if (session !== '') {
+    headers = { Authorization: `Bearer ${session}` };
+    if (token !== '') headers['Proxy-Authorization'] = `Bearer ${token}`;
+  } else {
+    headers = token === '' ? {} : { Authorization: `Bearer ${token}` };
+  }
+  return {
+    mode: 'lb',
+    url: origin + probePath,
+    headers,
+    authMissing: token === '',
+  };
+}
+
+// The one open control-API endpoint: `/api/session-info` answers WITHOUT the
+// editor's session token — it is the reachability probe. Every other control-API
+// path is gated under fail-closed auth, so the dashboard must attach the VM's
+// session token or get a 401. Kept here (pure, tested) rather than inline in the
+// caller so the open-vs-gated boundary has one authoritative home.
+const OPEN_PROBE_PATHS = new Set(['/api/session-info']);
+
+/** True when a probe path needs the VM's editor session token attached.
+ *
+ *  Only the open reachability probe (`/api/session-info`) is exempt; every other
+ *  control-API path is gated under fail-closed auth. A query string is ignored so
+ *  `/api/session-info?foo` still reads as the open path. */
+function pathNeedsSessionToken(apiPath) {
+  const p = (apiPath == null ? '' : String(apiPath)).split('?')[0];
+  return p !== '' && !OPEN_PROBE_PATHS.has(p);
+}
+
+// Hostname IAP redirects an unauthenticated request to. Matching this is what
+// separates "the token is missing/expired" from "the VM is genuinely down" —
+// both would otherwise read as a non-200 and blank the card identically.
+const IAP_LOGIN_HOST = 'accounts.google.com';
+
+/** Classify a probe response into the three outcomes the dashboard cares about.
+ *
+ *    'ok'                 — 200; caller still has to parse the body.
+ *    'auth-misconfigured' — IAP rejected or challenged us (302→login, 401, 403).
+ *                           The VM may be perfectly healthy; OUR credential is
+ *                           the problem, so this must never render as reachable
+ *                           and must never feed a reset decision.
+ *    'unreachable'        — anything else: the VM/LB backend is not serving.
+ */
+function classifyProbeResponse({ status, location } = {}) {
+  const code = Number(status);
+  if (code === 200) return 'ok';
+  if (code === 401 || code === 403) return 'auth-misconfigured';
+  if (code >= 300 && code < 400) {
+    const to = location == null ? '' : String(location);
+    return to.includes(IAP_LOGIN_HOST) ? 'auth-misconfigured' : 'unreachable';
+  }
+  return 'unreachable';
+}
+
+/** Name the LIKELY cause behind an 'auth-misconfigured' probe, for logs only.
+ *
+ * 401 and 403 both mean "our credential is the problem", so they deliberately
+ * share one outcome — but they have opposite fixes, and telling them apart
+ * previously cost a live `curl` session against the backend (2026-07-20):
+ *
+ *    401 — the fail-closed editor rejected our session token. IAP now rides in
+ *          Proxy-Authorization, so a 401 from the backend means the VM's own
+ *          editor session token in Authorization was missing, stale, or wrong —
+ *          the dashboard invalidates its cached token and self-heals next poll.
+ *    403 — the token is valid but the caller is not authorized. The automation SA
+ *          is missing roles/iap.httpsResourceAccessor on that backend service.
+ *
+ * Returns null for any other status, so callers can log unconditionally.
+ * Diagnostic only — this never feeds a reachability or reset decision. */
+function describeAuthMisconfig(status) {
+  const code = Number(status);
+  if (code === 401) {
+    return "session token rejected — the fail-closed editor requires this VM's " +
+      'own editor session token in Authorization; the dashboard fetch was ' +
+      'missing/stale (it invalidates the cached token and re-fetches next poll)';
+  }
+  if (code === 403) {
+    return 'missing accessor — the automation service account lacks ' +
+      'roles/iap.httpsResourceAccessor on this backend service ' +
+      '(re-grant: bash scripts/gcp/iap-access.sh <N> grant)';
+  }
+  return null;
+}
+
+/** Map a probe outcome (+ optional transport reason) to the per-VM card shape
+ *  the dashboard merges into `state.vms[n]`.
+ *
+ *  The rule this encodes: an 'auth-misconfigured' outcome is NOT reachable, and
+ *  stays distinguishable from a dead VM. Collapsing the two would either render
+ *  a broken credential as a healthy VM, or let our own expired token look like N
+ *  dead boxes and feed a reset decision. Anything unrecognized fails closed to
+ *  unreachable rather than leaking a truthy `reachable`. */
+function probeOutcomeToInfo(outcome, error) {
+  if (outcome === 'ok') return { reachable: true };
+  if (outcome === 'auth-misconfigured') {
+    return { reachable: false, error: 'auth-misconfigured', authMisconfigured: true };
+  }
+  return error ? { reachable: false, error } : { reachable: false };
+}
+
+/** Merge a parsed `/api/session-info` body into the per-VM card shape.
+ *
+ *  The contract, in one place instead of inlined in the dashboard's probe:
+ *    • an unreachable card never takes a body (a credential fault or a dead VM
+ *      must not gain fields from whatever the transport happened to return);
+ *    • a reachable card takes the body ONLY when it is a usable object.
+ *
+ *  That second rule used to be accidental rather than stated. The expression was
+ *  `info.reachable ? { ...info, ...json } : info`, and spreading `null` (or an
+ *  array, or a scalar) is a silent no-op — so an unusable body produced a card
+ *  that read reachable with `clientProject` and `editorIdentity` absent, which is
+ *  indistinguishable from a VM that genuinely reports neither. The resulting card
+ *  shape is deliberately UNCHANGED by making the rule explicit; what changes is
+ *  that the caller can now see the fault (probeBodyFault) and log it instead of
+ *  discovering it days later through a blank card. Pure. */
+function mergeSessionInfoBody(info, json) {
+  if (!info || !info.reachable) return info;
+  if (json === null || typeof json !== 'object' || Array.isArray(json)) return info;
+  return { ...info, ...json };
+}
+
+/** Name the fault when a probe SUCCEEDED at the transport layer but its body is
+ *  not a usable object, else null.
+ *
+ *  This is the hole that cost a full diagnostic session on 2026-07-29. The card
+ *  merge is `info.reachable ? { ...info, ...json } : info`, and spreading `null`
+ *  (or an array, or a JSON scalar) is a silent no-op — so a VM answering 200 with
+ *  an unusable body produced a card that read REACHABLE with every session-info
+ *  field absent (`clientProject` and `editorIdentity` null), and emitted no log
+ *  line at all. `stickyClientProject` then hid it for as long as a previously
+ *  polled value survived in memory, so the fault only surfaced after a dashboard
+ *  restart cleared the sticky cache.
+ *
+ *  A 'bad-json' transport error is the sibling case: the body was unparseable, so
+ *  the probe already fails closed to unreachable — correct, but equally silent.
+ *  Callers pass that through here too so both paths get one loud warning.
+ *
+ *  Returns a short, log-safe fault name:
+ *    'bad-json'    — body did not parse (caller passes error === 'bad-json')
+ *    'null-body'   — parsed to JSON null
+ *    'array-body'  — parsed to an array
+ *    '<type>-body' — parsed to a scalar (number/string/boolean)
+ *  and null when the body is a usable object (the normal case) or the outcome was
+ *  never 'ok' (already classified by probeOutcomeToInfo). Pure. */
+function probeBodyFault(outcome, json, error) {
+  if (error === 'bad-json') return 'bad-json';
+  if (outcome !== 'ok') return null;
+  if (json === null || json === undefined) return 'null-body';
+  if (Array.isArray(json)) return 'array-body';
+  if (typeof json !== 'object') return `${typeof json}-body`;
+  return null;
+}
+
+/** The log line for a probe-body fault, naming the VM, the fault and the HTTP
+ *  status — the three things that were missing when this failure mode cost a
+ *  full diagnostic session with zero log output to work from.
+ *
+ *  A missing status renders as `?` rather than `undefined`: the transport error
+ *  paths (timeout, socket error) never saw a response, and `HTTP undefined` reads
+ *  like a bug in the logger instead of an absent status.
+ *
+ *  Diagnostic only — this never feeds a reachability decision, same contract as
+ *  its sibling describeAuthMisconfig. Pure. */
+function describeProbeBodyFault(n, fault, status) {
+  const code = status == null || status === '' ? '?' : String(status);
+  return `probe VM-${n} /api/session-info: ${fault} (HTTP ${code}) — ` +
+    'card identity (clientProject/editorIdentity) absent this poll';
+}
+
+/** Per-VM, per-fault throttle for probe-fault warnings.
+ *
+ *  The poll cycle runs every ~3s across the whole fleet, so warning on every
+ *  faulted probe would bury the log. Throttling per (VM, fault) keeps a
+ *  persistent fault to one line per interval while still surfacing a NEW fault on
+ *  a different VM immediately.
+ *
+ *  Deterministic: the caller supplies `now`, so no clock is read here and the
+ *  behavior is unit-testable. */
+function createProbeFaultThrottle(intervalMs = 300000) {
+  const last = new Map();
+  return {
+    shouldWarn(n, fault, now) {
+      const key = `${n}:${fault}`;
+      const prev = last.get(key);
+      if (prev != null && now - prev < intervalMs) return false;
+      last.set(key, now);
+      return true;
+    },
+  };
+}
+
+module.exports = {
+  LOCAL_HOST,
+  IAP_LOGIN_HOST,
+  resolveVmProbeTarget,
+  pathNeedsSessionToken,
+  classifyProbeResponse,
+  describeAuthMisconfig,
+  probeOutcomeToInfo,
+  mergeSessionInfoBody,
+  probeBodyFault,
+  describeProbeBodyFault,
+  createProbeFaultThrottle,
+};

package/npm/fleet-vm-readiness.js

@@ -0,0 +1,237 @@
+'use strict';
+// Pure readiness derivation for the Fleet Dashboard's per-VM card
+// (scripts/operator/fleet-dashboard/server.js requires this). Given the merged
+// poll state `v` and the derived `ctx` the card builder already computes,
+// collapse the VM into a single readiness label the card renders. No I/O —
+// server.js owns the polling (including the slow-cadence LB backend-health
+// probe that fills `v.backendHealth`).
+//
+// The bug this fixes: a VM card rendered as idle with a CLICKABLE editor URL the
+// moment the VM was rostered + SSH-tunnel-reachable, even when its public LB URL
+// (vm-<N>.editor.<domain>) would return Envoy "no healthy upstream" (503). The
+// card reflected only SSH-tunnel reachability to :14199, never whether the load
+// balancer actually routes to a HEALTHY backend. Two situations cause the 503,
+// and the card had zero visibility into either:
+//
+//   transient half-wire — the editor is serving but the LB health check hasn't
+//                         marked the backend HEALTHY yet during cold start. It
+//                         resolves on its own; the card should say 'starting'.
+//   permanent half-wire — the per-VM LB backend service was never created (e.g.
+//                         the Add ran under a service account lacking
+//                         compute.backendServices.create), so the URL 503s
+//                         forever until re-wired. The card should say
+//                         'half-wired', visibly distinct from 'starting'.
+//
+// SSH reachability (v.reachable from probeVM over the tunnel) is necessary but
+// not sufficient: the tunnel is up in BOTH 503 cases. Only the LB backend health
+// (gcloud compute backend-services get-health, gathered into v.backendHealth)
+// distinguishes ready / starting / half-wired. The editor's own /healthz can't
+// see the half-wire, so it is not enough on its own.
+//
+//   'provisioning' — an Add/recover job is in flight; the VM is still being
+//                    built, so judging its public-URL readiness is premature.
+//   'unreachable'  — the editor did not answer over the tunnel. Nothing
+//                    downstream (broker, LB health) is meaningful; the link is
+//                    gated exactly as today.
+//   'half-wired'   — LB mode, the editor backend service is ABSENT (never
+//                    created). The permanent 503 case — the public URL will fail
+//                    until re-wired. The state that had NO signal before.
+//   'iap-access-missing' — LB mode, the EDITOR backend service is IAP-enabled but
+//                    has NO accessor binding, so IAP authorizes nobody: the public
+//                    URL returns "Error code 51" for everyone even when the backend
+//                    is healthy. Distinct from 'half-wired' (there the backend is
+//                    absent; here it exists and serves, but nobody's granted) — the
+//                    exact "wired + IAP-enabled but 51s in the browser" gap.
+//   'preview-iap-access-missing' — LB mode, the editor surface grants access but
+//                    the dedicated PREVIEW backend has no accessor binding. The
+//                    editor URL works, but the framed Live Preview (served from the
+//                    separate preview host on client-routed stacks) is blank for
+//                    every authorized user because nobody is granted THERE. A
+//                    softer, non-URL-blocking warning than 'iap-access-missing'
+//                    (the editor link is live) — the monitoring blind spot the
+//                    editor-only IAP probe used to hide.
+//   'starting'     — LB mode, the editor backend exists but is UNHEALTHY (LB has
+//                    not yet marked it HEALTHY). The transient 503 case; flips to
+//                    'ready' on its own once the health check passes.
+//   'broker-down'  — reachable + LB-healthy (or legacy mode), but the broker
+//                    daemon is down, so the VM cannot start an agent session.
+//   'ready'        — reachable, broker up, and (LB mode) the editor backend is
+//                    HEALTHY. The only state whose editor link is live + green.
+//
+// Legacy mode (FLEET_DOMAIN unset ⇒ ctx.lbMode falsey, or no backendHealth
+// supplied): there is no LB to health-check, so the backend-health branch is
+// skipped and readiness degrades to today's reachability/broker behavior — no
+// regression, no gcloud calls.
+//   'ws-dead'      — reachable + LB-healthy, but the public WebSocket path is
+//                    dead: the LB either refused the upgrade outright
+//                    (publicWsHealth 'unwired') or the backend-service timeout is
+//                    below the fleet minimum so the LB severs the socket on a
+//                    fixed interval (the VM5 guillotine). The editor answers HTTP
+//                    but the Build tab can't hold a terminal — NOT 'ready'.
+//   'cli-missing'  — the editor is up but the build-agent CLI isn't installed
+//                    (`providerAuth.cliInstalled === false`): a provisioning
+//                    fault, not a usable VM.
+//   'auth-unsettled' — the auth probe is wedged at `unknown` (timing out — the
+//                    exact VM5 auth shape): we can't even tell if login is
+//                    needed. A provisioning fault distinct from a clean
+//                    needs-login.
+//   'needs-login'  — CLI installed and auth SETTLED to `needs-login`: a
+//                    legitimate, expected state (the user must authenticate),
+//                    surfaced with the Authenticate affordance — NOT a fault and
+//                    NOT a provisioning fault that holds rostering.
+const READINESS_STATES = [
+  'provisioning',
+  'unreachable',
+  'half-wired',
+  'iap-access-missing',
+  'preview-iap-access-missing',
+  'starting',
+  'broker-down',
+  'ws-dead',
+  'cli-missing',
+  'auth-unsettled',
+  'needs-login',
+  'ready',
+];
+
+// The WS-timeout floor classifier lives next to classifyPublicUrlHealth (the
+// public-URL probe is one concern); readiness consumes its verdict.
+const fpub = require('./fleet-public-url');
+
+// Classify the build-agent usability axis from the editor's own `providerAuth`
+// subtree (vm: Readiness Verifies Real Usability). control-api emits the SAME
+// `providerAuth` (with `cliInstalled` + settled `state`) on BOTH /api/config and
+// /api/session-info via build_provider_auth_json, so the dashboard reads it
+// straight off the gathered VM record — no re-derivation. Returns one verdict:
+//   'cli-missing'    — `cliInstalled === false`: a provisioning fault.
+//   'auth-unsettled' — CLI installed but `state === 'unknown'` (probe wedged /
+//                      timing out — the VM5 shape): a provisioning fault.
+//   'needs-login'    — CLI installed, `state === 'needs-login'`: a LEGITIMATE,
+//                      actionable state, not a fault.
+//   'ready'          — CLI installed, `state === 'authenticated'`: usable.
+//   'unknown'        — providerAuth absent (older editor / probe never landed),
+//                      or any other shape: absence of evidence, never a fault.
+// Only an EXPLICIT `cliInstalled === false` / `state === 'unknown'` is a fault;
+// missing fields stay 'unknown' so an older editor never reads as broken.
+function classifyAgentUsability(providerAuth) {
+  if (!providerAuth || typeof providerAuth !== 'object') return 'unknown';
+  if (providerAuth.cliInstalled === false) return 'cli-missing';
+  if (providerAuth.cliInstalled !== true) return 'unknown';
+  if (providerAuth.state === 'unknown') return 'auth-unsettled';
+  if (providerAuth.state === 'needs-login') return 'needs-login';
+  if (providerAuth.state === 'authenticated') return 'ready';
+  return 'unknown';
+}
+
+// Map the agent-usability verdict to the tri-state the rostering gate
+// (fleet-cleanup's reapVerdict) consumes, mirroring `projectWired`'s
+// true|false|null contract so a flaky probe can never strand a healthy VM:
+//   false — a PROVISIONING FAULT ('cli-missing' / 'auth-unsettled'): the box is
+//           not usable, so don't roster it as healthy (the VM5 false-green).
+//   true  — usable enough to roster: 'ready', or a legitimate 'needs-login'
+//           (the user must auth, but that's an expected state, not a
+//           half-provisioned box that should be held back).
+//   null  — 'unknown' (no providerAuth / probe couldn't decide): absence of
+//           evidence must NEVER block rostering, exactly like reapVerdict's null
+//           tolerance for projectWired.
+function agentRosterReady(verdict) {
+  if (verdict === 'cli-missing' || verdict === 'auth-unsettled') return false;
+  if (verdict === 'ready' || verdict === 'needs-login') return true;
+  return null;
+}
+
+// A VM mid-provision: an Add (incl. its recovering re-run) that is queued
+// (number reserved, cloud:up not started) or running. Its public URL has no
+// meaningful readiness yet, so this takes precedence over every other signal —
+// a freshly-reserved VM must not flash 'half-wired' before its backend exists.
+function isProvisioning(job) {
+  if (!job) return false;
+  if (job.action === 'add' && (job.state === 'running' || job.state === 'queued')) return true;
+  if (job.recovering && job.state === 'running') return true;
+  return false;
+}
+
+// `v` is the merged poll state (state.vms[n]); `ctx` carries the derived values
+// the card builder already has on hand:
+//   ctx.job          — the active job (or null), for the provisioning check.
+//   ctx.brokerStatus — the debounced broker tri-state ('down'|'idle'|
+//                      'agent-live'|'unknown') the card already derives.
+//   ctx.lbMode       — true when FLEET_DOMAIN is set (the LB fronts the URLs).
+//                      When false, the backend-health branch is skipped.
+function deriveVmReadiness(v, ctx) {
+  const c = ctx || {};
+  // 1. Still being built — don't judge a half-built VM as ready or half-wired.
+  if (isProvisioning(c.job)) return 'provisioning';
+  // 2. Editor unreachable over the tunnel: we polled nothing, so broker / LB
+  //    health are unknowable. Link gated, exactly as the pre-readiness card did.
+  if (!v || !v.reachable) return 'unreachable';
+  // 3. LB mode only: the public URL's fate is the editor backend's LB health.
+  //    Skipped entirely in legacy mode (no LB) or before the first probe lands
+  //    (no backendHealth) — both fall through to the reachability/broker path.
+  const bh = v.backendHealth;
+  if (c.lbMode && bh) {
+    // Backend service never created ⇒ permanent 503 until re-wired.
+    if (bh.editor === 'absent') return 'half-wired';
+    // Backend exists but not yet HEALTHY ⇒ transient 503 during cold start.
+    if (bh.editor === 'unhealthy') return 'starting';
+    // 'healthy' falls through to ready; 'unknown' (get-health errored) is
+    // absence-of-evidence — never rendered as a problem, falls through too.
+  }
+  // 3b. IAP access: the backend is IAP-enabled but has NO accessor binding, so
+  //     IAP authorizes nobody and the public URL returns "Error code 51" for
+  //     everyone — even when the backend is healthy. A wiring-class fault a plain
+  //     GET / backend-health probe are both blind to. Only an EXPLICIT
+  //     'no-accessor' verdict fires; absence/'unknown' is never a fault (an older
+  //     dashboard that never gathered it must not read as broken). Gated on
+  //     lbMode — legacy quick-tunnel mode has no per-BES IAP to check.
+  if (c.lbMode && v.iapAccess === 'no-accessor') return 'iap-access-missing';
+  // 4. Reachable but the broker daemon is down: the VM can't start a session.
+  if (c.brokerStatus === 'down') return 'broker-down';
+  // 5. WS-usability (LB mode): the editor answers HTTP and the backend is
+  //    LB-healthy, but the public WebSocket path is dead — either the LB refused
+  //    the upgrade outright (publicWsHealth 'unwired') or the backend-service
+  //    timeout is below the fleet minimum so the LB severs the socket on a fixed
+  //    interval (the VM5 guillotine). Either way the Build tab can't hold a
+  //    terminal, so this is NOT 'ready'. Skipped in legacy mode (no LB). An
+  //    'unknown'/absent WS verdict is absence-of-evidence — never a fault.
+  if (c.lbMode) {
+    // Deterministic guillotine first: a BES timeout below the fleet minimum
+    // severs the socket on a fixed interval — trustworthy, no probe needed.
+    if (fpub.classifyWsTimeout(v.backendTimeoutSec) === 'ws-timeout-too-low') return 'ws-dead';
+    // The public WS probe is IAP-blind and false-positives `unwired` on a
+    // genuinely-healthy VM (VM-1, 2026-07-01: wired + HEALTHY + IAP-granted,
+    // yet `publicWsHealth: unwired` → phantom ws-dead → URL gated "not ready").
+    // Only trust an `unwired` verdict when the backend is NOT already HEALTHY —
+    // a HEALTHY backend with a valid/unknown timeout is never ws-dead.
+    if (v.publicWsHealth === 'unwired' && !(bh && bh.editor === 'healthy')) return 'ws-dead';
+  }
+  // 6. Agent usability: the box is up and the WS path carries frames, but the
+  //    build agent itself may not be usable — CLI not installed, or the auth
+  //    probe wedged at 'unknown'. A legitimate 'needs-login' surfaces as its own
+  //    actionable state (Authenticate), distinct from a provisioning fault.
+  //    Absence of providerAuth (older editor / unprobed) falls through to ready.
+  const usability = classifyAgentUsability(v.providerAuth);
+  if (usability === 'cli-missing') return 'cli-missing';
+  if (usability === 'auth-unsettled') return 'auth-unsettled';
+  if (usability === 'needs-login') return 'needs-login';
+  // 6b. Preview-host IAP gap: the editor surface grants access (the URL routes
+  //     and the box is otherwise ready) but the dedicated preview backend has no
+  //     accessor, so the framed Live Preview is blank for authorized users. A
+  //     softer warning than the editor 'iap-access-missing' — it does NOT block
+  //     the editor link (see URL_BLOCKED_READINESS) — so it is checked last, just
+  //     before 'ready'. Only an EXPLICIT 'preview-no-accessor' verdict fires;
+  //     absence/'unknown' is never a fault. Gated on lbMode like its editor twin.
+  if (c.lbMode && v.iapAccess === 'preview-no-accessor') return 'preview-iap-access-missing';
+  // 7. Reachable, broker up, WS carries frames, agent usable, and (LB mode) the
+  //    editor backend is HEALTHY — genuinely ready: green, clickable, the public
+  //    URL routes AND holds a WebSocket.
+  return 'ready';
+}
+
+module.exports = {
+  deriveVmReadiness,
+  READINESS_STATES,
+  isProvisioning,
+  classifyAgentUsability,
+  agentRosterReady,
+};

package/npm/fleet-vm-slugs.js

@@ -0,0 +1,116 @@
+'use strict';
+
+// npm/fleet-vm-slugs.js — the per-VM custom-slug sidecar
+// (`.codeyam/logs/fleet-vm-slugs.json`). A slug is an optional human-readable
+// override for a VM's leftmost hostname label, so its public URLs become
+// `<slug>.editor.<domain>` instead of the number-derived `vm-<N>.editor.<domain>`.
+//
+// Why a sidecar and not the roster: the roster (`npm/fleet-roster.js`) is a flat
+// integer array with a hard "sorted, de-duped set of integers" invariant that
+// bash consumers (`vm-urls.sh`, the watchdog) depend on. Rather than break that
+// shape, slugs live in a SEPARATE map `{ "<N>": "<slug>" }`, fronted by a
+// read+write seam modeled exactly on fleet-roster.js (atomic temp-file + rename,
+// tolerant of a missing/malformed file).
+//
+// The slug is purely a public-hostname override — internal GCP resource names
+// (NEG / backend service / path matcher) stay keyed off the VM number, so a VM
+// added without a slug keeps its `vm-<N>` URLs unchanged.
+//
+// Env override: `VM_SLUGS_FILE` relocates the file (mirrors fleet-roster.js's
+// `VMS_STATE_FILE`); resolved once at module load.
+
+const fs = require('fs');
+const path = require('path');
+
+const { rootDir } = require('./utils');
+const { normalizeVmNumber, normalizeVmSlug } = require('./vm-urls');
+
+const VM_SLUGS_FILE = process.env.VM_SLUGS_FILE
+  || path.join(rootDir, '.codeyam', 'logs', 'fleet-vm-slugs.json');
+
+// Read the slug sidecar, returning a `{ [vmNumber]: slug }` object, or null if
+// the file is missing or malformed (treated as "no slugs"). Keys are kept as the
+// string form JSON emits; callers look them up by `String(n)`.
+function readSlugs() {
+  try {
+    const data = JSON.parse(fs.readFileSync(VM_SLUGS_FILE, 'utf8'));
+    if (data && typeof data === 'object' && !Array.isArray(data)) return data;
+  } catch { /* missing or malformed */ }
+  return null;
+}
+
+// Persist `map` as the sidecar, atomically: write a temp file then `rename` it
+// over the target so a concurrent reader never observes a half-written file. The
+// temp name carries the pid so two processes writing at once don't clobber each
+// other's temp file before their renames land. Returns the written map.
+function writeSlugs(map) {
+  const next = map && typeof map === 'object' && !Array.isArray(map) ? map : {};
+  fs.mkdirSync(path.dirname(VM_SLUGS_FILE), { recursive: true });
+  const tmp = `${VM_SLUGS_FILE}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(next));
+  fs.renameSync(tmp, VM_SLUGS_FILE); // atomic replace
+  return next;
+}
+
+/** The slug mapped to VM `n`, or null when it has none (or the file is absent).
+ *  This is the resolver every hostname derivation funnels through:
+ *  `slugFor(n) || ('vm-' + n)`. */
+function slugFor(n) {
+  const num = normalizeVmNumber(n);
+  const map = readSlugs();
+  const slug = map && map[String(num)];
+  return typeof slug === 'string' && slug.length > 0 ? slug : null;
+}
+
+/** The VM number currently mapped to `slug`, or null when no VM owns it. Used to
+ *  reject a duplicate slug BEFORE it is assigned (a slug must be unique across
+ *  the fleet, else two VMs would claim the same hostname). `slug` is normalized
+ *  first so the comparison is case-insensitive. */
+function vmForSlug(slug) {
+  const want = normalizeVmSlug(slug);
+  const map = readSlugs() || {};
+  for (const [k, v] of Object.entries(map)) {
+    if (typeof v === 'string' && v.toLowerCase() === want) {
+      const num = Number(k);
+      if (Number.isInteger(num) && num > 0) return num;
+    }
+  }
+  return null;
+}
+
+/** Assign `slug` to VM `n`, validating the slug (via `normalizeVmSlug`) and
+ *  rejecting a slug already mapped to a DIFFERENT VM. Returns the written map.
+ *  Re-assigning a VM its own existing slug is an idempotent no-op-shaped write. */
+function setSlug(n, slug) {
+  const num = normalizeVmNumber(n);
+  const norm = normalizeVmSlug(slug);
+  const owner = vmForSlug(norm);
+  if (owner != null && owner !== num) {
+    throw new Error(
+      `VM slug "${norm}" is already assigned to VM-${owner} — pick another name`,
+    );
+  }
+  const map = { ...(readSlugs() || {}) };
+  map[String(num)] = norm;
+  return writeSlugs(map);
+}
+
+/** Remove VM `n`'s slug mapping, returning the new map. Removing an absent entry
+ *  is a no-op. Called on Destroy so a number freed and later re-used doesn't
+ *  inherit a stale slug. */
+function removeSlug(n) {
+  const num = normalizeVmNumber(n);
+  const map = { ...(readSlugs() || {}) };
+  delete map[String(num)];
+  return writeSlugs(map);
+}
+
+module.exports = {
+  VM_SLUGS_FILE,
+  readSlugs,
+  writeSlugs,
+  slugFor,
+  vmForSlug,
+  setSlug,
+  removeSlug,
+};