@codeyam-editor/codeyam-editor 0.1.5 → 0.1.6

package/npm/fleet-vm-access.js

@@ -105,6 +105,132 @@ function normalizeAccessList(input) {
   return out;
 }
 
+// The env/config key holding the standing default-operator principal(s) — the
+// fleet owner / ops identity that must ALWAYS be able to reach an IAP-secured VM.
+// Comma-separated `user:`/`group:`/`domain:` principals (a bare email defaults to
+// `user:`), e.g. `VM_ACCESS_DEFAULT=user:jared@codeyam.com`. Read from config, not
+// hardcoded here, so the default operator is tenant-configurable.
+const DEFAULT_OPERATOR_ENV = 'VM_ACCESS_DEFAULT';
+
+// The default gcloud-account resolver, split out so it is the ONLY function that
+// touches child_process — the module stays side-effect-free at load, and
+// resolveDefaultOperator takes an injectable `exec` so its fallback is unit
+// testable without a real gcloud. Returns the active account email, or '' when
+// gcloud is absent / errors (never throws to the caller).
+function defaultGcloudAccountExec() {
+  const { spawnSync } = require('child_process');
+  const r = spawnSync('gcloud', ['config', 'get-value', 'account'], { encoding: 'utf8' });
+  if (!r || r.status !== 0) return '';
+  return String(r.stdout || '').trim();
+}
+
+// Read the standing default-operator principal(s) from `.codeyam/cloud.json`'s
+// `vmAccessDefault` key — the durable per-project config that resolves the default
+// operator even when a launchd/systemd env was never re-baked with
+// `VM_ACCESS_DEFAULT`. Returns the raw config value ('' when the file is missing or
+// malformed, or the key is absent / not a string) so a broken cloud.json is treated
+// as "no config" and never throws. Split out (like defaultGcloudAccountExec) so the
+// cloud.json layer of resolveDefaultOperator is injectable/unit-testable without a
+// real file. `.codeyam/cloud.json` is resolved via `rootDir` — the same repo root
+// the access sidecar and other state files use. `cloudJsonPath` is a parameter
+// (defaulting to that resolved path) so the reader is unit-testable against a temp
+// file, the same injectable-for-testability posture as defaultGcloudAccountExec.
+// The path also honors `VM_ACCESS_CLOUD_JSON` — the same env-override isolation
+// posture as `VM_ACCESS_FILE` above — so a test process (or an operator) can point
+// this read at a throwaway path and never pick up the developer's real
+// `.codeyam/cloud.json` `vmAccessDefault`.
+function defaultCloudConfigRead(
+  cloudJsonPath = process.env.VM_ACCESS_CLOUD_JSON || path.join(rootDir, '.codeyam', 'cloud.json'),
+) {
+  try {
+    const raw = fs.readFileSync(cloudJsonPath, 'utf8');
+    const data = JSON.parse(raw);
+    if (data && typeof data === 'object' && !Array.isArray(data)) {
+      return typeof data.vmAccessDefault === 'string' ? data.vmAccessDefault : '';
+    }
+  } catch { /* missing or malformed cloud.json → no config */ }
+  return '';
+}
+
+/** Resolve the standing default-operator principal(s) that must be granted IAP
+ *  access whenever a VM's IAP is enabled — the fix for "IAP enabled but nobody
+ *  granted" (the Error-51-by-default footgun). Config first, most-specific to
+ *  least:
+ *    1. `VM_ACCESS_DEFAULT` (the env knob) — normalized and returned.
+ *    2. `.codeyam/cloud.json`'s `vmAccessDefault` — the DURABLE per-project config,
+ *       consulted when the env var is unset. This closes the gap that made every
+ *       fleet Add grant nobody: the dashboard/Add runs as the automation SERVICE
+ *       ACCOUNT, and with no `VM_ACCESS_DEFAULT` in the (un-re-baked) launchd env
+ *       the resolver used to fall straight through to the gcloud fallback and skip
+ *       the SA — resolving `[]`. Reading cloud.json here means every caller
+ *       (iap-access.sh, cloud.js, the dashboard) inherits the default operator
+ *       without an env re-bake.
+ *    3. Fallback: the active gcloud account, so a HUMAN operator running these
+ *       scripts locally gets access with no extra config. A SERVICE-ACCOUNT
+ *       session (the automation SA, whose account ends in `gserviceaccount.com`)
+ *       is skipped — granting the automation SA to itself is a pointless no-op,
+ *       and the human/ops identity it should grant is unknowable from the SA
+ *       session, so config (env or cloud.json) is REQUIRED there.
+ *  Returns a normalized principal array (possibly empty — callers treat empty as
+ *  "no default operator configured" and keep their prior behavior). `exec` and
+ *  `readCloudConfig` are injectable so the gcloud and cloud.json fallbacks are
+ *  unit-testable without a real gcloud / file. */
+function resolveDefaultOperator({ env = process.env, exec, readCloudConfig } = {}) {
+  const configured = env[DEFAULT_OPERATOR_ENV];
+  if (configured != null && String(configured).trim() !== '') {
+    try { return normalizeAccessList(configured); } catch { return []; }
+  }
+  let fromCloud = '';
+  try { fromCloud = String((readCloudConfig || defaultCloudConfigRead)() || '').trim(); }
+  catch { fromCloud = ''; }
+  if (fromCloud !== '') {
+    try { return normalizeAccessList(fromCloud); } catch { return []; }
+  }
+  let account = '';
+  try { account = String((exec || defaultGcloudAccountExec)() || '').trim(); }
+  catch { account = ''; }
+  if (account === '' || /gserviceaccount\.com$/i.test(account)) return [];
+  try { return normalizeAccessList(account); } catch { return []; }
+}
+
+/** The loud degraded reason(s) to attach to a freshly-added VM whose IAP would
+ *  authorize NOBODY. Fires only for a SUCCESSFUL `add` (`ok`) in LB mode (`lbMode`
+ *  — a FLEET_DOMAIN is configured so the VM's public URL is IAP-gated) when the
+ *  default operator resolved empty (`resolvedOperatorCount === 0`): the automation-
+ *  SA identity with no `VM_ACCESS_DEFAULT` env AND no `.codeyam/cloud.json`
+ *  `vmAccessDefault` fallback (the 2026-07-09 footgun). In that case the URL comes
+ *  up authorizing nobody yet the add reads as "done" — so we surface the exact
+ *  remedy on the card instead of a silently gated URL. `resolvedOperatorCount` is
+ *  `null` when the caller skipped the (gcloud) resolve because the cheap gates
+ *  already failed; the `!== 0` test covers both null and a positive count. Returns a
+ *  single actionable reason or [] so the dashboard can spread it into
+ *  `degradedReasons` with no conditional at the call site. Pure (no I/O): the string
+ *  lives in exactly one place and the trigger is unit-testable. */
+function noDefaultOperatorDegradedReasons({ ok, action, lbMode, resolvedOperatorCount, vmNumber } = {}) {
+  if (!ok || action !== 'add' || !lbMode || resolvedOperatorCount !== 0) return [];
+  return [
+    'iap-default-operator-missing: IAP default operator not configured — set '
+      + 'VM_ACCESS_DEFAULT or cloud.json vmAccessDefault (the public URL will '
+      + `authorize nobody; run scripts/gcp/iap-access.sh ${vmNumber} grant after configuring).`,
+  ];
+}
+
+/** Union the default-operator principal(s) into an access list, deduped and
+ *  order-preserving (explicit collaborators first, the operator appended if not
+ *  already present). Both inputs are normalized. The result is what gets GRANTED;
+ *  the per-VM sidecar still records only the explicit collaborators, so the
+ *  always-present operator never pollutes the per-VM whitelist display or a
+ *  reused number's stale-revoke computation. */
+function withDefaultOperator(list, defaultOperator) {
+  const base = normalizeAccessList(list);
+  const seen = new Set(base);
+  const out = base.slice();
+  for (const p of normalizeAccessList(defaultOperator)) {
+    if (!seen.has(p)) { seen.add(p); out.push(p); }
+  }
+  return out;
+}
+
 // Read the access sidecar, returning a `{ [vmNumber]: principal[] }` object, or
 // null if the file is missing or malformed (treated as "no access lists"). Keys
 // are the string form JSON emits; callers look them up by `String(n)`.
@@ -208,6 +334,44 @@ function parseProjectMembers(stdout) {
   return out;
 }
 
+/** Reconcile a VM's LOCAL access sidecar against LIVE IAM. PURE — the caller
+ *  does the two reads (the sidecar file, the gcloud IAP probe) and hands both in,
+ *  so this decision logic is unit-testable without the fleet dashboard's
+ *  untestable server shell around it.
+ *
+ *  `sidecar` is the recorded principal list (what someone asked to grant);
+ *  `iapMembers` is the aggregated live-IAM result from
+ *  fleet-public-url.js::aggregateIapMembers, or null/undefined when that read has
+ *  not landed or a surface errored. Returns:
+ *
+ *    live    — the principals IAM actually authorizes. The display truth.
+ *    drift   — sidecar principals live IAM does NOT confirm. These are failed
+ *              grants; a caller renders them flagged, never as access.
+ *    pending — the live read is unavailable, so NEITHER list is verified.
+ *    partial — a principal holds the role on some ingress surfaces but not all.
+ *
+ *  The pending distinction is the whole point. Treating an unavailable read as an
+ *  empty policy would render a genuinely-granted collaborator as missing — the
+ *  same false report as the bug this replaces, merely inverted. So when
+ *  `iapMembers` is absent, `live` is empty, every sidecar principal lands in
+ *  `drift`, and `pending` is true to tell the caller not to assert either way.
+ *
+ *  Comparison is case-insensitive: parseProjectMembers lowercases for
+ *  dedup-stability while the sidecar holds whatever normalizePrincipal produced. */
+function reconcileVmAccess(sidecar, iapMembers) {
+  const recorded = Array.isArray(sidecar) ? sidecar : [];
+  if (!iapMembers || !Array.isArray(iapMembers.all)) {
+    return { live: [], drift: recorded, pending: true, partial: false };
+  }
+  const live = new Set(iapMembers.all.map((m) => String(m).toLowerCase()));
+  return {
+    live: iapMembers.all,
+    drift: recorded.filter((p) => !live.has(String(p).toLowerCase())),
+    pending: false,
+    partial: iapMembers.partial === true,
+  };
+}
+
 /** Drop VM `n`'s entire access list, returning the new map. Clearing an absent
  *  entry is a no-op. Called on Destroy so a number freed and later re-used
  *  doesn't inherit a stale whitelist. */
@@ -221,9 +385,15 @@ function clearAccess(n) {
 module.exports = {
   VM_ACCESS_FILE,
   PRINCIPAL_TYPES,
+  DEFAULT_OPERATOR_ENV,
   normalizePrincipal,
   normalizeAccessList,
+  resolveDefaultOperator,
+  defaultCloudConfigRead,
+  noDefaultOperatorDegradedReasons,
+  withDefaultOperator,
   parseProjectMembers,
+  reconcileVmAccess,
   readAccess,
   writeAccess,
   accessFor,

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

@@ -36,6 +36,20 @@
 //   '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.
@@ -48,15 +62,84 @@
 // 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 —
@@ -94,11 +177,61 @@ function deriveVmReadiness(v, ctx) {
     // '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. Reachable, broker up, and (LB mode) the editor backend is HEALTHY —
-  //    genuinely ready: green, clickable, public URL actually routes.
+  // 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 };
+module.exports = {
+  deriveVmReadiness,
+  READINESS_STATES,
+  isProvisioning,
+  classifyAgentUsability,
+  agentRosterReady,
+};