@codeyam-editor/codeyam-editor 0.1.4 → 0.1.6

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
@@ -32,13 +64,38 @@ function buildVmEnvelope(v, ctx) {
     // upstream, debounced). Richer than brokerLive's is-an-agent-live boolean.
     brokerStatus: ctx.brokerStatus,
     awaitingInput: !!v.awaitingUserInput,
+    // True when the editor reports the build workflow reached its terminal step
+    // and is parked awaiting cleanup (session_info_response.rs emits it at
+    // step >= total). Flows onto poll state via the `...info` spread in server.js
+    // exactly like `feature`/`awaitingUserInput`; defaulted false here so a legacy
+    // editor that predates the field degrades to today's behavior. Consumed by
+    // fleet-live-status.js to read a parked-but-done agent as calm 'session-done'
+    // 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,
     status: ctx.status,
     orphan: ctx.orphan || null,
     degradedReasons: ctx.degradedReasons || [],
+    // Derived presentation split of degradedReasons (vm: Dashboard 'Finishing
+    // setup' state): `setupSteps` are expected first-run wiring rendered as a
+    // calm blue checklist, `attentionReasons` are genuine problems kept in the
+    // amber ⚠ treatment. `degradedReasons` is left intact for the many places
+    // that still consume the flat list (filters, sort, reconcile); these two are
+    // purely additive. Both default to [] so a legacy/healthy VM renders neither
+    // block. See npm/fleet-setup-steps.js::classifyReasons.
+    setupSteps: Array.isArray(ctx.setupSteps) ? ctx.setupSteps : [],
+    attentionReasons: Array.isArray(ctx.attentionReasons) ? ctx.attentionReasons : [],
     isHead: !!ctx.isHead,
     // True when this VM holds the queue head but is unreachable (operator
     // decides manually whether to release it).
@@ -55,12 +112,56 @@ 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
     // card's 🤖 agent badge. null for an older VM whose editor predates the
     // field (the card omits the badge rather than rendering a blank chip).
     currentProvider: v.currentProvider || null,
+    // Raw workflow timestamps (ISO) surfaced by /api/session-info and merged onto
+    // the poll state via the `...info` spread, exactly like feature/step/label.
+    // The card live-ticks the elapsed minutes off these between polls. null for a
+    // legacy editor that predates the fields, or a VM with no active step.
+    startedAt: v.startedAt || null,
+    featureStartedAt: v.featureStartedAt || null,
+    // The server-computed stuck / needs-you verdict (npm/fleet-stuck-status.js):
+    // { stepElapsedMs, level: 'ok'|'slow'|'stuck', needsYou, needsYouElapsedMs }.
+    // The authoritative level only changes on poll; the card colors the step
+    // tenure badge by it. null when buildData couldn't compute one.
+    attention: ctx.attention || null,
+    // Per-VM card readiness derived upstream (npm/fleet-vm-readiness.js): one of
+    // READINESS_STATES. The card colors the border and GATES the editor link on
+    // it — a non-'ready' VM never presents its public URL as live, because the
+    // LB would 503. Computed in buildData where the broker tri-state / job / LB
+    // mode are on hand, then carried here so the browser needs no extra request.
+    readiness: ctx.readiness || null,
+    // 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 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
+    // the Manage access modal's "this VM only" list. It was previously dropped
+    // here — the exact currentProvider-style envelope drift this module guards
+    // 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,
   };
 }
 
@@ -71,11 +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', 'feature', 'step', 'mode', 'label', 'status', 'orphan',
-  'degradedReasons', 'isHead', 'headHolderUnreachable', 'queuePos', 'queueLen',
+  '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', '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 +
@@ -175,13 +246,28 @@ function clearExitMarker(dir, n) {
   catch (_) { /* missing is fine */ }
 }
 
+// True when an integer exit code is the shell's "killed by signal N" encoding,
+// i.e. 128 + N for N in 1..37 — the realistic kills being 143 (SIGTERM, the
+// `launchctl bootout` graceful teardown), 137 (SIGKILL), 130 (SIGINT) and 129
+// (SIGHUP). Pure boundary check: 128 itself is NOT a signal kill (it's `exit
+// 128`, an ordinary failure code), so the range is the OPEN interval
+// (128, 165]. Anything outside it — a small `exit 1` from the addVm script's own
+// failure branches, 0, NaN, null — is not a signal kill. The split that matters:
+// "did a signal kill the provision shell" (interrupted → reconcile) vs "did the
+// provision logic itself decide it failed" (real error). Exported so the matrix
+// is unit-testable directly.
+function isSignalKillExit(code) {
+  return Number.isInteger(code) && code > 128 && code <= 165;
+}
+
 // Decide how a snapshot-restored `add` should be re-attached after a dashboard
 // restart, BEFORE any gcloud probe. Pure: takes the durable signals the boot
 // path gathers — whether the exit marker exists, its recorded code, and whether
 // the detached provision child is still alive (recorded pid, `kill -0`).
 //   verdict       when                                          dispatch
 //   'done'        marker present, exit code 0                   roster + recordLaunch, clear sidecar/marker
-//   'error'       marker present, non-zero exit code            surface the real failure, clear sidecar/marker
+//   'reconcile'   marker present, SIGNAL-kill code (128<c≤165)  interrupted, not failed — gcloud probe decides
+//   'error'       marker present, other non-zero exit code      surface the real failure, clear sidecar/marker
 //   'running'     no marker yet, child still alive              RE-ATTACH: keep polling, do NOT mark error
 //   'reconcile'   child gone, no usable marker                  fall through to fc.reapVerdict (gcloud probe)
 // This is the durable fix's brain: a provision that survived the kill (still
@@ -192,14 +278,33 @@ function clearExitMarker(dir, n) {
 // `reconcile` hands that exact (exists, containerUp, projectWired) decision to
 // fc.reapVerdict. A marker whose first line isn't an integer is treated as
 // absent (parseExitMarker → null) so a corrupt marker reconciles rather than
-// asserting a bogus code. The matrix is exhaustively tested without a live VM.
+// asserting a bogus code.
+//
+// SIGNAL-kill codes (improve46): `setsid` shields the detached provision from a
+// dashboard-process-GROUP SIGKILL (the 2GB launchd hard cap), but NOT from a
+// `launchctl bootout`, which tears down the whole launchd job tree regardless of
+// session/process-group. A graceful SIGTERM then reaches the "detached" child and
+// its EXIT trap records 143 (128+SIGTERM) into the marker. That is an INTERRUPTED
+// add, not a failed one — the manual re-add succeeds in seconds off the image the
+// interrupted build already left on the VM. So a signal-kill code routes to
+// 'reconcile' (let the gcloud probe read ground truth and roster / recover) rather
+// than 'error' (a false add-failed that throws away a resumable build). A genuine
+// provision failure exits with a small non-zero code (e.g. `exit 1`), which STILL
+// classifies 'error'. The matrix is exhaustively tested without a live VM.
 function reattachVerdict({ markerPresent, exitCode, childAlive } = {}) {
   if (markerPresent) {
     // Guard the null/undefined coercion BEFORE Number() — `Number(null)` is 0,
     // which would masquerade as a clean exit. A marker with no parseable code
     // (half-written / corrupt) must reconcile, not assert success.
     const code = exitCode == null ? NaN : Number(exitCode);
-    if (Number.isInteger(code)) return code === 0 ? 'done' : 'error';
+    if (Number.isInteger(code)) {
+      if (code === 0) return 'done';
+      // A signal killed the provision shell (e.g. bootout SIGTERM → 143): the add
+      // was interrupted, not failed — reconcile against real VM state instead of
+      // surfacing a false add-failed and discarding a resumable build.
+      if (isSignalKillExit(code)) return 'reconcile';
+      return 'error';
+    }
     return 'reconcile'; // marker present but no parseable code — let gcloud decide
   }
   if (childAlive) return 'running';
@@ -297,11 +402,119 @@ function orphanedAddsToReconcile({ jobs, sidecarKeys } = {}) {
 // posture). "Busy" (a live session or an in-flight add to this number) also
 // holds the entry for an operator rather than auto-removing — the shouldn't-
 // happen-but-fail-safe case where a vanished instance still reports a session.
-function reconcileRosteredVm({ exists, hasSession, hasPendingAdd } = {}) {
+//   verdict     when                                        dispatch
+//   'cleanup'   instance gone AND the VM is idle            runDestroyCleanup
+//   'leave'     exists uncertain (null), OR the VM is busy  do nothing this pass
+//   'keep'      instance still exists                       do nothing (healthy)
+//   'reset'     existing idle instance unreachable too long trigger auto-reset
+// Fail-safe by construction: cleanup fires ONLY on a DEFINITIVE absence
+// (exists === false) — a flaky/transient describe (null) is always 'leave', so a
+// gcloud blip can never evict a healthy VM (mirroring reapVerdict's `leave`
+// posture). "Busy" (a live session or an in-flight add to this number) also
+// holds the entry for an operator rather than auto-removing — the shouldn't-
+// happen-but-fail-safe case where a vanished instance still reports a session.
+// auto-reset escalation (vm: OOM Wedge Prevention):
+// When the VM has been unreachable for at least RESET_UNREACHABLE_THRESHOLD
+// (e.g. 200, which is roughly 10 minutes at a 3s poll rate), we issue a 'reset'
+// verdict. This auto-reset is guarded and bounded by a cooldown window (in ms)
+// and a max attempts limit to prevent infinite reboot loops.
+//
+// false-unreachable reboot safety (2026-06-25): "unreachable" as the dashboard
+// sees it means the LOCALLY-FORWARDED port is dark — which is ALSO the signature
+// of an operator-side fault (the laptop's gcloud auth expired, the ssh -L tunnel
+// zombied, a laptop network blip) where the VM itself is perfectly healthy.
+// Rebooting a healthy production VM off that signal interrupts a live session.
+// So three operator-fault guards are layered BEFORE the cooldown/attempts budget
+// (a reset is a last resort, never the response to a dark local port). Each is
+// OPT-IN: it only changes the verdict when the caller supplies the fact, so
+// legacy callers (and the OOM-wedge tests) that pass none keep the old behavior.
+//   operatorAuthDegraded  our own gcloud auth is broken → EVERY VM reads
+//                         unreachable; rebooting them all is exactly wrong → keep
+//   fleetWideUnreachable  a simultaneous N-VM "outage" is the operator (auth/
+//                         tunnel/network), not N dead VMs → keep
+//   gcpReachable          GCP-side confirmation: true  ⇒ the VM answers from
+//                         GCP's vantage, so the dark local port is a laptop
+//                         tunnel fault → 'respawn' (never reset); null ⇒ the
+//                         GCP-side probe was inconclusive → keep (don't escalate
+//                         a destructive reset on absence of evidence); false ⇒
+//                         genuinely unreachable from GCP too → fall through to
+//                         the cooldown/attempts budget and reset as before.
+function reconcileRosteredVm({ exists, hasSession, hasPendingAdd, streak, resetHistory, threshold, cooldownMs, maxAttempts, operatorAuthDegraded, fleetWideUnreachable, gcpReachable } = {}) {
   if (exists === null || exists === undefined) return "leave";
-  if (exists) return "keep";
-  if (hasSession || hasPendingAdd) return "leave";
-  return "cleanup";
+  if (!exists) {
+    if (hasSession || hasPendingAdd) return "leave";
+    return "cleanup";
+  }
+
+  // If the VM exists, check if it's dead-unreachable and eligible for auto-reset.
+  if (streak !== undefined && threshold !== undefined) {
+    if (streak >= threshold) {
+      if (hasSession || hasPendingAdd) {
+        // Do NOT auto-reset a VM that is busy (holding a live session or an in-flight add)
+        return "keep";
+      }
+
+      // Operator-fault guards — layered before the cooldown/attempts budget so a
+      // laptop-side fault never even consumes a reset attempt.
+      if (operatorAuthDegraded) return "keep";
+      if (fleetWideUnreachable) return "keep";
+      if (gcpReachable === true) return "respawn";
+      if (gcpReachable === null) return "keep";
+
+      const history = resetHistory || { count: 0, lastResetAt: 0 };
+      const attempts = history.count || 0;
+      const limit = maxAttempts !== undefined ? maxAttempts : 3;
+      
+      if (attempts >= limit) {
+        // Budget exhausted (VM wedges repeatedly) -> park (needs-manual-recovery status)
+        return "keep";
+      }
+      
+      const lastReset = history.lastResetAt || 0;
+      const cooldown = cooldownMs !== undefined ? cooldownMs : 600000; // default 10 minutes
+      const now = Date.now();
+      if (now - lastReset < cooldown) {
+        // Within cooldown window -> do not reset again yet
+        return "keep";
+      }
+
+      return "reset";
+    }
+  }
+
+  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 = {
@@ -314,11 +527,14 @@ module.exports = {
   reconcileRosteredVm,
   orphanedAddsToReconcile,
   classifyProjectWiring,
+  classifyLbReachableForReap,
   recoverBootstrapDecision,
+  continueBootstrapRecovery,
   exitMarkerName,
   parseExitMarker,
   readExitMarker,
   clearExitMarker,
+  isSignalKillExit,
   reattachVerdict,
   reattachNextStep,
 };