@codeyam-editor/codeyam-editor 0.1.8 → 0.1.9

package/npm/cloud.js

@@ -514,6 +514,28 @@ function previewSameOriginSafeFromStack(stackJson) {
   return typeof flag === "boolean" ? flag : true;
 }
 
+/** Resolve the sameOriginSafe flag a seed should ACT on, given the static
+ *  `stack.json` reading and the running editor's own `/api/config` verdict.
+ *
+ *  Precedence: a BOOLEAN effective verdict wins; anything else (`null`,
+ *  `undefined`, a non-boolean) defers to the static flag. The type check is the
+ *  whole rule — `null` means "no server was up to ask", which is the
+ *  pre-container seed and must leave the static read in charge, NOT "the server
+ *  said same-origin is fine". Collapsing the two would put the static flag back
+ *  in control on exactly the path that needs the override.
+ *
+ *  Extracted from `seedPreviewOrigin` because that function's inputs arrive over
+ *  gcloud SSH, so this rule was only reachable through heavy mocking — while
+ *  being precisely where the defect lived. `stack.json` cannot express the state
+ *  that matters here: a project escalates off the same-origin subpath at RUNTIME
+ *  after a hydration failure, and the adaptive-default stacks that happens to
+ *  (Next.js) deliberately omit the key. So a seeder that re-derives the flag
+ *  from the file writes back the same-origin sentinel that just failed, and the
+ *  project sits at `previewDedicatedOriginUnavailable: true` forever. Pure. */
+function resolveEffectiveSameOriginSafe(staticFlag, effectiveVerdict) {
+  return typeof effectiveVerdict === "boolean" ? effectiveVerdict : staticFlag;
+}
+
 // Matches an absolute cloudflared quick-tunnel origin
 // (`https://<sub>.trycloudflare.com`, optionally with a port/path/query). These
 // URLs ROTATE on every tunnel respawn, which is exactly why a frozen one rots.
@@ -958,6 +980,19 @@ function buildGcloudArgs(verb, cfg = {}, extras = {}) {
       return ["compute", "instances", "delete", instanceName, "--project", project, "--zone", zone, "--quiet"];
     case "instances-describe":
       return ["compute", "instances", "describe", instanceName, "--project", project, "--zone", zone, "--format=json"];
+    // Outstanding (not-yet-DONE) zone operations targeting this instance. Used to
+    // tell a normal transient PROVISIONING from a wedged insert: GCE can accept an
+    // insert and then never finish it, leaving an operation parked at RUNNING/0%
+    // that holds the instance name forever. The status filter is what makes this
+    // cheap and unambiguous — a DONE operation is history and says nothing about
+    // whether the slot is currently blocked.
+    case "operations-list-pending":
+      return [
+        "compute", "operations", "list",
+        "--project", project,
+        "--filter", `zone:(${zone}) AND targetLink~${instanceName}$ AND status!=DONE`,
+        "--format=json",
+      ];
     case "instances-list-tagged":
       return [
         "compute", "instances", "list",
@@ -1054,8 +1089,41 @@ function buildGcloudArgs(verb, cfg = {}, extras = {}) {
 // reconcile spawnSync sites (status probe, per-BES timeout converge) so all three
 // reference one value. 2 min is generous for any single describe/update/SSH probe
 // yet comfortably under the 600000 ms outer reconcile budget.
+//
+// It is a PROBE budget, and provisioning is exempt — see
+// GCLOUD_PROVISION_TIMEOUT_MS below. Do not re-collapse the two: raising this
+// constant to accommodate a slow create would un-bound the reconcile sweep,
+// which is the exact orphan-cascade this value exists to stop.
 const GCLOUD_CALL_TIMEOUT_MS = 120000;
 
+// `instances create` / `instances start` are NOT probes: each blocks until GCE's
+// insert (or start) operation reaches a terminal state, which routinely outruns
+// the probe budget under zonal contention. Inheriting GCLOUD_CALL_TIMEOUT_MS
+// SIGTERMd gcloud mid-insert; `spawnSync` then returned `status: null`, which
+// `!== 0`, so a local kill was indistinguishable from a remote rejection and the
+// caller threw a bare `Failed to create instance <name>` with no cause in it.
+// That mattered downstream: every arm of classifyAddFailure keys on a transcript
+// signature, so a causeless log fell through to the optimistic `verifying`
+// fallback and told the operator to WAIT on a VM GCE had already wedged
+// (observed 2026-09-04 on VM-8: insert 14:29:50Z, add errored 14:32:26Z — the
+// 120s budget plus teardown).
+//
+// Deliberately above the 600000 ms outer reconcile budget, on the same reasoning
+// as PROJECT_BOOTSTRAP_TIMEOUT_MS: ensureInstance is only ever reached from the
+// add path, never from the reconcile sweep, so the sweep-relative ceiling that
+// governs GCLOUD_CALL_TIMEOUT_MS does not apply. A create still running at 10
+// minutes is wedged, not slow.
+const GCLOUD_PROVISION_TIMEOUT_MS = 10 * 60 * 1000;
+
+/** The per-call spawn budget a given wrapper verb should run under. Provisioning
+ *  verbs get GCLOUD_PROVISION_TIMEOUT_MS; everything else keeps the probe budget.
+ *  Pure — the mapping is asserted directly, without spawning a process. */
+function gcloudCallTimeoutMs(verb) {
+  return verb === "instances-create" || verb === "instances-start"
+    ? GCLOUD_PROVISION_TIMEOUT_MS
+    : GCLOUD_CALL_TIMEOUT_MS;
+}
+
 // The project bootstrap is NOT a probe: it runs `git clone` + `npm install` in
 // the repo root and every `apps[].dir`, each package's `postinstall`, then
 // `npm run setup` — minutes of remote work on a heavy repo. It once ran as ONE
@@ -1128,6 +1196,66 @@ function formatGcloudFailure(result) {
   return "(no output captured from gcloud)";
 }
 
+/** The thrown message for a failed `instances create` / `instances start`.
+ *
+ *  Splits the two outcomes the old bare `Failed to create instance <name>`
+ *  collapsed, because they are different operator actions: a LOCAL timeout means
+ *  GCE may still be working the operation and it should be checked, while a
+ *  remote rejection means GCE said no and its own stderr is the answer. Both
+ *  arms put a cause in the transcript — classifyAddFailure keys on transcript
+ *  text, so a causeless message is what lands an add on the optimistic
+ *  `verifying` fallback. Pure: result in, string out.
+ *
+ *  `verb` is the operator-facing word ("create" / "start"), not a wrapper verb. */
+/** Operator-facing copy for a create GCE accepted and then abandoned, kept
+ *  separate from the guard that detects it for the same reason
+ *  provisionFailureMessage is: the decision of WHEN to refuse and the wording of
+ *  WHAT to say are different concerns, and only the wording needs asserting.
+ *  Extracting it is what lets the copy be tested without a live gcloud — and on
+ *  this feature the copy IS the fix, since the bug was a message that told the
+ *  operator to wait for a VM that would never arrive.
+ *
+ *  Every field is rendered defensively because this runs on a degraded path: the
+ *  operations read that produced `pending` is best-effort, so a partial record
+ *  must still yield a message that names the problem rather than printing
+ *  "undefined" at the operator. */
+function wedgedOperationMessage(instanceName, pending = {}) {
+  const detail = [
+    `${pending.name || "unnamed"}: ${pending.operationType || "unknown type"}`,
+    `status ${pending.status || "unknown"}`,
+    `progress ${pending.progress == null ? "unknown" : `${pending.progress}%`}`,
+    `error ${pending.errorCode || "unknown"}${pending.errorMessage ? `: ${pending.errorMessage}` : ""}`,
+  ].join(", ");
+  return (
+    `Instance ${instanceName} is stuck in PROVISIONING behind a wedged create operation (${detail}). ` +
+    "GCE accepted the create and never finished it, so this slot cannot be re-added and a delete will queue " +
+    "behind the wedged operation rather than clear it. This needs GCE-side resolution — open a Google Cloud " +
+    "Support case citing that error. Use a different VM number if you need a box now."
+  );
+}
+
+function provisionFailureMessage(verb, instanceName, result) {
+  if (isSpawnTimeout(result)) {
+    const minutes = Math.round(GCLOUD_PROVISION_TIMEOUT_MS / 60000);
+    // A SIGTERMd child legitimately often captured nothing, and appending
+    // formatGcloudFailure's "(no output captured)" placeholder to a message that
+    // already states the cause is noise. Append it only when it is real output.
+    const detail = formatGcloudFailure(result);
+    const captured = detail === "(no output captured from gcloud)" ? "" : `\n${detail}`;
+    return (
+      `Failed to ${verb} instance ${instanceName}: the gcloud call exceeded the local ` +
+      `${minutes}-minute provisioning budget and was SIGTERMd locally. GCE may still be ` +
+      `working the operation — check it with \`gcloud compute operations list\` before ` +
+      `retrying, and delete the half-built instance if one exists.` +
+      captured
+    );
+  }
+  return (
+    `Failed to ${verb} instance ${instanceName} (gcloud exit ${result && result.status}).\n` +
+    formatGcloudFailure(result)
+  );
+}
+
 // A bounded, pure classifier that keys on status === 255 (gcloud-ssh's exit
 // for an ssh failure) and a signature match against known transient strings.
 function isTransientSshFailure(result) {
@@ -1203,6 +1331,38 @@ function fetchInstanceState(cfg) {
   }
 }
 
+/** Read the instance's outstanding (not-DONE) zone operations and summarize the
+ *  first one, or null when there are none / the call failed. Shaped as
+ *  { name, operationType, status, progress, errorCode, errorMessage } — the fields
+ *  the wedged-insert refusal message and the fleet classifier both need.
+ *
+ *  Returning null on a failed or unparseable call is deliberate: this is a
+ *  DIAGNOSTIC read used to make a refusal more informative, so it must never turn
+ *  a working provision into a failing one just because the operations API hiccuped. */
+function fetchPendingOperation(cfg) {
+  const result = runGcloud(buildGcloudArgs("operations-list-pending", cfg), {
+    stdio: ["ignore", "pipe", "ignore"],
+  });
+  if (result.status !== 0) return null;
+  let ops;
+  try {
+    ops = JSON.parse(result.stdout);
+  } catch {
+    return null;
+  }
+  if (!Array.isArray(ops) || ops.length === 0) return null;
+  const op = ops[0];
+  const err = op && op.error && Array.isArray(op.error.errors) ? op.error.errors[0] : null;
+  return {
+    name: op.name || null,
+    operationType: op.operationType || null,
+    status: op.status || null,
+    progress: typeof op.progress === "number" ? op.progress : null,
+    errorCode: (err && err.code) || null,
+    errorMessage: (err && err.message) || null,
+  };
+}
+
 function loadOrInitCloudConfig(projectDir, flags) {
   const existing = loadCloudConfig(projectDir);
   // noTunnel is a per-invocation behavior, never persisted — else a later manual
@@ -1284,7 +1444,11 @@ async function ensureFirewallRule(cfg) {
   }
 }
 
-async function ensureInstance(cfg) {
+// `sleepFn` is injectable so the 60-iteration wait loop can be driven with a
+// no-op instead of burning 2 real minutes of clock — the same seam
+// runGcloudSshWithRetry / waitForEditorComposeRunning already expose.
+async function ensureInstance(cfg, { sleepFn } = {}) {
+  const sleep = sleepFn || ((ms) => new Promise((r) => setTimeout(r, ms)));
   console.error(`Checking instance ${cfg.instanceName}...`);
   const initialState = fetchInstanceState(cfg);
   const createdThisRun = initialState === null;
@@ -1295,29 +1459,59 @@ async function ensureInstance(cfg) {
   }
   if (initialState === "TERMINATED") {
     console.error(`  ${cfg.instanceName} is TERMINATED — starting...`);
-    const start = runGcloud(buildGcloudArgs("instances-start", cfg));
+    const start = runGcloud(buildGcloudArgs("instances-start", cfg), {
+      timeout: gcloudCallTimeoutMs("instances-start"),
+    });
     if (start.status !== 0) {
-      throw new Error(`Failed to start instance ${cfg.instanceName}`);
+      throw new Error(provisionFailureMessage("start", cfg.instanceName, start));
     }
   } else if (initialState === null) {
     console.error(`  ${cfg.instanceName} not found — creating...`);
-    const create = runGcloud(buildGcloudArgs("instances-create", cfg));
+    const create = runGcloud(buildGcloudArgs("instances-create", cfg), {
+      timeout: gcloudCallTimeoutMs("instances-create"),
+    });
     if (create.status !== 0) {
-      throw new Error(`Failed to create instance ${cfg.instanceName}`);
+      throw new Error(provisionFailureMessage("create", cfg.instanceName, create));
     }
   } else {
+    // A slot found in PROVISIONING is ambiguous, and the two readings need
+    // opposite handling. On a normal add it is a transient the poll loop below
+    // resolves in seconds. But GCE can also accept an insert and then never
+    // finish it (2026-09-04, VM-8): the operation parks at RUNNING/0%, eventually
+    // attaches an INTERNAL_ERROR without ever reaching DONE, and holds the
+    // instance name indefinitely — a delete queues behind it rather than clearing
+    // it. Polling that for 2 minutes only rediscovers, slowly and with a message
+    // naming neither the operation nor the wedge, a state the first describe
+    // already showed. Read the outstanding operation instead and fail immediately
+    // when it carries a terminal error, so the transcript carries the signature
+    // fleet-add-failure.js's wedged-insert arm keys on.
+    if (initialState === "PROVISIONING") {
+      const pending = fetchPendingOperation(cfg);
+      if (pending && pending.errorCode) {
+        throw new Error(wedgedOperationMessage(cfg.instanceName, pending));
+      }
+    }
     console.error(`  ${cfg.instanceName} is ${initialState}; waiting...`);
   }
 
+  let lastState = initialState;
   for (let i = 0; i < 60; i++) {
-    if (fetchInstanceState(cfg) === "RUNNING") {
+    lastState = fetchInstanceState(cfg);
+    if (lastState === "RUNNING") {
       console.error(`  ✓ ${cfg.instanceName} is RUNNING`);
       await waitForIapReady(cfg);
       return { createdThisRun };
     }
-    await new Promise((r) => setTimeout(r, 2000));
+    await sleep(2000);
   }
-  throw new Error(`Instance ${cfg.instanceName} did not reach RUNNING within 2 minutes`);
+  // Name the state it was actually stuck in. An instance parked in PROVISIONING
+  // is a different operator action from one that stopped answering describe at
+  // all, and the old message ("did not reach RUNNING") distinguished neither.
+  throw new Error(
+    `Instance ${cfg.instanceName} did not reach RUNNING within 2 minutes ` +
+      `(last observed state: ${lastState || "unknown — describe returned no state"}` +
+      `${createdThisRun ? "; a create was issued this run" : ""}).`,
+  );
 }
 
 /** GCE reports the instance as RUNNING the moment the boot disk is attached,
@@ -1785,17 +1979,32 @@ function projectBootstrapRunnerScript(repoName) {
 // makes the outcome probe honest: after a launch, a present `.done` can only
 // mean THIS run's script reached its terminal line, never a leftover from a
 // previous half-wired attempt.
-function projectBootstrapLaunchCommand(scriptBody, scriptArgs = [], envVars = {}, repoName) {
+function projectBootstrapLaunchCommand(scriptBody, scriptArgs = [], envVars = {}, repoName, libFiles = {}) {
   const scriptB64 = Buffer.from(scriptBody, "utf8").toString("base64");
   const runnerB64 = Buffer.from(projectBootstrapRunnerScript(repoName), "utf8").toString("base64");
   const argsString = scriptArgs.map(shQuote).join(" ");
   const envPrefix = envAssignmentPrefix(envVars);
+  // The bootstrap script is written STANDALONE to $HOME, so any `source`/`.` it
+  // does relative to its own directory resolves against $HOME — not against the
+  // repo layout it was authored in. `libFiles` carries those siblings, keyed by
+  // the $HOME-relative path the script will look for them at (e.g.
+  // "lib/npm-pin.sh"). Their directories do not exist on a fresh VM, hence the
+  // mkdir. Omitting a sourced library is not a soft failure: the script aborts
+  // under `set -euo pipefail` and cloud:up tears the new VM down, which is the
+  // 2026-09-04 fleet-wide add outage.
+  const libWrites = Object.entries(libFiles).flatMap(([relPath, body]) => {
+    const b64 = Buffer.from(body, "utf8").toString("base64");
+    const dir = path.posix.dirname(relPath);
+    const mkdir = dir && dir !== "." ? [`mkdir -p $HOME/${dir}`] : [];
+    return [...mkdir, `echo '${b64}' | base64 -d > $HOME/${relPath}`];
+  });
   // Writes run synchronously (fast, before any backgrounding) so a decode error
   // aborts before launch; then the runner is detached. The env prefix is on the
   // setsid command so the tokens are inherited through nohup→setsid→bash but
   // never appear in any argv. `& echo MARKER` (no `;` before echo) keeps the
   // launch in the background while still confirming it fired.
   const writes = [
+    ...libWrites,
     `echo '${scriptB64}' | base64 -d > ${projectBootstrapScriptPath(repoName)}`,
     `echo '${runnerB64}' | base64 -d > ${projectBootstrapRunnerPath(repoName)}`,
     `rm -f ${projectBootstrapStatusPath(repoName)} ${projectBootstrapDoneMarker(repoName)}`,
@@ -2027,6 +2236,13 @@ 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),
+  };
   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
@@ -2054,7 +2270,7 @@ async function ensureProjectBootstrapped(cfg, { sleepFn } = {}) {
     // install that will survive an SSH disconnect. Every step of
     // gcp-project-bootstrap.sh is skip-on-exists, so re-entering is cheap.
     console.error("  launching detached project bootstrap on the VM (survives SSH disconnect)...");
-    const launch = projectBootstrapLaunchCommand(scriptBody, scriptArgs, bootstrapEnv, repoName);
+    const launch = projectBootstrapLaunchCommand(scriptBody, scriptArgs, bootstrapEnv, repoName, bootstrapLibs);
     const launched = await runGcloudSshWithRetry(
       "ssh-script",
       cfg,
@@ -2805,8 +3021,30 @@ function buildEditorLocalSeedWriteCommand({ repoName, remotePath, b64 }) {
  *  `_managedPreviewOrigin` sentinel). We stamp the sentinel here too so the
  *  monitor doesn't mistake the cloud:up seed for a user pin. The
  *  skip-on-already-set guard stays: a non-empty previewOrigin (whether a user
- *  pin or a monitor write) is left untouched on every `cloud:up`. */
-async function seedPreviewOrigin(cfg, appPort = VITE_PORT) {
+ *  pin or a monitor write) is left untouched on every `cloud:up`.
+ *
+ *  `effectiveSameOriginSafe` is the RUNNING editor's own verdict
+ *  (`/api/config`'s `previewSameOriginSafe`), supplied by a caller that has
+ *  already fetched it. When it is a boolean it WINS over the static
+ *  `stack.json` read; `null`/absent leaves the static read in charge.
+ *
+ *  That parameter exists because this function had two sources of truth for one
+ *  flag, and they disagreed exactly where the adaptive default lives. A
+ *  subpath hydration failure escalates a project off `/__codeyam_preview` at
+ *  RUNTIME even when `stack.json` never declared `sameOriginSafe: false` — which
+ *  is the documented Next.js scaffold shape (a static `false` broke every
+ *  SSH-forward VM, so the key is deliberately absent). `healPreviewOriginAtReady`
+ *  decided WHETHER to heal from that runtime verdict and was right, then called
+ *  this function, which recomputed WHAT to write from the static flag and wrote
+ *  the very same-origin sentinel that had just failed. The project then sat
+ *  permanently at `previewDedicatedOriginUnavailable: true` — the editor knowing
+ *  it must leave the subpath and having nowhere to go — beside a preview host
+ *  that was already provisioned, LB-routed, HEALTHY and unused. */
+async function seedPreviewOrigin(
+  cfg,
+  appPort = VITE_PORT,
+  effectiveSameOriginSafe = null,
+) {
   const repoName = resolveProject(cfg).name;
   const remotePath = `~/projects/${repoName}/.codeyam/editor.local.json`;
   const stackPath = `~/projects/${repoName}/.codeyam/stack.json`;
@@ -2842,6 +3080,12 @@ async function seedPreviewOrigin(cfg, appPort = VITE_PORT) {
     current = parseObj(localJson);
     sameOriginSafe = previewSameOriginSafeFromStack(parseObj(stackJson));
   }
+  // The running editor's verdict overrides the static file — see
+  // `resolveEffectiveSameOriginSafe` for why only a boolean counts.
+  sameOriginSafe = resolveEffectiveSameOriginSafe(
+    sameOriginSafe,
+    effectiveSameOriginSafe,
+  );
 
   // Resolve this VM's custom slug (if any) so a dedicated-origin seed uses the
   // slug host. The slug rides on cfg at Add time (the --vm-slug flag, validated
@@ -2875,6 +3119,12 @@ async function seedPreviewOrigin(cfg, appPort = VITE_PORT) {
   //      `sameOriginSafe: true`, and seeded `/__codeyam_preview` — which a
   //      remote browser then loads as `127.0.0.1 refused to connect`). Once
   //      stack.json exists, heal it forward to the dedicated origin.
+  //      `sameOriginSafe` here is the EFFECTIVE verdict, so this exception also
+  //      covers the case stack.json can never report: a project whose static
+  //      flag is legitimately absent (the Next.js scaffold default) that
+  //      escalated off the subpath at runtime after a hydration failure. The
+  //      caller passes the editor's own answer; without it this predicate read
+  //      `true` and declined to heal the one shape it was needed for.
   // Because every dashboard action (Reset / Update / Add / bootstrap-recovery)
   // re-runs this seed over cloud:up, either heal reaches every touch-point the
   // moment stack.json is present — closing the race without re-ordering
@@ -2970,11 +3220,14 @@ async function healPreviewOriginAtReady(cfg, appPort = VITE_PORT) {
     `READY auto-heal: ${cfg.instanceName} reports a not-same-origin-safe stack ` +
       `but a wrong-mode previewOrigin (${config.previewOrigin}); re-seeding...`,
   );
-  // Re-run the seed: stack.json is now readable, so the wrong-mode heal writes
-  // the dedicated origin into editor.local.json (a published `<N>-preview`
-  // tunnel URL, else the localhost bootstrap for the window before the monitor's
-  // first tick).
-  await seedPreviewOrigin(cfg, appPort);
+  // Re-run the seed with the verdict we just read, so WHETHER to heal and WHAT
+  // to write come from the same source. Passing it is what makes this heal reach
+  // the adaptive-default stacks it exists for: on a Next.js project whose
+  // `stack.json` omits `sameOriginSafe` (the scaffolded shape), the static read
+  // inside the seed answers `true` and re-writes the same-origin sentinel that
+  // just failed to hydrate. We got here precisely BECAUSE the editor said
+  // `false`, so `false` is the answer the seed must use.
+  await seedPreviewOrigin(cfg, appPort, false);
   // Tell the running server to re-read editor.local.json — no restart (the
   // footgun that killed VM7's live Claude session).
   const reload = runGcloud(
@@ -3372,7 +3625,16 @@ function promptForInstanceName(expected) {
   });
 }
 
-const STREAMED_SCRIPTS = ["scripts/gcp-bootstrap.sh", "scripts/gcp-project-bootstrap.sh"];
+// 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.
+const STREAMED_SCRIPTS = [
+  "scripts/gcp-bootstrap.sh",
+  "scripts/gcp-project-bootstrap.sh",
+  "scripts/lib/npm-pin.sh",
+];
 
 /** The configured editor branch to compare/stream streamed scripts against.
  *  Resolved from config (`resolveEditorConfig` → `editorBranch`, itself derived
@@ -4202,6 +4464,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 +4587,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);
 
@@ -5299,6 +5634,9 @@ async function cloudMain() {
 module.exports = {
   // pure helpers
   isSpawnTimeout,
+  gcloudCallTimeoutMs,
+  provisionFailureMessage,
+  GCLOUD_PROVISION_TIMEOUT_MS,
   agentEnvVarName,
   agentNpmPackage,
   AGENT_ENV_VARS,
@@ -5334,6 +5672,7 @@ module.exports = {
   resolveConfiguredAppPort,
   resolveSeedPreviewOrigin,
   previewSameOriginSafeFromStack,
+  resolveEffectiveSameOriginSafe,
   isRottedManagedPreviewOrigin,
   isWrongModePreviewOrigin,
   isSilentlyBrokenPreview,
@@ -5392,6 +5731,8 @@ module.exports = {
   FORWARD_ENV_KEYS_ENV,
   parseEditorComposeState,
   fetchInstanceState,
+  fetchPendingOperation,
+  wedgedOperationMessage,
   formatGcloudFailure,
   isTransientSshFailure,
   runGcloudSshWithRetry,
@@ -5449,6 +5790,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.
   }