@codeyam-editor/codeyam-editor 0.1.15 → 0.1.16

package/npm/fleet-add-failure.js

@@ -1,6 +1,21 @@
 'use strict';
 
 const fc = require('./fleet-cleanup');
+const {
+  stockoutCapacityPhrase,
+  missingBranchRefFacts,
+  missingBranchRefRecovery,
+  wedgedInsertFacts,
+  wedgedInsertRecovery,
+  iapNotReadyFacts,
+  iapNotReadyRecovery,
+  streamedLibraryMissingFacts,
+  cleanTeardownReported,
+  streamedLibraryMissingRecovery,
+  hostDiskExhausted,
+  hostDiskExhaustedRecovery,
+  cloudUpFailedRecovery,
+} = require('./fleet-add-failure-evidence');
 const { parseRosterMarkers } = require('./fleet-early-roster');
 
 // npm/fleet-add-failure.js — pure classifier for a FAILED fleet-dashboard `add`
@@ -196,291 +211,6 @@ function nextValidActionRemedy(text) {
   return i === -1 ? '' : lines.slice(i).join('\n').trim();
 }
 
-// Name the capacity GCE was short of, from whatever the stockout transcript
-// happens to expose — for the capacity-stockout recovery line. GCE reports this
-// inconsistently: the 2026-08-20 VM-11 transcript carried `vmType:` / `zone:`
-// bullets under errorInfo.metadatas, while the 2026-08-18 VM-13 spelling
-// (ZONE_RESOURCE_POOL_EXHAUSTED_WITH_DETAILS) carried neither. So every part is
-// optional and the phrase degrades to a generic-but-true sentence rather than
-// interpolating `undefined` into operator-facing copy. Extracted alongside
-// nextValidActionRemedy (the same shape: a pure transcript reader that enriches
-// one arm's recovery text) so the degradation is asserted directly.
-//
-// `zone:` is anchored with ^\s* so the neighbouring `zonesAvailable:` bullet —
-// which lists the zones that DID have capacity — cannot be mistaken for the zone
-// that failed. Never throws; returns the generic phrase for empty input.
-function stockoutCapacityPhrase(logTail) {
-  const log = String(logTail || '');
-  const vmType = (log.match(/^\s*vmType:\s*(\S+)/m) || [])[1];
-  const zone = (log.match(/^\s*zone:\s*(\S+)/m) || [])[1];
-  return [vmType, 'capacity', zone ? `in ${zone}` : 'in the target zone']
-    .filter(Boolean)
-    .join(' ');
-}
-
-// The spellings git uses for "that branch is not on the remote", each capturing
-// the ref name. The union is not defensive padding — the two bootstrap scripts
-// reach the remote with DIFFERENT git commands, and git words the same condition
-// differently for each:
-//   `git fetch <url> <branch>`  (clone_editor_repo, scripts/gcp-bootstrap.sh)
-//        → fatal: couldn't find remote ref <ref>
-//   `git clone --branch <b>`    (clone_project, scripts/gcp-project-bootstrap.sh)
-//        → fatal: Remote branch <b> not found in upstream origin
-// Keying on only the first — the one the 2026-08-25 transcripts happened to
-// carry — would miss every client-side clone failure. Same union-of-spellings
-// lesson capacity-stockout learned from GCE.
-//
-// Deliberately NOT included: git's `warning: Could not find remote branch …`,
-// which is a submodule-update warning that accompanies a SUCCEEDING command.
-// Matching it here would let an add that failed for an unrelated reason claim
-// this category — and this arm sits above the generic one, so a false positive
-// would suppress the true cause rather than merely add noise.
-const MISSING_REF_PATTERNS = [
-  /couldn't find remote ref (\S+)/i,
-  /Remote branch (\S+) not found in upstream/i,
-];
-
-// Which branch died, and which config field carried it — read from the transcript.
-//
-// The field matters because clientBranch and editorBranch are configured in
-// different places: an operator who corrects only one re-issues a request that
-// fails identically. It is derived from the log prefix of the nearest preceding
-// marker line, because the two bootstrap scripts brand their output distinctly
-// (`[gcp-bootstrap]` builds the editor image from the editor branch;
-// `[project-bootstrap]` clones the client repo at the client branch). When the
-// transcript carries neither marker the field is left null and the copy names
-// both fields rather than guessing — the same degrade-to-true-but-generic
-// discipline stockoutCapacityPhrase uses. Never throws; returns
-// { ref: null, field: null } for input with no missing-ref signature.
-function missingBranchRefFacts(logTail) {
-  const lines = String(logTail || '').split('\n');
-  for (let i = 0; i < lines.length; i += 1) {
-    let ref = null;
-    for (const re of MISSING_REF_PATTERNS) {
-      const m = lines[i].match(re);
-      if (m) { ref = m[1]; break; }
-    }
-    if (!ref) continue;
-    let field = null;
-    for (let j = i; j >= 0; j -= 1) {
-      if (/\[project-bootstrap\]/.test(lines[j])) { field = 'clientBranch'; break; }
-      if (/\[gcp-bootstrap\]/.test(lines[j])) { field = 'editorBranch'; break; }
-    }
-    return { ref, field };
-  }
-  return { ref: null, field: null };
-}
-
-// Operator-facing recovery copy for the missing-branch-ref arm.
-//
-// Extracted from the arm for the same reason stockoutCapacityPhrase was — it is
-// the one arm whose copy VARIES with what the transcript happened to expose, so
-// pulling it out lets the wording be asserted directly instead of only through
-// classifyAddFailure, and keeps the arm itself a two-line decision.
-//
-// Two properties are load-bearing and are what the tests pin:
-//   - It states the outcome FIRST and never borrows the generic arm's "a partial
-//     instance may exist — reconcile or destroy it" language. At this point git
-//     has aborted before any image build or container work, so that advice sends
-//     the operator hunting for a box that was never created — the inversion that
-//     cost the 2026-08-25 recovery its first hour.
-//   - The remedy is a DIFFERENT action, never "retry". Re-issuing the same
-//     config against a deleted ref fails identically forever, which is exactly
-//     why this category is kept out of ADD_FAILURE_RETRYABLE.
-//
-// `field` is optional: when the transcript carries no bootstrap marker the copy
-// names both fields rather than guessing which one carried the dead ref.
-// Pure; no I/O.
-function missingBranchRefRecovery({ ref, field } = {}) {
-  const carried = field
-    ? `Its ${field} still points at it`
-    : 'Its clientBranch and editorBranch both need checking';
-  return (
-    `Branch '${ref}' is not on origin any more — it was almost certainly pruned when it merged. ` +
-    'Nothing was provisioned: git aborted before any image build or container work, so there is no instance, ' +
-    `disk, NEG or backend service to clean up, and nothing to destroy. ${carried}, so retrying as-is will fail ` +
-    'identically every time. Re-add on a branch that still exists (the current fleet branch is the usual answer).'
-  );
-}
-
-// Facts for the wedged-insert arm: a GCE instance insert that was ACCEPTED and
-// then never finished. Returns { wedged, code, instance } — `code` is the GCE
-// support code when the transcript carried one, so the recovery copy can hand the
-// operator the exact string a Support case needs instead of making them dig it out
-// of the transcript by hand.
-//
-// Two spellings reach here and both are proof, so the match is a UNION:
-//   A. The raw GCE prose, which is what the 2026-09-04 VM-8 transcript carried:
-//      `Internal error. Please try again or contact Google Support. (Code: '…')`
-//      PAIRED with evidence this run actually attempted a create. The pairing is
-//      what keeps the arm narrow — the same prose surfacing from some other
-//      gcloud call is not an insert that wedged, and must not claim to be one.
-//   B. ensureInstance's own fast-fail line (npm/cloud.js), which fires when a
-//      re-add finds the slot still parked in PROVISIONING behind an operation
-//      that never reached DONE. That path exists precisely so the transcript
-//      carries a signature instead of an uninformative 2-minute timeout, so this
-//      arm keys on it directly.
-//
-// Deliberately NOT keyed on elapsed time. A duration heuristic ("PROVISIONING for
-// too long") would misfire on a legitimately slow create; an INTERNAL_ERROR on an
-// accepted insert is provable evidence, which is the same signature-over-duration
-// discipline the capacity-stockout arm uses.
-const WEDGED_INSERT_PROSE = /Internal error\. Please try again or contact Google Support/i;
-const WEDGED_INSERT_FASTFAIL = /stuck in PROVISIONING behind a wedged create operation/i;
-const WEDGED_INSERT_CREATE_ATTEMPTED = /not found\s*—\s*creating|Failed to create instance|did not reach RUNNING/i;
-
-function wedgedInsertFacts(logTail) {
-  const log = String(logTail || '');
-  const wedged = WEDGED_INSERT_FASTFAIL.test(log)
-    || (WEDGED_INSERT_PROSE.test(log) && WEDGED_INSERT_CREATE_ATTEMPTED.test(log));
-  if (!wedged) return { wedged: false, code: null, instance: null };
-  return {
-    wedged: true,
-    code: (log.match(/\(Code:\s*'(-?\d+)'\)/) || [])[1] || null,
-    instance: (log.match(/Checking instance\s+(\S+?)\.\.\./) || [])[1] || null,
-  };
-}
-
-// Operator-facing recovery copy for the wedged-insert arm, extracted for the same
-// reason stockoutCapacityPhrase and missingBranchRefRecovery were: its wording
-// varies with what the transcript exposed, so pulling it out lets the copy be
-// asserted directly rather than only through classifyAddFailure.
-//
-// Three properties are load-bearing and are what the tests pin:
-//   - It never borrows the generic arm's "reconcile or destroy it" line. A delete
-//     against a wedged slot is ACCEPTED and then queues behind the wedged insert
-//     rather than clearing it, so that advice sends the operator to an action that
-//     provably does not work — the same inversion that cost the 2026-08-25
-//     missing-branch-ref recovery its first hour.
-//   - It says plainly that this is not the operator's fault and not their fix.
-//     The only thing that resolves it is GCE-side.
-//   - It names the Support code when one was captured, because that string is
-//     what a Google Cloud Support case is keyed on.
-function wedgedInsertRecovery({ code, instance } = {}) {
-  const named = instance || 'the instance';
-  const cite = code ? ` citing operation error code ${code}` : '';
-  return (
-    `GCE accepted the create for ${named} and then never finished it: the insert stayed at status RUNNING, progress 0 ` +
-    'and eventually attached an INTERNAL_ERROR without ever reaching DONE, leaving the instance in PROVISIONING and its ' +
-    'boot disk in CREATING. Nothing on our side failed and there is nothing here to reconcile. Do NOT retry — the ' +
-    'instance name is held by the wedged operation, so a re-add cannot succeed while it is outstanding. Do NOT try to ' +
-    'destroy it either — a delete is accepted but queues behind the wedged insert instead of clearing it. This needs ' +
-    `GCE-side resolution: open a Google Cloud Support case${cite}. If you need the slot before Google releases it, add ` +
-    'on a different VM number.'
-  );
-}
-
-// Facts for the iap-not-ready arm: waitForIapReady (npm/cloud.js) threw its
-// readiness timeout. Returns { timedOut, instance, budgetSecs, cause } — `cause` is
-// the label waitForIapReady derived from its probe stderr (null when none of its
-// signatures matched, or on a transcript from before the label existed), so the
-// recovery copy can name WHICH wait was blown instead of only `return code [255]`.
-//
-// The signature is emitted from exactly one place, and that place runs before any
-// bootstrap work, which is what lets this arm assert the instance is bare.
-const IAP_NOT_READY = /IAP did not become ready for (\S+) within (\d+)s/;
-
-function iapNotReadyFacts(logTail) {
-  const m = String(logTail || '').match(IAP_NOT_READY);
-  if (!m) return { timedOut: false, instance: null, budgetSecs: null, cause: null };
-  const cause = (String(logTail).match(/likely cause: ([^;)]+)/) || [])[1] || null;
-  return { timedOut: true, instance: m[1], budgetSecs: Number(m[2]), cause: cause && cause.trim() };
-}
-
-// Operator-facing recovery copy for the iap-not-ready arm. It states what the
-// generic arm cannot: the instance EXISTS and is BARE. "A partial instance may
-// exist" is what steered VM-4's operator toward destroy + re-add (15-25 minutes)
-// when Retry resumes on the same box in seconds — and it left nothing on the card
-// saying a RUNNING, billing instance was sitting there.
-function iapNotReadyRecovery({ instance, budgetSecs, cause } = {}) {
-  const named = instance || 'The instance';
-  const within = budgetSecs ? ` within ${budgetSecs}s` : '';
-  const why = cause ? ` (likely cause: ${cause})` : '';
-  return (
-    `${named} was created and is RUNNING, but SSH over IAP did not answer${within}${why}. This is usually a transient ` +
-    'control-plane race. Nothing was installed on it — the wait runs before any bootstrap step — so it is a bare box and ' +
-    'there is nothing partial to reconcile. Retry add resumes on this same instance rather than creating a second one. ' +
-    'Until you retry or destroy it, the instance keeps running and billing.'
-  );
-}
-
-// Facts for the streamed-library-missing arm: a streamed bootstrap script sourced
-// a `$HOME`-rooted `lib/…` file that was never shipped to the VM, and bash
-// reported `<script>: line N: <path>: No such file or directory`. This took ALL
-// fleet provisioning down twice (lib/npm-pin.sh 2026-09-04, lib/render-cloud-
-// compose.sh 2026-09-18). Returns { missing, script, library } — `script` is the
-// basename of the aborting script, `library` the `lib/…` path relative to $HOME,
-// which is how PROJECT_BOOTSTRAP_LIBS (npm/cloud.js) names its entries.
-const STREAMED_LIBRARY_MISSING = /(\S+): line \d+: \/(?:home\/[^/\s]+|root)\/(lib\/[^\s:]+): No such file or directory/;
-
-function streamedLibraryMissingFacts(logTail) {
-  const m = String(logTail || '').match(STREAMED_LIBRARY_MISSING);
-  if (!m) return { missing: false, script: null, library: null };
-  return { missing: true, script: m[1].split('/').pop(), library: m[2] };
-}
-
-// Did cloud:up report that it deleted the instance it created this run? The abort
-// path (npm/cloud.js) prints the teardown marker BEFORE it issues the delete, and
-// prints a `during abort teardown` warning when that delete fails — so the marker
-// alone is a claim of intent, and only the marker WITHOUT the warning is evidence
-// that no orphan was left behind.
-function cleanTeardownReported(logTail) {
-  const log = String(logTail || '');
-  return /tearing down the VM cloud:up created this run \(no orphan left behind\)/.test(log)
-    && !/during abort teardown/.test(log);
-}
-
-// Operator-facing recovery copy for the streamed-library-missing arm. It names
-// what to fix — register the library so it is streamed — and, when the transcript
-// proves a clean teardown, says there is no orphan to hunt for. Every add on this
-// branch fails identically until the registry is fixed, so it never offers Retry.
-function streamedLibraryMissingRecovery({ script, library, cleanTeardown } = {}) {
-  const lib = library || 'a lib/ file';
-  const from = script ? ` sourced by ${script}` : '';
-  const orphan = cleanTeardown
-    ? 'cloud:up already deleted the VM it created, so there is nothing to reconcile or destroy.'
-    : 'The transcript does not confirm the VM was deleted — check whether a partial instance exists before re-adding.';
-  return (
-    `${lib}${from} was never shipped to the VM, so the bootstrap aborted. Add it to PROJECT_BOOTSTRAP_LIBS in npm/cloud.js, ` +
-    `push, and re-add — every add from this branch fails the same way until then. ${orphan}`
-  );
-}
-
-// Did the OPERATOR HOST run out of filesystem? Node spells it `ENOSPC: no space
-// left on device`, the shell `No space left on device`, gcloud `OSError: [Errno
-// 28] No space left on device` — matched on the message, never on the errno
-// number, which means something else on other platforms. A transcript that says a
-// script "failed on the VM" is quoting the VM's own log tail (npm/cloud.js prints
-// that header above it), so an ENOSPC there is the VM's disk, not the host's, and
-// stays with the generic arm.
-const HOST_DISK_EXHAUSTED = /ENOSPC: no space left on device|No space left on device/i;
-
-function hostDiskExhausted(logTail) {
-  const log = String(logTail || '');
-  return HOST_DISK_EXHAUSTED.test(log) && !/failed on the VM/i.test(log);
-}
-
-// Operator-facing recovery copy for the host-disk-exhausted arm. The ENOSPC fires
-// on the operator host before `instances create`, so nothing exists on GCP; the
-// fix is freeing the host's filesystem, which every add needs first.
-function hostDiskExhaustedRecovery() {
-  return (
-    'The operator host ran out of filesystem space (bytes or inodes) before anything was created, so there is no VM to ' +
-    'reconcile or destroy. Prune old date directories under /root/.config/gcloud/logs — gcloud writes one log per ' +
-    'invocation and is the usual cause — and confirm with `df -i` and `df -h`. Every add fails the same way until then.'
-  );
-}
-
-// Operator-facing recovery copy for the generic cloud-up-failed arm. "A partial
-// instance may exist" is only true when the transcript does not show cloud:up
-// deleting what it created; saying it regardless sends the operator hunting for
-// an orphan that is not there.
-function cloudUpFailedRecovery({ cleanTeardown } = {}) {
-  return cleanTeardown
-    ? 'cloud:up failed during provisioning and deleted the VM it created, so nothing was left behind. Read the transcript for the cause before re-adding.'
-    : 'cloud:up failed during provisioning, so a partial instance may exist. Reconcile or destroy this VM before re-adding.';
-}
-
 // 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) {
@@ -489,6 +219,40 @@ function buildFailureVerdict(category, headline, recovery, extra) {
   return out;
 }
 
+// Arm 1's verdict: name the drifted files and the exact command that clears them.
+function preflightDriftVerdict(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 });
+}
+
+// Arm 13's verdict, for a read-back that found no human accessor on the policy.
+function iapReadbackVerdict(log, wiringInFlight) {
+  const remedy = nextValidActionRemedy(log);
+  //  9a. access-pending — no accessors YET. The grant is the LAST step of the
+  //      detached wire-add-tail, so while that tail is alive an empty policy is
+  //      the expected mid-flight reading, not a verdict. Calm: this is the state
+  //      that used to render a red "Add failed" on healthy VM-4/VM-7 minutes
+  //      before their grant step had even run (2026-08-11).
+  if (wiringInFlight) {
+    return buildFailureVerdict('access-pending', 'Access not granted yet',
+      'The VM is up and rostered, but its IAP policy has no human accessors yet — the add\'s background wiring applies the grant as its last step and is still running. This resolves on its own once that tail finishes; no action is needed unless it persists past the wiring deadline.');
+  }
+  //  9b. iap-unauthorized — the wiring is done and the policy STILL authorizes
+  //      nobody, so the public URL returns "Error code 51" for every human. This
+  //      is the 2026-08-09 case the read-back exists to catch (one step granted
+  //      the operator, the next revoked him) and it is a genuine hard failure.
+  //      Not retryable: the VM exists and is fine — re-adding it would duplicate
+  //      a live box when what is missing is one grant.
+  return buildFailureVerdict('iap-unauthorized', 'No one can reach this VM',
+    `The VM is up but its IAP policy authorizes no human, so the public URL returns "Error code 51" for everyone. Its background wiring is no longer running, so this will not resolve on its own — grant access to fix it. Do NOT destroy or re-add this VM.${remedy ? `\n\n${remedy}` : ''}`);
+}
+
 // Classify a failed add from its transcript tail + exit code.
 //
 //   logTail   the last lines of the provision transcript (string; '' when the
@@ -542,14 +306,7 @@ function classifyAddFailure({ logTail, exitCode, instanceAlive, containerHealthy
   //    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 });
+    return preflightDriftVerdict(log);
   }
 
   // 2. instance-vanished — the GCP instance is confirmed gone; nothing to orphan.
@@ -789,24 +546,7 @@ function classifyAddFailure({ logTail, exitCode, instanceAlive, containerHealthy
   //    always wins if both texts are ever present, and BEFORE converging/verifying
   //    because it is strictly more specific than either.
   if (/IAP policy authorizes no human/i.test(log)) {
-    const remedy = nextValidActionRemedy(log);
-    //  9a. access-pending — no accessors YET. The grant is the LAST step of the
-    //      detached wire-add-tail, so while that tail is alive an empty policy is
-    //      the expected mid-flight reading, not a verdict. Calm: this is the state
-    //      that used to render a red "Add failed" on healthy VM-4/VM-7 minutes
-    //      before their grant step had even run (2026-08-11).
-    if (wiringInFlight) {
-      return buildFailureVerdict('access-pending', 'Access not granted yet',
-        'The VM is up and rostered, but its IAP policy has no human accessors yet — the add\'s background wiring applies the grant as its last step and is still running. This resolves on its own once that tail finishes; no action is needed unless it persists past the wiring deadline.');
-    }
-    //  9b. iap-unauthorized — the wiring is done and the policy STILL authorizes
-    //      nobody, so the public URL returns "Error code 51" for every human. This
-    //      is the 2026-08-09 case the read-back exists to catch (one step granted
-    //      the operator, the next revoked him) and it is a genuine hard failure.
-    //      Not retryable: the VM exists and is fine — re-adding it would duplicate
-    //      a live box when what is missing is one grant.
-    return buildFailureVerdict('iap-unauthorized', 'No one can reach this VM',
-      `The VM is up but its IAP policy authorizes no human, so the public URL returns "Error code 51" for everyone. Its background wiring is no longer running, so this will not resolve on its own — grant access to fix it. Do NOT destroy or re-add this VM.${remedy ? `\n\n${remedy}` : ''}`);
+    return iapReadbackVerdict(log, wiringInFlight);
   }
 
   // 14. converging — the add reached the early-roster marker (`CY_ROSTER`): the

package/npm/fleet-build-data.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const fr = require('./fleet-reachability');
+const fph = require('./fleet-preview-health');
 
 // Assemble the per-VM wire object the dashboard's /data response carries to the
 // browser. This is the single source of truth for a card's transport shape: the
@@ -14,15 +15,14 @@ const fr = require('./fleet-reachability');
 // it lived in server memory and never reached the browser, and the badge never
 // appeared. A hand-maintained object literal inside a 197KB monolith has no
 // guard against that drift; a pure function does.
-//
-// `v` is the merged poll state (state.vms[n]). `ctx` carries the derived,
-// cross-VM, and side-effecting values buildData computes per VM (status,
-// debounced broker tri-state, reconciled job, queue position, launch cfg, …) —
-// the things this pure function can't know on its own.
-function buildVmEnvelope(v, ctx) {
+
+// The Live Preview half of the envelope: where the preview lives, and the three
+// independent axes the card reads before it offers the 👁 link — is the dev
+// server up, is the public URL wired, does the LB's own dial reach the app —
+// plus the amber badge those readings can raise. Every reading is three-state;
+// none may conflate "down" with "unknown".
+function previewEnvelopeFields(v, n) {
   return {
-    n: ctx.n,
-    url: v.url || null,
     // The VM's public Live Preview URL (<slug>.preview.<domain> in named-tunnel
     // mode, else the local forward). The card reads it as `previewSub` to render
     // the 👁 preview link. Server-computed in server.js and merged onto the poll
@@ -39,14 +39,46 @@ function buildVmEnvelope(v, ctx) {
     // true, placeholder → false, else null). Reaches every VM over the IAP-LB
     // seam on the GCE operator host, where the old loopback `previewReachable`
     // read false fleet-wide. The card gates the clickable 👁 link on `=== true`.
-    // Three-state, never conflating "down" with "unknown".
     previewServing: v.previewServing === true ? true : (v.previewServing === false ? false : null),
     // Sticky preview-INGRESS signal — "is the VM's public preview URL wired?" —
     // from a reachability probe of <slug>.preview.<domain> over the LB, DISTINCT
     // from previewServing. true = wired, false = confirmed dead (→ muted 'public
     // URL not wired' hint), null = unknown (skipped / IAP audience mismatch — a
-    // null must never gate the link off). Three-state, same discipline.
+    // null must never gate the link off).
     previewIngress: v.previewIngress === true ? true : (v.previewIngress === false ? false : null),
+    // The silently-broken Live Preview guard: { previewOrigin, expectedOrigin }
+    // when the VM's own /api/config proves its preview can never load in a
+    // remote browser (a not-same-origin-safe stack stuck on a loopback/subpath
+    // origin), null when healthy or unknown. Drives the card's amber "Live
+    // Preview unreachable" badge. Gated on `reachable` like providerAuth — an
+    // unreachable VM's last-known config is stale, and an unreachable card has
+    // louder problems to report than its preview origin.
+    // Two more reasons share the badge (npm/fleet-preview-health.js), each
+    // tagged `kind`: 'app-port-drift' when the host publishes one port and the
+    // project declares another, and 'endpoint-dead' when a dial of the preview
+    // NEG endpoint the LB uses is reset or times out. Either is a preview the
+    // editor's own view reports healthy while every remote browser gets Envoy's
+    // connection-termination error (VM-15, 2026-10-17).
+    previewMisconfigured: fph.resolvePreviewMisconfigured(v, n),
+    // The LB-path dial verdict for the preview, { verdict, endpoints }:
+    // 'answered' (any HTTP status), 'reset', 'timeout', or 'unknown'. A third
+    // preview axis beside previewServing (is the dev server up?) and
+    // previewIngress (is the public URL wired?) — a healthy dev server behind a
+    // broken port must not read as a dead dev server. null before the first
+    // slow gather lands, or off the GCE operator host (no VPC path to dial).
+    previewEndpoint: v.previewEndpoint || null,
+  };
+}
+
+// Build one VM's envelope. `v` is the merged poll state (state.vms[n]). `ctx`
+// carries the derived, cross-VM, and side-effecting values buildData computes
+// per VM (status, debounced broker tri-state, reconciled job, queue position,
+// launch cfg, …) — the things this pure function can't know on its own.
+function buildVmEnvelope(v, ctx) {
+  return {
+    n: ctx.n,
+    url: v.url || null,
+    ...previewEnvelopeFields(v, ctx.n),
     // `reachable` (three-state) + `reachableSource` (which signal decided, or
     // 'unpolled'). Same tri-state discipline as previewServing/previewIngress
     // above, but delegated to npm/fleet-reachability.js because FIVE consumers
@@ -137,14 +169,6 @@ function buildVmEnvelope(v, ctx) {
     // Auth state + reason + token expiry. Only surfaced when the editor is
     // reachable (an unreachable VM's cached auth is stale and misleading).
     providerAuth: v.reachable && v.providerAuth ? v.providerAuth : null,
-    // The silently-broken Live Preview guard: { previewOrigin, expectedOrigin }
-    // when the VM's own /api/config proves its preview can never load in a
-    // remote browser (a not-same-origin-safe stack stuck on a loopback/subpath
-    // origin), null when healthy or unknown. Drives the card's amber "Live
-    // Preview unreachable" badge. Gated on `reachable` like providerAuth — an
-    // unreachable VM's last-known config is stale, and an unreachable card has
-    // louder problems to report than its preview origin.
-    previewMisconfigured: (v.reachable && v.previewMisconfigured) || null,
     // The project's DECLARED datastore and whether it is answering:
     // { type, target, local, reachable, lastError }, or null when the project
     // declares none (a Rust CLI, a static site) — which is the common case and
@@ -182,7 +206,10 @@ function buildVmEnvelope(v, ctx) {
     // The raw LB backend-health map { editor, preview } the readiness derivation
     // consumed, surfaced so the card can show a precise tooltip (which surface
     // is unwired). null in legacy mode or before the first slow probe lands.
-    backendHealth: v.backendHealth || null,
+    // The LB health check dials the editor port, so its `preview` verdict cannot
+    // speak to the app; `healthy` is kept only when the preview endpoint dial
+    // answered, else it reads 'unhealthy' (dial reset/timed out) or 'unverified'.
+    backendHealth: fph.gatePreviewBackendHealth(v.backendHealth, v.previewEndpoint),
     // The per-VM IAP access whitelist (the principals explicitly granted
     // resource-level access to THIS VM, from the fleet-vm-access sidecar). Merged
     // onto the poll state at server.js, it drives the card's 🔐 access line and
@@ -215,7 +242,7 @@ const REQUIRED_CARD_FIELDS = [
   'degradedReasons', 'setupSteps', 'attentionReasons',
   'isHead', 'headHolderUnreachable', 'queuePos', 'queueLen',
   'job', 'config', 'project', 'variant', 'cardIdentity', 'brokerHistory',
-  'brokerDeath', 'providerAuth', 'previewMisconfigured', 'datastore', 'effects', 'currentProvider',
+  'brokerDeath', 'providerAuth', 'previewMisconfigured', 'previewEndpoint', 'datastore', 'effects', 'currentProvider',
   'readiness', 'backendHealth', 'vmAccess',
   'startedAt', 'featureStartedAt', 'attention', 'envOverride',
 ];