@codeyam-editor/codeyam-editor 0.1.8 → 0.1.10

package/npm/fleet-auth.js

@@ -108,9 +108,77 @@ function deriveDefaultAuthAccount(vms, lastAuthAt) {
   return best ? best.account : null;
 }
 
+// Enumerate the Claude accounts the fleet can seed a new VM from: one row per
+// distinct account email held by an authenticated VM, carrying the account
+// object and the VM numbers holding it (so the Add dialog can show
+// "jared@codeyam.com — VM-14"). Pure over the polled VM snapshot — the same
+// array deriveDefaultAuthAccount reads. Emails compare case-insensitively; rows
+// sort by email and each row's VM numbers ascend, so the result is deterministic.
+function listAvailableAccounts(vms) {
+  const byEmail = new Map();
+  for (const v of vms || []) {
+    const pa = v && v.providerAuth;
+    const acct = pa && pa.account;
+    if (!acct || !acct.email || pa.state !== 'authenticated') continue;
+    const key = String(acct.email).toLowerCase();
+    const row = byEmail.get(key) || { account: acct, vms: [] };
+    if (!row.vms.includes(v.n)) row.vms.push(v.n);
+    byEmail.set(key, row);
+  }
+  return [...byEmail.values()]
+    .map((r) => ({ account: r.account, vms: [...r.vms].sort((a, b) => a - b) }))
+    .sort((a, b) => String(a.account.email).localeCompare(String(b.account.email)));
+}
+
+// Pick the credential donor for a chosen account: the lowest-numbered VM in
+// `reachableDonors` whose authenticated account is `email`, or null when no
+// reachable VM holds it (or no email was asked for). `vms` is the per-VM poll
+// state keyed by VM number (`state.vms`). Pure.
+function selectDonorForAccount(reachableDonors, vms, email) {
+  if (!email) return null;
+  const want = String(email).toLowerCase();
+  for (const n of [...(reachableDonors || [])].sort((a, b) => a - b)) {
+    const pa = vms && vms[n] && vms[n].providerAuth;
+    const got = pa && pa.state === 'authenticated' && pa.account && pa.account.email;
+    if (got && String(got).toLowerCase() === want) return n;
+  }
+  return null;
+}
+
+// A plausible Claude account email: one "@", a dotted domain, no whitespace or
+// shell-significant characters. The shared guard for every place an operator
+// can name an account (the Add form's per-launch override, the set-default
+// action, the persisted sidecar). Deliberately NOT checked against the fleet,
+// whose roster can change between naming an account and provisioning with it.
+const ACCOUNT_EMAIL_RE = /^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}$/;
+function isAccountEmail(s) {
+  return typeof s === 'string' && ACCOUNT_EMAIL_RE.test(s.trim());
+}
+
+// Resolve the fleet's chosen Claude account email: the operator's persisted
+// choice (`saved`, read from npm/fleet-auth-account.js by the caller) when it is
+// a plausible email, else the derived default — the most recently auth-updated
+// VM's account — so a fleet that has never chosen behaves as it did before the
+// picker existed. Pure. Returns an email string, or null when neither exists.
+function resolveChosenAccount(saved, vms, lastAuthAt) {
+  if (isAccountEmail(saved)) return saved.trim();
+  const derived = deriveDefaultAuthAccount(vms, lastAuthAt);
+  return (derived && derived.email) || null;
+}
+
 // Return true if this one VM is eligible for an auth-start action now.
 function isAuthStartable(v, job) {
   return classifyAuthVm(v, job).eligible;
 }
 
-module.exports = { classifyAuthVm, selectAuthTargets, summarizeAuthBatch, deriveDefaultAuthAccount, isAuthStartable };
+module.exports = {
+  classifyAuthVm,
+  selectAuthTargets,
+  summarizeAuthBatch,
+  deriveDefaultAuthAccount,
+  listAvailableAccounts,
+  selectDonorForAccount,
+  isAccountEmail,
+  resolveChosenAccount,
+  isAuthStartable,
+};

package/npm/fleet-branch.js

@@ -46,4 +46,127 @@ function resolveFleetBranch({ envBranch, gitBranch, fallback } = {}) {
   return cleanBranch(fallback) || UNKNOWN_BRANCH;
 }
 
-module.exports = { UNKNOWN_BRANCH, cleanBranch, resolveFleetBranch };
+// ---------- Dead-pin detection ----------
+// `fleet-advance-to.sh` refuses to WRITE a pin for a branch absent from origin,
+// but that guard runs once and nothing re-checks the pin already in place —
+// while the branch it names can be deleted by anyone merging a PR with the
+// delete-branch box ticked. Observed 2026-08-15: PR #104 merged
+// `editor-improvements-72` and deleted it; hours later the operator host still
+// read `FLEET_BRANCH=editor-improvements-72` and nothing said so.
+//
+// The probe itself (`git ls-remote`) is I/O and belongs to server.js, on the
+// SLOW memo cadence rather than the ~3s /data poll. What lives here is the pure
+// classification of its outcome — which is the part a test can actually reach,
+// since a function defined in server.js can never be executed by a test (that
+// file has top-level side effects on require).
+//
+// The tri-state mirrors scripts/operator/lib/branch-on-origin.sh exactly, and
+// the mirroring is the point: `gone` is a DEFINITIVE absence, `indeterminate`
+// means absence was NOT proven (no network, no remote, auth trouble). Widening
+// `indeterminate` into `gone` would turn every offline operator host into a
+// fleet-wide "your pin is dead" alarm.
+
+/** Map a `git ls-remote --exit-code --heads` exit code to the shared tri-state.
+ *  0 -> 'live', 2 -> 'gone', anything else (including a non-numeric or absent
+ *  code) -> 'indeterminate'. Pure. */
+function lsRemoteStatus(exitCode) {
+  if (exitCode === 0) return 'live';
+  if (exitCode === 2) return 'gone';
+  return 'indeterminate';
+}
+
+/** Classify the health of the fleet's branch pin.
+ *
+ *  Returns `{ state, branch, pinned, dead, blocks, recovery }` where `state` is
+ *  'live' | 'gone' | 'indeterminate' | 'unknown'.
+ *
+ *  'unknown' is the un-probeable case — no branch, or the UNKNOWN_BRANCH
+ *  sentinel that `resolveFleetBranch` yields when there is neither a pin nor a
+ *  readable git HEAD. There is no ref to ask origin about, so reporting it as
+ *  `gone` would invent a deletion that never happened.
+ *
+ *  `dead` is true ONLY for 'gone'. It is the single field a caller should gate a
+ *  degradation banner on, so no consumer has to re-derive which states are
+ *  actionable.
+ *
+ *  `blocks` names what a dead pin is actively breaking — both consequences,
+ *  because neither announces itself: the operator-repo refresh cannot fetch a
+ *  deleted ref, and the pin also drives `cloud.json editorBranch`, so newly
+ *  provisioned VMs check out a ref that is not there. Pure; no I/O. */
+function classifyBranchPin({ branch, lsRemoteExitCode, pinned = false } = {}) {
+  const name = cleanBranch(branch);
+  const probeable = name !== null && name !== UNKNOWN_BRANCH;
+  const state = probeable ? lsRemoteStatus(lsRemoteExitCode) : 'unknown';
+  const dead = state === 'gone';
+  return {
+    state,
+    branch: name,
+    pinned: Boolean(pinned),
+    dead,
+    blocks: dead
+      ? [
+        'refresh-operator-repo.sh cannot fetch the pinned branch, so this host keeps serving whatever its clone already had',
+        'cloud.json editorBranch reads the same pin, so newly provisioned VMs check out a ref that does not exist',
+      ]
+      : [],
+    recovery: dead
+      ? `scripts/operator/fleet-advance-to.sh <BRANCH> — move the fleet to a live branch (it refuses a branch that is itself absent from origin)`
+      : null,
+  };
+}
+
+/** Decide whether the fleet pin should override a stored per-VM branch when an
+ *  add is RE-ISSUED, and report every override so the caller can log it.
+ *
+ *  Returns `{ config, overrides }` — a NEW config (the input is never mutated)
+ *  and `[{ field, from, to }]`, empty when nothing changed.
+ *
+ *  The problem this solves: a per-VM config that recorded `editor-improvements-75`
+ *  was not wrong when it was written — it EXPIRED, silently, the moment that
+ *  branch merged and origin pruned it. This repo prunes on merge, so every stored
+ *  feature-branch name has that property. The pin does not expire: it is the
+ *  durable statement of fleet-wide policy, and on 2026-08-25 it was correct
+ *  throughout while four retried cards each failed on their stale snapshot (a
+ *  fresh pool add read the pin and succeeded at the same moment).
+ *
+ *  Three guards, each declining to act rather than acting wrongly:
+ *   - `selfHost` false ⇒ untouched. A client VM's branch is a deliberate
+ *     per-project choice; overwriting it with a fleet pin would silently
+ *     retarget someone else's project. Only the self-host path, where the branch
+ *     IS fleet policy, falls back to the pin.
+ *   - no pin, or the UNKNOWN_BRANCH sentinel ⇒ untouched. There is no branch to
+ *     prefer, and stamping the sentinel would guarantee the failure this exists
+ *     to prevent.
+ *   - `pinState === 'gone'` ⇒ untouched. A pin PROVEN absent from origin is not
+ *     an improvement on a stale-but-possibly-live stored branch; swapping one
+ *     dead ref for another just moves the failure. Note the deliberate
+ *     asymmetry with 'indeterminate', which does NOT decline: absence was not
+ *     proven there, and refusing to converge every time the network blips would
+ *     strand the fleet on stale branches for the sake of a maybe.
+ *
+ *  Pure; no I/O. */
+function pinCorrectedBranches({ cfg, pin, selfHost = false, pinState } = {}) {
+  const config = { ...(cfg || {}) };
+  const overrides = [];
+  const name = cleanBranch(pin);
+  if (!selfHost || !name || name === UNKNOWN_BRANCH || pinState === 'gone') {
+    return { config, overrides };
+  }
+  for (const field of ['clientBranch', 'editorBranch']) {
+    const from = cleanBranch(config[field]);
+    if (from && from !== name) {
+      config[field] = name;
+      overrides.push({ field, from, to: name });
+    }
+  }
+  return { config, overrides };
+}
+
+module.exports = {
+  UNKNOWN_BRANCH,
+  cleanBranch,
+  resolveFleetBranch,
+  lsRemoteStatus,
+  classifyBranchPin,
+  pinCorrectedBranches,
+};

package/npm/fleet-build-data.js

@@ -120,6 +120,17 @@ function buildVmEnvelope(v, ctx) {
     // 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
+    // must render nothing at all. `reachable` is tri-state exactly like
+    // previewServing/previewIngress above: true = probe reached it, false =
+    // confirmed down, null = unknown (editor just booted, or the probe went
+    // stale). Never conflate "down" with "unknown" — only a confirmed false
+    // raises the amber reason. Gated on `reachable` like providerAuth: an
+    // unreachable VM's last-known datastore verdict is stale, and it has louder
+    // problems to report.
+    datastore: (v.reachable && v.datastore) || 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
@@ -177,7 +188,7 @@ const REQUIRED_CARD_FIELDS = [
   'degradedReasons', 'setupSteps', 'attentionReasons',
   'isHead', 'headHolderUnreachable', 'queuePos', 'queueLen',
   'job', 'config', 'project', 'variant', 'cardIdentity', 'brokerHistory',
-  'brokerDeath', 'providerAuth', 'previewMisconfigured', 'effects', 'currentProvider',
+  'brokerDeath', 'providerAuth', 'previewMisconfigured', 'datastore', 'effects', 'currentProvider',
   'readiness', 'backendHealth', 'vmAccess',
   'startedAt', 'featureStartedAt', 'attention', 'envOverride',
 ];

package/npm/fleet-cleanup.js

@@ -618,20 +618,37 @@ function reconcileRosteredVm({ exists, hasSession, hasPendingAdd, streak, resetH
 // 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.
+//
+// The exhausted branch records a TERMINAL DISPOSITION, not just a flag. The flag
+// alone was write-only: nothing destroys the instance and the only code that
+// clears the flag is a *subsequent* recovery attempt, which by definition never
+// comes once the budget is spent. VM-10 therefore ran empty and unrostered for a
+// full day on 2026-08-29, billing, while the dashboard rendered a generic
+// needs-manual-recovery card and clearing it needed hand-edited JSON.
+// `instancePresumedRunning` says the GCE instance is believed to still exist —
+// PRESUMED, because this ladder step never probes GCP; `exhaustedOrphanDisposition`
+// is what reconciles the presumption against reality. `exhaustedAt` anchors the
+// accrued-cost clock the card renders. `addVm` is still never called: that is the
+// safety property that stops a wedged VM looping cloud:up forever.
 function continueBootstrapRecovery(
   n,
   meta,
   cfg,
-  { state, addVm, log = console.log, err = console.error } = {},
+  { state, addVm, log = console.log, err = console.error, now = Date.now } = {},
 ) {
   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`,
+      `startup-reap: VM-${n} exceeded ${max} bootstrap-recovery attempts — instance presumed still running, leaving sidecar for manual action`,
     );
-    state.orphans[n] = { reason: "bootstrap-recovery-exhausted", attempts: attempt - 1 };
+    state.orphans[n] = {
+      reason: "bootstrap-recovery-exhausted",
+      attempts: attempt - 1,
+      instancePresumedRunning: true,
+      exhaustedAt: now(),
+    };
     return;
   }
   log(
@@ -643,6 +660,68 @@ function continueBootstrapRecovery(
   addVm(n, cfg, { recovering: true, recoverAttempt: attempt });
 }
 
+// The exit `continueBootstrapRecovery`'s exhausted flag never had. That flag is
+// written once and, until this verdict existed, could only be cleared by a
+// subsequent recovery attempt the spent budget guarantees will never run — so it
+// outlived the instance it described and had to be removed by hand-editing
+// `.codeyam/logs/dashboard-state.json`. This reconciles the flag's PRESUMPTION
+// (`instancePresumedRunning`) against two live facts the sweep supplies:
+//
+//   instanceExists  true  ⇒ the presumption holds, the box is still billing
+//                   false ⇒ the instance is gone (destroyed out-of-band) → 'clear',
+//                            so the card self-heals with no operator action
+//                   null  ⇒ the describe probe was INCONCLUSIVE. Never act on
+//                            absence of evidence — same discipline reapVerdict
+//                            applies to its own `exists === null`.
+//   rostered        false ⇒ flagged, billing, and in nobody's roster: invisible to
+//                            every roster-driven tool yet costing money → 'cost',
+//                            the distinct ownerless surface, NOT a generic
+//                            needs-manual-recovery card.
+//                   true  ⇒ still owned, so it is recoverable → 'keep'.
+//                   null  ⇒ roster unknown; keep rather than raise a cost alarm
+//                            that may be false (positive-signal-only, mirroring
+//                            how projectWired/agentReady downgrade).
+//
+// Deliberately NOT a destroy verdict. Destroying a VM is irreversible and a
+// half-provisioned box occasionally holds the clue that explains the failure, so
+// the terminal disposition is "surface it loudly and offer the button" — the
+// operator presses it.
+function exhaustedOrphanDisposition({ reason, instanceExists, rostered } = {}) {
+  if (reason !== 'bootstrap-recovery-exhausted') return 'leave';
+  if (instanceExists === null || instanceExists === undefined) return 'leave';
+  if (!instanceExists) return 'clear';
+  return rostered === false ? 'cost' : 'keep';
+}
+
+// Fold a 'cost'/'keep' verdict into the orphan entry the card renders. Split out
+// of the dashboard's poller because the stickiness rule below is the only real
+// logic in that branch, and inlined in server.js it was unreachable by any test:
+// the dashboard has top-level side effects on require, so its pollers can only be
+// covered by a source-scan wiring guard that cannot evaluate behavior.
+//
+// `ownerlessSince` dates the accrued cost from when the VM was FIRST confirmed
+// ownerless, not from the latest probe — re-stamping it every tick would peg the
+// card's elapsed time near zero forever and hide exactly the multi-day cost the
+// surface exists to reveal. It is dropped (not zeroed, not left stale) the moment
+// a VM stops being ownerless — an operator adopting it back into the roster flips
+// the verdict to 'keep', and a leftover `ownerlessSince` would let the cost card
+// resurrect itself with a fabricated start time if the VM ever went ownerless
+// again. `instanceConfirmedAt` records that the presumption was checked live.
+//
+// Returns a NEW entry; the caller decides where to store it. Both verdicts keep
+// the flag — the instance is real and only an operator may destroy it.
+function annotateOwnerlessCost(orphan, { verdict, now = Date.now() } = {}) {
+  const next = { ...orphan, instancePresumedRunning: true, instanceConfirmedAt: now };
+  if (verdict === 'cost') {
+    next.ownerlessCost = true;
+    next.ownerlessSince = (orphan && orphan.ownerlessSince) || now;
+    return next;
+  }
+  next.ownerlessCost = false;
+  delete next.ownerlessSince;
+  return next;
+}
+
 module.exports = {
   parsePendingJobFilename,
   persistPendingJob,
@@ -656,6 +735,8 @@ module.exports = {
   classifyLbReachableForReap,
   recoverBootstrapDecision,
   continueBootstrapRecovery,
+  exhaustedOrphanDisposition,
+  annotateOwnerlessCost,
   exitMarkerName,
   parseExitMarker,
   readExitMarker,

package/npm/fleet-datastore-health.js

@@ -0,0 +1,107 @@
+'use strict';
+
+// npm/fleet-datastore-health.js — pure classifier for the fleet dashboard's
+// "declared datastore unreachable" surface: is the datastore a VM's project
+// DECLARES actually answering?
+//
+// Nothing anywhere reported this, so a VM whose database was down read
+// perfectly green. On VM-12 (2026-08-24) the dashboard, the LB backend health,
+// the IAP edge and the editor's own server-identity all reported healthy while
+// every DB-backed route returned 500 — the only evidence was `ECONNREFUSED
+// 127.0.0.1:5432` buried in the container log, which nobody polls. The
+// 2026-08-14 occurrence on the same VM presented as previewServing=false with an
+// EMPTY degradedReasons list: the dashboard knew something was wrong and had
+// nothing to say about it. This module is the "something to say".
+//
+// The editor probes (it is the only party that knows what the project declares,
+// and the resolution already exists in-crate) and carries the result on the
+// existing session-info poll; this module decides, and server.js renders. Pure
+// like fleet-project-drift.js: all the decision logic lives here and unit-tests
+// without a VM, while server.js stays the thin I/O shell.
+//
+// A new `datastore-unreachable` code needs NO change to
+// fleet-setup-steps.js::classifyReasons — it routes unknown codes to
+// attentionReasons by design ("an unrecognized signal is surfaced loudly, never
+// silently hidden"), so this lands amber. It must NOT be added to SETUP_CODES: a
+// dead datastore is never expected first-run wiring.
+
+// Decide the datastore-health reasons for one VM.
+//
+//   declared   truthy when the project declares a datastore at all. A project
+//              with none (a Rust CLI, a static site) must never raise a reason.
+//   reachable  TRI-STATE, matching the editor's own discipline: true = the probe
+//              reached it, false = the probe failed, null/undefined = unknown
+//              (not probed yet, or the probe went stale). Only an explicit
+//              `false` raises a reason — collapsing unknown into false would
+//              light up every VM during the window between editor boot and the
+//              first probe, which is the failure mode that trains an operator to
+//              ignore the surface.
+//   target     credential-free rendering of where it lives ("127.0.0.1:5432/app",
+//              or a file path). Never the DSN — that carries credentials.
+//   shape      'file' (a database file on disk) or 'network' (a server on a
+//              socket). Published by the editor rather than inferred from `type`
+//              here, because "sqlite means file-shaped" is a per-stack fact this
+//              module would otherwise have to learn for every engine. It decides
+//              WHICH recovery applies at all: a down server gets started, a
+//              missing file gets restored.
+//   local      whether the datastore is something this VM is expected to host
+//              (loopback host, or a file database). Decides where the recovery
+//              points; a remote/managed datastore is still reported, but telling
+//              an operator to start it here would send them somewhere there is
+//              nothing to do.
+//   type       the declared engine ('postgresql' | 'sqlite' | 'mysql' | …), used
+//              only to name what is down.
+//   lastError  the probe's own failure string ("connection refused: …"), so the
+//              card says WHY rather than just that.
+//   n          the VM number, so a local recovery can name the VM to act on.
+//
+// Returns { unreachable, reasons }. `reasons` is [] whenever healthy, unknown, or
+// nothing is declared, so the caller spreads it unconditionally.
+function classifyDatastoreHealth({ declared, reachable, target, shape, local, type, lastError, n } = {}) {
+  // Explicit `false` only. `null`/`undefined` is unknown and never a fault —
+  // the same absence-of-evidence-is-not-a-fault rule the reachability and
+  // backend-health classifiers already follow.
+  const unreachable = !!declared && reachable === false;
+  if (!unreachable) return { unreachable: false, reasons: [] };
+  return {
+    unreachable: true,
+    reasons: [datastoreUnreachableReason({ type, target, shape, local, lastError, n })],
+  };
+}
+
+// Which recovery even applies, given what KIND of datastore this is and where
+// it lives. Its own function because "is it down?" and "what do you do about
+// it?" are separate decisions, and this is the one that grows a branch every
+// time a new datastore shape shows up.
+//
+// It follows the ingress-unwired precedent — the whole point of that reason was
+// carrying the exact fix instead of a bare complaint — but deliberately stops
+// short of naming a COMMAND. What an operator runs to start a datastore is a
+// property of the VM image, not of this module; naming one this module cannot
+// know is installed would be a confident lie on an amber card. What IS knowable,
+// and what actually unblocks someone, is which recovery applies and where to act.
+//
+// The `file` branch is not cosmetic: a file database has no server to start, so
+// routing it through the local branch would print the nonsensical "start it".
+function recoveryClause({ shape, local, n } = {}) {
+  if (shape === 'file') {
+    return 'Recover: this is a file database and the file is missing — restore or recreate it on the VM.';
+  }
+  if (local) {
+    return `Recover: start it on VM-${n} — it is declared local, so nothing outside the VM can be at fault.`;
+  }
+  return 'Recover: this is a remote/managed datastore — check the datastore service and the VM\'s network path. There is nothing local to start.';
+}
+
+// The single source for the `datastore-unreachable` reason string, mirroring
+// fleet-public-url.js::ingressUnwiredReason. Named and exported so the card
+// reason and any future log line cannot drift apart — the drift that a
+// template literal inlined at its one call site invites the moment a second
+// caller appears.
+function datastoreUnreachableReason({ type, target, shape, local, lastError, n } = {}) {
+  const what = `${type || 'declared'} datastore${target ? ` at ${target}` : ''}`;
+  const why = lastError ? ` (${lastError})` : '';
+  return `datastore-unreachable: the ${what} is not answering${why}. ${recoveryClause({ shape, local, n })}`;
+}
+
+module.exports = { classifyDatastoreHealth, recoveryClause, datastoreUnreachableReason };

package/npm/fleet-public-url.js

@@ -302,10 +302,32 @@ function ingressUnwiredReason({ url, domain, slug, n } = {}) {
  *  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. */
+ *  is satisfied.
+ *
+ *  FOURTH CASE — `routed === 'unrouted'` BYPASSES both `reachable` and the
+ *  `rewirable` backend test above, and that bypass is the whole point. A VM the
+ *  url-map carries no host rule for has no route from its public hostname to
+ *  anything, so it is unreachable BY CONSTRUCTION — gating its self-heal on
+ *  `reachable` gates it on the absence of the very symptom it exists to repair,
+ *  and it can therefore never fire. Observed 2026-09-08 on 3 of 3 freshly-added
+ *  self-host VMs: NEGs created, backend services created, NEGs ATTACHED, and no
+ *  host rule — the add's wiring tail died between the NEG attach and
+ *  `reconcile_host_rule_once`. The backend test misses it for an independent
+ *  reason: the backends WERE attached, so this reads as a genuinely-converging
+ *  'unhealthy' that the gate deliberately excludes. Both exclusions are correct
+ *  for a VM that answers and is merely mis-routed, and both are exactly inverted
+ *  for a VM with no route at all — hence a distinct entry condition rather than
+ *  a relaxation of the existing one. Do NOT "restore" the `reachable`
+ *  precondition on this branch as an obvious safety check; it is what made three
+ *  plainly-broken VMs invisible to the automation for a day.
+ *  'unknown' (the url-map read errored) is NOT 'unrouted' — absence of evidence
+ *  never authorizes a re-wire, matching classifyBackendAttachment's error case.
+ *  The add's own wiring tail is still excluded here by `inFlight`: a VM mid-
+ *  wiring is unrouted-so-far, not broken. */
 function shouldAutoRewireIngress({
   verdict,
   reachable,
+  routed,
   backendEditorHealth,
   backendEditorBackendless,
   inFlight,
@@ -314,21 +336,67 @@ function shouldAutoRewireIngress({
   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;
+  // An unrouted VM skips the reachability + backend-health tests below (see the
+  // FOURTH CASE note above), but never the in-flight and debounce guards — those
+  // are what keep one re-wire per VM per propagation window.
+  const unrouted = routed === 'unrouted';
+  if (!unrouted) {
+    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 whether the shared fleet url-map routes `host` at all — the input
+ *  `shouldAutoRewireIngress`'s unrouted branch turns on, and a signal no backend
+ *  probe can give. `backendEditorHealth` describes the backend SERVICE; none of
+ *  its four values can express "nothing routes here", which is why all three of
+ *  the 2026-09-08 stranded VMs classified as a converging 'unhealthy' while
+ *  carrying no host rule at all. Reads:
+ *
+ *    'routed'   — `host` appears verbatim among the url-map's host rules.
+ *    'unrouted' — the read SUCCEEDED, listed at least one host rule, and `host`
+ *                 is not among them. This is the only reading that authorizes a
+ *                 re-wire, and it requires positive evidence of a populated map.
+ *    'unknown'  — the read errored, produced nothing, or no host was asked for.
+ *
+ *  EMPTY OUTPUT IS 'unknown', NOT 'unrouted', and the distinction is load-
+ *  bearing. A url-map that lists zero host rules is indistinguishable from a
+ *  read that silently returned nothing, and reading it as 'unrouted' would
+ *  authorize a simultaneous re-wire for EVERY VM in the fleet off a single
+ *  unreliable read — the re-wire storm classifyBackendAttachment's error case
+ *  exists to prevent, at fleet scale. Absence of evidence never manufactures a
+ *  fault.
+ *
+ *  Matching is by exact token, never substring: gcloud flattens
+ *  `value(hostRules.hosts)` with whitespace and `;` separators, and a substring
+ *  test would read `vm-2.editor.<domain>` as routed on the strength of an
+ *  unrelated `staging.vm-2.editor.<domain>` rule.
+ *
+ *  Takes the raw (err, stdout) pair rather than a VM number so it stays PURE and
+ *  needs no domain/slug derivation — the same I/O-edge / pure-half split
+ *  classifyBackendAttachment follows. The caller derives `host` from
+ *  google-ingress's `urlMapHostRules` / vmUrls and does the gcloud read. */
+function classifyUrlMapRouting(err, stdout, host) {
+  if (err) return 'unknown';
+  if (!host) return 'unknown';
+  const hosts = String(stdout == null ? '' : stdout)
+    .split(/[\s;,]+/)
+    .filter(Boolean);
+  if (hosts.length === 0) return 'unknown';
+  return hosts.includes(String(host)) ? 'routed' : 'unrouted';
+}
+
 /** 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
@@ -390,5 +458,6 @@ module.exports = {
   ingressUnwiredReason,
   shouldAutoRewireIngress,
   classifyBackendAttachment,
+  classifyUrlMapRouting,
   classifyUrlWiringState,
 };