@codeyam-editor/codeyam-editor 0.1.3 → 0.1.5

package/npm/fleet-prewarm.js

@@ -0,0 +1,165 @@
+'use strict';
+
+// npm/fleet-prewarm.js — pure verdicts for the fleet dashboard's concurrent
+// cold-add pre-warm (vm--concurrent-add-prewarm-branch-image).
+//
+// When several VMs are added at once on a branch whose prebuilt image is not yet
+// published, EVERY VM compiles the editor from source (~10 min each) in
+// parallel — none has finished compiling-and-publishing before its siblings
+// start, so the self-feeding fast path (publish_compiled_binary in
+// scripts/gcp-bootstrap.sh) never gets a chance to prime. The fix is to bring up
+// ONE "pacer" VM first, wait until it has published the branch binary (or
+// settled on a definite won't-publish), then release the rest so they pull it.
+//
+// This module holds the *decisions* — pace-or-fan-out, which tags constitute a
+// usable image, parsing the bootstrap's machine markers, and the push-token
+// diagnostic — so each case is unit-tested without a live VM or registry. The
+// I/O (the manifest probe, reading the add log, threading the held queue) lives
+// in the server / cloud.js shells that call these.
+
+// Machine-detectable markers gcp-bootstrap.sh emits into the cloud:up add log
+// (streamed to /tmp/dash-add-vm-<n>.log). They are stable contracts the
+// dashboard greps for — keep them in sync with scripts/gcp-bootstrap.sh.
+const MARKER_PUBLISHED = 'CY_BINARY_PUBLISHED'; // pacer published the branch binary; held adds can pull it
+const MARKER_PUBLISH_SKIPPED = 'CY_BINARY_PUBLISH_SKIPPED'; // pacer will NOT publish (no token / no branch / failure)
+const MARKER_PATH_PULL = 'CY_PROVISION_PATH pull'; // this VM pulled a prebuilt image (~2 min fast path)
+const MARKER_PATH_COMPILE = 'CY_PROVISION_PATH compile'; // this VM compiled from source (~10 min slow path)
+
+// Mirror scripts/gcp-bootstrap.sh's BRANCH_SLUG: '/' → '-', lowercased, capped
+// at 128 chars. The dashboard and the VM MUST agree on the slug or the probe
+// checks different tags than the bootstrap pulls. Empty / missing branch → the
+// universal "main" slug, matching the bootstrap's detached-HEAD fallback.
+function branchSlug(branch) {
+  if (!branch || typeof branch !== 'string') return 'main';
+  const slug = branch.replace(/\//g, '-').toLowerCase().slice(0, 128);
+  return slug || 'main';
+}
+
+// The tag chain that constitutes a "usable" prebuilt editor image, in the same
+// precedence the dev bootstrap pulls (build_editor_image in gcp-bootstrap.sh):
+//   1. cloud-smoke:<slug>-latest   — the branch base image
+//   2. cloud-smoke:main-latest     — the universal CI fallback (skipped when
+//                                    the branch already IS main, no duplicate)
+//   3. binary:<slug>-latest        — the branch binary overlay
+// If a manifest HEAD on ANY of these succeeds, a cold add can pull instead of
+// compiling, so no pacer is needed. Registry defaults to the same
+// CODEYAM_REGISTRY the bootstrap reads.
+function usableImageTags({ registry, branch } = {}) {
+  const reg = registry || 'ghcr.io/codeyam-ai';
+  const slug = branchSlug(branch);
+  const tags = [`${reg}/codeyam-editor-cloud-smoke:${slug}-latest`];
+  if (slug !== 'main') tags.push(`${reg}/codeyam-editor-cloud-smoke:main-latest`);
+  tags.push(`${reg}/codeyam-editor-binary:${slug}-latest`);
+  return tags;
+}
+
+// The core verdict: should a batch add pace one VM ahead of the rest?
+//
+//   count           how many VMs the operator asked to add
+//   hasUsableImage  the probe result — true (image present), false (definitely
+//                   absent), or null (couldn't determine: no token, probe error)
+//   hasPushToken    a write:packages token is present, so the pacer CAN publish
+//
+// Pace ONLY when it strictly pays AND can work:
+//   - count > 1            — a single add is never serialized (never slower)
+//   - hasUsableImage === false — known-absent; an existing image means all N can
+//                                pull concurrently, and `null` (unknown) falls
+//                                back to today's fan-out rather than risk a
+//                                10-min serialization that buys nothing
+//   - hasPushToken         — without it the pacer can't publish, so pacing would
+//                            just serialize N source compiles for no gain
+// Any miss → fan out all N immediately (today's behavior, strictly additive).
+function decideBatchPrewarm({ count, hasUsableImage, hasPushToken } = {}) {
+  const k = Math.round(Number(count) || 0);
+  if (k <= 1) return { pace: false, reason: 'single add — never serialized' };
+  if (hasUsableImage === true)
+    return { pace: false, reason: 'usable prebuilt image exists — all pull concurrently' };
+  if (hasUsableImage !== false)
+    return { pace: false, reason: 'image presence undetermined — fan out (no worse than today)' };
+  if (!hasPushToken)
+    return { pace: false, reason: 'no push token — pacer could not publish, fan out' };
+  return { pace: true, reason: `pacing 1 of ${k} — branch image absent, will publish for the rest` };
+}
+
+// Has the pacer's add log settled to a definite publish outcome the held batch
+// can act on? Returns 'published' (binary is now pullable — release and pull),
+// 'skipped' (pacer will NOT publish — release; they recompile, today's
+// behavior), or null (still in flight — keep waiting). A SKIPPED that is later
+// followed by a PUBLISHED still reports published (the success wins), so marker
+// ordering can't strand the batch on a transient earlier skip.
+function detectPublishSettled(logText) {
+  if (!logText || typeof logText !== 'string') return null;
+  if (logText.includes(MARKER_PUBLISHED)) return 'published';
+  if (logText.includes(MARKER_PUBLISH_SKIPPED)) return 'skipped';
+  return null;
+}
+
+// The pure release decision for the pre-warm hold (startPrewarmWatch's per-tick
+// verdict): given the pacer's current signals, should the held batch be released
+// now, and why? Returns a human reason string to release, or null to keep
+// waiting. Releases on the FIRST of: a settled publish marker, the pacer job
+// terminating without one, or the bounded timeout — so a publish failure or a
+// stuck pacer can never strand the batch.
+//
+//   settled     detectPublishSettled() result: 'published' | 'skipped' | null
+//   pacerJob    the pacer add job record ({ state, ... }) or null/undefined
+//   elapsedMs   ms since the watch started
+//   timeoutMs   the bounded fallback after which the batch releases regardless
+function prewarmReleaseDecision({ settled, pacerJob, elapsedMs, timeoutMs } = {}) {
+  if (settled) return `pacer ${settled}`;
+  const st = pacerJob && pacerJob.state;
+  if (st === 'done' || st === 'error') return `pacer ${st}`;
+  if (Number(elapsedMs) > Number(timeoutMs)) return 'timeout';
+  return null;
+}
+
+// Which provision path did a VM take, parsed from its add log's path marker?
+// Returns 'pull' (~2 min prebuilt pull), 'compile' (~10 min source compile), or
+// null (not yet determined). The LAST marker wins — a VM that tries a pull,
+// misses, then falls back to a compile correctly reads 'compile'.
+function provisionPath(logText) {
+  if (!logText || typeof logText !== 'string') return null;
+  const pull = logText.lastIndexOf(MARKER_PATH_PULL);
+  const compile = logText.lastIndexOf(MARKER_PATH_COMPILE);
+  if (pull < 0 && compile < 0) return null;
+  return compile > pull ? 'compile' : 'pull';
+}
+
+// Operator-facing one-liner for a provision path, for the add card sub-status.
+// null path → null (render nothing).
+function provisionPathLabel(path) {
+  if (path === 'pull') return 'pulling prebuilt image (~2 min)';
+  if (path === 'compile') return 'compiling from source (~10 min)';
+  return null;
+}
+
+// The push-token diagnostic surfaced on the dashboard. Without a write:packages
+// token the self-feeding publish is silently off, so EVERY cold add recompiles
+// (~10 min) and the pacer can't help either — a state the operator must see, not
+// discover from a buried per-VM log line.
+function pushTokenDiagnostic({ hasPushToken } = {}) {
+  if (hasPushToken) return { warn: false, message: null };
+  return {
+    warn: true,
+    message:
+      'Self-feeding disabled: no CODEYAM_GHCR_PUSH_TOKEN (write:packages). ' +
+      'Cold adds will always recompile the editor from source (~10 min each) ' +
+      'and concurrent batches cannot pre-warm. Install a write-scoped token and ' +
+      'reinstall the fleet agents to enable the fast path.',
+  };
+}
+
+module.exports = {
+  MARKER_PUBLISHED,
+  MARKER_PUBLISH_SKIPPED,
+  MARKER_PATH_PULL,
+  MARKER_PATH_COMPILE,
+  branchSlug,
+  usableImageTags,
+  decideBatchPrewarm,
+  detectPublishSettled,
+  prewarmReleaseDecision,
+  provisionPath,
+  provisionPathLabel,
+  pushTokenDiagnostic,
+};

package/npm/fleet-public-url.js

@@ -0,0 +1,160 @@
+'use strict';
+// Pure classification + reason-string derivation for the dashboard's public-URL
+// reachability probe (vm: Dashboard validates the public ingress URL, not just
+// the tunnel).
+//
+// The fleet dashboard probes each VM's editor through the local SSH tunnel and,
+// in Google-LB mode, the per-VM backend SERVICE health (gcloud get-health) —
+// but never the public `<slug>.editor.<domain>` URL the card advertises. VM5
+// (2026-06-19) sat "healthy" on every one of those signals while the advertised
+// URL returned 503 "no healthy upstream" for hours: a reused-slug Add aborted on
+// a `Duplicate path matcher` collision before binding the host rule, so the
+// hostname fell through to the default backend. A backend-health probe is
+// structurally blind to a missing host rule; only an end-to-end GET of the
+// advertised hostname catches it.
+//
+// This module is the PURE half — parsing + string derivation, no network —
+// mirroring classifyBackendHealth's `absent|unknown|unhealthy|healthy`
+// contract. The HTTPS GET I/O lives in server.js's gatherPublicUrlHealth, the
+// same split gatherBackendHealth / classifyBackendHealth already follow. Unit-
+// tested in npm/fleet-public-url.test.js.
+//
+// Stack note: this is fleet-operator infrastructure (the GCE fleet that runs
+// codeyam-editor itself), GCP / HTTPS-LB-specific by design — the same posture
+// as the scripts it backstops. A project that never joins the fleet never sets
+// FLEET_DOMAIN and never reaches this probe.
+
+// The Google HTTPS-LB "no backend answered" body signature: GFE emits this when
+// a host rule routes nowhere (or to a backendless default). A single source so
+// the classifier and any future log line agree on the string.
+const NO_HEALTHY_UPSTREAM_RE = /no healthy upstream/i;
+
+/** Classify a public-URL probe result into the ingress-wiring vocabulary,
+ *  following classifyBackendHealth's contract — absence of evidence is never a
+ *  problem state:
+ *
+ *    'unknown' — a network / TLS / timeout / DNS error (no statusCode): the
+ *                probe couldn't reach a verdict. NEVER a degraded state, exactly
+ *                like classifyBackendHealth's 'unknown'. Also covers an
+ *                unexpected non-503 HTTP error (a 404/500 from the editor
+ *                itself) — that means the host rule DID route, just not to a
+ *                happy response, so it is neither 'unwired' nor a clean 'wired'.
+ *    'unwired' — the LB answered but no backend is bound to the advertised host:
+ *                a 503, or a recognizable "no healthy upstream" default-backend
+ *                body. THIS is the missing-host-rule signal a backend-health
+ *                probe cannot see (the VM5 case).
+ *    'wired'   — any 2xx / 3xx: the editor answered (a 200, or its login 302
+ *                redirect — the real VM5-healthy shape). The host rule routes.
+ */
+function classifyPublicUrlHealth({ statusCode, body, error } = {}) {
+  if (error || statusCode == null) return 'unknown';
+  const code = Number(statusCode);
+  if (code === 503) return 'unwired';
+  if (NO_HEALTHY_UPSTREAM_RE.test(String(body || ''))) return 'unwired';
+  if (code >= 200 && code < 400) return 'wired';
+  // Any other 4xx/5xx is the editor answering with an error of its own — the
+  // host rule routes, so it is NOT 'unwired'; but it is not a clean success
+  // either. Treat as 'unknown' (absence of the unwired signal) so we never raise
+  // a false ingress-unwired reason on it.
+  return 'unknown';
+}
+
+/** The sticky `ingress-unwired` degraded-reason string — the single source for
+ *  both the dashboard card reason and any log line. Embeds the advertised URL
+ *  and the EXACT re-wire command an operator runs to fix it, so the amber card
+ *  is self-documenting (the surface VM5 should have shown for hours instead of
+ *  reading healthy). */
+function ingressUnwiredReason({ url, domain, slug, n } = {}) {
+  const target = url || `(vm-${n} editor URL)`;
+  const slugEnv = slug ? ` VM_SLUG=${slug}` : '';
+  const rewire = `FLEET_DOMAIN=${domain}${slugEnv} bash scripts/gcp/vm-ingress.sh ${n} up`;
+  return `ingress-unwired: ${target} returns 503 (host rule missing). Re-wire: ${rewire}`;
+}
+
+/** Decide whether a just-landed public-URL verdict warrants an auto-rewire
+ *  self-heal. PURE — the dashboard reads the live VM state (I/O at the edge) and
+ *  passes the facts in; the gate logic itself is unit-testable without network
+ *  or server state. Fires only for a GENUINE missing-host-rule case:
+ *    - `verdict` is 'unwired' (the URL 503s), AND
+ *    - `reachable` (the tunnel is up — a down VM is not a missing-host-rule
+ *      case; re-wiring it accomplishes nothing), AND
+ *    - `backendEditorHealth` is 'healthy' (the backend SERVICE is fine, so only
+ *      the host rule is missing — the VM5 host-rule-drift case) OR 'absent' (the
+ *      per-VM backend service was NEVER created — the interrupted-add VM-4 case,
+ *      where a SIGTERM killed `backend-services create` mid-wiring) OR
+ *      'unhealthy' *with* `backendEditorBackendless` true (the BES EXISTS but has
+ *      ZERO NEG backends attached — the concurrent-add editor-band race, where the
+ *      backend slipped its NEG attachment but the BES object landed). All three
+ *      are recoverable by a single `vm-ingress.sh up`, which is
+ *      describe-before-create idempotent and creates/attaches only the missing
+ *      pieces. A backendless BES classifies as 'unhealthy' (get-health returns
+ *      empty, indistinguishable from a still-cold backend) yet will NEVER converge
+ *      on its own — it has no endpoint to become healthy — so it MUST re-wire, not
+ *      wait. 'unknown' (a transient gcloud/auth error — absence of evidence must
+ *      never trigger a re-wire storm) and a GENUINELY-converging 'unhealthy' (a
+ *      backend IS attached, health still flipping — `backendEditorBackendless`
+ *      false: let it converge, don't churn the LB) stay EXCLUDED, AND
+ *    - no re-wire is already `inFlight` (one per VM), AND
+ *    - the debounce window has elapsed since `lastRewireAt`.
+ *  The debounce is load-bearing: GCP host-rule changes take minutes to roll out
+ *  to all GFEs (VM5's CORRECT rule 503'd for ~minutes before flipping), so a
+ *  per-cycle re-fire would storm the LB while a good change is still
+ *  propagating. A missing/0 `lastRewireAt` means "never re-wired" → the window
+ *  is satisfied. */
+function shouldAutoRewireIngress({
+  verdict,
+  reachable,
+  backendEditorHealth,
+  backendEditorBackendless,
+  inFlight,
+  lastRewireAt,
+  now,
+  debounceMs,
+} = {}) {
+  if (verdict !== 'unwired') return false;
+  if (!reachable) return false;
+  // 'healthy' = host-rule drift (VM5); 'absent' = backend never created
+  // (interrupted-add VM-4); 'unhealthy' + backendless = BES exists with zero NEG
+  // backends (concurrent-add editor-band race) — it can't converge unaided, so it
+  // re-wires too. A genuinely-converging 'unhealthy' (backend attached, health
+  // flipping → backendless false) and 'unknown' stay excluded.
+  const rewirable =
+    backendEditorHealth === 'healthy' ||
+    backendEditorHealth === 'absent' ||
+    (backendEditorHealth === 'unhealthy' && backendEditorBackendless === true);
+  if (!rewirable) return false;
+  if (inFlight) return false;
+  return (Number(now) - (Number(lastRewireAt) || 0)) >= Number(debounceMs);
+}
+
+/** Classify a `gcloud compute backend-services describe --format=value(backends[].group)`
+ *  result into the attachment vocabulary — the signal `get-health` cannot give,
+ *  because an empty health result is ambiguous between "no backend attached" and
+ *  "a backend attached but still health-pending":
+ *
+ *    'backendless' — the BES EXISTS but has ZERO NEG backends attached (the
+ *                    describe printed empty / whitespace-only output). This BES
+ *                    will NEVER converge on its own — there is no endpoint to
+ *                    become healthy — so it is re-wirable, feeding
+ *                    shouldAutoRewireIngress's `backendEditorBackendless` branch
+ *                    (the concurrent-add editor-band slip).
+ *    'attached'    — the describe printed at least one backend group, OR it
+ *                    ERRORED. An error is treated as 'attached' (absence of
+ *                    evidence): a NotFound is the 'absent' case classifyBackendHealth
+ *                    already owns, and a transient gcloud/auth failure must NEVER
+ *                    manufacture a 'backendless' verdict that storms the LB with a
+ *                    re-wire. Pure (no I/O), so the empty-backends classification is
+ *                    unit-testable without gcloud — the I/O lives in server.js's
+ *                    gatherEditorBackendless, the same split classifyPublicUrlHealth
+ *                    follows. */
+function classifyBackendAttachment(err, stdout) {
+  if (err) return 'attached';
+  return String(stdout == null ? '' : stdout).trim() === '' ? 'backendless' : 'attached';
+}
+
+module.exports = {
+  classifyPublicUrlHealth,
+  ingressUnwiredReason,
+  shouldAutoRewireIngress,
+  classifyBackendAttachment,
+};

package/npm/fleet-queue.js

@@ -37,4 +37,41 @@ function decideAutoReleaseGoneHead({ queue, vms, jobs, orphans }) {
   return { release: true, uuid: head.uuid, vm: n, reason: `owning VM-${n} left the fleet` };
 }
 
-module.exports = { decideAutoReleaseGoneHead };
+/** Compute the set-priority writes a reorder requires.
+ *
+ *  A reorder POSTs a desired uuid order; the queue's priority convention is
+ *  first=N … last=1 (higher priority sorts earlier). This maps the desired
+ *  order onto target priorities, drops the entries already at their target
+ *  priority (no-ops — no `set-priority` shell-out needed), and sorts the
+ *  remaining writes intended-HEAD-first so the head lands first even if a
+ *  later write fails. `current` is the authoritative queue ([{uuid,priority}]);
+ *  `order` is the desired uuid sequence.
+ *
+ *  Returns one of:
+ *    { ok: false, reason: 'empty' }           — no order supplied
+ *    { ok: false, reason: 'stale' }           — order doesn't match current set
+ *    { ok: true, targets: [{uuid, prio}] }    — writes to apply (possibly [])
+ *  Pure; no I/O.
+ */
+function computeReorderTargets({ order, current }) {
+  const ord = (order || []).map((s) => String(s).trim()).filter(Boolean);
+  const cur = current || [];
+  const curUuids = cur.map((e) => e.uuid);
+  if (!ord.length) return { ok: false, reason: 'empty' };
+  // Same membership, same length — a reorder, not an add/remove. Anything else
+  // means the queue changed underneath the operator since they last saw it.
+  if (ord.length !== curUuids.length || !ord.every((u) => curUuids.includes(u))) {
+    return { ok: false, reason: 'stale' };
+  }
+  const N = ord.length;
+  const targets = ord
+    .map((uuid, i) => ({ uuid, prio: N - i }))                     // first=N … last=1
+    .filter(({ uuid, prio }) => {
+      const e = cur.find((x) => x.uuid === uuid);
+      return !e || e.priority !== prio;                            // skip no-ops
+    })
+    .sort((a, b) => b.prio - a.prio);                              // intended HEAD first
+  return { ok: true, targets };
+}
+
+module.exports = { decideAutoReleaseGoneHead, computeReorderTargets };

package/npm/fleet-reconcile.js

@@ -33,4 +33,103 @@ function computeUnrostered(running, shown) {
     .sort((a, b) => a - b);
 }
 
-module.exports = { parseRunningFleetVms, computeUnrostered };
+// Streak bookkeeping for the adopt-direction stranded-instance reconcile — the
+// mirror of pollVanishedInstances' `unreachableStreak` gate, in the opposite
+// (adopt) direction. Given the currently-stranded VM numbers (running in GCP
+// but absent from roster / provisioning / orphan), the prior streak map, and
+// the threshold, return the NEXT streak map (incremented for each still-stranded
+// number; entries for no-longer-stranded numbers dropped so a transient blip
+// never leaves a stale count) plus `ready` — the numbers whose streak has
+// reached the threshold and may now be auto-finished. A single stale
+// `runningFleetVms` snapshot therefore can't trigger a recovery: the instance
+// must read stranded for `threshold` consecutive polls first. Pure, so the gate
+// is unit-tested without gcloud or a running server.
+function strandedAdoptDecision({ stranded, streaks, threshold } = {}) {
+  const prev = streaks || {};
+  const t = Number(threshold) > 0 ? Number(threshold) : 1;
+  const present = [...new Set((stranded || []).filter((n) => Number.isInteger(n) && n > 0))];
+  const next = {};
+  const ready = [];
+  for (const n of present) {
+    const count = (Number(prev[n]) || 0) + 1;
+    next[n] = count;
+    if (count >= t) ready.push(n);
+  }
+  ready.sort((a, b) => a - b);
+  return { streaks: next, ready };
+}
+
+// Map a single degraded reason to the live health signal that resolves it.
+// Returns true only when that signal now passes; a reason with no mapped signal
+// returns false (retained — a genuine config problem, never a false-green).
+// Start with the two observed classes (improve41); extend the table as new
+// degraded reasons gain a corresponding live signal.
+function reasonClearedByHealth(reason, { reachableServing, authed }) {
+  const r = String(reason || '');
+  if (/claude auth|claude\.json|login/i.test(r)) return authed;
+  if (/container|never came up|provisioning failed/i.test(r)) return reachableServing;
+  return false;
+}
+
+// Given a terminal add-job badge and the VM's live health, return the corrected
+// badge — or null when nothing changes. Conservative by construction: clears a
+// degraded reason only when its live health signal now passes; flips a bare
+// `error` add to `done` when the VM is reachable + serving; leaves any reason
+// with no health signal intact (no false-green). The poll loop supplies the live
+// facts (I/O at the edge) and applies the result; the verdict itself is pure.
+//   job:    { state: 'done'|'error', degraded, degradedReasons }
+//   health: { reachable, editorHttpOk, providerAuthState }
+//   → null | { state, degraded, degradedReasons, transition }
+function reconcileTerminalAddBadge({ job, health } = {}) {
+  if (!job || !health) return null;
+  const reachableServing = !!(health.reachable && health.editorHttpOk);
+  const authed = health.providerAuthState === 'authenticated';
+
+  // Bare `error` add (no degraded reasons): flip to `done` once the VM is
+  // reachable + serving — the VM3 case (a manual `cloud:up` recovered the editor
+  // outside the dashboard's view).
+  if (job.state === 'error') {
+    const reasons = job.degradedReasons || [];
+    if (reasons.length === 0 && reachableServing) {
+      return { state: 'done', degraded: false, degradedReasons: [], transition: 'error→done (editor 200)' };
+    }
+    return null;
+  }
+
+  // Terminal `done` that is degraded: clear each reason whose live signal now
+  // passes; retain the rest. Drop `degraded` only when no reasons remain.
+  if (job.state === 'done' && job.degraded) {
+    const reasons = job.degradedReasons || [];
+    const remaining = reasons.filter((reason) => !reasonClearedByHealth(reason, { reachableServing, authed }));
+    if (remaining.length === reasons.length) return null; // nothing cleared → no-op
+    const cleared = reasons.length - remaining.length;
+    return {
+      state: 'done',
+      degraded: remaining.length > 0,
+      degradedReasons: remaining,
+      transition: remaining.length > 0
+        ? `degraded: cleared ${cleared} reason(s), ${remaining.length} remain`
+        : 'degraded→clear (health restored)',
+    };
+  }
+
+  return null;
+}
+
+// Self-heal for the slug sidecar: given the slug map (`{ "<N>": "<slug>" }`) and
+// the roster (the live VM numbers), return the sorted, de-duped VM numbers whose
+// slug entry should be released because the VM is no longer rostered. A
+// destroyed VM is removed from the roster, so any slug still keyed to a
+// non-rostered number is stranded (e.g. a destroy path that failed to call
+// `removeSlug`) and would otherwise block re-using that name forever. Pure: the
+// caller reads the sidecar + roster (I/O at the edge) and applies `removeSlug`
+// to each returned number. Tolerates a null/absent slug map and an empty roster.
+function pruneOrphanSlugs({ slugs, roster } = {}) {
+  const rostered = new Set((roster || []).filter(Number.isInteger));
+  const orphans = Object.keys(slugs || {})
+    .map((k) => Number(k))
+    .filter((n) => Number.isInteger(n) && n > 0 && !rostered.has(n));
+  return [...new Set(orphans)].sort((a, b) => a - b);
+}
+
+module.exports = { parseRunningFleetVms, computeUnrostered, strandedAdoptDecision, reconcileTerminalAddBadge, pruneOrphanSlugs };