@codeyam-editor/codeyam-editor 0.1.10 → 0.1.11-staging.g493e6ea

package/npm/cloud.js

@@ -115,6 +115,9 @@ const { addToRoster, readRoster } = require("./fleet-roster");
 // container) apart from a real `docker compose up -d` failure, so the abort path
 // can converge instead of escalating to instance deletion.
 const { classifyComposeUpFailure } = require("./compose-conflict");
+// The two streamed bootstrap scripts, named once for this file's STREAMED_SCRIPTS
+// and for the advance's provisioning pre-flight, which checks the same set.
+const { BOOTSTRAP_SCRIPT, PROJECT_BOOTSTRAP_SCRIPT } = require("./provisioning-contract");
 
 // =============================================================================
 // Pure helpers — every export here is unit-tested in cloud.test.js without
@@ -1540,6 +1543,7 @@ async function waitForIapReady(cfg) {
   const deadline = Date.now() + 180_000;
   let attempts = 0;
   let lastErr = "";
+  const probeStderrs = [];
   while (Date.now() < deadline) {
     attempts++;
     const probe = runGcloud(
@@ -1550,17 +1554,42 @@ async function waitForIapReady(cfg) {
       console.error(`  ✓ IAP ready (${attempts} ${attempts === 1 ? "probe" : "probes"})`);
       return;
     }
-    lastErr = String(probe.stderr || "").trim().split("\n").slice(-1)[0] || "";
+    const stderr = String(probe.stderr || "").trim();
+    probeStderrs.push(stderr);
+    lastErr = stderr.split("\n").slice(-1)[0] || "";
     // Exponential-ish backoff: 2s, 3s, 5s, 8s, then cap at 8s.
     const delay = Math.min(2000 * Math.pow(1.5, attempts - 1), 8000);
     await new Promise((r) => setTimeout(r, delay));
   }
+  const cause = iapProbeCause(probeStderrs);
   throw new Error(
     `IAP did not become ready for ${cfg.instanceName} within 180s ` +
-      `(${attempts} probes; last error: ${lastErr || "unknown"})`,
+      `(${attempts} probes; ${cause ? `likely cause: ${cause}; ` : ""}` +
+      `last error: ${lastErr || "unknown"})`,
   );
 }
 
+/** Name the likely cause behind a run of failed IAP SSH probes. The last stderr
+ *  line alone is almost always `ssh exited with return code [255]`, which
+ *  collapses three different waits — each with its own expected duration — into
+ *  one unactionable string. The full stderr of each probe still distinguishes
+ *  them. Scans newest-first so the label describes where the wait ENDED (IAP lag
+ *  often gives way to key propagation on a fresh box). Returns null when no
+ *  signature matches; the raw last line is kept beside it either way. */
+function iapProbeCause(probeStderrs) {
+  const signatures = [
+    [/4047|Failed to lookup instance/i, "IAP has not registered the instance yet"],
+    [/Permission denied \(publickey/i, "OS Login SSH key not propagated yet"],
+    [/Connection (refused|closed|reset)/i, "sshd on the instance not accepting connections yet"],
+  ];
+  for (const text of [...(probeStderrs || [])].reverse()) {
+    for (const [re, label] of signatures) {
+      if (re.test(text)) return label;
+    }
+  }
+  return null;
+}
+
 /** Read `process.env[FORWARD_ENV_KEYS_ENV]` (comma-separated key list set by
  *  the fleet dashboard) and return the subset of `process.env` that should
  *  ride along into the VM's project-bootstrap shell. Whitelisted to the
@@ -2216,6 +2245,20 @@ function buildReconcileAdminCommand(repoName, value) {
   );
 }
 
+// Every library `scripts/gcp-project-bootstrap.sh` sources, keyed by the path it
+// sources it AS — i.e. relative to the script's own directory, which on the VM is
+// `$HOME`. A streamed script is a SINGLE FILE, so each of these must be shipped
+// beside it or the script dies at its source line and cloud:up tears the
+// freshly-created VM back down. Adding a `source` line to that script without
+// adding it here has now broken every add on the fleet twice (`lib/npm-pin.sh`
+// 2026-09-04, `lib/render-cloud-compose.sh` 2026-09-18), so this list is the one
+// place to register it: STREAMED_SCRIPTS derives its library entries from this
+// constant rather than repeating them, and a unit test reads the shipped script
+// and fails on any source line missing from it. Keep it a ONE-LINE array literal:
+// the advance's provisioning pre-flight reads it out of a branch's cloud.js TEXT
+// (provisioning-contract.js → parseProjectBootstrapLibs).
+const PROJECT_BOOTSTRAP_LIBS = ["lib/npm-pin.sh", "lib/render-cloud-compose.sh"];
+
 async function ensureProjectBootstrapped(cfg, { sleepFn } = {}) {
   const repoName = resolveProject(cfg).name;
   console.error(`Checking project bootstrap state for ${repoName}...`);
@@ -2245,13 +2288,16 @@ async function ensureProjectBootstrapped(cfg, { sleepFn } = {}) {
   console.error(`  streaming scripts/gcp-project-bootstrap.sh to VM for ${cfg.repo}...`);
   const scriptPath = path.join(rootDir, "scripts", "gcp-project-bootstrap.sh");
   const scriptBody = readStreamedScript(scriptPath, cfg);
-  // gcp-project-bootstrap.sh sources lib/npm-pin.sh relative to its own
-  // directory. Read it through readStreamedScript too, so the library is subject
-  // to the same drift guard as the script that sources it — streaming a reviewed
-  // remote script beside a stale on-disk library would defeat the guard.
-  const bootstrapLibs = {
-    "lib/npm-pin.sh": readStreamedScript(path.join(rootDir, "scripts", "lib", "npm-pin.sh"), cfg),
-  };
+  // gcp-project-bootstrap.sh sources its libraries relative to its own
+  // directory. Read them through readStreamedScript too, so each library is
+  // subject to the same drift guard as the script that sources it — streaming a
+  // reviewed remote script beside a stale on-disk library would defeat the guard.
+  const bootstrapLibs = Object.fromEntries(
+    PROJECT_BOOTSTRAP_LIBS.map((rel) => [
+      rel,
+      readStreamedScript(path.join(rootDir, "scripts", ...rel.split("/")), cfg),
+    ]),
+  );
   const scriptArgs = clientProjectBootstrapArgs(cfg);
   // Git identity, forwarded launch-form keys, fleet-domain ingress and the admin
   // toggle — see projectBootstrapEnv for what each key is for and when it is
@@ -3635,14 +3681,18 @@ function promptForInstanceName(expected) {
 }
 
 // Every file streamed to a VM, and therefore every file the drift guard must
-// compare against the reviewed remote tip. `scripts/lib/npm-pin.sh` is here
-// because gcp-project-bootstrap.sh SOURCES it: a library that reaches the VM is
-// as much streamed content as the script that sources it, and leaving it out
-// meant the drift guard silently vouched for only half of what was shipped.
+// compare against the reviewed remote tip. The libraries are here because
+// gcp-project-bootstrap.sh SOURCES them: a library that reaches the VM is as
+// much streamed content as the script that sources it, and leaving one out meant
+// the drift guard silently vouched for only half of what was shipped. They are
+// DERIVED from PROJECT_BOOTSTRAP_LIBS rather than listed again — when the two
+// were maintained separately, a library added to neither took the whole fleet's
+// provisioning down, and a library added to only one would have been shipped
+// unvouched-for.
 const STREAMED_SCRIPTS = [
-  "scripts/gcp-bootstrap.sh",
-  "scripts/gcp-project-bootstrap.sh",
-  "scripts/lib/npm-pin.sh",
+  BOOTSTRAP_SCRIPT,
+  PROJECT_BOOTSTRAP_SCRIPT,
+  ...PROJECT_BOOTSTRAP_LIBS.map((rel) => `scripts/${rel}`),
 ];
 
 /** The configured editor branch to compare/stream streamed scripts against.
@@ -5647,6 +5697,7 @@ async function cloudMain() {
 module.exports = {
   // pure helpers
   isSpawnTimeout,
+  iapProbeCause,
   gcloudCallTimeoutMs,
   provisionFailureMessage,
   GCLOUD_PROVISION_TIMEOUT_MS,
@@ -5760,6 +5811,7 @@ module.exports = {
   gatherScriptDriftFacts,
   readStreamedScript,
   STREAMED_SCRIPTS,
+  PROJECT_BOOTSTRAP_LIBS,
   // ingress wiring (pure decision + spawn wrappers)
   envPosInt,
   ingressWiringPlan,

package/npm/fleet-add-failure.js

@@ -47,6 +47,13 @@ const { parseRosterMarkers } = require('./fleet-early-roster');
 //      `ensureBootstrapped` skips on the present image, and
 //      `ensureProjectBootstrapped` re-attaches to the in-flight install rather
 //      than starting a second `npm install` over the first.
+//      `iap-not-ready` is the same ground in its strongest form: the throw comes
+//      from waitForIapReady, which ensureInstance calls BEFORE ensureBootstrapped,
+//      ensureProjectBootstrapped or ensureEditorContainerUp — so the provable state
+//      is "an instance exists and nothing else has run". The retry reuses that
+//      live instance and every later step runs for the first time. (VM-4,
+//      2026-09-17: destroy + an identical re-add succeeded in 10 minutes; the
+//      failure was a transient IAP/SSH race, not a broken box.)
 //
 // Ground 2 is deliberately narrow — it is NOT "the VM probably still works".
 // `container-stuck` and `incomplete-workspace` also leave a live VM, but their
@@ -56,6 +63,7 @@ const ADD_FAILURE_RETRYABLE = new Set([
   'instance-vanished',
   'capacity-stockout',
   'project-bootstrap-timeout',
+  'iap-not-ready',
 ]);
 
 // Collect the `    - <path>` bullets the drift guard prints AFTER the "following
@@ -350,6 +358,92 @@ function wedgedInsertRecovery({ code, instance } = {}) {
   );
 }
 
+// Facts for the iap-not-ready arm: waitForIapReady (npm/cloud.js) threw its
+// readiness timeout. Returns { timedOut, instance, budgetSecs, cause } — `cause` is
+// the label waitForIapReady derived from its probe stderr (null when none of its
+// signatures matched, or on a transcript from before the label existed), so the
+// recovery copy can name WHICH wait was blown instead of only `return code [255]`.
+//
+// The signature is emitted from exactly one place, and that place runs before any
+// bootstrap work, which is what lets this arm assert the instance is bare.
+const IAP_NOT_READY = /IAP did not become ready for (\S+) within (\d+)s/;
+
+function iapNotReadyFacts(logTail) {
+  const m = String(logTail || '').match(IAP_NOT_READY);
+  if (!m) return { timedOut: false, instance: null, budgetSecs: null, cause: null };
+  const cause = (String(logTail).match(/likely cause: ([^;)]+)/) || [])[1] || null;
+  return { timedOut: true, instance: m[1], budgetSecs: Number(m[2]), cause: cause && cause.trim() };
+}
+
+// Operator-facing recovery copy for the iap-not-ready arm. It states what the
+// generic arm cannot: the instance EXISTS and is BARE. "A partial instance may
+// exist" is what steered VM-4's operator toward destroy + re-add (15-25 minutes)
+// when Retry resumes on the same box in seconds — and it left nothing on the card
+// saying a RUNNING, billing instance was sitting there.
+function iapNotReadyRecovery({ instance, budgetSecs, cause } = {}) {
+  const named = instance || 'The instance';
+  const within = budgetSecs ? ` within ${budgetSecs}s` : '';
+  const why = cause ? ` (likely cause: ${cause})` : '';
+  return (
+    `${named} was created and is RUNNING, but SSH over IAP did not answer${within}${why}. This is usually a transient ` +
+    'control-plane race. Nothing was installed on it — the wait runs before any bootstrap step — so it is a bare box and ' +
+    'there is nothing partial to reconcile. Retry add resumes on this same instance rather than creating a second one. ' +
+    'Until you retry or destroy it, the instance keeps running and billing.'
+  );
+}
+
+// Facts for the streamed-library-missing arm: a streamed bootstrap script sourced
+// a `$HOME`-rooted `lib/…` file that was never shipped to the VM, and bash
+// reported `<script>: line N: <path>: No such file or directory`. This took ALL
+// fleet provisioning down twice (lib/npm-pin.sh 2026-09-04, lib/render-cloud-
+// compose.sh 2026-09-18). Returns { missing, script, library } — `script` is the
+// basename of the aborting script, `library` the `lib/…` path relative to $HOME,
+// which is how PROJECT_BOOTSTRAP_LIBS (npm/cloud.js) names its entries.
+const STREAMED_LIBRARY_MISSING = /(\S+): line \d+: \/(?:home\/[^/\s]+|root)\/(lib\/[^\s:]+): No such file or directory/;
+
+function streamedLibraryMissingFacts(logTail) {
+  const m = String(logTail || '').match(STREAMED_LIBRARY_MISSING);
+  if (!m) return { missing: false, script: null, library: null };
+  return { missing: true, script: m[1].split('/').pop(), library: m[2] };
+}
+
+// Did cloud:up report that it deleted the instance it created this run? The abort
+// path (npm/cloud.js) prints the teardown marker BEFORE it issues the delete, and
+// prints a `during abort teardown` warning when that delete fails — so the marker
+// alone is a claim of intent, and only the marker WITHOUT the warning is evidence
+// that no orphan was left behind.
+function cleanTeardownReported(logTail) {
+  const log = String(logTail || '');
+  return /tearing down the VM cloud:up created this run \(no orphan left behind\)/.test(log)
+    && !/during abort teardown/.test(log);
+}
+
+// Operator-facing recovery copy for the streamed-library-missing arm. It names
+// what to fix — register the library so it is streamed — and, when the transcript
+// proves a clean teardown, says there is no orphan to hunt for. Every add on this
+// branch fails identically until the registry is fixed, so it never offers Retry.
+function streamedLibraryMissingRecovery({ script, library, cleanTeardown } = {}) {
+  const lib = library || 'a lib/ file';
+  const from = script ? ` sourced by ${script}` : '';
+  const orphan = cleanTeardown
+    ? 'cloud:up already deleted the VM it created, so there is nothing to reconcile or destroy.'
+    : 'The transcript does not confirm the VM was deleted — check whether a partial instance exists before re-adding.';
+  return (
+    `${lib}${from} was never shipped to the VM, so the bootstrap aborted. Add it to PROJECT_BOOTSTRAP_LIBS in npm/cloud.js, ` +
+    `push, and re-add — every add from this branch fails the same way until then. ${orphan}`
+  );
+}
+
+// Operator-facing recovery copy for the generic cloud-up-failed arm. "A partial
+// instance may exist" is only true when the transcript does not show cloud:up
+// deleting what it created; saying it regardless sends the operator hunting for
+// an orphan that is not there.
+function cloudUpFailedRecovery({ cleanTeardown } = {}) {
+  return cleanTeardown
+    ? 'cloud:up failed during provisioning and deleted the VM it created, so nothing was left behind. Read the transcript for the cause before re-adding.'
+    : 'cloud:up failed during provisioning, so a partial instance may exist. Reconcile or destroy this VM before re-adding.';
+}
+
 // Build a verdict, stamping `retryable` from the single-source-of-truth Set so it
 // can never drift from the category.
 function buildFailureVerdict(category, headline, recovery, extra) {
@@ -392,7 +486,12 @@ function buildFailureVerdict(category, headline, recovery, extra) {
 // instance. `wedged-insert` (arm 8) is the third: it sits directly above the
 // generic arm so a create GCE accepted-and-abandoned cannot report as an ordinary
 // provisioning failure whose advice is to destroy the box — a destroy that, on a
-// wedged slot, queues behind the wedge instead of clearing it.
+// wedged slot, queues behind the wedge instead of clearing it. `iap-not-ready`
+// (arm 9) is the fourth: it keeps a bare, retry-safe instance from reporting as a
+// possibly-partial one whose only recovery is destroy + re-add.
+// `streamed-library-missing` (arm 10) is the fifth: it names the unshipped library
+// that broke every add, instead of advising a hunt for an orphan cloud:up already
+// deleted.
 function classifyAddFailure({ logTail, exitCode, instanceAlive, containerHealthy, wiringDeadlineBlown, wiringInFlight } = {}) {
   const log = String(logTail || '');
 
@@ -554,28 +653,64 @@ function classifyAddFailure({ logTail, exitCode, instanceAlive, containerHealthy
       wedgedInsertRecovery(wedgedInsert));
   }
 
-  // 9. cloud-up-failed — a generic cloud:up failure, reached ONLY when the drift /
-  //    vanished / stuck / stockout / missing-ref / wedged-insert signatures above
-  //    did not match. A partial instance may exist, so not retryable.
+  // 9. iap-not-ready — the instance reached RUNNING but IAP-tunneled SSH never
+  //    answered inside waitForIapReady's budget. That wait is called from
+  //    ensureInstance before any bootstrap work, so the box exists and is bare.
+  //    Retryable on the re-entrancy ground (see ADD_FAILURE_RETRYABLE); the budget
+  //    was already raised 60s → 180s for this race, and VM-4 still blew it, so the
+  //    answer is a cheap retry rather than a longer wait for every dead add.
+  //
+  //    Tested BEFORE cloud-up-failed for the reason arm 6 documents: the provision
+  //    shell echoes cloud:up's tail into every transcript, so matching the generic
+  //    line first refuses the safe retry — exactly the VM-4 failure.
+  const iapNotReady = iapNotReadyFacts(log);
+  if (iapNotReady.timedOut) {
+    return buildFailureVerdict('iap-not-ready', 'SSH never became reachable',
+      iapNotReadyRecovery(iapNotReady));
+  }
+
+  // 10. streamed-library-missing — a streamed bootstrap script sourced a `lib/…`
+  //    file that was never shipped to the VM. The failure that has taken ALL fleet
+  //    provisioning down twice (2026-09-04, 2026-09-18); both times it fell through
+  //    to cloud-up-failed, whose recovery told six operators to hunt for a partial
+  //    instance cloud:up had already deleted, and said nothing about the cause.
+  //
+  //    NOT retryable: re-issuing the same add streams the same scripts without the
+  //    library and fails identically — the missing-branch-ref reasoning. The fix is
+  //    a code change (register the library), which is what the recovery names.
+  //
+  //    Tested BEFORE cloud-up-failed for the reason arm 6 documents: the provision
+  //    shell echoes cloud:up's tail into every transcript, so matching the generic
+  //    line first is precisely the bug being fixed.
+  const missingLib = streamedLibraryMissingFacts(log);
+  if (missingLib.missing) {
+    return buildFailureVerdict('streamed-library-missing', `Bootstrap library never shipped: ${missingLib.library}`,
+      streamedLibraryMissingRecovery({ ...missingLib, cleanTeardown: cleanTeardownReported(log) }));
+  }
+
+  // 11. cloud-up-failed — a generic cloud:up failure, reached ONLY when the drift /
+  //    vanished / stuck / stockout / missing-ref / wedged-insert / iap-not-ready /
+  //    streamed-library signatures above did not match. Not retryable. Whether a
+  //    partial instance may exist is read off the transcript's teardown evidence.
   if (/cloud:up FAILED \(exit/i.test(log)) {
     return buildFailureVerdict('cloud-up-failed', 'Provisioning failed',
-      'cloud:up failed during provisioning, so a partial instance may exist. Reconcile or destroy this VM before re-adding.');
+      cloudUpFailedRecovery({ cleanTeardown: cleanTeardownReported(log) }));
   }
 
-  // 10. interrupted — a signal kill (OOM 137, SIGTERM 143, …) or an explicit
+  // 12. interrupted — a signal kill (OOM 137, SIGTERM 143, …) or an explicit
   //    Killed / out-of-memory marker. The real VM state is unknown. Not retryable.
   if (fc.isSignalKillExit(Number(exitCode)) || /\bKilled\b/.test(log) || /Out of memory/i.test(log)) {
     return buildFailureVerdict('interrupted', 'Provisioning interrupted',
       'The provision was interrupted (killed or out of memory), so the VM state is unknown. Reconcile or destroy this VM before re-adding.');
   }
 
-  // 11. The post-add IAP read-back verdicts. Unlike every signature above, this one
+  // 13. The post-add IAP read-back verdicts. Unlike every signature above, this one
   //    is not produced by the provision transcript at all — it is the BLOCKED
   //    reason iapReadbackOutcome hands to annotateAddFailure, which is what
   //    stops a read-back failure from being the one add failure that reaches the
   //    card with no category at all (and so no differentiated headline, no
   //    recovery, no guarded Retry, and no chance for holdConvergingBadge to hold it
-  //    calm). Tested AFTER all eight hard-failure signatures so a proven failure
+  //    calm). Tested AFTER every hard-failure signature so a proven failure
   //    always wins if both texts are ever present, and BEFORE converging/verifying
   //    because it is strictly more specific than either.
   if (/IAP policy authorizes no human/i.test(log)) {
@@ -599,7 +734,7 @@ function classifyAddFailure({ logTail, exitCode, instanceAlive, containerHealthy
       `The VM is up but its IAP policy authorizes no human, so the public URL returns "Error code 51" for everyone. Its background wiring is no longer running, so this will not resolve on its own — grant access to fix it. Do NOT destroy or re-add this VM.${remedy ? `\n\n${remedy}` : ''}`);
   }
 
-  // 12. converging — the add reached the early-roster marker (`CY_ROSTER`): the
+  // 14. converging — the add reached the early-roster marker (`CY_ROSTER`): the
   //    container gate passed, the instance is real, and the VM is rostered, yet it
   //    exited non-zero WITHOUT matching any specific hard-failure signature above.
   //    By construction of the provision script, every genuine hard failure (drift,
@@ -617,7 +752,7 @@ function classifyAddFailure({ logTail, exitCode, instanceAlive, containerHealthy
       'The container is up and the VM is rostered; the LB ingress is still wiring in the background. This resolves on its own once the editor is reachable over the LB — no action needed unless it persists past the wiring deadline.');
   }
 
-  // 13. The residue: no failure signature above matched. The polarity here is
+  // 15. The residue: no failure signature above matched. The polarity here is
   //    INVERTED from the original design. It used to read "no recognized success
   //    signature ⇒ failed", which made red the DEFAULT for "we don't know" — so a
   //    VM whose container was Up and whose editor answered /api/health 200 got a
@@ -739,4 +874,14 @@ function wedgedRetryMessage(n) {
   );
 }
 
-module.exports = { classifyAddFailure, extractDriftFiles, lastNonEmptyLines, canRetryAdd, transcriptRostered, holdConvergingBadge, addFailureCorroborated, containerHealthWitness, stockoutCapacityPhrase, missingBranchRefFacts, missingBranchRefRecovery, deadRefRetryMessage, wedgedInsertFacts, wedgedInsertRecovery, wedgedRetryMessage, CALM_ADD_CATEGORIES, ADD_FAILURE_RETRYABLE };
+// Refusal copy for a one-click "Retry add" after a streamed-library abort,
+// extracted for the same reason wedgedRetryMessage was. The retry is refused
+// because every add from this branch fails identically until the library is
+// registered, and the generic refusal would again send the operator after an
+// orphan cloud:up already deleted. Repeats the classified recovery, which names
+// the fix and says whether anything was left behind. Pure; no I/O.
+function streamedLibraryRetryMessage(n, recovery) {
+  return `VM-${n} cannot be retried until the code is fixed: ${recovery || 'a streamed bootstrap library was never shipped to the VM.'}`;
+}
+
+module.exports = { classifyAddFailure, extractDriftFiles, lastNonEmptyLines, canRetryAdd, transcriptRostered, holdConvergingBadge, addFailureCorroborated, containerHealthWitness, stockoutCapacityPhrase, missingBranchRefFacts, missingBranchRefRecovery, deadRefRetryMessage, wedgedInsertFacts, wedgedInsertRecovery, wedgedRetryMessage, iapNotReadyFacts, iapNotReadyRecovery, streamedLibraryMissingFacts, cleanTeardownReported, streamedLibraryMissingRecovery, cloudUpFailedRecovery, streamedLibraryRetryMessage, CALM_ADD_CATEGORIES, ADD_FAILURE_RETRYABLE };

package/npm/fleet-auth.js

@@ -133,18 +133,56 @@ function listAvailableAccounts(vms) {
 // 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.
+// state keyed by VM number (`state.vms`). A donor whose credential failed the
+// integrity probe (`providerAuth.credentialIntact === false`) is skipped as
+// though it were not authenticated — its credential cannot be copied, so the
+// sink would refuse it after an add had already committed to it. An unprobed
+// verdict (null/absent) is usable: a probe failure is not evidence. 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;
+    if (pa && pa.credentialIntact === false) continue;
     const got = pa && pa.state === 'authenticated' && pa.account && pa.account.email;
     if (got && String(got).toLowerCase() === want) return n;
   }
   return null;
 }
 
+// Split the reachable donor candidates into those whose credential can be
+// copied and those the integrity probe failed, so the add can drop the failed
+// ones BEFORE resolveCredsSource's first-donor fallback could pick one, and name
+// each dropped donor in the add log. Order is preserved; unprobed is usable.
+// Returns { usable: number[], skipped: number[] }. Pure.
+function partitionDonorsByIntegrity(reachableDonors, vms) {
+  const usable = [];
+  const skipped = [];
+  for (const n of reachableDonors || []) {
+    const pa = vms && vms[n] && vms[n].providerAuth;
+    if (pa && pa.credentialIntact === false) skipped.push(n);
+    else usable.push(n);
+  }
+  return { usable, skipped };
+}
+
+// Fold the dashboard's credential-integrity verdict into a VM's editor-reported
+// providerAuth record. The editor derives `state` from whether the access token
+// works NOW, so a credential with no refresh token still reads `authenticated`
+// (VM-11, 2026-09-17) — a VM that will strand at its next token expiry and that
+// no add can copy from. When the probe says the credential is incomplete, the
+// card must say what the remedy is: `needs-login`. `credentialIntact` rides on
+// the record either way (null = unprobed) so donor selection reads one place.
+// Returns null for a null auth (editor didn't answer). Pure.
+function applyCredentialIntegrity(auth, credentialIntact) {
+  if (!auth) return null;
+  const intact = credentialIntact === true || credentialIntact === false ? credentialIntact : null;
+  if (intact === false && auth.state === 'authenticated') {
+    return { ...auth, state: 'needs-login', credentialIntact: false };
+  }
+  return { ...auth, credentialIntact: intact };
+}
+
 // 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
@@ -178,6 +216,8 @@ module.exports = {
   deriveDefaultAuthAccount,
   listAvailableAccounts,
   selectDonorForAccount,
+  partitionDonorsByIntegrity,
+  applyCredentialIntegrity,
   isAccountEmail,
   resolveChosenAccount,
   isAuthStartable,

package/npm/fleet-reconcile.js

@@ -72,7 +72,21 @@ function strandedAdoptDecision({ stranded, streaks, threshold } = {}) {
 // only would be the opposite mistake: reasons like `claude auth copy failed on
 // VM-2 (…)` are already recorded in live snapshots and carry no prefix at all,
 // so both shapes have to match.
+//
+// FIRST MATCH WINS, so the anchored structured prefixes come before the loose
+// free-text patterns: a `binary-stale:` reason names a branch, and a branch
+// called `fix-login` must not route it to the auth witness.
+//
+// `binary-stale:` (gcp-bootstrap.sh's report_binary_staleness) describes the
+// binary installed AT ADD TIME. Its witness is that binary having since been
+// replaced: a deployment record installed after the add finished. Every path
+// that writes that record after provisioning — the operator refresh, and so any
+// fleet advance — refuses to install an artifact behind its branch tip, so a
+// later install is positive evidence the stale binary is gone. A record from
+// the provision itself predates `finishedAt` and proves nothing, and no record
+// at all is silence, which never clears a reason.
 const REASON_WITNESSES = [
+  { match: /^\s*binary-stale\b/i, witness: 'binaryReplaced' },
   { match: /^\s*claude-auth-not-seeded\b/i, witness: 'authed' },
   { match: /claude auth|claude\.json|login/i, witness: 'authed' },
   { match: /container|never came up|provisioning failed/i, witness: 'reachableServing' },
@@ -81,11 +95,21 @@ const REASON_WITNESSES = [
 // 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).
-function reasonClearedByHealth(reason, { reachableServing, authed }) {
+function reasonClearedByHealth(reason, witnesses) {
   const r = String(reason || '');
   const entry = REASON_WITNESSES.find((e) => e.match.test(r));
   if (!entry) return false;
-  return entry.witness === 'authed' ? !!authed : !!reachableServing;
+  return !!witnesses[entry.witness];
+}
+
+// True only when the VM's live deployment record was installed strictly after
+// the add job finished. Either timestamp missing or unparseable → false: an
+// unprovable replacement is not a replacement.
+function binaryReplacedAfter(installedAt, finishedAt) {
+  const installed = Date.parse(installedAt || '');
+  const finished = Date.parse(finishedAt || '');
+  if (Number.isNaN(installed) || Number.isNaN(finished)) return false;
+  return installed > finished;
 }
 
 // Given a terminal add-job badge and the VM's live health, return the corrected
@@ -94,8 +118,8 @@ function reasonClearedByHealth(reason, { reachableServing, authed }) {
 // `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 }
+//   job:    { state: 'done'|'error', degraded, degradedReasons, finishedAt }
+//   health: { reachable, editorHttpOk, providerAuthState, deploymentInstalledAt }
 //   → null | { state, degraded, degradedReasons, retiredReasons, transition }
 //
 // `retiredReasons` names the reasons this verdict just dropped. Without it a
@@ -108,6 +132,7 @@ function reconcileTerminalAddBadge({ job, health } = {}) {
   if (!job || !health) return null;
   const reachableServing = !!(health.reachable && health.editorHttpOk);
   const authed = health.providerAuthState === 'authenticated';
+  const binaryReplaced = binaryReplacedAfter(health.deploymentInstalledAt, job.finishedAt);
 
   // 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
@@ -133,7 +158,8 @@ function reconcileTerminalAddBadge({ job, health } = {}) {
     const remaining = [];
     const retired = [];
     for (const reason of reasons) {
-      const bucket = reasonClearedByHealth(reason, { reachableServing, authed }) ? retired : remaining;
+      const cleared = reasonClearedByHealth(reason, { reachableServing, authed, binaryReplaced });
+      const bucket = cleared ? retired : remaining;
       bucket.push(reason);
     }
     if (retired.length === 0) return null; // nothing cleared → no-op

package/npm/fleet-setup-steps.js

@@ -39,6 +39,31 @@ function parseDriftReason(reason) {
   return m ? { expected: m[1].trim(), running: m[2].trim() } : { expected: null, running: null };
 }
 
+// The Claude-auth reason shapes that classify as the calm `auth` setup step.
+// The structured `claude-auth-not-seeded` prefix is what every producer emits
+// now; the two anchored free-text shapes are what `buildCredsSteps`
+// (npm/launch-config.js) emitted before it carried the prefix, and they are
+// already persisted in live add-job snapshots, so they must keep classifying.
+//
+// NARROW AND ANCHORED, ON PURPOSE — do not "unify" these with the broad
+// `/claude auth|claude\.json|login/i` in npm/fleet-reconcile.js. Over-matching
+// there only retires a reason once a live witness proves the VM authenticated,
+// so a false positive costs nothing. Here it is inverted: over-matching routes a
+// genuine problem into the calm checklist and hides it.
+const AUTH_REASON_PATTERNS = [
+  /^claude-auth-not-seeded/,
+  /^claude auth copy failed\b/,
+  /^claude\.json copy failed\b/,
+];
+
+// True when a degraded reason means "this VM's only gap is Claude login". The
+// single match rule for the `auth` step — server.js's auto-kick and login
+// follow-up gates call this rather than hand-rolling their own prefix test.
+function isAuthReason(reason) {
+  const r = String(reason);
+  return AUTH_REASON_PATTERNS.some((re) => re.test(r));
+}
+
 // Partition degradedReasons into { setupSteps, attentionReasons }.
 //
 //   setupSteps        ordered [{ code, label, detail, action? }] — expected
@@ -54,7 +79,7 @@ function classifyReasons(degradedReasons = []) {
   const list = Array.isArray(degradedReasons) ? degradedReasons : [];
   for (const raw of list) {
     const reason = String(raw);
-    if (reason.startsWith('claude-auth-not-seeded')) {
+    if (isAuthReason(reason)) {
       setupSteps.push({ code: 'auth', label: 'Claude login', detail: reason });
     } else if (reason.startsWith('ingress-unwired')) {
       // System-handled: the dashboard reconcile wires the public URL
@@ -109,4 +134,4 @@ function onlySetupCode(degradedReasons = [], code) {
     && setupSteps.every((s) => s.code === code);
 }
 
-module.exports = { classifyReasons, hasOnlySetup, onlySetupCode, SETUP_CODES, SCAFFOLD_PROJECT_DIR };
+module.exports = { classifyReasons, isAuthReason, hasOnlySetup, onlySetupCode, SETUP_CODES, SCAFFOLD_PROJECT_DIR };

package/npm/fleet-vm-readiness.js

@@ -33,6 +33,11 @@
 //   'unreachable'  — the editor did not answer over the tunnel. Nothing
 //                    downstream (broker, LB health) is meaningful; the link is
 //                    gated exactly as today.
+//   'access-locked' — reachable, but the editor's /api/health reports
+//                    `accessModeUndeclared: true`: no access mode is declared on
+//                    its public bind, so it issues no session and serves only the
+//                    "configure an access mode" page (a 200). Remedy is a config
+//                    declaration — never a restart, rebuild, or re-wire.
 //   'half-wired'   — LB mode, the editor backend service is ABSENT (never
 //                    created). The permanent 503 case — the public URL will fail
 //                    until re-wired. The state that had NO signal before.
@@ -88,6 +93,7 @@
 const READINESS_STATES = [
   'provisioning',
   'unreachable',
+  'access-locked',
   'half-wired',
   'iap-access-missing',
   'preview-iap-access-missing',
@@ -176,6 +182,19 @@ function agentRosterReady(verdict) {
   return null;
 }
 
+// Read the access-mode lockout off a parsed /api/health body as a tri-state:
+//   true  — the editor reports it issues a session to no one (no access mode
+//           declared on a public bind). Feeds the 'access-locked' readiness.
+//   false — the editor reports it is NOT locked out.
+//   null  — no body (probe failed) or a body without a boolean field (a binary
+//           that predates it). Absence of evidence, never a verdict either way,
+//           so an older VM keeps today's card instead of reading as locked.
+function readAccessModeUndeclared(healthBody) {
+  if (!healthBody || typeof healthBody !== 'object') return null;
+  const flag = healthBody.accessModeUndeclared;
+  return typeof flag === 'boolean' ? flag : null;
+}
+
 // A VM mid-provision: an Add (incl. its recovering re-run) that is queued
 // (number reserved, cloud:up not started) or running. Its public URL has no
 // meaningful readiness yet, so this takes precedence over every other signal —
@@ -201,6 +220,13 @@ function deriveVmReadiness(v, ctx) {
   // 2. Editor unreachable over the tunnel: we polled nothing, so broker / LB
   //    health are unknowable. Link gated, exactly as the pre-readiness card did.
   if (!v || !v.reachable) return 'unreachable';
+  // 2b. Reachable, but the editor itself reports it serves no one: no access
+  //     mode is declared on its public bind, so `/` is the "configure an access
+  //     mode" page — a 200, which is why every HTTP check read it as healthy.
+  //     Ahead of the LB / broker / CLI checks because none of their remedies
+  //     help: only declaring a mode does. Only an EXPLICIT `true` fires; a
+  //     binary predating the field leaves it null and falls through.
+  if (v.accessModeUndeclared === true) return 'access-locked';
   // 3. LB mode only: the public URL's fate is the editor backend's LB health.
   //    Skipped entirely in legacy mode (no LB) or before the first probe lands
   //    (no backendHealth) — both fall through to the reachability/broker path.
@@ -275,4 +301,5 @@ module.exports = {
   isProvisioning,
   classifyAgentUsability,
   agentRosterReady,
+  readAccessModeUndeclared,
 };