@codeyam-editor/codeyam-editor 0.1.0-staging.g3858572 → 0.1.0-staging.g52ee0eb

package/npm/cloud.js

@@ -4202,6 +4202,75 @@ function releaseVmSlugOnDestroy(cfg) {
   return vmNumber;
 }
 
+/** Does `branch` still exist on `repo`? Answered with a single
+ *  `git ls-remote --heads` — about a second, and no cloud resource touched.
+ *
+ *  Tri-state on purpose, and the third state is the load-bearing one:
+ *    true   — the ref resolved.
+ *    false  — the remote answered and the ref is NOT there. Provably gone.
+ *    null   — we could not get an answer (no network, no credentials, git
+ *             missing, timeout). NOT evidence of a deleted branch.
+ *  Only `false` refuses an add. Collapsing `null` into `false` would turn every
+ *  transient GitHub blip into a fleet-wide add outage, which is a far worse
+ *  failure than the one this preflight exists to prevent — and the classifier
+ *  arm downstream still catches a genuinely dead ref, just later and dearer.
+ *
+ *  A private repo needs credentials, so the token is inlined into the URL the
+ *  same way clone_editor_repo does it on the VM side (x-access-token), and for
+ *  the same reason: the plain URL 401s. The token is confined to this argv and
+ *  never logged — the caller prints `repo` (the un-inlined form) instead. */
+function gitBranchRefExists({ repo, branch }) {
+  if (!repo || !branch) return null;
+  let url = repo;
+  const token = resolveGithubToken();
+  if (token && /^https:\/\/github\.com\//.test(repo)) {
+    url = repo.replace("https://", `https://x-access-token:${token}@`);
+  }
+  const res = spawnSync("git", ["ls-remote", "--heads", url, branch], {
+    encoding: "utf8",
+    timeout: 30000,
+  });
+  // A non-zero exit is an unreachable/unauthorized remote, not an absent branch:
+  // git exits 0 and prints nothing for "connected fine, no such head".
+  if (res.error || res.status !== 0) return null;
+  return String(res.stdout || "").trim().length > 0;
+}
+
+/** Refuse an add whose stored branch has been deleted from origin, BEFORE the
+ *  first gcloud call.
+ *
+ *  Without this the failure lands as late and as expensively as it possibly can:
+ *  on 2026-08-25 four fleet VMs each created a real GCE instance, booted it,
+ *  installed npm and cloned 13,226 files before `git fetch` inside the VM said
+ *  `fatal: couldn't find remote ref editor-improvements-75` — a branch pruned
+ *  from origin hours earlier when it merged. One `git ls-remote` establishes the
+ *  same fact in about a second, for free. This repo prunes branches on merge, so
+ *  ANY stored feature-branch name expires silently; that makes this a recurring
+ *  condition, not a one-off.
+ *
+ *  Placed beside checkScriptDrift and assertVariantProvisionable — the other
+ *  "fail loud before creating a GCE instance" guards — because it is only worth
+ *  anything ahead of ensureInstance. It cannot live in scripts/gcp-bootstrap.sh,
+ *  which already runs ON the provisioned box and never sees the client branch.
+ *
+ *  Throws with the field, the branch and the repo named. Never throws for a ref
+ *  it could not check (see gitBranchRefExists). */
+function assertBranchRefsExist(cfg, { refExists = gitBranchRefExists } = {}) {
+  // Lazy require: launch-config.js requires THIS module at load time, so a
+  // top-level require here would close the cycle. Same pattern as the
+  // isPlaceholderProject call sites above.
+  const lc = require("./launch-config");
+  const { editorRepo, editorBranch } = resolveEditorConfig(cfg);
+  const targets = lc.branchRefTargets(
+    { clientRepo: cfg.repo, clientBranch: cfg.branch, editorBranch },
+    { editorRepo },
+  );
+  if (!targets.length) return;
+  console.error("Checking that the requested branches still exist on origin...");
+  const missing = lc.missingBranchRefs(targets, refExists);
+  if (missing.length) throw new Error(lc.missingBranchRefMessage(missing));
+}
+
 async function cmdUp(args, projectDir = rootDir) {
   ensureGcloud();
   const flags = parseFlags(args);
@@ -4256,6 +4325,10 @@ async function cmdUp(args, projectDir = rootDir) {
 
   checkScriptDrift(cfg);
 
+  // Last of the pre-instance guards: a deleted branch ref is checkable in ~1s
+  // and otherwise costs a full instance + boot + 13k-file clone to discover.
+  assertBranchRefsExist(cfg);
+
   await ensureFirewallRule(cfg);
   const { createdThisRun } = await ensureInstance(cfg);
 
@@ -5449,6 +5522,8 @@ module.exports = {
   readVmAppPort,
   buildVmAppPortReadCommand,
   resolveLaptopGitIdentity,
+  gitBranchRefExists,
+  assertBranchRefsExist,
 };
 
 if (require.main === module) {

package/npm/editor-dev.js

@@ -40,6 +40,8 @@ const {
   logLauncherTeardownSignal,
   readMergedEditorConfig,
   resolveLauncherPort,
+  readServerOutputLogTail,
+  formatLaunchFailureError,
   staleBinaryBanner,
   enforceFreshBinary,
 } = require("./utils");
@@ -447,9 +449,29 @@ if (require.main === module) {
         buildLauncherArtifacts();
       }
 
+      // Both helpers take the port to BIND plus the TARGET PROJECT dir — the
+      // latter is what lets them find the project's `server-state.json`, and so
+      // find a running server whose control port is not `SERVER_PORT` at all.
       const serverChild = shouldRestart
-        ? await restartServer(SERVER_PORT)
-        : await ensureServer(SERVER_PORT);
+        ? await restartServer(SERVER_PORT, projectDir)
+        : await ensureServer(SERVER_PORT, projectDir);
+
+      // Nothing below may claim the editor is up until something is actually
+      // listening on the port we just bound. `ensureServer` returns null only
+      // when it ATTACHED to a live server, and its spawn path already races the
+      // port — but a launcher that prints a URL it never bound turned a
+      // recoverable port conflict into a debugging session, so the banner is
+      // gated on an independent probe rather than on that internal contract.
+      if (!(await waitForPort(SERVER_PORT, 10000, 200))) {
+        console.error(
+          formatLaunchFailureError(
+            SERVER_PORT,
+            projectDir,
+            readServerOutputLogTail(projectDir),
+          ),
+        );
+        process.exit(1);
+      }
 
       // Re-read the (possibly just-initialized) project config to decide
       // whether to wait on a dev server at all. On a project where init

package/npm/editor.js

@@ -27,6 +27,7 @@ const {
   readMergedEditorConfig,
   resolveLauncherPort,
   resolveWrappedAppPort,
+  resolveRunningControlPort,
   classifyPortHolder,
   fetchServerIdentity,
   formatForeignListenerError,
@@ -247,13 +248,22 @@ async function main() {
   // possible outcome of a port collision — only stop the listener if
   // the identity probe confirms it's this project's server.
   if (shouldRestart) {
-    const holder = await classifyPortHolder(SERVER_PORT);
+    // The port to TEAR DOWN is not necessarily SERVER_PORT: under the Project
+    // Launcher or the desktop supervisor the running server took a dynamic
+    // control port and recorded it in `server-state.json`, while
+    // `proxy.controlPort` is only the static default. `resolveRunningControlPort`
+    // is the one resolver for that question (it mirrors `resolve_control_port`
+    // in `crates/codeyam-editor/src/commands/editor/control_port.rs`); gating
+    // teardown on the configured port alone is what let a stale server survive a
+    // restart. SERVER_PORT stays the port to BIND.
+    const runningPort = resolveRunningControlPort(process.cwd(), SERVER_PORT);
+    const holder = await classifyPortHolder(runningPort);
     if (holder.kind === "foreign") {
-      console.error(formatForeignListenerError(SERVER_PORT));
+      console.error(formatForeignListenerError(runningPort));
       process.exit(1);
     }
     if (holder.kind === "cross-project") {
-      const outcome = await resolveCrossProjectCollision(SERVER_PORT, holder, "restart");
+      const outcome = await resolveCrossProjectCollision(runningPort, holder, "restart");
       if (outcome.action !== "took-over") {
         // "abort" (non-TTY) or "declined": resolver already printed the message.
         process.exit(1);
@@ -261,8 +271,8 @@ async function main() {
       // took-over: stopServer freed the port; fall through to the fresh-boot path.
     }
     if (holder.kind === "same-project") {
-      console.error(`Stopping existing server on port ${SERVER_PORT}...`);
-      await stopServer(SERVER_PORT);
+      console.error(`Stopping existing server on port ${runningPort}...`);
+      await stopServer(runningPort);
     }
     // holder.kind === "free": nothing to stop, fall through to ensureServer.
   }

package/npm/fleet-add-failure.js

@@ -33,7 +33,11 @@ const { parseRosterMarkers } = require('./fleet-early-roster');
 //
 //   1. NOTHING WAS PROVISIONED. The classifier can prove no cloud resource was
 //      created (`preflight-drift` aborts before the first gcloud call;
-//      `instance-vanished` confirms the instance is gone). Retry starts clean.
+//      `instance-vanished` confirms the instance is gone; `capacity-stockout`
+//      pairs a GCE stockout signature with the `Failed to create instance` line
+//      that `ensureInstance` throws from exactly one place — the branch where the
+//      instance was not found AND the create call failed, so no instance, disk,
+//      NEG or backend service can exist). Retry starts clean.
 //
 //   2. THE REMAINING WORK IS RE-ENTRANT. A real VM exists, but every step the
 //      retry would re-run is skip-on-exists or re-attaching, so the retry
@@ -50,6 +54,7 @@ const { parseRosterMarkers } = require('./fleet-early-roster');
 const ADD_FAILURE_RETRYABLE = new Set([
   'preflight-drift',
   'instance-vanished',
+  'capacity-stockout',
   'project-bootstrap-timeout',
 ]);
 
@@ -171,6 +176,113 @@ function nextValidActionRemedy(text) {
   return i === -1 ? '' : lines.slice(i).join('\n').trim();
 }
 
+// Name the capacity GCE was short of, from whatever the stockout transcript
+// happens to expose — for the capacity-stockout recovery line. GCE reports this
+// inconsistently: the 2026-08-20 VM-11 transcript carried `vmType:` / `zone:`
+// bullets under errorInfo.metadatas, while the 2026-08-18 VM-13 spelling
+// (ZONE_RESOURCE_POOL_EXHAUSTED_WITH_DETAILS) carried neither. So every part is
+// optional and the phrase degrades to a generic-but-true sentence rather than
+// interpolating `undefined` into operator-facing copy. Extracted alongside
+// nextValidActionRemedy (the same shape: a pure transcript reader that enriches
+// one arm's recovery text) so the degradation is asserted directly.
+//
+// `zone:` is anchored with ^\s* so the neighbouring `zonesAvailable:` bullet —
+// which lists the zones that DID have capacity — cannot be mistaken for the zone
+// that failed. Never throws; returns the generic phrase for empty input.
+function stockoutCapacityPhrase(logTail) {
+  const log = String(logTail || '');
+  const vmType = (log.match(/^\s*vmType:\s*(\S+)/m) || [])[1];
+  const zone = (log.match(/^\s*zone:\s*(\S+)/m) || [])[1];
+  return [vmType, 'capacity', zone ? `in ${zone}` : 'in the target zone']
+    .filter(Boolean)
+    .join(' ');
+}
+
+// The spellings git uses for "that branch is not on the remote", each capturing
+// the ref name. The union is not defensive padding — the two bootstrap scripts
+// reach the remote with DIFFERENT git commands, and git words the same condition
+// differently for each:
+//   `git fetch <url> <branch>`  (clone_editor_repo, scripts/gcp-bootstrap.sh)
+//        → fatal: couldn't find remote ref <ref>
+//   `git clone --branch <b>`    (clone_project, scripts/gcp-project-bootstrap.sh)
+//        → fatal: Remote branch <b> not found in upstream origin
+// Keying on only the first — the one the 2026-08-25 transcripts happened to
+// carry — would miss every client-side clone failure. Same union-of-spellings
+// lesson capacity-stockout learned from GCE.
+//
+// Deliberately NOT included: git's `warning: Could not find remote branch …`,
+// which is a submodule-update warning that accompanies a SUCCEEDING command.
+// Matching it here would let an add that failed for an unrelated reason claim
+// this category — and this arm sits above the generic one, so a false positive
+// would suppress the true cause rather than merely add noise.
+const MISSING_REF_PATTERNS = [
+  /couldn't find remote ref (\S+)/i,
+  /Remote branch (\S+) not found in upstream/i,
+];
+
+// Which branch died, and which config field carried it — read from the transcript.
+//
+// The field matters because clientBranch and editorBranch are configured in
+// different places: an operator who corrects only one re-issues a request that
+// fails identically. It is derived from the log prefix of the nearest preceding
+// marker line, because the two bootstrap scripts brand their output distinctly
+// (`[gcp-bootstrap]` builds the editor image from the editor branch;
+// `[project-bootstrap]` clones the client repo at the client branch). When the
+// transcript carries neither marker the field is left null and the copy names
+// both fields rather than guessing — the same degrade-to-true-but-generic
+// discipline stockoutCapacityPhrase uses. Never throws; returns
+// { ref: null, field: null } for input with no missing-ref signature.
+function missingBranchRefFacts(logTail) {
+  const lines = String(logTail || '').split('\n');
+  for (let i = 0; i < lines.length; i += 1) {
+    let ref = null;
+    for (const re of MISSING_REF_PATTERNS) {
+      const m = lines[i].match(re);
+      if (m) { ref = m[1]; break; }
+    }
+    if (!ref) continue;
+    let field = null;
+    for (let j = i; j >= 0; j -= 1) {
+      if (/\[project-bootstrap\]/.test(lines[j])) { field = 'clientBranch'; break; }
+      if (/\[gcp-bootstrap\]/.test(lines[j])) { field = 'editorBranch'; break; }
+    }
+    return { ref, field };
+  }
+  return { ref: null, field: null };
+}
+
+// Operator-facing recovery copy for the missing-branch-ref arm.
+//
+// Extracted from the arm for the same reason stockoutCapacityPhrase was — it is
+// the one arm whose copy VARIES with what the transcript happened to expose, so
+// pulling it out lets the wording be asserted directly instead of only through
+// classifyAddFailure, and keeps the arm itself a two-line decision.
+//
+// Two properties are load-bearing and are what the tests pin:
+//   - It states the outcome FIRST and never borrows the generic arm's "a partial
+//     instance may exist — reconcile or destroy it" language. At this point git
+//     has aborted before any image build or container work, so that advice sends
+//     the operator hunting for a box that was never created — the inversion that
+//     cost the 2026-08-25 recovery its first hour.
+//   - The remedy is a DIFFERENT action, never "retry". Re-issuing the same
+//     config against a deleted ref fails identically forever, which is exactly
+//     why this category is kept out of ADD_FAILURE_RETRYABLE.
+//
+// `field` is optional: when the transcript carries no bootstrap marker the copy
+// names both fields rather than guessing which one carried the dead ref.
+// Pure; no I/O.
+function missingBranchRefRecovery({ ref, field } = {}) {
+  const carried = field
+    ? `Its ${field} still points at it`
+    : 'Its clientBranch and editorBranch both need checking';
+  return (
+    `Branch '${ref}' is not on origin any more — it was almost certainly pruned when it merged. ` +
+    'Nothing was provisioned: git aborted before any image build or container work, so there is no instance, ' +
+    `disk, NEG or backend service to clean up, and nothing to destroy. ${carried}, so retrying as-is will fail ` +
+    'identically every time. Re-add on a branch that still exists (the current fleet branch is the usual answer).'
+  );
+}
+
 // 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) {
@@ -200,11 +312,17 @@ function buildFailureVerdict(category, headline, recovery, extra) {
 // Returns { category, headline, recovery, retryable, files? }.
 //
 // Detection is ORDER-SENSITIVE. The provision shell echoes cloud:up's tail, so a
-// drift / instance-vanished / container-stuck transcript ALSO contains the
-// generic `cloud:up FAILED (exit N)` line. Each specific (and every retryable)
-// signature is therefore tested BEFORE the generic cloud-up-failed signature, or
-// a retryable drift would misclassify as a non-retryable cloud:up failure and the
-// operator would lose the safe one-click recovery.
+// drift / instance-vanished / container-stuck / capacity-stockout /
+// missing-branch-ref transcript ALSO contains the generic `cloud:up FAILED
+// (exit N)` line. Each specific (and every retryable) signature is therefore
+// tested BEFORE the generic cloud-up-failed signature, or a retryable drift would
+// misclassify as a non-retryable cloud:up failure and the operator would lose the
+// safe one-click recovery. That is not a hypothetical: it is exactly the bug
+// `capacity-stockout` (arm 6) was added to fix, and its placement immediately
+// above cloud-up-failed is load-bearing. `missing-branch-ref` (arm 7) has the
+// same property for the same reason — it also sits immediately above the generic
+// arm, and its ordering is what stops a dead ref reporting as a half-provisioned
+// instance.
 function classifyAddFailure({ logTail, exitCode, instanceAlive, containerHealthy, wiringDeadlineBlown, wiringInFlight } = {}) {
   const log = String(logTail || '');
 
@@ -272,33 +390,97 @@ function classifyAddFailure({ logTail, exitCode, instanceAlive, containerHealthy
       'The container came up but the project was never scaffolded (no .codeyam/editor.json on the VM), so provisioning did not finish onboarding. Reconcile this VM to complete the scaffold, then re-add.');
   }
 
-  // 6. cloud-up-failed — a generic cloud:up failure, reached ONLY when the drift /
-  //    vanished / stuck signatures above did not match. A partial instance may
-  //    exist, so not retryable.
+  // 6. capacity-stockout — GCE had no capacity for the machine type in the target
+  //    zone, so `ensureInstance` (npm/cloud.js) threw from its create branch. This
+  //    fired twice in three days — VM-13 / payper on 2026-08-18 and VM-11 /
+  //    codeyam-cms on 2026-08-20 — and both times classified as the generic
+  //    cloud-up-failed below, whose copy wrongly warned that a partial instance may
+  //    exist and whose non-retryable verdict refused the one failure that needs
+  //    nothing but a retry. Each incident cost manual state surgery on the operator
+  //    host.
+  //
+  //    Retryable on ground 1 (NOTHING WAS PROVISIONED), proven STRUCTURALLY rather
+  //    than by trusting the error prose: the arm fires only on a stockout signature
+  //    AND the `Failed to create instance` line, which ensureInstance throws from
+  //    exactly one place — the branch where the instance was not found and the
+  //    create call then failed. That conjunction is positive proof no cloud
+  //    resource exists, the same standing preflight-drift and instance-vanished
+  //    already have; both incidents were verified by hand to have left no instance,
+  //    disk, NEG or backend service behind. The not-rostered guard is belt-and-
+  //    braces: if a future transcript stockouts on one attempt and then creates a
+  //    box, a roster marker means a real VM exists and this arm must not fire.
+  //
+  //    The signature is a UNION because GCE spells this more than one way: the
+  //    2026-08-18 transcript carried `ZONE_RESOURCE_POOL_EXHAUSTED_WITH_DETAILS`
+  //    with `reason: stockout`, while 2026-08-20 carried `reason:
+  //    resource_availability` with `state:STOCKOUT, sub-state:STOCKOUT` and the
+  //    prose below. Keying on only the first would have missed the second. The
+  //    prose alternative uses `\s+` because the message wraps mid-sentence.
+  //
+  //    Tested BEFORE cloud-up-failed because the provision shell echoes cloud:up's
+  //    tail, so a stockout transcript ALSO carries `cloud:up FAILED (exit N)` —
+  //    matching that first is precisely the bug being fixed here.
+  if (/ZONE_RESOURCE_POOL_EXHAUSTED|\bSTOCKOUT\b|reason:\s*resource_availability|does not have\s+enough resources available/i.test(log)
+      && /Failed to create instance/i.test(log)
+      && !transcriptRostered(log)) {
+    return buildFailureVerdict('capacity-stockout', 'No capacity in the zone',
+      `GCE had no ${stockoutCapacityPhrase(log)} at that moment, so the create call failed before anything existed — there is no instance, disk, NEG or backend service to clean up, and nothing to undo. Capacity is transient but its return is not scheduled: wait a few minutes, then Retry add. Do NOT destroy anything.`);
+  }
+
+  // 7. missing-branch-ref — the requested branch no longer exists on origin, so
+  //    git aborted the clone/fetch. Observed live on 2026-08-25: VMs 2, 4, 5 and
+  //    7 each died on `fatal: couldn't find remote ref editor-improvements-75`,
+  //    a branch pruned from origin earlier that day when it merged. This repo
+  //    prunes on merge, so ANY stored feature-branch name expires silently —
+  //    this is a recurring condition, not a one-off.
+  //
+  //    NOT retryable, and deliberately NOT a member of ADD_FAILURE_RETRYABLE
+  //    even though it satisfies ground 1 (nothing was provisioned). Membership
+  //    means "re-issuing the SAME request can succeed"; re-issuing an add
+  //    against a deleted ref fails identically forever. Admitting it would
+  //    automate the guaranteed-fail loop the operator was stuck in by hand. The
+  //    honest remedy is a DIFFERENT request — re-add on a live branch — which is
+  //    what the recovery copy names.
+  //
+  //    Tested BEFORE cloud-up-failed for the reason arm 6 documents: the
+  //    provision shell echoes cloud:up's tail, so this transcript ALSO carries
+  //    the generic `cloud:up FAILED (exit N)` line. Matching that first is the
+  //    bug being fixed — it is what made the real incident report the OPPOSITE
+  //    of the truth, warning that "a partial instance may exist — reconcile or
+  //    destroy it" when nothing had been provisioned at all.
+  const missingRef = missingBranchRefFacts(log);
+  if (missingRef.ref) {
+    return buildFailureVerdict('missing-branch-ref', 'Branch no longer exists',
+      missingBranchRefRecovery(missingRef));
+  }
+
+  // 8. cloud-up-failed — a generic cloud:up failure, reached ONLY when the drift /
+  //    vanished / stuck / stockout / missing-ref signatures above did not match. A
+  //    partial instance may exist, so not retryable.
   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.');
   }
 
-  // 7. interrupted — a signal kill (OOM 137, SIGTERM 143, …) or an explicit
+  // 9. 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.');
   }
 
-  // 8. The post-add IAP read-back verdicts. Unlike every signature above, this one
+  // 10. 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 seven hard-failure signatures so a proven failure
+  //    calm). Tested AFTER all eight hard-failure signatures 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)) {
     const remedy = nextValidActionRemedy(log);
-    //  8a. access-pending — no accessors YET. The grant is the LAST step of the
+    //  9a. access-pending — no accessors YET. The grant is the LAST step of the
     //      detached wire-add-tail, so while that tail is alive an empty policy is
     //      the expected mid-flight reading, not a verdict. Calm: this is the state
     //      that used to render a red "Add failed" on healthy VM-4/VM-7 minutes
@@ -307,7 +489,7 @@ function classifyAddFailure({ logTail, exitCode, instanceAlive, containerHealthy
       return buildFailureVerdict('access-pending', 'Access not granted yet',
         'The VM is up and rostered, but its IAP policy has no human accessors yet — the add\'s background wiring applies the grant as its last step and is still running. This resolves on its own once that tail finishes; no action is needed unless it persists past the wiring deadline.');
     }
-    //  8b. iap-unauthorized — the wiring is done and the policy STILL authorizes
+    //  9b. iap-unauthorized — the wiring is done and the policy STILL authorizes
     //      nobody, so the public URL returns "Error code 51" for every human. This
     //      is the 2026-08-09 case the read-back exists to catch (one step granted
     //      the operator, the next revoked him) and it is a genuine hard failure.
@@ -317,12 +499,12 @@ 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}` : ''}`);
   }
 
-  // 9. converging — the add reached the early-roster marker (`CY_ROSTER`): the
+  // 11. 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,
-  //    instance-vanished, container-stuck, incomplete-workspace, cloud-up-failed,
-  //    interrupted) is printed BEFORE `CY_ROSTER`, so a rostered transcript that
+  //    instance-vanished, container-stuck, incomplete-workspace, capacity-stockout,
+  //    cloud-up-failed, interrupted) is printed BEFORE `CY_ROSTER`, so a rostered transcript that
   //    fell through to here is a still-wiring box owned by the detached
   //    wire-add-tail / reconcile-ingress — NOT an add failure. Surface it as an
   //    honest in-flight state instead of the scary red `unknown`. Not retryable:
@@ -335,7 +517,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.');
   }
 
-  // 10. The residue: no failure signature above matched. The polarity here is
+  // 12. 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
@@ -345,7 +527,7 @@ function classifyAddFailure({ logTail, exitCode, instanceAlive, containerHealthy
   //
   //    Red now requires positive proof of death, and everything else is in-flight:
   //
-  //    10a. unknown — a non-zero exit CORROBORATED by a durable fact (see
+  //    11a. unknown — a non-zero exit CORROBORATED by a durable fact (see
   //        addFailureCorroborated). The box is provably dead or provably never
   //        came up, so the loud, terminal escalation is warranted and unchanged.
   //        Still never invites an unproven retry.
@@ -354,7 +536,7 @@ function classifyAddFailure({ logTail, exitCode, instanceAlive, containerHealthy
       'The add failed for an unclassified reason and the VM is confirmed dead or never came up — inspect the transcript below, then reconcile or destroy this VM before re-adding.');
   }
 
-  //    10b. verifying — the honest default. No failure signature, and nothing
+  //    11b. verifying — the honest default. No failure signature, and nothing
   //        durable proves this VM is dead: it may still be provisioning or
   //        wiring, and the ingress can keep propagating for minutes after the
   //        wrapper is gone. Calm copy, transcript still one click away. NOT
@@ -405,4 +587,36 @@ function holdConvergingBadge({ category, wiringDeadlineBlown } = {}) {
   return CALM_ADD_CATEGORIES.has(category) && !wiringDeadlineBlown;
 }
 
-module.exports = { classifyAddFailure, extractDriftFiles, lastNonEmptyLines, canRetryAdd, transcriptRostered, holdConvergingBadge, addFailureCorroborated, containerHealthWitness, CALM_ADD_CATEGORIES, ADD_FAILURE_RETRYABLE };
+// Refusal copy for a Retry on a card whose branch was deleted from origin.
+//
+// The generic non-retryable refusal says the add "may have left a
+// half-provisioned instance — reconcile or destroy it". For this category that
+// is the OPPOSITE of the truth: git aborts before any image build or container
+// work, so nothing exists. Sending an operator to hunt for a box that was never
+// created is what cost the 2026-08-25 recovery its first hour, so this copy
+// leads with the outcome (nothing to clean up) before naming the mechanism.
+//
+// The remedy is deliberately not "retry". Re-issuing the same config against a
+// deleted ref fails identically forever — which is exactly why the category is
+// kept OUT of ADD_FAILURE_RETRYABLE — so the honest advice is a different
+// action. For a self-host VM the fleet pin names the live branch and a re-add
+// now picks it up, so the copy can be specific; for a client VM the branch is a
+// per-project choice only the operator can make, so it asks instead of guessing.
+//
+// `ref` / `field` come from missingBranchRefFacts and are both optional: the copy
+// degrades to true-but-generic rather than interpolating `undefined`, the same
+// discipline stockoutCapacityPhrase uses. Pure; no I/O.
+function deadRefRetryMessage({ n, ref, field, selfHost = false, pin } = {}) {
+  const which = ref ? `'${ref}'` : 'the requested branch';
+  const carried = field ? ` (${field})` : '';
+  const remedy = selfHost && pin
+    ? `Add VM again — it now picks up the current fleet branch (${pin}) instead of the stored one.`
+    : 'Add VM again with a branch that still exists on origin.';
+  return (
+    `VM-${n}: branch ${which}${carried} no longer exists on origin, so nothing was provisioned — ` +
+    'there is no instance, disk or backend service to clean up. Retrying as-is re-targets ' +
+    `the same dead branch and fails identically every time. ${remedy}`
+  );
+}
+
+module.exports = { classifyAddFailure, extractDriftFiles, lastNonEmptyLines, canRetryAdd, transcriptRostered, holdConvergingBadge, addFailureCorroborated, containerHealthWitness, stockoutCapacityPhrase, missingBranchRefFacts, missingBranchRefRecovery, deadRefRetryMessage, CALM_ADD_CATEGORIES, ADD_FAILURE_RETRYABLE };