@codeyam-editor/codeyam-editor 0.1.4 → 0.1.6

package/npm/fleet-add-failure.js

@@ -0,0 +1,252 @@
+'use strict';
+
+const fc = require('./fleet-cleanup');
+const { parseRosterMarkers } = require('./fleet-early-roster');
+
+// npm/fleet-add-failure.js — pure classifier for a FAILED fleet-dashboard `add`
+// provision. Before this, every failed add rendered an identical red "add error"
+// badge whose only action was "Clear badge", and a restart mid-add collapsed the
+// message to a content-free `(re-attached after restart — detached provision
+// exited 1)`. The real cause — captured to the provision transcript on disk — was
+// thrown away. This happened live with VM9/VM10: both aborted at the streamed-
+// script drift guard because a bootstrap script had uncommitted local edits, but
+// the operator saw only "exited 1" and had to dig through /tmp/dash-add-vm-N.log.
+//
+// classifyAddFailure turns a transcript tail + exit code into a differentiated,
+// ACTIONABLE verdict: a plain-language headline, a concrete recovery instruction,
+// and — crucially — a `retryable` flag that is true ONLY where a one-click retry
+// provably cannot orphan or duplicate a GCP box: either nothing was provisioned,
+// or the remaining work is re-entrant so the retry converges on the existing VM.
+// Both grounds are spelled out on ADD_FAILURE_RETRYABLE below. The decision logic
+// lives here as a pure module (like fleet-job-badge.js::canClearBadge) so the
+// whole failure matrix is unit-tested without a live VM; server.js is the thin
+// I/O shell that gathers the transcript and turns the verdict into a card + a
+// server-re-guarded retry action.
+
+// The SINGLE source of truth for which categories are safe to auto-retry.
+// `retryable` on every returned verdict is stamped from this Set, so the
+// invariant `retryable === has(category)` holds by construction and the server
+// can re-guard a retry against the same Set.
+//
+// A category earns membership on EITHER of two grounds — both of which
+// guarantee a one-click retry cannot silently orphan or duplicate a GCP box:
+//
+//   1. NOTHING WAS PROVISIONED. The classifier can prove no cloud resource was
+//      created (`preflight-drift` aborts before the first gcloud call;
+//      `instance-vanished` confirms the instance is gone). Retry starts clean.
+//
+//   2. THE REMAINING WORK IS RE-ENTRANT. A real VM exists, but every step the
+//      retry would re-run is skip-on-exists or re-attaching, so the retry
+//      CONVERGES on the existing box instead of building a second one.
+//      `project-bootstrap-timeout` is this shape: the VM is up and its detached
+//      bootstrap is still running, `ensureInstance` reuses the live instance,
+//      `ensureBootstrapped` skips on the present image, and
+//      `ensureProjectBootstrapped` re-attaches to the in-flight install rather
+//      than starting a second `npm install` over the first.
+//
+// Ground 2 is deliberately narrow — it is NOT "the VM probably still works".
+// `container-stuck` and `incomplete-workspace` also leave a live VM, but their
+// remaining work is NOT provably re-entrant, so they stay non-retryable.
+const ADD_FAILURE_RETRYABLE = new Set([
+  'preflight-drift',
+  'instance-vanished',
+  'project-bootstrap-timeout',
+]);
+
+// Collect the `    - <path>` bullets the drift guard prints AFTER the "following
+// files differ" header (see npm/cloud.js), stopping at the first non-bullet line
+// so an unrelated "- " elsewhere in the transcript can't leak in. Returns [] when
+// no drift block is present.
+function extractDriftFiles(logTail) {
+  const lines = String(logTail || '').split('\n');
+  const files = [];
+  let inBlock = false;
+  for (const line of lines) {
+    if (!inBlock) {
+      if (/following files differ/i.test(line)) inBlock = true;
+      continue;
+    }
+    const m = line.match(/^\s+-\s+(.+?)\s*$/);
+    if (m) { files.push(m[1]); continue; }
+    break; // first non-bullet after the header ends the block
+  }
+  return files;
+}
+
+// Pure transform: the last `maxLines` non-empty lines of a transcript, each
+// right-trimmed. Extracted from readProvisionTail (server.js) so the aggregation
+// is unit-tested and that function stays a thin filesystem-boundary call. Returns
+// '' for empty/whitespace-only input.
+function lastNonEmptyLines(text, maxLines = 50) {
+  const lines = String(text || '')
+    .split('\n')
+    .map((l) => l.replace(/\s+$/, ''))
+    .filter((l) => l.length > 0)
+    .slice(-maxLines);
+  return lines.join('\n');
+}
+
+// True iff the provision transcript reached the early-roster marker (`CY_ROSTER
+// <n>`) — i.e. the instance exists and the container gate passed, so the VM is
+// rostered. Reuses parseRosterMarkers (npm/fleet-early-roster.js) so the
+// `CY_ROSTER` grammar has a single owner rather than a second inlined regex. Any
+// valid marker means "rostered"; the specific VM number is irrelevant here — a
+// provision transcript only ever carries its own VM's marker. Never throws.
+function transcriptRostered(logTail) {
+  return parseRosterMarkers(String(logTail || '')).length > 0;
+}
+
+// Build a verdict, stamping `retryable` from the single-source-of-truth Set so it
+// can never drift from the category.
+function buildFailureVerdict(category, headline, recovery, extra) {
+  const out = { category, headline, recovery, retryable: ADD_FAILURE_RETRYABLE.has(category) };
+  if (extra && extra.files) out.files = extra.files;
+  return out;
+}
+
+// Classify a failed add from its transcript tail + exit code.
+//
+//   logTail   the last lines of the provision transcript (string; '' when the
+//             log was unreadable — must never throw)
+//   exitCode  the provision's exit code (number; used for signal-kill detection)
+//
+// Returns { category, headline, recovery, retryable, files? }.
+//
+// Detection is ORDER-SENSITIVE. The provision shell echoes cloud:up's tail, so a
+// drift / instance-vanished / container-stuck transcript ALSO contains the
+// generic `cloud:up FAILED (exit N)` line. Each specific (and every retryable)
+// signature is therefore tested BEFORE the generic cloud-up-failed signature, or
+// a retryable drift would misclassify as a non-retryable cloud:up failure and the
+// operator would lose the safe one-click recovery.
+function classifyAddFailure({ logTail, exitCode } = {}) {
+  const log = String(logTail || '');
+
+  // 1. preflight-drift — the streamed-script drift guard aborted BEFORE any
+  //    gcloud call, so nothing was provisioned. Retryable once the file is fixed.
+  //    We match the unambiguous abort header / verdict label, NOT the bare
+  //    `CODEYAM_SKIP_SCRIPT_DRIFT_CHECK` token: that token ALSO appears in the
+  //    "bypass active — skipping drift check" warning, so keying on it would
+  //    misclassify a bypass-active add that later failed for a real reason as a
+  //    (retryable!) drift — inviting an unsafe retry. The header below is printed
+  //    only on a genuine drift abort.
+  if (/Streamed scripts carry unreviewed local content/i.test(log)
+      || /UNCOMMITTED LOCAL EDITS/.test(log)) {
+    const files = extractDriftFiles(log);
+    const fileList = files.length ? files.join(', ') : 'the streamed scripts';
+    const fix = files.length
+      ? `Commit & push them, or discard with \`git checkout -- ${files.join(' ')}\`, then Retry add.`
+      : 'Commit & push them, or discard the local edits, then Retry add.';
+    return buildFailureVerdict('preflight-drift', 'Blocked by local edits',
+      `Uncommitted local edits in ${fileList} tripped the streamed-script drift guard, which aborts before any cloud resource is created. ${fix}`,
+      { files });
+  }
+
+  // 2. instance-vanished — the GCP instance is confirmed gone; nothing to orphan.
+  if (/instance .* is gone/i.test(log)) {
+    return buildFailureVerdict('instance-vanished', 'Instance never came up',
+      'The GCP instance is gone — provisioning failed before the container started, so nothing was left behind. Retrying the add is safe.');
+  }
+
+  // 3. project-bootstrap-timeout — the VM came up and its DETACHED project
+  //    bootstrap is still running; we merely stopped waiting on it. This is the
+  //    VM-8 / six-self-host-VM incident: a heavy `npm install` (a ~293 MB
+  //    playwright postinstall, a large `git clone`) outran a local budget, the
+  //    SIGTERM'd gcloud child returned `status: null`, and the abort path read
+  //    that as a broken bootstrap script and DELETED A COMPLETELY HEALTHY VM.
+  //
+  //    Retryable on re-entrancy grounds (see ADD_FAILURE_RETRYABLE): the retry
+  //    re-attaches to the in-flight install rather than starting a second one.
+  //    Tested BEFORE cloud-up-failed because the provision shell echoes cloud:up's
+  //    tail, so this transcript ALSO carries the generic `cloud:up FAILED (exit N)`
+  //    line — matching that first would strip the safe recovery and steer the
+  //    operator to destroy a healthy, still-provisioning VM. The signature is the
+  //    wording ensureProjectBootstrapped (npm/cloud.js) throws for both its
+  //    overall-deadline and its launch-budget timeouts.
+  if (/project bootstrap exceeded the local/i.test(log)) {
+    return buildFailureVerdict('project-bootstrap-timeout', 'Still installing — we stopped waiting',
+      'The VM provisioned fine and its project bootstrap is still running on it; only the local wait budget elapsed. Nothing is broken and nothing was left half-built. Retry the add to re-attach to the running install — each bootstrap step is skip-on-exists. Do NOT destroy this VM.');
+  }
+
+  // 4. container-stuck — the instance exists but the editor container never
+  //    became healthy, so a half-provisioned box may exist. Not retryable.
+  if (/container never came up/i.test(log)) {
+    return buildFailureVerdict('container-stuck', 'Container never became healthy',
+      'The instance came up but the editor container never became healthy — it may be half-provisioned. Reconcile or destroy this VM before re-adding.');
+  }
+
+  // 5. incomplete-workspace — the container came up but the project was never
+  //    scaffolded: no `.codeyam/editor.json` exists under ~/projects on the VM,
+  //    so the greenfield `init` did not complete onboarding. This is specific
+  //    and more actionable than the generic cloud-up-failed below, so it is
+  //    tested first. The VM exists and is half-provisioned, so it is NOT
+  //    auto-retryable — reconcile finishes the scaffold, then re-add.
+  if (/no \.codeyam\/editor\.json found under ~\/projects/i.test(log)) {
+    return buildFailureVerdict('incomplete-workspace', 'Workspace never scaffolded',
+      'The container came up but the project was never scaffolded (no .codeyam/editor.json on the VM), so provisioning did not finish onboarding. Reconcile this VM to complete the scaffold, then re-add.');
+  }
+
+  // 6. cloud-up-failed — a generic cloud:up failure, reached ONLY when the drift /
+  //    vanished / stuck signatures above did not match. A partial instance may
+  //    exist, so not retryable.
+  if (/cloud:up FAILED \(exit/i.test(log)) {
+    return buildFailureVerdict('cloud-up-failed', 'Provisioning failed',
+      'cloud:up failed during provisioning, so a partial instance may exist. Reconcile or destroy this VM before re-adding.');
+  }
+
+  // 7. interrupted — a signal kill (OOM 137, SIGTERM 143, …) or an explicit
+  //    Killed / out-of-memory marker. The real VM state is unknown. Not retryable.
+  if (fc.isSignalKillExit(Number(exitCode)) || /\bKilled\b/.test(log) || /Out of memory/i.test(log)) {
+    return buildFailureVerdict('interrupted', 'Provisioning interrupted',
+      'The provision was interrupted (killed or out of memory), so the VM state is unknown. Reconcile or destroy this VM before re-adding.');
+  }
+
+  // 8. converging — the add reached the early-roster marker (`CY_ROSTER`): the
+  //    container gate passed, the instance is real, and the VM is rostered, yet it
+  //    exited non-zero WITHOUT matching any specific hard-failure signature above.
+  //    By construction of the provision script, every genuine hard failure (drift,
+  //    instance-vanished, container-stuck, incomplete-workspace, cloud-up-failed,
+  //    interrupted) is printed BEFORE `CY_ROSTER`, so a rostered transcript that
+  //    fell through to here is a still-wiring box owned by the detached
+  //    wire-add-tail / reconcile-ingress — NOT an add failure. Surface it as an
+  //    honest in-flight state instead of the scary red `unknown`. Not retryable:
+  //    the VM exists and its detached wiring owns finishing it, so a one-click
+  //    retry could duplicate/orphan a live box. Tested LAST so a hard-failure
+  //    signature (all printed pre-roster) always wins — `converging` can never
+  //    shadow a proven failure.
+  if (transcriptRostered(log)) {
+    return buildFailureVerdict('converging', 'Add still converging',
+      'The container is up and the VM is rostered; the LB ingress is still wiring in the background. This resolves on its own once the editor is reachable over the LB — no action needed unless it persists past the wiring deadline.');
+  }
+
+  // 9. unknown — fallback. Never invite an unproven retry.
+  return buildFailureVerdict('unknown', 'Add failed',
+    'The add failed for an unclassified reason — inspect the transcript below, then reconcile or destroy this VM before re-adding.');
+}
+
+// Pure guard for the operator "Retry add" action: given a VM number and its
+// carried job, decide whether a one-click retry is SAFE. Retry is allowed ONLY
+// for a terminal add-error whose classifier verdict is retryable (a category
+// where nothing was provisioned). Returns { ok, reason } — reason is a stable
+// code the server shell (actionRetryAdd) maps to an operator message. Mirrors
+// fleet-job-badge.js::canClearBadge so the handler stays a thin I/O shell and the
+// safety decision is unit-tested without a live dashboard.
+function canRetryAdd({ n, job } = {}) {
+  if (!Number.isInteger(n) || n < 1) return { ok: false, reason: 'invalid-vm' };
+  if (!job || job.action !== 'add' || job.state !== 'error') return { ok: false, reason: 'no-failed-add' };
+  if (!job.retryable) return { ok: false, reason: 'not-retryable' };
+  return { ok: true, reason: null };
+}
+
+// Pure badge-hold predicate for deriveStatus (server.js): hold the calm in-flight
+// `add-converging` card — instead of the red add-failed — ONLY when the add was
+// classified `converging` AND its detached first-wiring is still in flight. Once
+// the wire-add-tail fails/deadlines (`addTailFailed`) or is gone (`addTailInflight`
+// false), or the category is anything else, return false so the caller falls
+// through to the red add-failed status — the operator-chosen escalation. Kept pure
+// (like canRetryAdd / canClearBadge) so the badge decision is unit-tested without a
+// live dashboard.
+function holdConvergingBadge({ category, addTailInflight, addTailFailed } = {}) {
+  return category === 'converging' && !!addTailInflight && !addTailFailed;
+}
+
+module.exports = { classifyAddFailure, extractDriftFiles, lastNonEmptyLines, canRetryAdd, transcriptRostered, holdConvergingBadge, ADD_FAILURE_RETRYABLE };

package/npm/fleet-asset-version.js

@@ -0,0 +1,37 @@
+'use strict';
+// Pure content-hash UI versioning for the fleet dashboard's cache-busting
+// (vm: Honest VM Card Display + Dashboard Cache-Busting).
+//
+// The dashboard serves its single-file UI (public/index.html) with `no-store`,
+// so a hard-refresh always fetches the new code — but an already-OPEN tab never
+// refetches the HTML and silently runs the pre-restart UI until the operator
+// manually reloads. To fix that, the server stamps a short content hash of the
+// served HTML into every /data response; the client records the version it
+// booted with and `location.reload()`s on a mismatch, so a dashboard restart
+// with new UI reaches an open tab automatically.
+//
+// This module is the PURE half — a deterministic hash of the HTML string, no
+// I/O — mirroring the pure/impure split the other fleet-* modules follow
+// (server.js owns reading the file; this owns turning bytes into a version).
+// Unit-tested in npm/fleet-asset-version.test.js.
+//
+// Stack note: this is fleet-operator dashboard infrastructure (the GCE fleet
+// that runs codeyam-editor itself). A project that never runs the dashboard
+// never reaches it.
+const crypto = require('crypto');
+
+// computeAssetVersion returns a stable, short (12 hex chars) fingerprint of the
+// served UI. Same HTML in ⇒ same version out (so an unchanged deploy never
+// spuriously reloads open tabs); any byte change ⇒ a different version (so a
+// real UI change always reloads them). 12 hex chars of SHA-1 is ample to make
+// an accidental collision between two distinct UI builds negligible while
+// keeping the badge short.
+function computeAssetVersion(html) {
+  return crypto
+    .createHash('sha1')
+    .update(String(html == null ? '' : html))
+    .digest('hex')
+    .slice(0, 12);
+}
+
+module.exports = { computeAssetVersion };

package/npm/fleet-auth-health.js

@@ -0,0 +1,213 @@
+'use strict';
+// Pure decision helpers for the fleet dashboard's false-unreachable reboot
+// safety (2026-06-25 incident). The dashboard's server.js execs gcloud and reads
+// its in-memory state; the DECISIONS those I/O results drive live here so they
+// are unit-testable in isolation (npm/fleet-auth-health.test.js), the same
+// split npm/fleet-cleanup.js (reconcileRosteredVm) and npm/fleet-host.js
+// (gcloudCommand) follow.
+//
+// Pure logic only — no I/O, no env reads, no clock.
+
+const fr = require('./fleet-reachability');
+
+// Classify operator gcloud auth health from the facts server.js gathers via the
+// ${GCLOUD} chokepoint. Returns { degraded, kind, reason }: degraded true means
+// the operator's own side is faulted (which makes EVERY VM read unreachable), so
+// the reset gate must suppress all reboots and the UI must surface a banner.
+//   account       trimmed `gcloud config list account` output (may be empty)
+//   accountErrMsg non-null when the account-resolve exec itself errored
+//   tokenOk       true/false when `auth print-access-token` was run; null when
+//                 it was not (account-only phase) — a valid SA account with
+//                 tokenOk null is "account looks fine, token not yet proven",
+//                 which is NOT degraded, so the caller can proceed to the mint.
+//
+// `kind` DISCRIMINATES the two failures that used to collapse into one banner
+// (2026-07-29): 'auth' means the CREDENTIAL is broken (re-bind the SA), while
+// 'probe-failed' means the INVOCATION never produced an answer (restart the
+// throttled process). Empty output with NO error message is the 'probe-failed'
+// signature — a subprocess starved under cgroup throttling exits without writing
+// anything, whereas a genuine credential failure always produces a message. Both
+// still latch degraded: this adds a discriminator for the operator-facing
+// RECOVERY, it does not weaken the guard. A 'probe-failed' verdict is
+// inconclusive about credentials, so the caller must corroborate with local
+// pressure signals before naming resource exhaustion — the mapping lives in
+// fleet-destroy-safety.classifyDestroyBlock.
+function classifyOperatorAuth({ account, accountErrMsg, tokenOk } = {}) {
+  const acct = typeof account === 'string' ? account.trim() : '';
+  if (accountErrMsg || !acct) {
+    return {
+      degraded: true,
+      kind: accountErrMsg ? 'auth' : 'probe-failed',
+      reason: `operator gcloud could not resolve an account (${accountErrMsg || 'empty output'})`,
+    };
+  }
+  if (!/\.gserviceaccount\.com$/.test(acct)) {
+    return {
+      degraded: true,
+      kind: 'auth',
+      reason: `operator gcloud is on a non-service-account '${acct}' — config drift; run scripts/operator/setup-service-account.sh`,
+    };
+  }
+  if (tokenOk === false) {
+    return {
+      degraded: true,
+      kind: 'auth',
+      reason: `operator gcloud cannot mint a token for ${acct} (expired/absent credentials); run scripts/operator/setup-service-account.sh`,
+    };
+  }
+  return { degraded: false, kind: null, reason: null };
+}
+
+// Consecutive-failure debounce for the FLEET-WIDE operator-auth-degraded BANNER
+// (vm--flap-tolerant-reachability). Splits the two behaviors of the degraded
+// verdict: the auto-reset SUPPRESSION stays conservative (server.js suppresses a
+// reboot on even ONE failed probe — a broken laptop must never reboot a healthy
+// VM), but a single transient gcloud-resolve hiccup must NOT blank the whole
+// fleet with the scary "every VM reads unreachable" banner (observed 2026-07-01:
+// the exact command succeeded 5/5 right after; the degraded flag self-cleared).
+// The BANNER / all-VMs-unreachable DISPLAY requires `threshold` CONSECUTIVE
+// degraded probes; a single healthy probe resets the streak to 0.
+//   prevStreak  the consecutive degraded-probe count from the previous check
+//   degraded    this probe's raw degraded verdict (classifyOperatorAuth.degraded)
+//   threshold   consecutive degraded probes required before the banner fires
+// Returns { streak, display }: display true only once the streak crosses.
+const OPERATOR_AUTH_DISPLAY_THRESHOLD = 3;
+function debounceOperatorAuthDisplay(prevStreak, degraded, threshold = OPERATOR_AUTH_DISPLAY_THRESHOLD) {
+  if (!degraded) return { streak: 0, display: false };
+  const streak = (prevStreak || 0) + 1;
+  return { streak, display: streak >= threshold };
+}
+
+// True when at least `fleetWideThreshold` VMs are simultaneously past the
+// reset-unreachable `threshold` — the signature of an operator-side fault
+// (auth/tunnel/network on the dashboard host) rather than independent VM
+// failures. A real VM failure is isolated; a simultaneous N-VM "outage" is the
+// operator, and the reset gate uses this to refuse rebooting the whole fleet.
+// `vms` is an array of per-VM state objects (missing/null entries are ignored).
+function isFleetWideUnreachable(vms, threshold, fleetWideThreshold) {
+  let count = 0;
+  for (const vm of Array.isArray(vms) ? vms : []) {
+    // Only a DEFINITE unreachable verdict counts. A VM whose reachability is
+    // unknown (never polled, or held inconclusive) has established nothing, and
+    // an unknown must never be evidence in a decision that gates a reboot — the
+    // shared invariant in npm/fleet-reachability.js.
+    if (vm && fr.isConfirmedUnreachable(vm.reachable) && (vm.unreachableStreak || 0) >= threshold) count++;
+  }
+  return count >= fleetWideThreshold;
+}
+
+// Classify a one-shot GCP-side IAP editor probe (server.js execs the SSH+curl).
+// true  → editor answered 200 from GCP's vantage (VM healthy; the dark local
+//         port is a laptop tunnel fault → respawn, never reset);
+// false → the VM is up but the editor does not answer (genuinely unreachable);
+// null  → the IAP probe itself failed (inconclusive — never escalate a reset).
+// The HTTP code is read from the LAST three chars of stdout because gcloud/ssh
+// can prepend banner noise before curl's `%{http_code}` output.
+function classifyIapEditorProbe({ err, stdout } = {}) {
+  if (err) return null;
+  const code = String(stdout || '').trim().slice(-3);
+  return code === '200';
+}
+
+// Choose WHICH signal decides a VM's per-poll reachability, and what it says.
+//
+// The laptop and the GCE operator host see a VM through different eyes. A laptop
+// holds SSH `-L` forwards, so the cheap local-port probe (127.0.0.1:PORT_BASE+n)
+// is a true reachability signal there. The GCE operator host has NO such
+// forwards, so that probe fails for EVERY VM on every poll — which climbed each
+// VM's unreachable streak into the vanish-reconcile path and fired a ~15-60s
+// IAP-SSH tunnel probe per VM per cycle. With ~10 VMs those piled up faster than
+// they drained and drove the host past load 25 (diagnosed live 2026-07-19).
+//
+// On GCE the fix is to read the LB editor backend-service health the dashboard
+// ALREADY gathers (one cheap `gcloud ... backend-services get-health` per slow
+// cycle) as the primary verdict: O(1 API call), no tunnel, fleet-scalable.
+//
+//   onGce                true on the GCE operator host (FLEET_ON_GCE)
+//   lbReachable          the LB+IAP probe (probeVM) actually reached the VM's
+//                        editor. Only supplied when PROBE_VIA_LB is on; a
+//                        null/undefined means "no LB probe on this deployment"
+//                        (the laptop) and this axis stays silent.
+//   backendEditorHealth  classifyBackendHealth's verbatim verdict for the editor
+//                        backend: 'healthy'|'unhealthy'|'unknown'|'absent'
+//                        (null/undefined before the first slow gather lands)
+//   localProbeOk         the 127.0.0.1:PORT_BASE+n editor probe answered
+//   iapVerdict           classifyIapEditorProbe's result, when one is on hand
+//
+// Returns { reachable, source }:
+//   reachable  true | false | null, where null is INCONCLUSIVE — hold. It must
+//              never read as reachable and must never advance an unreachable
+//              streak toward an auto-reset. A genuinely-down VM must not read
+//              healthy, and a not-yet-known VM must not read dead.
+//   source     'lb' | 'backend' | 'local' | 'iap' — which signal decided, for the log.
+//
+// Only 'absent' falls through to the local/IAP path on GCE: a VM with no
+// vm-<N>-editor-bes has no LB signal at all (mid-add / un-wired), and there are
+// few of those at any time, so the occasional IAP probe there is affordable.
+// 'unknown' and the pre-first-gather null deliberately HOLD rather than fall
+// through, because on GCE falling through means a guaranteed-false local probe.
+function classifyReachability({ onGce, backendEditorHealth, localProbeOk, iapVerdict, lbReachable } = {}) {
+  if (onGce) {
+    // The LB+IAP probe outranks backend health (vm--gce-reachable-flag-from-lb-probe).
+    // It is the only signal on the GCE host that actually REACHES the VM's editor:
+    // the local-port probe has no SSH `-L` forward there so it always fails, and
+    // backendEditorHealth is filled by a slow gather that early-returns for
+    // not-yet-reachable VMs — the reachable⇄backend-health deadlock that pinned the
+    // dashboard at 0/10 while every probe was in fact succeeding. Only a definite
+    // boolean speaks; null/undefined (no LB probe configured — the laptop) falls
+    // through to the pre-existing backend/local/IAP ladder unchanged.
+    if (lbReachable === true) return { reachable: true, source: 'lb' };
+    if (lbReachable === false) return { reachable: false, source: 'lb' };
+    if (backendEditorHealth === 'healthy') return { reachable: true, source: 'backend' };
+    if (backendEditorHealth === 'unhealthy') return { reachable: false, source: 'backend' };
+    // 'unknown', or no gather yet (null/undefined): inconclusive, hold.
+    if (backendEditorHealth !== 'absent') return { reachable: null, source: 'backend' };
+    // 'absent' falls through to the laptop-shaped local/IAP path below.
+  }
+  // Laptop path (and GCE's backend-less VMs): the local port probe is primary,
+  // exactly as before. The IAP verdict only speaks when the local port is dark.
+  if (localProbeOk) return { reachable: true, source: 'local' };
+  if (iapVerdict === true) return { reachable: true, source: 'iap' };
+  if (iapVerdict === false) return { reachable: false, source: 'iap' };
+  return { reachable: false, source: 'local' };
+}
+
+// Resolve ONE poll's reachability record from a (possibly inconclusive) verdict
+// plus the prior poll's state. Where classifyReachability answers "which signal
+// decides, and what does it say", this answers "so what does this poll record".
+//
+// This is the safety-critical half of vm--lb-health-reachability-on-gce: an
+// INCONCLUSIVE verdict (reachable null — on GCE, backend health 'unknown' or not
+// yet gathered) must neither invent a reachability nor advance the unreachable
+// streak. The streak is what pollVanishedInstances gates on before it spends an
+// IAP probe and ultimately reboots a VM, so letting an unknown signal increment
+// it would march a VM toward a destructive reset on evidence we do not have.
+// Instead: hold the last-known reachability, and FREEZE the streak.
+//
+//   verdict               classifyReachability's { reachable, source }
+//   prevReachable         the previous poll's resolved reachability
+//   prevUnreachableStreak the previous poll's consecutive-unreachable count
+//
+// Returns { reachable, unreachableStreak }. A reachable poll zeroes the streak
+// immediately (we never delay clearing a false alarm, only delay raising one).
+function resolveReachabilityPoll({ verdict, prevReachable, prevUnreachableStreak } = {}) {
+  const prevStreak = prevUnreachableStreak || 0;
+  const raw = verdict ? verdict.reachable : null;
+  if (raw === null || raw === undefined) {
+    return { reachable: !!prevReachable, unreachableStreak: prevStreak };
+  }
+  return {
+    reachable: !!raw,
+    unreachableStreak: raw ? 0 : prevStreak + 1,
+  };
+}
+
+module.exports = {
+  classifyOperatorAuth,
+  debounceOperatorAuthDisplay,
+  OPERATOR_AUTH_DISPLAY_THRESHOLD,
+  isFleetWideUnreachable,
+  classifyIapEditorProbe,
+  classifyReachability,
+  resolveReachabilityPoll,
+};

package/npm/fleet-auth.js

@@ -108,4 +108,9 @@ function deriveDefaultAuthAccount(vms, lastAuthAt) {
   return best ? best.account : null;
 }
 
-module.exports = { classifyAuthVm, selectAuthTargets, summarizeAuthBatch, deriveDefaultAuthAccount };
+// Return true if this one VM is eligible for an auth-start action now.
+function isAuthStartable(v, job) {
+  return classifyAuthVm(v, job).eligible;
+}
+
+module.exports = { classifyAuthVm, selectAuthTargets, summarizeAuthBatch, deriveDefaultAuthAccount, isAuthStartable };