@codeyam-editor/codeyam-editor 0.1.5 → 0.1.7

package/npm/fleet-auth-health.js

@@ -8,37 +8,74 @@
 //
 // 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, reason }: degraded true means the
-// operator's own auth is broken (which makes EVERY VM read unreachable), so the
-// reset gate must suppress all reboots and the UI must surface a banner.
+// ${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, reason: null };
+  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
@@ -50,7 +87,11 @@ function classifyOperatorAuth({ account, accountErrMsg, tokenOk } = {}) {
 function isFleetWideUnreachable(vms, threshold, fleetWideThreshold) {
   let count = 0;
   for (const vm of Array.isArray(vms) ? vms : []) {
-    if (vm && !vm.reachable && (vm.unreachableStreak || 0) >= threshold) count++;
+    // 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;
 }
@@ -68,8 +109,105 @@ function classifyIapEditorProbe({ err, stdout } = {}) {
   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-build-data.js

@@ -1,5 +1,7 @@
 'use strict';
 
+const fr = require('./fleet-reachability');
+
 // 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
 // card UI (scripts/operator/fleet-dashboard/public/index.html) reads `v.<field>`
@@ -21,7 +23,37 @@ function buildVmEnvelope(v, ctx) {
   return {
     n: ctx.n,
     url: v.url || null,
-    reachable: !!v.reachable,
+    // 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
+    // state — but it was dropped here, so the link was silently absent on EVERY
+    // card fleet-wide even when the VM's preview served fine. The exact
+    // currentProvider/vmAccess envelope-drift class this module guards against.
+    previewUrl: v.previewUrl || null,
+    // The app dev-server port the VM serves on (Vite 5173, Next 3000, …),
+    // resolved stickily upstream. The card reads it as `appUp` to gate the
+    // preview link live. Dropped alongside previewUrl — same silent-omit bug.
+    appPort: v.appPort != null ? v.appPort : null,
+    // Sticky preview-SERVING signal — "is the VM's dev server up?" — derived
+    // from the previewState the editor emits on /api/session-info (forwarding →
+    // 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.
+    previewIngress: v.previewIngress === true ? true : (v.previewIngress === false ? false : null),
+    // `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
+    // ask the same question and the old `!!v.reachable` coercion here is what
+    // manufactured the 2026-07-30 fleet-wide phantom outage — 13 cards claiming
+    // a definite `false` that no probe had ever established.
+    ...fr.normalizeReachability(v),
     hasSession: !!v.hasSession,
     // Three-state: true = broker confirmed up, false = confirmed down, null =
     // editor unreachable so broker state is unknown. Never conflate "down" with
@@ -41,6 +73,14 @@ function buildVmEnvelope(v, ctx) {
     // instead of active-green 'building'.
     needsCleanup: !!v.needsCleanup,
     feature: v.feature || null,
+    // The VM's live-claimed plan slug, reported by /api/session-info and merged
+    // (sticky) onto the poll state. The card renders it as the what-it's-working-on
+    // line when `feature` is null — a VM that has claimed a plan but not yet named
+    // a feature (early plan/explore steps) previously showed a blank "no feature
+    // (idle)" card. Preferred over the origin claim-ref because this live source
+    // never goes stale under a failed claim-ref push. null for a legacy editor
+    // that predates the field, or a VM with no claimed plan.
+    selectedPlan: v.selectedPlan || null,
     step: v.step != null ? v.step : null,
     mode: v.mode || null,
     label: v.label || null,
@@ -72,6 +112,14 @@ 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,
     effects: v.effects || null,
     // The VM's live-configured build agent (lowercase provider), reported by
     // /api/session-info and merged (sticky) onto the poll state. Drives the
@@ -107,6 +155,13 @@ function buildVmEnvelope(v, ctx) {
     // against — so the line and list rendered empty even when the sidecar held
     // principals. Defaults to [] for a VM with no list.
     vmAccess: Array.isArray(v.vmAccess) ? v.vmAccess : [],
+    // Per-slot persisted-env override verdict (set by reapplyVmEnv, sticky on
+    // poll state): { present, skipped, reason, taggedRepo, setAt, keys }. Drives
+    // the card's env-override badge — an "applied" chip listing the masked keys +
+    // tagged repo, or a warning when a stale/untagged override is NOT replayed so
+    // a months-old override is never invisible again. null when no env is
+    // persisted for the slot (or the slot has never been reapplied).
+    envOverride: v.envOverride || null,
   };
 }
 
@@ -117,14 +172,14 @@ function buildVmEnvelope(v, ctx) {
 // card renders means adding it here AND in buildVmEnvelope — the test fails loud
 // if you do one without the other.
 const REQUIRED_CARD_FIELDS = [
-  'n', 'url', 'reachable', 'hasSession', 'brokerLive', 'brokerStatus',
-  'awaitingInput', 'needsCleanup', 'feature', 'step', 'mode', 'label', 'status', 'orphan',
+  'n', 'url', 'previewUrl', 'appPort', 'previewServing', 'previewIngress', 'reachable', 'reachableSource', 'hasSession', 'brokerLive', 'brokerStatus',
+  'awaitingInput', 'needsCleanup', 'feature', 'selectedPlan', 'step', 'mode', 'label', 'status', 'orphan',
   'degradedReasons', 'setupSteps', 'attentionReasons',
   'isHead', 'headHolderUnreachable', 'queuePos', 'queueLen',
   'job', 'config', 'project', 'variant', 'cardIdentity', 'brokerHistory',
-  'brokerDeath', 'providerAuth', 'effects', 'currentProvider',
+  'brokerDeath', 'providerAuth', 'previewMisconfigured', 'effects', 'currentProvider',
   'readiness', 'backendHealth', 'vmAccess',
-  'startedAt', 'featureStartedAt', 'attention',
+  'startedAt', 'featureStartedAt', 'attention', 'envOverride',
 ];
 
 module.exports = { buildVmEnvelope, REQUIRED_CARD_FIELDS };

package/npm/fleet-cleanup.js

@@ -78,13 +78,19 @@ function classifyDescribeError(err, stderr) {
 // Decide what the startup reap should do for one sidecar. Pure: takes the
 // decoded sidecar + GCP-existence verdict + (for adds) container-up verdict +
 // (for up adds) project-wiring verdict, returns a tag the caller dispatches on.
-//   verdict             when                                              dispatch
-//   'cleanup'           destroy gone, OR add gone                         runDestroyCleanup / runAddCleanup
-//   'reconcile-add'     add up, container up, project wired (or unknown)  ensure roster + recordLaunch, then clear
-//   'half-provisioned'  add up, container up, but project NOT wired       surface needs-recovery card (finish-wire from cfg)
-//   'recover-bootstrap' add instance up but container missing/down        re-run cloud:up to finish the half-done bootstrap
-//   'clear-only'        destroy sidecar but instance still exists         just clear the sidecar
-//   'leave'             gcloud uncertain (exists === null)                 leave for the next boot
+//   verdict               when                                              dispatch
+//   'cleanup'             destroy gone, OR add gone                         runDestroyCleanup / runAddCleanup
+//   'reconcile-add'       add up, container up, project wired, agent usable ensure roster + recordLaunch, then clear
+//   'half-provisioned'    add up, container up, but project NOT wired       surface needs-recovery card (finish-wire from cfg)
+//   'provision-incomplete' add up + container up + wired, but agent NOT     surface needs-recovery card (the agent
+//                          usable (CLI missing / auth wedged at unknown)    isn't installed/authed — VM5 false-green)
+//   'recover-bootstrap'   add instance up but container missing/down        re-run cloud:up to finish the half-done bootstrap
+//                                                                          (runAddRecoverBootstrap first probes the editor
+//                                                                           directly and diverts to rostering when the
+//                                                                           bootstrap is actually done and only the LB
+//                                                                           ingress is missing)
+//   'clear-only'          destroy sidecar but instance still exists         just clear the sidecar
+//   'leave'               gcloud uncertain (exists === null)                 leave for the next boot
 // The (exists, containerUp) split distinguishes a finished add from a container-
 // down half-provisioned one: a dashboard SIGKILL'd mid-`cloud:up` leaves a GCP
 // instance with no docker/container, which the old (exists-only) matrix wrongly
@@ -99,17 +105,82 @@ function classifyDescribeError(err, stderr) {
 // for an add whose instance exists; destroy and the instance-gone add path ignore
 // them. Splitting the matrix out lets the table be exhaustively tested without any
 // of the side-effects in server.js.
-function reapVerdict({ action, exists, containerUp, projectWired }) {
+//
+// The `agentReady` axis (vm: Readiness Verifies Real Usability) closes the VM5
+// false-green: an instance + container that ARE up and wired, but whose build
+// agent isn't usable — the CLI isn't installed, or the auth probe is wedged at
+// `unknown` — is NOT a finished add. Mirrors `projectWired`'s posture EXACTLY:
+// only a POSITIVE not-ready signal (`agentReady === false`) downgrades, to
+// 'provision-incomplete'; `null`/`undefined` (the probe couldn't decide, or an
+// older editor doesn't report it) stays 'reconcile-add' so a flaky probe never
+// strands a healthy VM. Checked AFTER `projectWired` — an unwired box is the more
+// fundamental fault and keeps its own verdict.
+//
+// NOT an axis here (vm--batch-add-must-roster-and-wire-each-vm): "the editor
+// answers on its own port but has no LB ingress". That state is a finished
+// bootstrap missing its wiring, and re-running cloud:up cannot create the
+// missing ingress — so it used to burn the 3-attempt budget and land on
+// 'bootstrap-recovery-exhausted', because the signal being retried on
+// (`lbReachable`) can never pass while the ingress is absent:
+//
+//   no ingress → LB 503 → not reachable → recover → still no ingress → exhausted
+//
+// The rescue deliberately lives in server.js's runAddRecoverBootstrap rather
+// than as a verdict here, because it needs a live IAP probe and is only worth
+// paying for on the branch that was about to spend a recovery attempt. Adding it
+// as a `reapVerdict` axis would force every container-down reap to run that
+// probe eagerly just to compute a verdict, for a state that is rare.
+function reapVerdict({ action, exists, containerUp, projectWired, agentReady, lbReachable }) {
   if (exists === null) return 'leave';
   if (action === 'destroy') return exists ? 'clear-only' : 'cleanup';
   if (action === 'add') {
     if (!exists) return 'cleanup';
+    // The `lbReachable` axis (vm--gce-reachable-flag-from-lb-probe) closes the
+    // false-orphan: a VM whose editor ANSWERS over the LB is provisioned by
+    // definition — its add finished, whatever a stale `add-<n>.json` sidecar
+    // left lying around implies. Without this, the container probe below could
+    // report "container down" for a VM that is demonstrably up and serving,
+    // driving recover-bootstrap → "exceeded 3 attempts" → a
+    // needs-manual-recovery card for a perfectly healthy box.
+    // Inverted posture vs projectWired/agentReady, and deliberately so: those
+    // axes let only a NEGATIVE signal downgrade, this one lets only a POSITIVE
+    // signal promote. `false`/`null`/`undefined` (probe said no, couldn't
+    // decide, or never ran) all fall through to the unchanged ladder below, so
+    // this can never strand a VM — it can only rescue one.
+    if (lbReachable === true) return 'reconcile-add';
     if (!containerUp) return 'recover-bootstrap';
-    return projectWired === false ? 'half-provisioned' : 'reconcile-add';
+    if (projectWired === false) return 'half-provisioned';
+    if (agentReady === false) return 'provision-incomplete';
+    return 'reconcile-add';
   }
   return 'leave';
 }
 
+// Classify the startup reap's LB rescue signal from a best-effort LB+IAP editor
+// probe. Pure: server.js runs the HTTP probe and hands the raw outcome here, the
+// same split classifyProjectWiring follows, so the rule is unit-testable without
+// a live VM or an LB.
+//
+// Deliberately tri-state and ASYMMETRIC — it returns `true` or `null`, NEVER
+// `false`:
+//   - probeViaLb false (a laptop has no LB to ask)  → null (no opinion)
+//   - err present (threw, auth fault, timeout)      → null (no opinion)
+//   - the editor answered                           → true (add is finished)
+//   - the editor did not answer                     → null (NOT false)
+//
+// That last line is the load-bearing one. A silent probe is not evidence a VM is
+// dead — the LB may be unwired mid-add, or the IAP token not yet minted. Since
+// reapVerdict promotes on `true` and ignores everything else, returning null
+// leaves the pre-existing container/wiring ladder in charge. Returning `false`
+// here would be indistinguishable to reapVerdict, but it would be a lie about
+// what the probe proved, and the next person to add an axis would read it as
+// evidence. The invariant this pins: this signal can rescue a VM, never strand one.
+function classifyLbReachableForReap({ probeViaLb, reachable, err } = {}) {
+  if (!probeViaLb) return null;
+  if (err) return null;
+  return reachable ? true : null;
+}
+
 // Classify whether a VM's editor `/workspace` is actually wired to a client
 // project, from a best-effort probe of two signals: the git remote URL and
 // whether `package.json` carries a real `name`. Pure: server.js runs the SSH +
@@ -266,6 +337,132 @@ function reattachNextStep(verdict) {
   return 'probe'; // 'done' and 'reconcile' both confirm via the gcloud probe
 }
 
+// May the PERIODIC stranded-reconcile pass drive a recover/roster probe for this
+// VM, or is a provision already running that a second cloud:up would collide
+// with? This is the guard the boot re-attach path has always had and the
+// stranded path never did — the 2026-08-07 asymmetry that destroyed VM-4/VM-5.
+//
+// On that day an `add` job badge read `error` while its detached `cloud:up`
+// child was alive and healthy (a source-build bootstrap runs ~40 minutes;
+// `npm install` alone took 25m). `pollStrandedInstances` builds `activeAddNs`
+// from BADGE state and deliberately excludes an `error` add so the bounded
+// bootstrap-recovery budget can retry on a timer — so the VM read
+// running-but-unrostered, crossed STRANDED_ADOPT_THRESHOLD in ~3 minutes, and
+// the pass launched a SECOND cloud:up on top of the live one. The two raced on
+// `docker compose up -d`, the loser hit `Conflict. The container name
+// "/codeyam-editor-editor-1" is already in use`, and its abort handler deleted
+// the instance. The badge is a derived, lossy signal that was wrong for 30
+// minutes straight; LIVENESS is the ground truth, so this gate reads exactly
+// what `reattachAdd` reads — the exit marker plus a `kill -0` of the recorded
+// pid — and composes `reattachVerdict`/`reattachNextStep` rather than forking a
+// parallel matrix.
+//
+//   'watch'  no marker + a live child   → the provision is genuinely in flight.
+//                                         Re-attach and watch (mirroring
+//                                         runStartupReap); NEVER provision.
+//   'defer'  no marker, no live child, and no pid was EVER recorded, inside the
+//            ambiguity window            → we cannot tell whether a child is
+//                                         running. Do nothing this tick.
+//   'probe'  everything else             → existing behavior: drive the gcloud
+//                                         probe (reconcileViaGcloud →
+//                                         reapVerdict).
+//
+// The 'defer' rung exists because `childAlive` is FALSE-NEGATIVE-PRONE on one
+// specific path: when `strandedReconcileMeta` finds no sidecar it reconstructs
+// cfg from launch history and persists `{ cfg }` with NO pid, so `isPidAlive`
+// reads false for a VM whose child may well be alive — and, worse, that pid-less
+// sidecar is what every later tick reads back, blinding the guard permanently.
+// `pidRecorded` separates "we knew the pid and the process is gone" (real
+// evidence → probe) from "we never had a pid" (absence of evidence → defer).
+// Erring toward NOT provisioning is the asymmetric-cost choice: waiting one more
+// 60s tick costs nothing, being wrong costs a destroyed VM.
+//
+// The window is what keeps 'defer' from becoming a permanent refusal that would
+// break stranded adoption outright: once more than `ambiguityWindowMs` has
+// elapsed since we first saw the pid-less sidecar, no plausible provision child
+// is still running, so the probe proceeds and the self-heal path is preserved.
+// An unknown/unstamped elapsed is treated as "just noticed" (defer), again the
+// safe direction; a caller that supplies no window at all opts out entirely and
+// keeps the old probe-always behavior.
+//
+// Pure, so the whole matrix is testable without a VM: server.js maps the verdict
+// to its side effect.
+function strandedRecoverGate({
+  markerPresent,
+  exitCode,
+  childAlive,
+  pidRecorded,
+  sinceMs,
+  ambiguityWindowMs,
+} = {}) {
+  // A live child is a live child — reuse the existing classifier so 'running'
+  // keeps meaning exactly what the boot path means by it.
+  if (reattachNextStep(reattachVerdict({ markerPresent, exitCode, childAlive })) === 'watch') {
+    return 'watch';
+  }
+  // A marker is durable proof the child reached its EXIT trap: nothing is in
+  // flight, so the probe is safe. (Which probe outcome follows — roster,
+  // recover-bootstrap, surface-error — stays reapVerdict's call, not ours.)
+  if (markerPresent) return 'probe';
+  // We knew the pid and `kill -0` says it is gone: real evidence, so probe.
+  if (pidRecorded) return 'probe';
+  const window = Number(ambiguityWindowMs);
+  if (!Number.isFinite(window) || window <= 0) return 'probe'; // caller opted out
+  const elapsed = Number(sinceMs);
+  if (!Number.isFinite(elapsed)) return 'defer'; // unstamped — treat as just-noticed
+  return elapsed < window ? 'defer' : 'probe';
+}
+
+// Is an `add` genuinely IN FLIGHT for this VM right now?
+//
+// Extracted from pollVanishedInstances, where the inline expression was
+// `addPending.has(n) || !!(state.jobs[n] && state.jobs[n].action === 'add')` —
+// whose second clause is also true for a TERMINAL (`done` / `error`) add job.
+// That permanently marks the VM busy, so `reconcileRosteredVm` can never return
+// 'cleanup' and a rostered VM whose instance is gone can never be auto-reaped.
+// Live evidence from the same 2026-08-07 incident: VM-5's instance was deleted
+// at ~12:46 and its card logged `vanish-reconcile: VM-5 unreachable …` once a
+// minute for 50 consecutive polls, only clearing after a manual `clear-badge`
+// deleted the terminal job record.
+//
+// The on-disk sidecar clause is already correct and is preserved: a sidecar is
+// removed on the add's success path, so its presence really does mean in-flight.
+// The job clause now filters on job STATE the same way `activeAddNs` and
+// `pollStartupProbes` do. Pure so the caller's computation is directly
+// assertable — the bug was never in `reconcileRosteredVm`'s contract, it was in
+// what this expression fed it.
+const IN_FLIGHT_ADD_STATES = ['running', 'queued', 'recovering'];
+
+function hasInFlightAdd({ sidecarPending, job } = {}) {
+  if (sidecarPending) return true;
+  if (!job || job.action !== 'add') return false;
+  return IN_FLIGHT_ADD_STATES.includes(job.state);
+}
+
+// WHICH of reconcileRosteredVm's two distinct 'leave' causes fired, as a tag the
+// caller renders. Pure so the distinction is directly assertable.
+//
+// 'leave' is returned both when the GCP probe was INCONCLUSIVE (exists null /
+// undefined — absence of evidence, never act) and when the instance is
+// CONFIRMED gone but the VM is busy. The old single log line conflated them into
+// a self-contradiction — it announced "instance-gone unconfirmed (exists=false)"
+// when exists=false IS the confirmation — which cost hours of code-reading
+// during the 2026-08-07 incident to work out which branch was actually firing.
+//
+//   'probe-inconclusive'  exists is null/undefined — retry next tick
+//   'live-session'        instance confirmed gone but a session is live
+//   'in-flight-add'       instance confirmed gone but an add is in flight
+//   null                  not a 'leave' case at all
+//
+// Mirrors reconcileRosteredVm's own precedence (exists-uncertainty first, then
+// hasSession, then hasPendingAdd) so the tag can never disagree with the verdict.
+function vanishLeaveReason({ exists, hasSession, hasPendingAdd } = {}) {
+  if (exists === null || exists === undefined) return 'probe-inconclusive';
+  if (hasSession) return 'live-session';
+  if (hasPendingAdd) return 'in-flight-add';
+  return null;
+}
+
 // Anti-loop budget for the `recover-bootstrap` path. Pure: given the count of
 // recoveries ALREADY persisted on the sidecar, return the next attempt number,
 // whether the reap should proceed (re-run cloud:up) or treat the VM as
@@ -414,6 +611,38 @@ function reconcileRosteredVm({ exists, hasSession, hasPendingAdd, streak, resetH
   return "keep";
 }
 
+// The bootstrap-recovery ladder step the startup reap runs for a VM whose first
+// cloud:up did not finish: decide (via recoverBootstrapDecision) whether another
+// attempt is allowed, then either flag the VM exhausted (leave the sidecar for
+// manual action) or clear any stale orphan flag and re-run cloud:up via `addVm`.
+// The dashboard's `state` and `addVm` are injected so this stays a pure,
+// importable unit — `log`/`err` default to the console but are overridable in
+// tests. Behavior mirrors the previous inline server.js definition exactly.
+function continueBootstrapRecovery(
+  n,
+  meta,
+  cfg,
+  { state, addVm, log = console.log, err = console.error } = {},
+) {
+  const { attempt, proceed, max } = recoverBootstrapDecision({
+    recoverAttempts: meta.recoverAttempts,
+  });
+  if (!proceed) {
+    err(
+      `startup-reap: VM-${n} exceeded ${max} bootstrap-recovery attempts — leaving sidecar for manual action`,
+    );
+    state.orphans[n] = { reason: "bootstrap-recovery-exhausted", attempts: attempt - 1 };
+    return;
+  }
+  log(
+    `startup-reap: VM-${n} re-running cloud:up to finish bootstrap (recovery attempt ${attempt}/${max})`,
+  );
+  // A prior exhausted/no-cfg run may have flagged this VM; clear it now that a
+  // fresh attempt is starting so the card moves to `recovering`, not stale red.
+  delete state.orphans[n];
+  addVm(n, cfg, { recovering: true, recoverAttempt: attempt });
+}
+
 module.exports = {
   parsePendingJobFilename,
   persistPendingJob,
@@ -424,7 +653,9 @@ module.exports = {
   reconcileRosteredVm,
   orphanedAddsToReconcile,
   classifyProjectWiring,
+  classifyLbReachableForReap,
   recoverBootstrapDecision,
+  continueBootstrapRecovery,
   exitMarkerName,
   parseExitMarker,
   readExitMarker,
@@ -432,4 +663,7 @@ module.exports = {
   isSignalKillExit,
   reattachVerdict,
   reattachNextStep,
+  strandedRecoverGate,
+  hasInFlightAdd,
+  vanishLeaveReason,
 };