@codeyam-editor/codeyam-editor 0.1.0-staging.gac4ca32 → 0.1.0-staging.gc0a93f0

package/npm/cloud.js

@@ -11,6 +11,7 @@
 
 const { spawn, spawnSync } = require("child_process");
 const fs = require("fs");
+const https = require("https");
 const os = require("os");
 const path = require("path");
 const readline = require("readline");
@@ -58,6 +59,7 @@ const {
   normalizePrincipal,
   resolveDefaultOperator,
   withDefaultOperator,
+  unauthorizableAddRefusal,
   accessFor,
   setAccess,
   addAccess,
@@ -75,9 +77,11 @@ const {
   regionFromZone,
   vmIngressInvocation,
   vmIngressStatusInvocation,
+  vmIngressGrantAccessInvocation,
   parseIngressStatusVerdict,
   parseIngressTeardownVerdict,
   selectIngressReconcileTargets,
+  selectIngressGrantOnlyTargets,
   selectOrphanIngressTargets,
   classifyOrphanDownResult,
   backendServicesListInvocation,
@@ -90,6 +94,11 @@ const {
   iapAccessInvocation,
   sharedIngressInvocation,
   backendServiceTimeoutInvocation,
+  FLEET_FIREWALL_RULE_NAMES,
+  fleetFirewallDescribeInvocation,
+  fleetFirewallConvergeInvocation,
+  firewallNeedsConverge,
+  firewallAdmitsPort,
 } = require("./ingress-invoke");
 // Shared fleet-roster writer/reader. `cloud:up` rosters the VM it just
 // provisioned so the dashboard, the cloudflared-monitor tunnel publisher, and
@@ -97,6 +106,10 @@ const {
 // edit (the invisible-VM gap improve38 closes). `readRoster` enumerates the
 // fleet for `reconcile-ingress`.
 const { addToRoster, readRoster } = require("./fleet-roster");
+// Tells a docker container-name conflict (a concurrent run already started this
+// 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");
 
 // =============================================================================
 // Pure helpers — every export here is unit-tested in cloud.test.js without
@@ -159,14 +172,34 @@ const KNOWN_FLAGS = [
   // default is loud — a tokenless VM cannot sync plan claims and must never
   // report healthy silently. Use only when push genuinely isn't wanted.
   "allow-no-git-credentials",
+  // Provision the VM in admin mode: forward CODEYAM_ADMIN=1 into the container
+  // so the Home-tab Setup door renders. Equivalent to `CODEYAM_ADMIN=1 npm run
+  // cloud:up …`; absent = strict non-admin (the safe default). Survives
+  // re-provision because it rides the compose-render substitution, unlike a
+  // manual VM compose edit.
+  "admin",
+  // GCE machine type for the VM (e.g. n2-standard-4, e2-standard-4). Persisted
+  // in cloud.json so a later bare `cloud:up` keeps it. Defaults to
+  // DEFAULT_FLEET_MACHINE_TYPE. The whole point of exposing this is fleet
+  // scale-out: the region's E2_CPUS quota (72 in us-central1) caps the fleet at
+  // ~14 e2-standard-4 VMs, while N2_CPUS/N2D_CPUS (200, unused) leave room for
+  // 30 — so the fleet defaults to N2 and this flag lets a caller override.
+  "machine-type",
 ];
 
 // Flags that take no value (presence = true). parseFlags must not demand a
 // value for these or `--no-tunnel` would error "requires a value".
-const BOOLEAN_FLAGS = ["no-tunnel", "skip-setup", "list", "allow-no-git-credentials"];
+const BOOLEAN_FLAGS = ["no-tunnel", "skip-setup", "list", "allow-no-git-credentials", "admin"];
 
 const FIREWALL_RULE_NAME = "codeyam-editor-iap-ssh";
 const INSTANCE_TAG = "codeyam-editor";
+// Default GCE machine type for fleet VMs. N2 (not E2) because the fleet must
+// reach 30 VMs: us-central1 E2_CPUS quota is 72, so 30 × e2-standard-4 (120
+// vCPU) + the operator host exceed it and cap the fleet at ~14 regardless of
+// code — while N2_CPUS/N2D_CPUS are 200 and unused, leaving headroom for 30 ×
+// n2-standard-4. Override per-VM with `--machine-type`. See the vm--scale-
+// fleet-to-30-vms plan for the measured quota rationale.
+const DEFAULT_FLEET_MACHINE_TYPE = "n2-standard-4";
 const EDITOR_PORT = 14199;
 const VITE_PORT = 5173;
 
@@ -481,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.
@@ -550,6 +605,32 @@ function isWrongModePreviewOrigin(localJson, sameOriginSafe) {
   return LOOPBACK_ORIGIN_RE.test(origin);
 }
 
+/** Decide whether a VM is presenting as HEALTHY while its Live Preview is
+ *  silently dead — the VM-9 failure mode. The heal
+ *  (`reconcilePreviewOriginToSlugHost`) fixes the mechanism; this predicate is
+ *  the smoke detector that catches a FUTURE mechanism gap (a new stack shape, a
+ *  new provisioning path) by observation instead of by a user noticing a blank
+ *  iframe days later.
+ *
+ *  Input is the editor's own `/api/config` payload — the effective truth table
+ *  (`previewSameOriginSafe` + the resolved `previewOrigin`), not a
+ *  re-derivation from stack.json over ssh. True iff the stack is NOT
+ *  same-origin-safe AND its effective previewOrigin is one a remote browser can
+ *  never load (the `/__codeyam_preview` sentinel, any relative path, or a
+ *  loopback origin) — i.e. exactly `isWrongModePreviewOrigin`'s wrong-mode
+ *  condition, evaluated against the live config rather than editor.local.json.
+ *  Composing the two keeps ONE definition of "wrong-mode origin" in this file.
+ *
+ *  Deliberately conservative: a missing/unparseable payload, an absent
+ *  `previewSameOriginSafe`, or a legitimate same-origin-safe stack on the
+ *  subpath all return false. Absence of evidence is never a false alarm — the
+ *  caller renders "unknown" instead. Pure. */
+function isSilentlyBrokenPreview(apiConfig) {
+  if (!apiConfig || typeof apiConfig !== "object") return false;
+  if (apiConfig.previewSameOriginSafe !== false) return false;
+  return isWrongModePreviewOrigin(apiConfig, false);
+}
+
 /** Read the operator-laptop cloudflared-urls.json sidecar. Missing/unparseable
  *  → {} (the monitor may not have run yet; the seed falls back to localhost). */
 function readCloudflaredUrls() {
@@ -747,6 +828,28 @@ function buildEditorLocalEnvPatch(localEnv, agent) {
   return { provider: agent, env: { [varName]: value } };
 }
 
+/** Build the editor.local.json patch that seeds a GREENFIELD project's
+ *  `projectTitle` so its live identity resolves to the real project name from
+ *  first boot. A greenfield project (`--new-project <name>`, no clientRepo) has
+ *  no origin remote and is bind-mounted at /workspace on the VM, so the editor's
+ *  identity resolver would otherwise fall back to the bare mount basename
+ *  "workspace" — which the fleet dashboard then reads as a permanent false
+ *  project-dir-drift. Seeding `projectTitle` (deep-merged over editor.json on the
+ *  VM) makes `project_identity::read` prefer the real name.
+ *
+ *  Returns `null` for a clone (a repo Add already labels from its origin
+ *  basename, and re-seeding a clone's title would be wrong) or when no
+ *  greenfield name is available, so the caller can no-op without an SSH round
+ *  trip. Pure — mirrors buildEditorLocalEnvPatch so the decision is unit-tested
+ *  without a live VM. */
+function buildGreenfieldTitlePatch(cfg = {}) {
+  const p = resolveProject(cfg);
+  if (!p.greenfield) return null;
+  const name = typeof p.name === 'string' ? p.name.trim() : '';
+  if (!name) return null;
+  return { projectTitle: name };
+}
+
 /** Parse `docker compose ps --format json` (compose v2 — one JSON object per
  *  line) and return the editor service's `State` string, or null when the
  *  service is absent / output is unparseable. Two callers shared an identical
@@ -769,6 +872,79 @@ function parseEditorComposeState(stdout) {
   return null;
 }
 
+/** Decide whether `cloud:up`'s abort handler may delete the instance it is
+ *  unwinding. Pure `{ createdThisRun, containerUp, rostered, probeInconclusive }
+ *  → 'delete' | 'keep'`, matching the `reapVerdict` / `reattachVerdict` /
+ *  `reconcileRosteredVm` pattern in npm/fleet-cleanup.js, so the whole matrix is
+ *  exhaustively testable without a VM.
+ *
+ *  `createdThisRun` stays a NECESSARY condition — never delete an instance this
+ *  run did not create — but 2026-08-07 proved it is not SUFFICIENT. It answers
+ *  "did I create this?", not "is it safe to destroy?", and in a concurrent
+ *  provision race the losing run legitimately owns the flag while the winner has
+ *  already brought the VM up and rostered it. Deleting there destroyed VM-4 and
+ *  VM-5. So authorization also requires CURRENT-STATE evidence that the VM is
+ *  out of service:
+ *
+ *  - `containerUp` — the editor container is running (per the compose-ps probe).
+ *    A VM serving an editor is in use by definition.
+ *  - `rostered` — the VM is in the fleet roster, the operator-visible source of
+ *    truth. Note this is true whether the winning run or THIS run rostered it;
+ *    either way the VM is visible in the dashboard and removable in one command,
+ *    so it is not the silent orphan teardown exists to prevent.
+ *  - `probeInconclusive` — liveness could not be determined. This must fail
+ *    SAFE: a failing probe is how we reach the abort handler in the first place,
+ *    so it can never count as evidence the VM is dead. An orphan costs one
+ *    `npm run cloud:destroy`; a wrong delete costs a 15-40 minute rebuild plus
+ *    any unpushed work on the VM. */
+function abortTeardownDecision({ createdThisRun, containerUp, rostered, probeInconclusive } = {}) {
+  if (!createdThisRun) return "keep";
+  if (probeInconclusive) return "keep";
+  if (containerUp) return "keep";
+  if (rostered) return "keep";
+  return "delete";
+}
+
+/** Gather the CURRENT-STATE inputs {@link abortTeardownDecision} needs, so the
+ *  abort handler reads gather → decide → act instead of inlining probes among
+ *  the delete calls.
+ *
+ *  Only runs the probes when `createdThisRun` is true — the decision is `keep`
+ *  regardless otherwise, and an abort path should not spend SSH round trips
+ *  proving something it already knows. In that case it returns the
+ *  probe-inconclusive shape, which is the safe default at every layer.
+ *
+ *  Both lookups are wrapped: a throwing probe or an unreadable roster must fail
+ *  SAFE (toward `keep`), never take a second exception path into the delete.
+ *  `deps` is injectable so the matrix is unit-tested without a VM. */
+function probeAbortTeardownState(cfg, createdThisRun, deps = {}) {
+  if (!createdThisRun) {
+    return { containerUp: false, rostered: false, probeInconclusive: true };
+  }
+  const probe = deps.probeEditorComposeState || probeEditorComposeState;
+  const roster = deps.readRoster || readRoster;
+  const resolveVm = deps.resolveFleetVmNumber || resolveFleetVmNumber;
+  const log = deps.log || ((m) => console.error(m));
+
+  let liveness = { state: null, inconclusive: true };
+  try {
+    liveness = probe(cfg);
+  } catch (e) {
+    log(`  (liveness probe failed: ${e && e.message})`);
+  }
+  let rostered = false;
+  try {
+    const vm = resolveVm(cfg.instanceName);
+    rostered = vm != null && (roster() || []).includes(vm);
+  } catch { /* unreadable roster — treated as not-rostered; liveness still guards */ }
+
+  return {
+    containerUp: liveness.state === "running",
+    rostered,
+    probeInconclusive: liveness.inconclusive,
+  };
+}
+
 /** Translate one of the wrapper's verbs into the exact `gcloud` argv. The
  *  switch's job is to keep every per-verb command shape in one reviewable
  *  place — tests assert the arrays without ever spawning a process. */
@@ -789,7 +965,7 @@ function buildGcloudArgs(verb, cfg = {}, extras = {}) {
       return [
         "compute", "instances", "create", instanceName,
         "--project", project, "--zone", zone,
-        "--machine-type=e2-standard-4",
+        `--machine-type=${cfg.machineType || DEFAULT_FLEET_MACHINE_TYPE}`,
         "--image-family=debian-12",
         "--image-project=debian-cloud",
         "--boot-disk-size=100GB",
@@ -804,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",
@@ -889,11 +1078,94 @@ function buildGcloudArgs(verb, cfg = {}, extras = {}) {
 // real use. Unit tests pin their exports so a refactor cannot drop them.
 // =============================================================================
 
+// Per-call wall-clock budget for a single gcloud / SSH invocation. A hung
+// `gcloud describe` (metadata / IAP hiccup) used to block the whole
+// `cloud:reconcile-ingress` sweep forever — the only timeout in the reconcile
+// path was the outer 10-minute exec budget in the dashboard, and that never
+// cascaded to the orphaned descendants. Bounding every per-call spawn well under
+// that outer budget means a single hang trips HERE first: the call returns a
+// timed-out result (formatGcloudFailure renders it), the sweep skips that VM,
+// and no descendant is left hanging to pile up. Shared by runGcloud and the two
+// 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
+// blocking `runGcloud("ssh-script")` call, so it inherited GCLOUD_CALL_TIMEOUT_MS
+// (a budget whose own comment scopes it to "any single describe/update/SSH
+// probe"). That SIGTERMd the gcloud child mid-clone; `spawnSync` then returned
+// `status: null`, which `!== 0`, so the timeout was indistinguishable from a
+// genuine remote failure and the caller's abort path DELETED A COMPLETELY
+// HEALTHY VM.
+//
+// Observed twice: 2026-07-28 on client repo `lets-go-compost-portal` (a root
+// postinstall of `playwright install chromium`, ~293 MB), and 2026-07-29
+// provisioning six self-host `codeyam-editor` VMs, whose clone alone exceeds the
+// probe budget — all six were built, torn down mid-clone, and reported as
+// "scripts/gcp-project-bootstrap.sh failed on the VM".
+//
+// The install is now DETACHED (projectBootstrapLaunchCommand + a re-attaching
+// follow loop, outcome read from VM-side state), so no single call carries the
+// whole install any more. This constant is therefore the OVERALL deadline across
+// re-attaches — the point at which we stop waiting on a still-healthy VM and say
+// exactly that. Deliberately well above the outer reconcile budget: a long remote
+// install is not a step in a sweep, so the sweep-relative ceiling that governs
+// GCLOUD_CALL_TIMEOUT_MS does not apply to it.
+const PROJECT_BOOTSTRAP_TIMEOUT_MS = 40 * 60 * 1000;
+
+/** Whether a `spawnSync` result is a LOCAL timeout kill rather than a remote
+ *  failure. `spawnSync` reports a timeout as `status: null` plus an ETIMEDOUT
+ *  error, so a bare `status !== 0` check conflates the two — which is what made
+ *  a timed-out bootstrap look like a broken one. Pure. */
+function isSpawnTimeout(result) {
+  if (!result) return false;
+  if (result.status !== null && result.status !== undefined) return false;
+  const code = result.error && result.error.code;
+  return code === "ETIMEDOUT" || result.signal === "SIGTERM";
+}
+
 function runGcloud(args, opts = {}) {
   return spawnSync("gcloud", args, {
     stdio: opts.stdio || "inherit",
     input: opts.input,
     encoding: opts.encoding || "utf8",
+    timeout: opts.timeout != null ? opts.timeout : GCLOUD_CALL_TIMEOUT_MS,
   });
 }
 
@@ -924,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) {
@@ -999,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
@@ -1080,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;
@@ -1091,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,
@@ -1496,7 +1894,320 @@ function bootstrapLogTail(cfg, lines = 40) {
   return String(r.stdout || "").trim() || "(log unavailable)";
 }
 
-async function ensureProjectBootstrapped(cfg) {
+// ─── Detached PROJECT bootstrap ──────────────────────────────────────────────
+//
+// The VM bootstrap above solved a problem the PROJECT bootstrap still had: read
+// success and failure from VM-SIDE STATE, never from the SSH exit code, so a
+// dropped follow-session over a healthy VM is not misreported as "failed on the
+// VM". The project bootstrap ran instead as ONE blocking ssh-script call, so a
+// local budget elapsing (or an SSH pipe breaking) was indistinguishable from a
+// genuine remote failure and the caller's abort path DELETED A HEALTHY VM.
+// Raising the budget alone just moves the cliff; these helpers remove it by
+// mirroring the VM-bootstrap contract — detached launch, re-attaching follow
+// loop, VM-side outcome probe.
+//
+// All VM-side paths are keyed by repo name so two projects on one VM never
+// collide, and they sit beside the `.done` marker projectBootstrapDoneMarker
+// already defines. Pure string builders (like their VM-bootstrap counterparts)
+// so the whole grammar is unit-testable without a live VM.
+function projectBootstrapScriptPath(repoName) {
+  return `$HOME/.codeyam-project-bootstrap-${repoName}.sh`;
+}
+function projectBootstrapRunnerPath(repoName) {
+  return `$HOME/.codeyam-project-bootstrap-${repoName}-run.sh`;
+}
+function projectBootstrapLogPath(repoName) {
+  return `$HOME/.codeyam-project-bootstrap-${repoName}.log`;
+}
+function projectBootstrapPidPath(repoName) {
+  return `$HOME/.codeyam-project-bootstrap-${repoName}.pid`;
+}
+// The runner's recorded EXIT STATUS. Deliberately `.status`, NOT `.done`:
+// `.done` is already taken by scripts/gcp-project-bootstrap.sh's own terminal
+// SUCCESS marker (a timestamp, written only after `set -euo pipefail` carried
+// every step through — see projectBootstrapDoneMarker). Reusing `.done` for an
+// exit code would overwrite the success signal that both improve40's false-skip
+// fix and the follow loop below depend on. Two files, two distinct meanings:
+// `.done` = "the script reached its last line", `.status` = "the runner exited,
+// here is its code".
+function projectBootstrapStatusPath(repoName) {
+  return `$HOME/.codeyam-project-bootstrap-${repoName}.status`;
+}
+const PROJECT_BOOTSTRAP_LAUNCHED_MARKER = "CODEYAM_PROJECT_BOOTSTRAP_LAUNCHED";
+const PROJECT_BOOTSTRAP_STATUS_MARKER = "CYPROJ";
+// One follow session caps at 15 min; the overall wait caps at
+// PROJECT_BOOTSTRAP_TIMEOUT_MS across re-attaches before we bail loudly with
+// the VM-side log location. Unlike the VM-bootstrap follow loop — whose follow
+// calls inherit the 120 s probe budget and so re-attach every two minutes over
+// a ~14-min build — the project follow call below is given an explicit local
+// budget just above this remote deadline, so a long install streams in one
+// session instead of churning re-attaches.
+const PROJECT_BOOTSTRAP_FOLLOW_SECS = 900;
+const PROJECT_BOOTSTRAP_FOLLOW_TIMEOUT_MS = (PROJECT_BOOTSTRAP_FOLLOW_SECS + 60) * 1000;
+
+// The tiny VM-side wrapper the detached launch execs: run the real bootstrap,
+// redirect all output to the per-repo log, and record the exit status in the
+// `.status` sentinel — the single source of truth for "did the runner exit, and
+// with what?" once the SSH follow-session is gone. Contains NO secrets (tokens
+// arrive via the launch env prefix, never written to disk).
+function projectBootstrapRunnerScript(repoName) {
+  return [
+    "#!/usr/bin/env bash",
+    "# Detached project-bootstrap runner (written by npm/cloud.js",
+    "# ensureProjectBootstrapped). Survives SSH disconnect: the laptop only",
+    "# *follows* the log below; this process keeps running under its own session",
+    "# if the follow drops. Records its own PID so the status probe can check",
+    "# liveness via `kill -0` (a `pgrep` on the script path would also match the",
+    "# probe command itself).",
+    `echo "$$" > "${projectBootstrapPidPath(repoName)}"`,
+    `bash "${projectBootstrapScriptPath(repoName)}" "$@" > "${projectBootstrapLogPath(repoName)}" 2>&1`,
+    "status=$?",
+    `echo "$status" > "${projectBootstrapStatusPath(repoName)}"`,
+    `rm -f "${projectBootstrapPidPath(repoName)}"`,
+    "",
+  ].join("\n");
+}
+
+// Build the remote command that (1) materializes the bootstrap script + runner
+// on the VM, (2) clears the stale sentinels, (3) launches the runner DETACHED
+// (`nohup setsid`, new session, stdio to /dev/null) so it outlives the SSH
+// session, and (4) prints a launched marker. The detach is the durable fix: the
+// install no longer dies when the laptop's SSH pipe breaks, and the VM is no
+// longer torn down because it did.
+//
+// BOTH sentinels are cleared, `.status` and `.done`. Clearing `.done` is what
+// 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, 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)}`,
+  ].join(" && ");
+  const launch =
+    `${envPrefix}nohup setsid bash ${projectBootstrapRunnerPath(repoName)} ${argsString}`.trimEnd() +
+    ` </dev/null >/dev/null 2>&1 &`;
+  return `${writes}; ${launch} echo ${PROJECT_BOOTSTRAP_LAUNCHED_MARKER}`;
+}
+
+// Build the remote command that FOLLOWS the detached install: tail the log live
+// for the operator, polling for the `.status` sentinel, and exit when the runner
+// finishes OR a per-session deadline elapses. If the SSH session drops
+// mid-follow this command dies but the detached install keeps going — the caller
+// then re-attaches.
+function projectBootstrapFollowCommand(repoName, deadlineSecs = PROJECT_BOOTSTRAP_FOLLOW_SECS) {
+  const log = projectBootstrapLogPath(repoName);
+  const status = projectBootstrapStatusPath(repoName);
+  return [
+    `touch ${log}`,
+    `tail -n +1 -F ${log} 2>/dev/null & TP=$!`,
+    `waited=0`,
+    `while [ ! -f ${status} ]; do ` +
+      `sleep 3; waited=$((waited+3)); ` +
+      `if [ "$waited" -ge ${deadlineSecs} ]; then kill "$TP" 2>/dev/null; exit 0; fi; ` +
+      `done`,
+    `sleep 1`,
+    `kill "$TP" 2>/dev/null`,
+  ].join("; ");
+}
+
+// Build the remote command that reports terminal VM state in one parseable
+// line: whether the script's terminal `.done` marker exists, the runner's
+// recorded exit status (or `none`), and whether the runner is still alive.
+// Cheap — runs over ssh-probe.
+function projectBootstrapStatusCommand(repoName) {
+  const pid = projectBootstrapPidPath(repoName);
+  const status = projectBootstrapStatusPath(repoName);
+  // Liveness via the runner's PID file + `kill -0`, NOT pgrep: the status
+  // command's own argv contains the bootstrap path, so a `pgrep -f` on it would
+  // match this very probe and always report running. A stale PID file from a
+  // killed runner reads as not-running because `kill -0` fails.
+  return [
+    `done=no; [ -f ${projectBootstrapDoneMarker(repoName)} ] && done=yes`,
+    `st=none; [ -f ${status} ] && st=$(cat ${status} 2>/dev/null)`,
+    `run=no; if [ -f ${pid} ]; then p=$(cat ${pid} 2>/dev/null); ` +
+      `{ [ -n "$p" ] && kill -0 "$p" 2>/dev/null; } && run=yes; fi`,
+    `echo "${PROJECT_BOOTSTRAP_STATUS_MARKER} done=$done status=$st running=$run"`,
+  ].join("; ");
+}
+
+// Parse the single status line emitted by projectBootstrapStatusCommand.
+// Returns `{ done, status, running }` or null when no status line is present
+// (e.g. the probe ssh itself failed and produced no stdout).
+function parseProjectBootstrapStatus(stdout) {
+  const m = String(stdout || "").match(
+    new RegExp(`${PROJECT_BOOTSTRAP_STATUS_MARKER} done=(\\S+) status=(\\S+) running=(\\S+)`),
+  );
+  if (!m) return null;
+  return { done: m[1], status: m[2], running: m[3] };
+}
+
+// Decide the project-bootstrap outcome from VM-side state alone — never the SSH
+// exit code. The `.done` marker is the real artifact (the script writes it only
+// after `set -euo pipefail` carried every step to success), so its presence is
+// success regardless of how the follow session ended — the same reasoning that
+// makes the docker image authoritative for the VM bootstrap. A live runner means
+// "re-attach". A recorded exit status without the marker means the install ran
+// and failed. Nothing at all means it was never started (or the probe could not
+// see it).
+function decideProjectBootstrapOutcome(status) {
+  if (!status) return "absent";
+  const { done, status: exitStatus, running } = status;
+  if (done === "yes") return "success";
+  if (running === "yes") return "running";
+  if (exitStatus && exitStatus !== "none") return "failed";
+  return "absent";
+}
+
+// Reduce one follow-loop iteration to an action: "success" | "failed" |
+// "timeout" | "reattach". Extracted as a pure function because its PRECEDENCE is
+// load-bearing — it decides whether an operator is told a VM is broken:
+//
+//   • success and failed outrank the deadline. Otherwise the final poll of a
+//     slow-but-successful bootstrap reports a timeout, and the operator is sent
+//     to reconcile a VM that actually finished.
+//   • a still-running install past the deadline is a TIMEOUT, never a failure.
+//     That is the VM-8 case: healthy VM, still installing, and saying so is what
+//     gets the add classified retryable instead of destroyed.
+//   • an unseen runner ("absent") before the deadline re-attaches rather than
+//     failing — "I could not see it" is not "it broke" — but is still bounded by
+//     the deadline so the loop cannot spin forever.
+function decideProjectBootstrapFollowAction({ outcome, now, deadline } = {}) {
+  if (outcome === "success") return "success";
+  if (outcome === "failed") return "failed";
+  if (now >= deadline) return "timeout";
+  return "reattach";
+}
+
+// Probe the VM for the detached project bootstrap's terminal state and reduce it
+// to a single outcome string ("success" | "failed" | "running" | "absent").
+// Used both for the idempotent re-attach decision and after each follow session.
+function probeProjectBootstrapOutcome(cfg, repoName) {
+  const r = runGcloud(
+    buildGcloudArgs("ssh-probe", cfg, { command: projectBootstrapStatusCommand(repoName) }),
+    { stdio: ["ignore", "pipe", "pipe"] },
+  );
+  return decideProjectBootstrapOutcome(parseProjectBootstrapStatus(r.stdout));
+}
+
+/** Assemble the env forwarded into the project-bootstrap shell on the VM.
+ *  Extracted from ensureProjectBootstrapped so its CONDITIONAL keys are testable
+ *  without a VM — previously you could not assert "FLEET_DOMAIN is omitted for a
+ *  non-fleet project" or "a re-provision without --admin stays non-admin"
+ *  without invoking the whole gcloud-touching bootstrap.
+ *
+ *  Keys, and why each is here:
+ *    GITHUB_TOKEN                  — clone a private client repo.
+ *    CY_GIT_USER_{NAME,EMAIL}      — rendered into the compose file, then written
+ *                                    to `git config --global` by the entrypoint so
+ *                                    plan_claim_refs::create_claim's commit-tree
+ *                                    call succeeds. Empty is legitimate (a CI
+ *                                    runner with no author); the entrypoint warns
+ *                                    and proceeds, so the keys stay present.
+ *    FLEET_DOMAIN                  — ONLY for a numbered fleet VM with a domain
+ *                                    configured, so the compose render publishes
+ *                                    on 0.0.0.0 for the LB NEG. Omitted entirely
+ *                                    otherwise, preserving the loopback-only
+ *                                    publish a plain client project expects.
+ *    <forwarded launch-form keys>  — DATABASE_URL et al, whitelisted by the
+ *                                    dashboard via CY_FORWARD_ENV_KEYS, so the
+ *                                    bootstrap-time `npm run setup` sees them on
+ *                                    the first try. Empty on plain `cloud:up`.
+ *    CODEYAM_ADMIN                 — the Home-tab Setup door. Defaults to the
+ *                                    strict non-admin "".
+ *
+ *  Later spreads win, matching the original inline assembly exactly. `deps` lets
+ *  a test supply the token and git identity instead of reading the real
+ *  environment and shelling out to git. */
+function projectBootstrapEnv(cfg = {}, { env = process.env, githubToken, gitIdentity } = {}) {
+  const git = gitIdentity || resolveLaptopGitIdentity();
+  const out = {
+    GITHUB_TOKEN: githubToken !== undefined ? githubToken : resolveGithubToken(),
+    CY_GIT_USER_NAME: git.name,
+    CY_GIT_USER_EMAIL: git.email,
+  };
+  const ingressPlan = ingressWiringPlan(cfg, env);
+  if (ingressPlan.wire) out.FLEET_DOMAIN = ingressPlan.domain;
+  Object.assign(out, resolveSetupForwardEnv(env));
+  Object.assign(out, buildProvisionEnv(env, cfg));
+  return out;
+}
+
+// Fetch the tail of the VM-side project-bootstrap log for an actionable failure
+// message — the operator sees WHY the install failed, not a bare exit code.
+function projectBootstrapLogTail(cfg, repoName, lines = 40) {
+  const r = runGcloud(
+    buildGcloudArgs("ssh-probe", cfg, {
+      command: `tail -n ${lines} ${projectBootstrapLogPath(repoName)} 2>/dev/null`,
+    }),
+    { stdio: ["ignore", "pipe", "pipe"] },
+  );
+  return String(r.stdout || "").trim() || "(log unavailable)";
+}
+
+/** Assemble the extra provision-time env forwarded into the bootstrap shell,
+ *  where it feeds the compose-render substitution. Currently just the admin
+ *  toggle: CODEYAM_ADMIN gates the Home-tab Setup door and is read from the
+ *  editor-server process env (handlers.rs::admin_enabled, strict literal "1").
+ *  The operator opts in with `CODEYAM_ADMIN=1 npm run cloud:up …` or `--admin`
+ *  (which lands as cfg.admin); anything else forwards "" so a normal launch —
+ *  and a re-provision without the flag — is strict non-admin. Pure over its
+ *  inputs so cloud.test.js can pin it without touching gcloud. */
+function buildProvisionEnv(env = process.env, flags = {}) {
+  const admin = flags.admin === true || env.CODEYAM_ADMIN === "1";
+  return { CODEYAM_ADMIN: admin ? "1" : "" };
+}
+
+/** Build the one-shot SSH shell command that reconciles a running VM's admin
+ *  mode without a full re-provision: rewrite the rendered compose's
+ *  CODEYAM_ADMIN line to `value` — or insert it under `environment:` on a legacy
+ *  VM whose compose predates the placeholder — then recreate the editor service
+ *  so admin_enabled() re-reads it. `value` is always "1" or "" (the caller
+ *  normalizes), so inlining it into sed is safe. Pure/string-only so
+ *  cloud.test.js can assert its shape without SSHing. */
+function buildReconcileAdminCommand(repoName, value) {
+  const f = "docker-compose.cloud.yml";
+  const entry = `      - CODEYAM_ADMIN=${value}`;
+  // Capture only the leading indentation (\1) and re-emit the literal key, so a
+  // value that starts with a digit (e.g. "1") never lands right after the
+  // backreference — `\11` would be read by sed as group 11, not `\1` + "1".
+  return (
+    `cd ~/projects/${repoName} && ` +
+    `if grep -qE '^[[:space:]]*- CODEYAM_ADMIN=' ${f}; then ` +
+    `sed -i -E 's#^([[:space:]]*)- CODEYAM_ADMIN=.*#\\1- CODEYAM_ADMIN=${value}#' ${f}; ` +
+    `else ` +
+    `sed -i -E 's#^([[:space:]]*environment:[[:space:]]*)$#\\1\\n${entry}#' ${f}; ` +
+    `fi && ` +
+    `docker compose -f ${f} up -d editor`
+  );
+}
+
+async function ensureProjectBootstrapped(cfg, { sleepFn } = {}) {
   const repoName = resolveProject(cfg).name;
   console.error(`Checking project bootstrap state for ${repoName}...`);
   // Gate on the TERMINAL completion marker the script writes as its very last
@@ -1525,44 +2236,162 @@ async function ensureProjectBootstrapped(cfg) {
   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);
-  // Forward the laptop's git author identity so the rendered compose file
-  // carries CY_GIT_USER_{NAME,EMAIL} → the entrypoint writes them to
-  // `git config --global` → plan_claim_refs::create_claim's commit-tree call
-  // succeeds. Empty strings are fine (laptop has no identity, e.g. a CI
-  // runner); the entrypoint warns and proceeds.
-  const laptopGit = resolveLaptopGitIdentity();
-  // Forward the operator's launch-form env keys (DATABASE_URL, etc.) into the
-  // bootstrap shell so the bootstrap-time `npm run setup` sees them on the
-  // first try — without this, Prisma `db:push`/`db:seed` fail for lack of
-  // env and the bootstrap's fail-soft branch leaves the app schema-less until
-  // the post-add `reapplyVmEnv` re-fires setup. See
-  // `improve37-launch-form-env-injected-into-cloud-up-bootstrap-not-just-applied-after`.
-  // Whitelisted by the dashboard via CY_FORWARD_ENV_KEYS — empty on the
-  // standalone `cloud:up` path, so that flow is unchanged.
-  const forwardEnv = resolveSetupForwardEnv();
-  // Forward the fleet domain so the bootstrap's compose render publishes the
-  // editor/app ports on 0.0.0.0 (the LB NEG reaches them on the VM's internal
-  // IP) instead of loopback-only. Only when a fleet domain is configured AND
-  // this is a numbered fleet VM — a non-fleet client project keeps the
-  // loopback-only publish (legacy parity). Absent ⇒ key omitted entirely.
-  const ingressEnv = {};
-  const ingressPlan = ingressWiringPlan(cfg);
-  if (ingressPlan.wire) ingressEnv.FLEET_DOMAIN = ingressPlan.domain;
-  const command = sshScriptCommand(scriptBody, scriptArgs, {
-    GITHUB_TOKEN: resolveGithubToken(),
-    CY_GIT_USER_NAME: laptopGit.name,
-    CY_GIT_USER_EMAIL: laptopGit.email,
-    ...ingressEnv,
-    ...forwardEnv,
-  });
-  const result = runGcloud(
-    buildGcloudArgs("ssh-script", cfg, { command }),
-    { stdio: "inherit" },
+  // 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
+  // omitted. Extracted so those conditionals are testable without a VM.
+  const bootstrapEnv = projectBootstrapEnv(cfg);
+
+  // Idempotent re-attach: a prior cloud:up whose follow-session dropped may have
+  // left a detached install still running. Converge on it instead of starting a
+  // second `npm install` on top of the first.
+  //
+  // NOTE the deliberate asymmetry with ensureBootstrapped, which DOES return
+  // early on an outcome of "success". There, the done-probe and the outcome probe
+  // read the same artifact (the docker image), so they always agree. Here the
+  // done-probe above is a strictly STRONGER three-way AND (`.done` marker +
+  // ~/projects/<repo>/.codeyam + docker-compose.cloud.yml) than this probe's
+  // `.done`-alone success, and it has already said no. Honoring a bare `.done`
+  // here would re-open the improve40 VM-7 false-skip from the other side, so only
+  // "running" short-circuits the launch.
+  const initial = probeProjectBootstrapOutcome(cfg, repoName);
+  if (initial === "running") {
+    console.error("  ↺ a detached project bootstrap is already in progress — re-attaching to its log...");
+  } else {
+    // "absent" (never started), "failed" (a prior run died), or "success" (a bare
+    // marker the stricter done-probe rejected) → (re)launch a fresh detached
+    // 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, bootstrapLibs);
+    const launched = await runGcloudSshWithRetry(
+      "ssh-script",
+      cfg,
+      { command: launch },
+      { stdio: ["ignore", "pipe", "pipe"], label: "project bootstrap launch", sleepFn },
+    );
+    if (isSpawnTimeout(launched)) {
+      // The LOCAL budget elapsed and we SIGTERMd the gcloud child. Say so:
+      // the launch is a short write-and-detach, so this is an SSH-reachability
+      // problem, NOT a broken bootstrap script — and the VM may be perfectly
+      // healthy. Conflating the two is what destroyed VM-8.
+      throw new Error(
+        `launching the detached project bootstrap exceeded the local gcloud call budget ` +
+          `and was SIGTERMd locally — the VM may be healthy and simply unreachable over SSH ` +
+          `right now. Re-run to re-attach (each bootstrap step is skip-on-exists).`,
+      );
+    }
+    if (launched.status !== 0) {
+      throw new Error(
+        `failed to launch the detached project bootstrap on the VM (gcloud ssh exit ${launched.status}).\n` +
+          formatGcloudFailure(launched),
+      );
+    }
+  }
+
+  // Follow the live log, re-attaching across any follow-session drops, until the
+  // VM reports a terminal state or the overall deadline elapses. Success and
+  // failure are read from VM state (the `.done` marker + the `.status` sentinel),
+  // never the SSH exit code — so "my laptop's SSH dropped" or "a heavy npm
+  // install outran a local budget" no longer masquerades as a broken bootstrap
+  // and no longer gets a healthy VM deleted.
+  const deadline = Date.now() + PROJECT_BOOTSTRAP_TIMEOUT_MS;
+  for (;;) {
+    runGcloud(
+      buildGcloudArgs("ssh-script", cfg, { command: projectBootstrapFollowCommand(repoName) }),
+      { stdio: "inherit", timeout: PROJECT_BOOTSTRAP_FOLLOW_TIMEOUT_MS },
+    );
+    const outcome = probeProjectBootstrapOutcome(cfg, repoName);
+    const action = decideProjectBootstrapFollowAction({
+      outcome,
+      now: Date.now(),
+      deadline,
+    });
+    if (action === "success") {
+      console.error(`  ✓ ${repoName} bootstrap complete`);
+      return;
+    }
+    if (action === "failed") {
+      const tail = projectBootstrapLogTail(cfg, repoName);
+      throw new Error(
+        "scripts/gcp-project-bootstrap.sh failed on the VM. " +
+          `Last lines of ${projectBootstrapLogPath(repoName)}:\n${tail}`,
+      );
+    }
+    if (action === "timeout") {
+      // The install is STILL RUNNING on a healthy VM and we simply stopped
+      // waiting. This message is the signature npm/fleet-add-failure.js keys on
+      // to classify the add as `project-bootstrap-timeout` (retryable) instead of
+      // the non-retryable generic cloud-up-failed that tore down VM-8.
+      throw new Error(
+        `project bootstrap exceeded the local ${Math.round(PROJECT_BOOTSTRAP_TIMEOUT_MS / 60000)}-minute budget ` +
+          `— the VM and its detached bootstrap may be healthy and still running. ` +
+          `Re-run to re-attach (each bootstrap step is skip-on-exists), or inspect ` +
+          `${projectBootstrapLogPath(repoName)} on the VM.`,
+      );
+    }
+    // action === "reattach": the follow session ended but the install is alive
+    // (or the probe could not see it yet). Re-attach to its log.
+    console.error("  ↺ follow session ended but the project bootstrap is still running — re-attaching...");
+  }
+}
+
+/** Run the compose-ps liveness probe over SSH and report BOTH the editor
+ *  service's state and whether the probe itself could be trusted.
+ *
+ *  The `|| true` keeps the remote pipeline's exit status 0 whenever SSH itself
+ *  worked, so a non-zero `status` means the transport failed (auth/SSH/IAP) —
+ *  not that the container is down. Callers that must fail safe (the abort
+ *  teardown) need that distinction; `parseEditorComposeState` alone collapses
+ *  "no container" and "could not ask" into the same `null`.
+ *
+ *  Returns `{ state, inconclusive }` where `state` is the compose `State` string
+ *  (`"running"`, `"exited"`, …) or null when the service is absent, and
+ *  `inconclusive` is true only for a transport failure. */
+function probeEditorComposeState(cfg) {
+  const repoName = resolveProject(cfg).name;
+  const composeCmd = `docker compose -f docker-compose.cloud.yml`;
+  const probe = runGcloud(
+    buildGcloudArgs("ssh-probe", cfg, {
+      command: `cd ~/projects/${repoName} 2>/dev/null && ${composeCmd} ps --format json 2>/dev/null || true`,
+    }),
+    { stdio: ["ignore", "pipe", "ignore"] },
   );
-  if (result.status !== 0) {
-    throw new Error("scripts/gcp-project-bootstrap.sh failed on the VM");
+  if (probe.status !== 0) {
+    return { state: null, inconclusive: true };
   }
+  return { state: parseEditorComposeState(probe.stdout), inconclusive: false };
+}
+
+/** Poll {@link probeEditorComposeState} until the editor service reads
+ *  `running`, returning true as soon as it does. Used to close the TOCTOU window
+ *  after a container-name conflict: the winning run may still be inside
+ *  `Creating`/`Created` when the conflict surfaces, so a single immediate probe
+ *  can under-read and report a healthy container as absent.
+ *
+ *  Deliberately short (default ~30s): this is not the multi-minute first-boot
+ *  budget `waitForContainerRunning` grants, it is the tail of a start that
+ *  another process has already begun. `sleepFn` and `probeFn` are injectable so
+ *  a unit test drives the whole loop with neither wall-clock delay nor a VM. */
+async function waitForEditorComposeRunning(cfg, { attempts = 6, delayMs = 5000, sleepFn, probeFn } = {}) {
+  const sleep = sleepFn || ((ms) => new Promise((r) => setTimeout(r, ms)));
+  const probe = probeFn || probeEditorComposeState;
+  for (let i = 0; i < attempts; i++) {
+    if (probe(cfg).state === "running") {
+      return true;
+    }
+    if (i < attempts - 1) {
+      await sleep(delayMs);
+    }
+  }
+  return false;
 }
 
 async function ensureEditorContainerUp(cfg) {
@@ -1572,13 +2401,7 @@ async function ensureEditorContainerUp(cfg) {
   // cloud variant when self-hosting (see gcp-project-bootstrap.sh).
   const composeCmd = `docker compose -f docker-compose.cloud.yml`;
   console.error("Checking editor container state...");
-  const probe = runGcloud(
-    buildGcloudArgs("ssh-probe", cfg, {
-      command: `cd ~/projects/${repoName} && ${composeCmd} ps --format json 2>/dev/null || true`,
-    }),
-    { stdio: ["ignore", "pipe", "ignore"] },
-  );
-  if (probe.status === 0 && parseEditorComposeState(probe.stdout) === "running") {
+  if (probeEditorComposeState(cfg).state === "running") {
     console.error("  ✓ editor container is already running");
     // containerStarted: the container is confirmed up, so the CLI install runs
     // its POST-start path with no wait — see the precondition on ensureAgentCliInstalled.
@@ -1586,14 +2409,47 @@ async function ensureEditorContainerUp(cfg) {
     return;
   }
   console.error("  starting editor container (docker compose up -d)...");
+  // CAPTURE rather than `stdio: "inherit"`: the daemon writes its container-name
+  // conflict to stderr, and with "inherit" that text went straight to our parent
+  // and was never observable here — so the conflict could not be told apart from
+  // a real failure (the 2026-08-07 VM-4/VM-5 delete). spawnSync cannot both
+  // stream and capture, so the operator's view is preserved by echoing the
+  // captured streams immediately below instead of live. Do NOT revert this to
+  // "inherit"; classification depends on it.
   const up = runGcloud(
     buildGcloudArgs("ssh-probe", cfg, {
       command: `cd ~/projects/${repoName} && ${composeCmd} up -d`,
     }),
-    { stdio: "inherit" },
+    { stdio: ["ignore", "pipe", "pipe"] },
   );
+  if (up.stdout) process.stderr.write(up.stdout);
+  if (up.stderr) process.stderr.write(up.stderr);
   if (up.status !== 0) {
-    throw new Error("docker compose up -d failed on the VM");
+    const verdict = classifyComposeUpFailure({ status: up.status, stderr: `${up.stderr || ""}\n${up.stdout || ""}` });
+    if (verdict !== "name-conflict") {
+      throw new Error("docker compose up -d failed on the VM");
+    }
+    // A name conflict means a concurrent run already created this container —
+    // the goal we were about to pursue is being reached by someone else. Confirm
+    // that positively before converging: a conflict whose container never
+    // reaches `running` (e.g. a stale STOPPED container squatting the name) is a
+    // genuine problem and must still fail loudly, or convergence becomes a
+    // catch-all that papers over real breakage.
+    console.error(
+      "  a concurrent run already created the editor container — confirming it reaches running...",
+    );
+    if (!(await waitForEditorComposeRunning(cfg))) {
+      throw new Error(
+        "docker compose up -d hit a container-name conflict on the VM, but the conflicting " +
+          "container never reached running (a stale stopped container may be holding the name). " +
+          `Inspect with: gcloud compute ssh ${cfg.instanceName} --command 'cd ~/projects/${repoName} && ${composeCmd} ps -a'`,
+      );
+    }
+    console.error("  ✓ editor container is running (started by a concurrent run)");
+    // containerStarted: the container is confirmed up — same post-start contract
+    // as the already-running short-circuit above.
+    await ensureAgentCliInstalled(cfg, { containerStarted: true });
+    return;
   }
   // containerStarted: `up -d` returned 0, so the CLI install is legitimately a
   // post-start step. A brief wait-for-running here (slow boot settling) is
@@ -1609,18 +2465,10 @@ async function ensureEditorContainerUp(cfg) {
 // success. This throws (non-zero exit) when the editor service isn't
 // `running`, converting a silent partial provision into a loud, actionable
 // failure the operator (and the dashboard's fail-fast-on-nonzero path) can act
-// on. The `|| true` keeps the probe's exit status 0 so the real signal is the
-// parsed compose state, not the SSH/cd exit code.
+// on. An inconclusive probe is not "running" here — a terminal gate must have
+// positive evidence, and the caller's job is to fail loudly without it.
 async function assertEditorContainerRunning(cfg) {
-  const repoName = resolveProject(cfg).name;
-  const composeCmd = `docker compose -f docker-compose.cloud.yml`;
-  const probe = runGcloud(
-    buildGcloudArgs("ssh-probe", cfg, {
-      command: `cd ~/projects/${repoName} 2>/dev/null && ${composeCmd} ps --format json 2>/dev/null || true`,
-    }),
-    { stdio: ["ignore", "pipe", "ignore"] },
-  );
-  if (!(probe.status === 0 && parseEditorComposeState(probe.stdout) === "running")) {
+  if (probeEditorComposeState(cfg).state !== "running") {
     throw new Error(
       `provisioning incomplete: editor container is not running on ${cfg.instanceName} ` +
         `(no /workspace or container). Re-run: npm run cloud:up -- --instance-name ${cfg.instanceName}`,
@@ -1763,49 +2611,113 @@ function resolveGhcrPushToken() {
   return process.env.CODEYAM_GHCR_PUSH_TOKEN || "";
 }
 
+// Registry manifest media types we accept when probing image presence over the
+// GHCR HTTP API — Docker v2 + manifest lists and their OCI equivalents, so a
+// multi-arch index answers 200 the same as a single-arch manifest.
+const MANIFEST_ACCEPT = [
+  "application/vnd.docker.distribution.manifest.v2+json",
+  "application/vnd.docker.distribution.manifest.list.v2+json",
+  "application/vnd.oci.image.manifest.v1+json",
+  "application/vnd.oci.image.index.v1+json",
+].join(", ");
+const GHCR_PROBE_TIMEOUT_MS = 15000;
+
+/** Default HTTPS client for the registry probe: a GET that resolves to
+ *  `{ statusCode }` and NEVER rejects — any socket / DNS / timeout error resolves
+ *  to `statusCode: 0` (the probe reads that as "undetermined"). Injected as the
+ *  `httpImpl` option so probeUsableEditorImage is unit-testable with no network
+ *  (and no Docker daemon). `requestImpl` (defaulting to `https.request`) is
+ *  injectable so the response / error / timeout mapping is itself unit-testable
+ *  without a real socket. */
+function httpsManifestGet({ hostname, path: reqPath, headers }, requestImpl = https.request) {
+  return new Promise((resolve) => {
+    const req = requestImpl(
+      { hostname, path: reqPath, method: "GET", headers },
+      (res) => {
+        res.resume(); // drain the body so the socket is freed
+        res.on("end", () => resolve({ statusCode: res.statusCode }));
+      },
+    );
+    req.on("error", () => resolve({ statusCode: 0 }));
+    req.setTimeout(GHCR_PROBE_TIMEOUT_MS, () => req.destroy());
+    req.end();
+  });
+}
+
+/** Probe ONE fully-qualified image ref (`host/repo:tag`) over the registry HTTP
+ *  API — no docker daemon, so a docker-less operator host can still determine
+ *  presence. Returns true (200 present), false (404 absent), or null (auth /
+ *  network / malformed-ref → can't tell absent from forbidden). */
+async function probeManifestRef(fullRef, bearer, httpGet) {
+  const colon = fullRef.lastIndexOf(":");
+  if (colon < 0) return null;
+  const ref = fullRef.slice(0, colon); // host/repo
+  const tag = fullRef.slice(colon + 1); // slug-latest
+  const slash = ref.indexOf("/");
+  if (slash < 0) return null;
+  const hostname = ref.slice(0, slash); // ghcr.io
+  const repo = ref.slice(slash + 1); // codeyam-ai/codeyam-editor-cloud-smoke
+  let res;
+  try {
+    res = await httpGet({
+      hostname,
+      path: `/v2/${repo}/manifests/${encodeURIComponent(tag)}`,
+      headers: { Authorization: `Bearer ${bearer}`, Accept: MANIFEST_ACCEPT },
+    });
+  } catch (_e) {
+    return null;
+  }
+  const code = res && res.statusCode;
+  if (code === 200) return true;
+  if (code === 404) return false;
+  return null; // 401 / 403 / 5xx / 0 (network) → undetermined
+}
+
 /** Read-only probe: does a usable prebuilt editor image already exist on the
  *  registry for `branch`? Used by the fleet dashboard BEFORE a concurrent batch
  *  add to decide whether to pace one VM ahead of the rest (see
- *  npm/fleet-prewarm.js::decideBatchPrewarm). A `docker manifest inspect` is a
- *  HEAD-equivalent — it reads the manifest without pulling the (multi-GB) image.
+ *  npm/fleet-prewarm.js::decideBatchPrewarm).
+ *
+ *  Queries the registry over its HTTP API (`GET /v2/<repo>/manifests/<tag>`, a
+ *  HEAD-equivalent that reads the manifest without pulling the multi-GB image)
+ *  instead of `docker login` / `docker manifest inspect`. This is the root fix
+ *  for the docker-less GCE operator host: the old docker path errored on the
+ *  first `docker login` spawn (the control plane has no docker daemon) and so
+ *  returned `null` forever, which decideBatchPrewarm read as "fan out" — the
+ *  image was therefore never published and every cold add source-built. Over
+ *  HTTP the probe returns a DEFINITIVE verdict with no daemon.
  *
  *  Returns:
  *    true  — at least one of the usable tags exists (a cold add can pull; no pacer)
  *    false — every tag was checked and none exists (known-absent; pacing pays)
- *    null  — undetermined: no read token, docker missing, or a probe error that
- *            can't be distinguished from "absent". The caller treats null as
- *            "fan out" (today's behavior, never worse) rather than risk a
- *            10-min serialization that might buy nothing.
+ *    null  — undetermined: no read token, or an auth/network error that can't be
+ *            distinguished from "absent".
  *
- *  The private packages require auth, so we `docker login` with the read token
- *  first; without a token we can't tell absent from forbidden, so → null.
- *  `spawnImpl` is injectable for unit tests. */
-function probeUsableEditorImage({ branch, registry, token, spawnImpl } = {}) {
+ *  GHCR's private packages require auth; without a read token we can't tell
+ *  absent from forbidden, so → null. The read token is sent as the registry
+ *  bearer (GHCR accepts a base64-encoded PAT directly — no separate token-
+ *  exchange round-trip). `httpImpl` is injectable for unit tests; a legacy
+ *  `spawnImpl` option is still accepted (and ignored) for backward-compat — the
+ *  HTTP happy path needs no spawn. */
+async function probeUsableEditorImage({ branch, registry, token, httpImpl } = {}) {
   const fp = require("./fleet-prewarm");
-  const spawn = spawnImpl || spawnSync;
   const reg = registry || process.env.CODEYAM_REGISTRY || "ghcr.io/codeyam-ai";
   const readToken = token || resolveGhcrToken();
   if (!readToken) return null; // can't auth → can't distinguish absent from forbidden
-  const host = String(reg).split("/")[0];
-  const login = spawn(
-    "docker",
-    ["login", host, "-u", process.env.CODEYAM_GHCR_USER || "codeyam", "--password-stdin"],
-    { input: readToken, encoding: "utf8" },
-  );
-  // spawn error (docker missing) or a non-zero login → undetermined.
-  if (!login || login.error || login.status !== 0) return null;
+  const httpGet = httpImpl || httpsManifestGet;
+  // GHCR accepts a base64-encoded PAT as the registry bearer — no token-exchange
+  // round-trip needed.
+  const bearer = Buffer.from(readToken).toString("base64");
   const tags = fp.usableImageTags({ registry: reg, branch });
   let allClean = true;
-  for (const tag of tags) {
-    const res = spawn("docker", ["manifest", "inspect", tag], { encoding: "utf8" });
-    if (!res || res.error) {
-      allClean = false; // probe itself failed to run — can't claim "absent"
-      continue;
-    }
-    if (res.status === 0) return true; // a usable image exists
-  }
-  // Every tag inspected cleanly and none existed → definitively absent. If any
-  // probe failed to run, we can't be sure → undetermined.
+  for (const fullRef of tags) {
+    const verdict = await probeManifestRef(fullRef, bearer, httpGet);
+    if (verdict === true) return true; // a usable image exists
+    if (verdict === null) allClean = false; // this tag's probe was inconclusive
+    // verdict === false → this tag is absent; keep checking the rest
+  }
+  // Every tag probed cleanly and none existed → definitively absent. If any probe
+  // was inconclusive we can't claim absence → undetermined.
   return allClean ? false : null;
 }
 
@@ -1842,6 +2754,15 @@ function classifyGitRemoteError(stderr) {
   ) {
     return "network";
   }
+  // A greenfield project (`--new-project` scaffold) has no origin remote and an
+  // unborn `main`, so `git ls-remote origin` fails with "does not appear to be a
+  // git repository". No token would fix this — there is simply nothing to push
+  // yet — so it is neither `credential` nor `network` nor `git-spawn`. Keep the
+  // match narrow: `repository not found` is a genuine access failure against a
+  // real remote and must NOT be swallowed here.
+  if (lower.includes("does not appear to be a git repository")) {
+    return "no-remote";
+  }
   return "other";
 }
 
@@ -1879,6 +2800,14 @@ function decideCredentialHeal({ stagingEmpty, lsRemoteOk, lsRemoteStderr }) {
         reason: "git binary failed to launch — not a credential gap, not re-seeding",
       };
     }
+    if (category === "no-remote") {
+      return {
+        heal: false,
+        category,
+        reason:
+          "no git remote configured — greenfield project, nothing to push yet (not a credential gap)",
+      };
+    }
     return {
       heal: true,
       category,
@@ -1896,6 +2825,16 @@ function decideCredentialHeal({ stagingEmpty, lsRemoteOk, lsRemoteStderr }) {
   };
 }
 
+/** The single GitHub credential line format shared by every seed path: the
+ *  host staging file, the durable on-disk `store` fallback, and the live
+ *  cache-daemon approve all expect `https://x-access-token:<token>@github.com`
+ *  (git's credential-URL form, matched by both the entrypoint parser and
+ *  git-credential-store). Centralized so the `x-access-token` shape has one
+ *  source of truth instead of being re-typed at each call site. */
+function githubCredentialLine(token) {
+  return `https://x-access-token:${token}@github.com`;
+}
+
 /** Write the laptop's GitHub token into ~/.codeyam-cloud-git-credentials on
  *  the VM so the cloud compose can mount it into /root/.git-credentials —
  *  without this, claude / codex / gemini inside the container can clone the
@@ -1921,21 +2860,28 @@ async function seedGithubCredentials(cfg, opts = {}) {
   console.error(
     `Writing GitHub token (from ${source}) into ~/.codeyam-cloud-git-credentials on the VM...`,
   );
-  const credLine = `https://x-access-token:${token}@github.com`;
+  const credLine = githubCredentialLine(token);
   // Quote the token through one shell layer (gcloud ssh --command); the
   // value is base64'd to keep it out of the shell history.
   const b64 = Buffer.from(`${credLine}\n`).toString("base64");
-  // Verify-before-move: decode into a chmod-600 temp, assert it is non-empty
-  // (`[ -s ]`), and only THEN move it over the live staging file. An empty or
+  // Verify-before-write: decode into a chmod-600 temp, assert it is non-empty
+  // (`[ -s ]`), and only THEN copy it over the live staging file. An empty or
   // unreadable decode must never clobber an existing good file — the entrypoint
   // reads this file on every boot, and a silent empty write is exactly how a
   // reprovision lands a VM that "could not read Username for github.com". The
-  // trailing `echo OK` runs only on the move, so an empty write can't mask
+  // trailing `echo OK` runs only on success, so an empty write can't mask
   // success with a `&& echo` (the failure shape seen on the Claude creds sinks).
+  //
+  // Use `cat "$t" > "$f"` (in-place truncate), NOT `mv`: the staging file is
+  // bind-mounted read-only into the running container, and `mv` mints a NEW
+  // inode that the live `:ro` mount does not follow — so a `mv`-based re-seed
+  // never reached the running container until a full recreate. Truncating the
+  // existing file in place keeps its inode, so the durable write is visible to
+  // the container immediately. Then remove the temp.
   const remoteCmd =
     `f=$HOME/.codeyam-cloud-git-credentials && t="$f.tmp.$$" && ` +
     `echo ${b64} | base64 -d > "$t" && chmod 600 "$t" && ` +
-    `if [ -s "$t" ]; then mv "$t" "$f" && echo OK; ` +
+    `if [ -s "$t" ]; then cat "$t" > "$f" && chmod 600 "$f" && rm -f "$t" && echo OK; ` +
     `else rm -f "$t"; echo EMPTY-WRITE-REFUSED >&2; exit 1; fi`;
   const result = runGcloud(
     buildGcloudArgs("ssh-probe", cfg, { command: remoteCmd }),
@@ -1946,26 +2892,76 @@ async function seedGithubCredentials(cfg, opts = {}) {
   }
 }
 
+/** Sentinel the remote read prints when it cannot find an `editor.json` under
+ *  any `~/projects/*` directory. Distinguishes "this VM has no scaffolded
+ *  project" (a real miss worth warning about) from "the project is scaffolded
+ *  but declares no port" (legitimately a `VITE_PORT` default). Without the
+ *  distinction both collapse to `{}` and the miss is silent. */
+const VM_APP_PORT_NO_CONFIG = "<<<NOCONFIG>>>";
+
+/** Build the remote shell command that locates the project's `.codeyam` dir and
+ *  cats its two config files in one round-trip.
+ *
+ *  Resolution is glob-based rather than `~/projects/<repoName>` alone: the host
+ *  directory is not guaranteed to be named after the repo (a renamed repo, a
+ *  manually-cloned dir, a fleet slug), and when the guess missed, the old code
+ *  silently returned `VITE_PORT` and forwarded the wrong port. The repo-named
+ *  path is still tried FIRST so a multi-project VM resolves deterministically;
+ *  the glob is the fallback. When nothing matches, print the sentinel so the
+ *  caller can warn instead of guessing. Pure string builder; no I/O. */
+function buildVmAppPortReadCommand(repoName) {
+  return (
+    `d=""; ` +
+    `for c in ~/projects/${repoName}/.codeyam ~/projects/*/.codeyam; do ` +
+    `if [ -f "$c/editor.json" ]; then d="$c"; break; fi; done; ` +
+    `if [ -z "$d" ]; then echo '${VM_APP_PORT_NO_CONFIG}'; else ` +
+    `cat "$d/editor.json" 2>/dev/null || echo '{}'; ` +
+    `echo '<<<LOCAL>>>'; ` +
+    `cat "$d/editor.local.json" 2>/dev/null || echo '{}'; fi`
+  );
+}
+
 /** Best-effort read of the VM's resolved app dev-server port so cloud:up's
  *  laptop `-L` forward, readiness probe, and previewOrigin seed all target the
  *  port the app actually serves on instead of a hardcoded 5173. Cats the VM's
  *  editor.json and editor.local.json in one SSH round-trip and resolves via
- *  `resolveConfiguredAppPort`. Any failure (SSH error, missing/corrupt JSON)
- *  falls back to `VITE_PORT` — the same default `resolved_port()` lands on for
- *  a portless config, so a 5173/greenfield project sees no behavior change. */
+ *  `resolveConfiguredAppPort`.
+ *
+ *  Falls back to `VITE_PORT` on any failure — but fails LOUD, not silent. A
+ *  wrong port here is not a cosmetic default: it forwards the wrong `-L` port,
+ *  and if the preview ends up on a dedicated origin the viewer gets
+ *  "localhost refused to connect" with nothing pointing at the cause. So an SSH
+ *  failure or a VM with no scaffolded project warns on stderr naming that
+ *  symptom. A scaffolded project that simply declares no port is NOT a miss —
+ *  `VITE_PORT` is genuinely correct there (it is what `resolved_port()` lands
+ *  on) and stays quiet. */
 async function readVmAppPort(cfg) {
   const repoName = resolveProject(cfg).name;
-  const base = `~/projects/${repoName}/.codeyam`;
   const read = runGcloud(
     buildGcloudArgs("ssh-probe", cfg, {
-      command:
-        `cat ${base}/editor.json 2>/dev/null || echo '{}'; ` +
-        `echo '<<<LOCAL>>>'; ` +
-        `cat ${base}/editor.local.json 2>/dev/null || echo '{}'`,
+      command: buildVmAppPortReadCommand(repoName),
     }),
     { stdio: ["ignore", "pipe", "ignore"] },
   );
-  if (read.status !== 0 || typeof read.stdout !== "string") return VITE_PORT;
+  if (read.status !== 0 || typeof read.stdout !== "string") {
+    console.error(
+      `[cloud] WARNING: could not read the VM's app port over SSH — ` +
+        `falling back to ${VITE_PORT}. If the app does not serve on ` +
+        `${VITE_PORT}, the laptop port-forward targets the wrong port and the ` +
+        `Live Preview will show "localhost refused to connect".`,
+    );
+    return VITE_PORT;
+  }
+  if (read.stdout.includes(VM_APP_PORT_NO_CONFIG)) {
+    console.error(
+      `[cloud] WARNING: no .codeyam/editor.json found under ~/projects on the ` +
+        `VM (looked for '${repoName}', then any project dir) — falling back to ` +
+        `${VITE_PORT}. If the project is scaffolded under a different name and ` +
+        `serves on another port, the port-forward targets the wrong port and ` +
+        `the Live Preview will show "localhost refused to connect".`,
+    );
+    return VITE_PORT;
+  }
   const parse = (s) => {
     try {
       const v = JSON.parse(s);
@@ -2025,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`;
@@ -2062,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
@@ -2095,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
@@ -2190,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(
@@ -2289,6 +3322,66 @@ async function seedAgentApiKey(cfg) {
   // vm--no-cli-install-before-container-started removed; do not re-add it.
 }
 
+/** Pure: deep-merge `patch` over the VM's current editor.local.json content and
+ *  return the base64 of the pretty-printed result, ready for
+ *  buildEditorLocalSeedWriteCommand. `currentRaw` is the raw `cat` output of the
+ *  remote file (may be undefined, empty, or corrupt) — anything that doesn't
+ *  parse to a plain object is treated as `{}`, because overwriting a corrupt
+ *  override file with a known-good one is safer than refusing to seed. Extracted
+ *  so seedGreenfieldProjectTitle stays a thin I/O passthrough and the
+ *  parse+merge+encode is unit-tested without a live VM. */
+function mergeEditorLocalPatchB64(currentRaw, patch) {
+  let current = {};
+  try {
+    const parsed = JSON.parse(currentRaw);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      current = parsed;
+    }
+  } catch {
+    // Unparseable / missing remote content → start from {}.
+  }
+  const merged = deepMergeJson(current, patch);
+  return Buffer.from(JSON.stringify(merged, null, 2), "utf8").toString("base64");
+}
+
+/** Seed a GREENFIELD project's `projectTitle` into the VM's editor.local.json
+ *  BEFORE compose up, so the editor caches the real project name at startup and
+ *  the fleet dashboard renders the correct card label with no false
+ *  project-dir-drift. Like seedAgentApiKey, this MUST run before
+ *  ensureEditorContainerUp — the editor reads its config once at startup.
+ *
+ *  No-op for a clone (buildGreenfieldTitlePatch returns null): a repo Add labels
+ *  from its origin basename, so there is nothing to seed and no SSH round-trip
+ *  is spent. Runs on every cloud:up, so a reconfigure re-seeds the title,
+ *  converging a VM provisioned before this fix onto the correct identity without
+ *  a destroy. Thin I/O passthrough: the parse+merge+encode lives in the pure
+ *  mergeEditorLocalPatchB64 helper. */
+async function seedGreenfieldProjectTitle(cfg) {
+  const patch = buildGreenfieldTitlePatch(cfg);
+  if (!patch) return; // clone (or no greenfield name) — nothing to seed
+
+  const repoName = resolveProject(cfg).name;
+  const remotePath = `~/projects/${repoName}/.codeyam/editor.local.json`;
+  console.error(`Seeding projectTitle='${patch.projectTitle}' into ${remotePath}...`);
+
+  const read = runGcloud(
+    buildGcloudArgs("ssh-probe", cfg, {
+      command: `cat ${remotePath} 2>/dev/null || echo '{}'`,
+    }),
+    { stdio: ["ignore", "pipe", "ignore"] },
+  );
+  const b64 = mergeEditorLocalPatchB64(read.stdout, patch);
+  const write = runGcloud(
+    buildGcloudArgs("ssh-probe", cfg, {
+      command: buildEditorLocalSeedWriteCommand({ repoName, remotePath, b64 }),
+    }),
+    { stdio: ["ignore", "inherit", "inherit"] },
+  );
+  if (write.status !== 0) {
+    throw new Error(`Failed to write ${remotePath} on VM`);
+  }
+}
+
 /** Tri-state probe of the editor container's running state on the VM host.
  *  One ssh round-trip; returns `"running"`, `"not-running"`, or `"unknown"`.
  *
@@ -2532,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
@@ -2551,6 +3653,42 @@ function streamedScriptMergeBase(editorBranch) {
   return mbResult.status === 0 ? mbResult.stdout.trim() : null;
 }
 
+/** Fetch `editorBranch` from origin into a REAL remote-tracking ref
+ *  (`refs/remotes/origin/<branch>`) rather than only into `FETCH_HEAD`.
+ *
+ *  Operator hosts are commonly shallow, single-branch clones that track only
+ *  `+refs/heads/main`, so `origin/<some-feature-branch>` is not a local ref and
+ *  every `git show origin/<branch>:<path>` against it fails. Fetching through an
+ *  explicit refspec creates the ref, which keeps the drift verdict and the bytes
+ *  actually streamed derived from the same object. Falls back to a plain fetch
+ *  (FETCH_HEAD only) when the refspec form is rejected — `readRemoteScriptBlob`
+ *  can still read through FETCH_HEAD in that case. */
+function fetchStreamedScriptRef(editorBranch) {
+  const refspec = `${editorBranch}:refs/remotes/origin/${editorBranch}`;
+  const withRef = spawnSync("git", ["fetch", "--force", "origin", refspec], { encoding: "utf8" });
+  if (withRef.status === 0) return { ok: true, stderr: "" };
+
+  const plain = spawnSync("git", ["fetch", "origin", editorBranch], { encoding: "utf8" });
+  if (plain.status === 0) return { ok: true, stderr: "" };
+  return { ok: false, stderr: (plain.stderr || withRef.stderr || "").trim() };
+}
+
+/** Resolve one revision of a streamed script from the fetched remote, trying the
+ *  remote-tracking ref first and `FETCH_HEAD` second. `gitArg` is the git verb
+ *  (`rev-parse` for the blob hash, `show` for the bytes) so the drift facts and the
+ *  streamed bytes resolve through the SAME ref-preference order — a verdict of
+ *  "stream remote" can therefore never disagree with what actually got streamed.
+ *  Returns `{ ok: false }` only when the blob is unreadable through both refs. */
+function resolveRemoteScriptRev(gitArg, relPath, editorBranch) {
+  for (const ref of [`origin/${editorBranch}`, "FETCH_HEAD"]) {
+    const result = spawnSync("git", [gitArg, `${ref}:${relPath}`], { encoding: "utf8" });
+    if (result.status === 0 && typeof result.stdout === "string") {
+      return { ok: true, stdout: result.stdout, ref };
+    }
+  }
+  return { ok: false, stdout: "", ref: null };
+}
+
 /** Gather the drift facts for one streamed script relative to `origin/<editorBranch>`:
  *  its local (working-tree) blob hash, the remote-tip blob hash, the merge-base blob
  *  hash, and whether the working tree is dirty. Any git failure yields a null hash,
@@ -2562,11 +3700,8 @@ function gatherScriptDriftFacts(relPath, editorBranch, mergeBase) {
   const localHashResult = spawnSync("git", ["hash-object", relPath], { encoding: "utf8" });
   const localHash = localHashResult.status === 0 ? localHashResult.stdout.trim() : null;
 
-  let remoteHash = null;
-  const remoteHashResult = spawnSync("git", ["rev-parse", `origin/${editorBranch}:${relPath}`], { encoding: "utf8" });
-  if (remoteHashResult.status === 0) {
-    remoteHash = remoteHashResult.stdout.trim();
-  }
+  const remoteRev = resolveRemoteScriptRev("rev-parse", relPath, editorBranch);
+  const remoteHash = remoteRev.ok ? remoteRev.stdout.trim() : null;
 
   let baseHash = null;
   if (mergeBase) {
@@ -2589,7 +3724,15 @@ function gatherScriptDriftFacts(relPath, editorBranch, mergeBase) {
  *  un-pulled dashboard can't add VMs" failure. Streams the on-disk copy instead
  *  when the operator authored local content the remote tip lacks (dirty edit or a
  *  committed local-ahead change — developer mode) or when the remote is unreachable
- *  (offline fallback). `absScriptPath` is an absolute path under the repo root. */
+ *  (offline fallback — `remoteHash === null`, the only sanctioned on-disk path).
+ *
+ *  A "remote" verdict NEVER falls back to the on-disk copy. On a clean-but-behind
+ *  checkout the on-disk bytes are precisely the stale bytes the drift guard exists
+ *  to keep off the VM, so substituting them silently defeats the guard: the verdict
+ *  said "stream the reviewed remote tip" and the VM would instead receive the old
+ *  script, with only a `[Warning]` to show for it. When the remote blob cannot be
+ *  read through either ref this throws, aborting the add.
+ *  `absScriptPath` is an absolute path under the repo root. */
 function readStreamedScript(absScriptPath, cfg = {}) {
   const relPath = path.relative(rootDir, absScriptPath) || absScriptPath;
   const editorBranch = streamedScriptEditorBranch(cfg);
@@ -2598,15 +3741,18 @@ function readStreamedScript(absScriptPath, cfg = {}) {
 
   const { streamedScriptSource } = require("./script-drift");
   if (streamedScriptSource(facts) === "remote") {
-    const remote = spawnSync("git", ["show", `origin/${editorBranch}:${relPath}`], { encoding: "utf8" });
-    if (remote.status === 0 && typeof remote.stdout === "string") {
-      console.error(`  streaming canonical ${relPath} from origin/${editorBranch} (checkout behind remote is fine)`);
+    const remote = resolveRemoteScriptRev("show", relPath, editorBranch);
+    if (remote.ok) {
+      console.error(`  streaming canonical ${relPath} from ${remote.ref} (checkout behind remote is fine)`);
       return remote.stdout;
     }
-    // Remote read failed unexpectedly (raced fetch, ref pruned): fall through to disk.
-    console.error(
-      `  [Warning] Could not read ${relPath} from origin/${editorBranch} ` +
-        `(${(remote.stderr || "").trim() || "unavailable"}). Falling back to the on-disk copy.`,
+    // The facts said "the remote tip is the canonical source" but its bytes are
+    // unreadable. Streaming the on-disk copy here would provision unreviewed stale
+    // bytes under the banner of a successful add — fail loud instead.
+    throw new Error(
+      `could not read ${relPath} from origin/${editorBranch} (or FETCH_HEAD); ` +
+        `refusing to stream a possibly-stale on-disk copy. ` +
+        `Fetch the branch first: git fetch origin ${editorBranch}:refs/remotes/origin/${editorBranch}`,
     );
   }
   return fs.readFileSync(absScriptPath, "utf8");
@@ -2628,10 +3774,11 @@ function checkScriptDrift(cfg) {
 
   console.error(`Checking streamed-script drift against origin/${editorBranch}...`);
 
-  // 1. git fetch origin <editorBranch>
-  const fetchResult = spawnSync("git", ["fetch", "origin", editorBranch], { encoding: "utf8" });
-  if (fetchResult.status !== 0) {
-    console.error(`  [Warning] Failed to fetch origin ${editorBranch} (${(fetchResult.stderr || "").trim() || "unknown error"}). Skipping drift check.`);
+  // 1. Fetch into refs/remotes/origin/<editorBranch> so the ref resolves even on a
+  //    single-branch clone that tracks only +refs/heads/main.
+  const fetchResult = fetchStreamedScriptRef(editorBranch);
+  if (!fetchResult.ok) {
+    console.error(`  [Warning] Failed to fetch origin ${editorBranch} (${fetchResult.stderr || "unknown error"}). Skipping drift check.`);
     return;
   }
 
@@ -2724,8 +3871,9 @@ function fleetInstancePrefix() {
  *  scripts/gcp/vm-ingress.sh with the resolved coordinates. Returns the spawnSync
  *  result so callers decide fatality — Add treats a non-zero as a loud warning
  *  (the VM is provisioned; ingress can be re-wired), Destroy likewise warns so a
- *  teardown still removes the instance. */
-function runVmIngress(cfg, action, vmNumber, domain, appPort, slug) {
+ *  teardown still removes the instance. `vmAccess` (up only) is the Add's intended
+ *  principal set, which the script's grant step uses in place of its sidecar read. */
+function runVmIngress(cfg, action, vmNumber, domain, appPort, slug, vmAccess) {
   const scriptPath = path.join(rootDir, "scripts", "gcp", "vm-ingress.sh");
   const inv = vmIngressInvocation({
     scriptPath,
@@ -2737,6 +3885,7 @@ function runVmIngress(cfg, action, vmNumber, domain, appPort, slug) {
     appPort,
     instancePrefix: fleetInstancePrefix(),
     slug,
+    vmAccess,
   });
   return spawnSync(inv.command, inv.args, {
     stdio: "inherit",
@@ -2744,17 +3893,100 @@ function runVmIngress(cfg, action, vmNumber, domain, appPort, slug) {
   });
 }
 
+/** Grant-only pass: (re-)apply one VM's default IAP access grant by spawning
+ *  `scripts/gcp/vm-ingress.sh <N> grant-access` — the churn-free action that runs
+ *  `apply_default_iap_access` without touching any NEG/BES/host-rule resource.
+ *  Reconcile uses this for already-`wired` VMs its re-wire loop skips, so a healed
+ *  VM whose backends already exist still (re-)grants the automation SA the IAP
+ *  accessor. Returns the spawnSync result so the caller logs granted vs failed;
+ *  best-effort + loud, never fatal. */
+function runVmIngressGrantAccess(cfg, vmNumber, domain, slug) {
+  const scriptPath = path.join(rootDir, "scripts", "gcp", "vm-ingress.sh");
+  const inv = vmIngressGrantAccessInvocation({
+    scriptPath,
+    vmNumber,
+    domain,
+    project: cfg.project,
+    zone: cfg.zone,
+    slug,
+  });
+  return spawnSync(inv.command, inv.args, {
+    stdio: "inherit",
+    env: { ...process.env, ...inv.env },
+  });
+}
+
+/** THE principal set that must have IAP access to this VM after the Add: the
+ *  explicit `cfg.vmAccess` collaborators unioned with the resolved default
+ *  operator. Both add-time access paths consume this ONE function —
+ *  `wireVmIngressOnAdd` (which hands it to vm-ingress.sh's grant) and
+ *  `applyVmAccessOnAdd` (which grants it and subtracts it from the stale-revoke
+ *  set). They used to decide independently, and that is precisely how one path
+ *  granted `user:jared@codeyam.com` at 00:09:31 and the other revoked the same
+ *  principal 18 seconds later as a "stale prior tenant" (VMs 4/5/6, 2026-08-09):
+ *  the ingress path read the SIDECAR (still holding the prior tenant) while
+ *  `applyVmAccessOnAdd` resolved an empty operator. One source of truth removes
+ *  the whole class of disagreement. `env` is injectable for tests; the only I/O
+ *  is `resolveDefaultOperator`'s config/gcloud read. */
+function intendedVmPrincipals(cfg = {}, env = process.env) {
+  return withDefaultOperator(
+    normalizeAccessList(cfg.vmAccess || []),
+    resolveDefaultOperator({ env }),
+  );
+}
+
+/** Add preflight: throw — BEFORE any GCE instance exists — when this Add would
+ *  come up on an IAP-gated public URL that authorizes NOBODY. The whole condition
+ *  is env + config (`intendedVmPrincipals` needs no GCP state), which is why it
+ *  belongs beside cmdUp's other cheap boundary validations rather than after a
+ *  machine has been provisioned: checking later means a half-provisioned VM to
+ *  clean up. On 2026-08-09 the un-refused version of this Add reported `done` for
+ *  VMs 4/5/6, left three unreachable URLs, and revoked each slot's prior tenant on
+ *  the way.
+ *
+ *  Only fires in LB mode on a numbered fleet VM with nothing to grant; an explicit
+ *  `--vm-access` satisfies it with no default operator configured, so the
+ *  collaborator flow is unaffected, as is every legacy quick-tunnel Add. The
+ *  refusal text (and its `Next valid action:` remedy naming all three config
+ *  tiers) is the pure `unauthorizableAddRefusal`; this function is the composition
+ *  and the throw. */
+function assertAddCanAuthorizeSomeone(cfg, env = process.env) {
+  let plan;
+  try {
+    plan = ingressWiringPlan(cfg, env);
+  } catch {
+    // A malformed domain is `resolveIngressDomain`'s error to raise on the wiring
+    // path; it must not masquerade here as an authorization refusal.
+    plan = { wire: false };
+  }
+  const refusal = unauthorizableAddRefusal({
+    lbMode: !!plan.wire,
+    vmNumber: plan.wire ? plan.vmNumber : null,
+    intendedCount: plan.wire ? intendedVmPrincipals(cfg, env).length : null,
+  });
+  if (refusal) throw new Error(refusal);
+}
+
 /** Add-time hook: wire VM-N onto the shared LB when a fleet domain is set.
  *  Best-effort + loud — a wiring hiccup must never abort an otherwise-green Add
  *  (the VM is reachable operator-side over SSH regardless), so on failure it
  *  prints the exact re-run command rather than throwing. No-op (and silent) in
- *  legacy quick-tunnel mode or for a non-fleet client project. */
+ *  legacy quick-tunnel mode or for a non-fleet client project.
+ *
+ *  RETURNS the principals this call granted (`intendedVmPrincipals`), or [] when
+ *  it did not wire — the explicit dataflow `applyVmAccessOnAdd` needs to know what
+ *  the Add has already granted before it computes a stale-revoke. Returned on the
+ *  FAILURE path too: a non-zero `vm-ingress.sh up` may still have completed its
+ *  grant step, and a principal that was possibly granted must never be revoked. */
 function wireVmIngressOnAdd(cfg, appPort, env = process.env) {
   const plan = ingressWiringPlan(cfg, env);
-  if (!plan.wire) return;
+  if (!plan.wire) return [];
   const label = plan.slug || `vm-${plan.vmNumber}`;
+  // Hand the intended set to the script so its `apply_default_iap_access` grants
+  // THIS Add's principals instead of reading the sidecar's prior tenant.
+  const vmAccess = intendedVmPrincipals(cfg, env);
   console.error(`  wiring LB ingress for VM-${plan.vmNumber} on ${plan.domain}...`);
-  const res = runVmIngress(cfg, "up", plan.vmNumber, plan.domain, appPort, plan.slug);
+  const res = runVmIngress(cfg, "up", plan.vmNumber, plan.domain, appPort, plan.slug, vmAccess);
   if (res.status === 0) {
     console.error(`  ✓ LB ingress wired: https://${label}.editor.${plan.domain}`);
   } else {
@@ -2776,6 +4008,7 @@ function wireVmIngressOnAdd(cfg, appPort, env = process.env) {
         `(vm-ingress.sh up exited ${res.status == null ? "abnormally" : res.status}). Re-wire: ${rewire}`,
     );
   }
+  return vmAccess;
 }
 
 /** Destroy-time hook: unwire VM-N's LB backends before the instance is deleted,
@@ -2844,8 +4077,15 @@ function runIapAccess(cfg, vmNumber, action, principals) {
  *  a revoke/grant hiccup (e.g. the SA missing IAP-admin) prints the exact re-run
  *  command rather than aborting an otherwise-green Add. `cfg.vmAccess` is the
  *  array (or comma-separated string) cmdUp validated; absent ⇒ an empty desired
- *  list (the clean-slate case). */
-function applyVmAccessOnAdd(cfg, env = process.env) {
+ *  list (the clean-slate case).
+ *
+ *  `grantedThisRun` is what an EARLIER step of this same Add already granted —
+ *  `wireVmIngressOnAdd`'s return value. It is subtracted from the stale-revoke
+ *  set, so a principal this Add just authorized can never be revoked moments later
+ *  as a prior tenant. That is a second, cheaper guard than the shared
+ *  `intendedVmPrincipals` resolver above: it holds even if the two paths drift
+ *  apart again, which is exactly how VMs 4/5/6 broke on 2026-08-09. */
+function applyVmAccessOnAdd(cfg, env = process.env, { grantedThisRun = [] } = {}) {
   const desired = normalizeAccessList(cfg.vmAccess || []);
   let plan;
   try {
@@ -2862,11 +4102,15 @@ function applyVmAccessOnAdd(cfg, env = process.env) {
   // never inaccessible-by-default (the Error-51 footgun). The default operator is
   // NOT persisted to the sidecar (it's a standing grant, not a per-VM
   // collaborator), so `desired` alone drives the sidecar + stale-revoke below.
-  const toGrant = withDefaultOperator(desired, resolveDefaultOperator({ env }));
+  const toGrant = intendedVmPrincipals(cfg, env);
   const stale = accessFor(vmNumber);
   // Never revoke a principal we're about to (re-)grant — a prior tenant who was
-  // also the default operator must not be revoked-then-regranted for nothing.
-  const staleOnly = stale.filter((p) => !toGrant.includes(p));
+  // also the default operator must not be revoked-then-regranted for nothing —
+  // NOR one an earlier step of this same Add already granted. `toGrant` alone
+  // protected nothing when it was empty: the ingress step had granted the operator
+  // seconds earlier and this revoke took it straight back off (VMs 4/5/6).
+  const grantedAlready = new Set([...toGrant, ...normalizeAccessList(grantedThisRun || [])]);
+  const staleOnly = stale.filter((p) => !grantedAlready.has(p));
 
   if (plan.wire) {
     if (staleOnly.length > 0) {
@@ -2983,12 +4227,23 @@ async function convergeVmIngressOnAdd(cfg, appPort, env = process.env, deps = {}
   }
   if (!plan.wire) {
     // Nothing to converge — the no-op wire keeps the clean-slate invariant.
-    wireVmIngressOnAdd(cfg, appPort, env);
-    return { wired: true, reason: "no-wire" };
-  }
-
+    const granted = wireVmIngressOnAdd(cfg, appPort, env);
+    return { wired: true, reason: "no-wire", grantedThisRun: granted };
+  }
+
+  // The intended set, resolved ONCE and handed to every `up` attempt so each
+  // converge iteration grants the same principals — and reported back to the
+  // caller as `grantedThisRun` so the access reconcile that follows cannot revoke
+  // them. Every `up` runs the script's grant step, so these are granted whether
+  // the loop converges or hits its deadline. Injectable via `deps` like the rest
+  // of this loop's slow I/O: the resolve spawns `gcloud config get-value account`
+  // on its last tier, and a unit test must never depend on the gcloud identity
+  // that happens to be active on the machine running it.
+  const grantedThisRun =
+    deps.grantedThisRun != null ? deps.grantedThisRun : intendedVmPrincipals(cfg, env);
   const runUp =
-    deps.runUp || ((p) => runVmIngress(cfg, "up", p.vmNumber, p.domain, appPort, p.slug));
+    deps.runUp
+    || ((p) => runVmIngress(cfg, "up", p.vmNumber, p.domain, appPort, p.slug, grantedThisRun));
   const probeVerdict = deps.probeVerdict || ((p) => probeVmIngressVerdict(cfg, p));
   const sleep = deps.sleep || ((ms) => new Promise((r) => setTimeout(r, ms)));
   const now = deps.now || (() => Date.now());
@@ -3031,7 +4286,7 @@ async function convergeVmIngressOnAdd(cfg, appPort, env = process.env, deps = {}
     if (decision.done) {
       if (decision.wired) {
         console.error(`  ✓ LB ingress wired: https://${label}.editor.${plan.domain}`);
-        return { wired: true, reason: "wired", attempts: attempt + 1 };
+        return { wired: true, reason: "wired", attempts: attempt + 1, grantedThisRun };
       }
       const rewire =
         `FLEET_DOMAIN=${plan.domain}${plan.slug ? ` VM_SLUG=${plan.slug}` : ""} ` +
@@ -3048,7 +4303,7 @@ async function convergeVmIngressOnAdd(cfg, appPort, env = process.env, deps = {}
         `CY_DEGRADED ingress-wiring-failed: VM-${plan.vmNumber} public URL did not wire ` +
           `within the add window (last verdict=${verdict || "unknown"}). Re-wire: ${rewire}`,
       );
-      return { wired: false, reason: "deadline", attempts: attempt + 1 };
+      return { wired: false, reason: "deadline", attempts: attempt + 1, grantedThisRun };
     }
     attempt += 1;
     await sleep(decision.delayMs);
@@ -3077,8 +4332,8 @@ function startDetachedAddWiring(cfg, appPort, env = process.env) {
   if (!plan.wire) {
     // Nothing slow to detach: wiring is a no-op and the access reconcile is a cheap
     // sidecar write. Run them inline so the clean-slate invariant still holds.
-    wireVmIngressOnAdd(cfg, appPort, env);
-    applyVmAccessOnAdd(cfg, env);
+    const grantedThisRun = wireVmIngressOnAdd(cfg, appPort, env);
+    applyVmAccessOnAdd(cfg, env, { grantedThisRun });
     return;
   }
   const marker = ingressInflightMarkerPath(INGRESS_INFLIGHT_DIR, plan.vmNumber);
@@ -3110,8 +4365,8 @@ function startDetachedAddWiring(cfg, appPort, env = process.env) {
         `running it inline instead.`,
     );
     try { fs.unlinkSync(marker); } catch { /* marker may not exist */ }
-    wireVmIngressOnAdd(cfg, appPort, env);
-    applyVmAccessOnAdd(cfg, env);
+    const grantedThisRun = wireVmIngressOnAdd(cfg, appPort, env);
+    applyVmAccessOnAdd(cfg, env, { grantedThisRun });
   }
 }
 
@@ -3143,8 +4398,11 @@ async function cmdWireAddTail() {
     // Converge the URL to `verdict=wired` (retry-until-wired), not a single-shot
     // `up` left to the slow reconcile sweep — then the IAP access grant, in the
     // SAME order cmdUp ran them inline.
-    await convergeVmIngressOnAdd(cfg, appPort);
-    applyVmAccessOnAdd(cfg);
+    // Carry what the converge granted into the access reconcile, so the revoke
+    // step cannot take back a principal this same Add just authorized — the exact
+    // grant-then-revoke-18s-later sequence `/tmp/cy-wire-add-vm-4.log` recorded.
+    const { grantedThisRun } = await convergeVmIngressOnAdd(cfg, appPort);
+    applyVmAccessOnAdd(cfg, process.env, { grantedThisRun });
   } finally {
     if (marker) {
       try { fs.unlinkSync(marker); } catch { /* already gone — fine */ }
@@ -3206,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);
@@ -3256,8 +4583,14 @@ async function cmdUp(args, projectDir = rootDir) {
     }
   }
 
+  assertAddCanAuthorizeSomeone(cfg);
+
   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);
 
@@ -3287,6 +4620,10 @@ async function cmdUp(args, projectDir = rootDir) {
       }
     }
     await seedAgentApiKey(cfg);
+    // Greenfield only (no-op for a clone): seed projectTitle so the editor
+    // resolves its identity to the real project name instead of the bare
+    // /workspace mount basename — the source of the false project-dir-drift.
+    await seedGreenfieldProjectTitle(cfg);
     await ensureEditorContainerUp(cfg);
     // Provision contract: a just-provisioned VM must actually reach GitHub.
     // Verify in-container git auth now that the container (and its credential
@@ -3358,7 +4695,27 @@ async function cmdUp(args, projectDir = rootDir) {
       );
     }
   } catch (err) {
-    if (createdThisRun) {
+    // `createdThisRun` alone MUST NOT authorize deletion. Gather what state the
+    // VM is in right now, then let the pure decision rule — see
+    // abortTeardownDecision's doc comment for why each input is load-bearing.
+    const state = probeAbortTeardownState(cfg, createdThisRun);
+    const verdict = abortTeardownDecision({ createdThisRun, ...state });
+    if (createdThisRun && verdict === "keep") {
+      // Deliberately loud and specific. The old blanket "tearing down the VM
+      // cloud:up created this run (no orphan left behind)" was actively
+      // misleading here — it asserted no orphan while deleting a working VM.
+      const why = state.probeInconclusive
+        ? "its liveness could not be confirmed (probe failed), and an unconfirmed VM is never deleted"
+        : state.containerUp
+          ? "its editor container is RUNNING — another run brought it up"
+          : "it is in the fleet roster and visible to the dashboard";
+      console.error(
+        `✗ provisioning aborted — the VM ${cfg.instanceName} was LEFT IN PLACE because ${why}.\n` +
+          `  This run created the instance, but that alone does not authorize deleting a VM that is in service.\n` +
+          `  If it really should go, remove it deliberately: npm run cloud:destroy`,
+      );
+    }
+    if (verdict === "delete") {
       console.error(
         `✗ provisioning aborted — tearing down the VM cloud:up created this run (no orphan left behind)`,
       );
@@ -3540,14 +4897,7 @@ async function cmdStatus(args, projectDir = rootDir) {
   const imgStatus = String(imgProbe.stdout || "").trim() || "?";
   console.error(`  image:            ${imgStatus}`);
 
-  const repoName = resolveProject(cfg).name;
-  const containerProbe = runGcloud(
-    buildGcloudArgs("ssh-probe", cfg, {
-      command: `cd ~/projects/${repoName} 2>/dev/null && docker compose -f docker-compose.cloud.yml ps --format json 2>/dev/null || echo`,
-    }),
-    { stdio: ["ignore", "pipe", "ignore"] },
-  );
-  const containerStatus = parseEditorComposeState(containerProbe.stdout) || "missing";
+  const containerStatus = probeEditorComposeState(cfg).state || "missing";
   console.error(`  editor container: ${containerStatus}`);
 
   const appPort = await readVmAppPort(cfg);
@@ -3641,17 +4991,40 @@ async function cmdReconcileIngress(args, projectDir = rootDir) {
       zone: cfg.zone,
       slug,
     });
+    // Bound the per-VM status probe: a hung `bash vm-ingress.sh <N> status`
+    // (its gcloud describes stalling on an IAP/metadata hiccup) must not stall the
+    // whole sweep. On timeout res.stdout is empty, so parseIngressStatusVerdict
+    // returns null → an `unknown` verdict → selectIngressReconcileTargets SKIPS
+    // this VM and the sweep continues to the next one.
     const res = spawnSync(inv.command, inv.args, {
       env: { ...process.env, ...inv.env },
       encoding: "utf8",
+      timeout: GCLOUD_CALL_TIMEOUT_MS,
     });
     return { vmNumber: n, slug, verdict: parseIngressStatusVerdict(res.stdout || "") };
   });
   const targets = selectIngressReconcileTargets(statuses);
   const targetNums = new Set(targets.map((t) => t.vmNumber));
+  // The complement of the re-wire loop: `wired` VMs whose backends already exist
+  // so the re-wire loop skips them, yet still need the SA-accessor (re-)granted —
+  // `up` is the only path that grants it, and it never runs for a wired VM. This
+  // closes the VM-8 heal-path gap (a wired VM whose backends predate the SA-grant
+  // fix would otherwise stay 403 forever). Disjoint from `targets` by construction.
+  const grantOnlyNums = new Set(
+    selectIngressGrantOnlyTargets(statuses).map((g) => g.vmNumber),
+  );
   for (const s of statuses) {
-    if (!targetNums.has(s.vmNumber)) {
-      const label = s.slug || `vm-${s.vmNumber}`;
+    if (targetNums.has(s.vmNumber)) continue;
+    const label = s.slug || `vm-${s.vmNumber}`;
+    if (grantOnlyNums.has(s.vmNumber)) {
+      // Churn-free grant-only pass: (re-)grant the accessor without re-wiring any
+      // NEG/BES/host-rule resource. Idempotent (a no-op when the SA is already
+      // bound) and best-effort-but-loud — a grant hiccup logs, never aborts.
+      const gres = runVmIngressGrantAccess(cfg, s.vmNumber, domain, s.slug);
+      console.error(
+        `  VM-${s.vmNumber} ${label}: wired → ok (accessor ${gres.status === 0 ? "granted" : "grant FAILED"})`,
+      );
+    } else {
       console.error(`  VM-${s.vmNumber} ${label}: ${s.verdict || "unknown"} → ok`);
     }
   }
@@ -3681,7 +5054,13 @@ async function cmdReconcileIngress(args, projectDir = rootDir) {
     for (const surface of gi.SURFACES) {
       const bes = gi.backendServiceName(n, surface);
       const inv = backendServiceTimeoutInvocation({ bes, project: cfg.project });
-      const res = spawnSync(inv.command, inv.args, { encoding: "utf8" });
+      // Bound the per-BES converge too: a hung `gcloud backend-services update`
+      // returns a non-zero (timed-out) result, so it falls into the skip branch
+      // below and the sweep moves on to the next BES rather than stalling.
+      const res = spawnSync(inv.command, inv.args, {
+        encoding: "utf8",
+        timeout: GCLOUD_CALL_TIMEOUT_MS,
+      });
       if (res.status === 0) {
         console.error(`  ${bes}: timeout → 86400`);
       } else {
@@ -3691,6 +5070,12 @@ async function cmdReconcileIngress(args, projectDir = rootDir) {
     }
   }
 
+  // Converge the shared fleet firewall, then surface any app port it still fails to
+  // admit. Both ride this same boot + periodic cadence so the running fleet
+  // self-heals without a hand-run bootstrap.
+  const firewallState = convergeFleetFirewall({ cfg });
+  await reportFirewallPortGaps({ cfg, roster, firewallState });
+
   // Auto-clean orphaned LB ingress (vm--auto-clean-orphaned-lb-ingress): any
   // backend service whose VM number is gone from the roster is a destroyed VM's
   // leftover — cleaned here automatically with the verified `down`, so the
@@ -3720,6 +5105,106 @@ async function cmdReconcileIngress(args, projectDir = rootDir) {
  *  summary (null when the backend-service enumeration itself failed) — the same
  *  shape it prints — so the flow is directly assertable. `deps` is injectable so
  *  the enumerate → select → down flow is testable without gcloud. */
+/** Converge the shared fleet firewall rule to all-tcp so the LB reaches whatever
+ *  port a project's app actually serves.
+ *
+ *  A rule pinned to a hardcoded port list (`tcp:14199,tcp:5173,tcp:3000`) drops
+ *  LB→VM traffic for any VM serving outside it — the VM-6-on-8080 Live Preview
+ *  outage — while the preview backend service still reads HEALTHY, because its
+ *  health check runs on the always-admitted editor port. The failure is therefore
+ *  invisible until someone opens the preview. Converging here (not only in the
+ *  hand-run google-ingress.sh bootstrap) is what makes a drifted rule self-heal on
+ *  the running fleet.
+ *
+ *  All-tcp is the right exposure, not a per-stack port list: the rule stays scoped
+ *  to Google's LB + health-check source ranges and the fleet instance tag either
+ *  way, so it admits any app port (Vite 5173, Next 3000, Astro 4321, Go 8080, …)
+ *  without enumeration. EVERY candidate name in FLEET_FIREWALL_RULE_NAMES is
+ *  converged: describing only one silently no-ops on a fleet wired under the other.
+ *
+ *  Scope-safe by construction — `update --rules=tcp` rewrites only the allowed
+ *  protocols/ports, never a rule's source ranges or target tags, so this can never
+ *  change who the rule applies to. Best-effort throughout: a describe/update
+ *  failure logs and continues, never aborting the rest of the reconcile.
+ *
+ *  Returns `[{ ruleName, rules, converged }]` for every rule that exists — `rules`
+ *  is the post-converge allowed value — so the flow is assertable without gcloud.
+ *  `deps.spawnSync` is injectable for the same reason.
+ *  See plan vm--self-healing-app-port-agnostic-fleet-lb-firewall. */
+function convergeFleetFirewall({ cfg } = {}, deps = {}) {
+  const run = deps.spawnSync || spawnSync;
+  const project = cfg && cfg.project;
+  const state = [];
+  for (const ruleName of FLEET_FIREWALL_RULE_NAMES) {
+    const dinv = fleetFirewallDescribeInvocation({ ruleName, project });
+    const dres = run(dinv.command, dinv.args, { encoding: "utf8" });
+    // A non-zero describe means no rule under this name — expected, not an error:
+    // only one of the candidate names is deployed on any given fleet.
+    if (!dres || dres.status !== 0) continue;
+    const current = ((dres.stdout || "") + "").trim();
+    if (!firewallNeedsConverge(current)) {
+      console.error(`  firewall ${ruleName}: already all-tcp → ok`);
+      state.push({ ruleName, rules: "tcp", converged: false });
+      continue;
+    }
+    const cinv = fleetFirewallConvergeInvocation({ ruleName, project });
+    const cres = run(cinv.command, cinv.args, { encoding: "utf8" });
+    if (cres && cres.status === 0) {
+      console.error(`  firewall ${ruleName}: rules '${current}' → tcp (all-tcp)`);
+      state.push({ ruleName, rules: "tcp", converged: true });
+    } else {
+      const tail = (
+        (cres && (cres.stderr || (cres.error && cres.error.message))) || ""
+      ).toString().trim().split("\n").pop() || "error";
+      console.error(`  firewall ${ruleName}: converge skipped (${tail})`);
+      state.push({ ruleName, rules: current, converged: false });
+    }
+  }
+  if (!state.length) {
+    console.error(
+      `  firewall: no rule found under ${FLEET_FIREWALL_RULE_NAMES.join(" / ")} —` +
+        " LB→VM traffic may be blocked; run scripts/gcp/google-ingress.sh",
+    );
+  }
+  return state;
+}
+
+/** Surface any rostered VM whose app port the fleet firewall does not admit — the
+ *  tripwire for a masked "HEALTHY but unreachable" preview.
+ *
+ *  The preview backend service health-checks the fixed editor port, so a rule that
+ *  admits that port but not the app's real one reads HEALTHY while every real
+ *  request is dropped. That masking is what made the VM-6 outage invisible. Emits a
+ *  machine-readable `CY_FIREWALL_PORT_GAP <json>` line per gap, mirroring the
+ *  `CY_ORPHAN_SWEEP` marker convention the dashboard already parses.
+ *
+ *  Only runs when a rule is still port-pinned: a converged all-tcp rule admits every
+ *  port, so the healthy path cannot produce a gap and skipping it avoids an SSH
+ *  round-trip per rostered VM for a check that cannot fail. In practice this fires
+ *  only if the converge itself failed (e.g. a permissions regression).
+ *
+ *  Returns the emitted `[{ vmNumber, appPort, rule, allowed }]` gaps — the same
+ *  shape it prints — so the marker contract is directly assertable.
+ *  `deps.readVmAppPort` is injectable so tests never reach for SSH. */
+async function reportFirewallPortGaps({ cfg, roster, firewallState } = {}, deps = {}) {
+  const readPort = deps.readVmAppPort || readVmAppPort;
+  const pinned = (firewallState || []).filter((f) => firewallNeedsConverge(f.rules));
+  const gaps = [];
+  if (!pinned.length) return gaps;
+  for (const n of roster || []) {
+    const perVmCfg = { ...cfg, instanceName: `${fleetInstancePrefix()}${n}` };
+    const appPort = await readPort(perVmCfg);
+    for (const f of pinned) {
+      if (firewallAdmitsPort(f.rules, appPort)) continue;
+      const gap = { vmNumber: n, appPort, rule: f.ruleName, allowed: f.rules };
+      console.error(`  VM-${n}: app port ${appPort} NOT admitted by ${f.ruleName}`);
+      console.log(`CY_FIREWALL_PORT_GAP ${JSON.stringify(gap)}`);
+      gaps.push(gap);
+    }
+  }
+  return gaps;
+}
+
 function sweepOrphanIngress({ cfg, domain, roster, projectDir = rootDir } = {}, deps = {}) {
   const gi = deps.googleIngress || require("./google-ingress.js");
   const fcl = deps.fleetCleanup || require("./fleet-cleanup.js");
@@ -3820,7 +5305,14 @@ function sweepOrphanIngress({ cfg, domain, roster, projectDir = rootDir } = {},
     });
     const res = run(inv.command, inv.args, { encoding: "utf8", env: { ...process.env, ...inv.env } });
     const verdict = parseIngressTeardownVerdict((res && res.stdout) || "");
-    const outcome = classifyOrphanDownResult({ verdict, status: res ? res.status : null });
+    // Pass `signal` too: a teardown the caller's group-kill reaped has a NULL
+    // status, which the classifier would otherwise report as `spawn-failed`
+    // rather than the truthful `killed=SIGKILL`.
+    const outcome = classifyOrphanDownResult({
+      verdict,
+      status: res ? res.status : null,
+      signal: res ? res.signal : null,
+    });
     if (outcome.cleaned) {
       summary.cleaned.push(n);
       console.error(`  VM-${n}: orphaned ingress → auto-cleaned (verified clean)`);
@@ -3889,20 +5381,33 @@ async function probeGitCredentials(cfg) {
 /** Seed the LIVE in-memory git credential-cache daemon over its socket — the
  *  same `git credential approve` shape the entrypoint uses
  *  (scripts/cloud-editor-entrypoint.sh) — so push works immediately with no
- *  container restart. base64 keeps the token out of the shell history across
- *  the gcloud-ssh → docker layers. Throws if the approve fails. Shared by
- *  {@link cmdReconcileCredentials} and {@link assertGitPushCredentials}. */
+ *  container restart. ALSO writes the container-local on-disk `store` fallback
+ *  file (the fill-only second helper baked into the image) directly, so a
+ *  reconcile leaves the VM durable against the cache daemon dying mid-life, not
+ *  just healthy for the moment. base64 keeps the token out of the shell history
+ *  across the gcloud-ssh → docker layers, and the store write is an in-place
+ *  `cat > file` truncate (chmod 600), never touched by git's approve path.
+ *  Throws if either write fails. Shared by {@link cmdReconcileCredentials} and
+ *  {@link assertGitPushCredentials}. */
 async function seedLiveCredentialCache(cfg, token) {
   const repoName = resolveProject(cfg).name;
   const projectCd = `cd ~/projects/${repoName}`;
   const composeExec = `docker compose -f docker-compose.cloud.yml exec -T editor`;
   const socket = "/run/codeyam/git-credential-cache.socket";
+  const store = "/run/codeyam/git-credentials-store";
   const approveStdin = `protocol=https\nhost=github.com\nusername=x-access-token\npassword=${token}\n\n`;
   const b64 = Buffer.from(approveStdin).toString("base64");
+  // The store-file line is the same one-URL-per-line format as the host staging
+  // file; the image's fill-only `store` helper reads it on a cache miss.
+  const storeB64 = Buffer.from(`${githubCredentialLine(token)}\n`).toString("base64");
   const seedCmd =
-    `${projectCd} && echo ${b64} | base64 -d | ${composeExec} ` +
+    `${projectCd} && ` +
+    `echo ${b64} | base64 -d | ${composeExec} ` +
     `git -c 'credential.helper=cache --timeout=31536000 --socket=${socket}' ` +
-    `credential approve && echo APPROVED`;
+    `credential approve && ` +
+    `echo ${storeB64} | base64 -d | ${composeExec} ` +
+    `bash -c 'cat > ${store} && chmod 600 ${store}' && ` +
+    `echo APPROVED`;
   const seed = runGcloud(
     buildGcloudArgs("ssh-probe", cfg, { command: seedCmd }),
     { stdio: ["ignore", "pipe", "inherit"] },
@@ -3941,6 +5446,39 @@ async function cmdReconcileCredentials(args, projectDir = rootDir) {
   );
 }
 
+/** `cloud:reconcile-admin` — flip admin mode on/off for an already-running VM
+ *  WITHOUT a full re-provision. Resolves the desired value from this invocation
+ *  (`--admin` / `CODEYAM_ADMIN`, else off), rewrites the rendered compose's
+ *  CODEYAM_ADMIN line, and recreates the editor service — matching what a manual
+ *  compose edit + `docker compose up -d editor` does today, so the durable admin
+ *  setting no longer requires a full re-provision to change. */
+async function cmdReconcileAdmin(args, projectDir = rootDir) {
+  ensureGcloud();
+  const flags = parseFlags(args);
+  const cfg = loadCloudConfig(projectDir);
+  if (!cfg) {
+    throw new Error("No .codeyam/cloud.json found. Run `npm run cloud:up` first.");
+  }
+  const desired =
+    buildProvisionEnv(process.env, flags).CODEYAM_ADMIN === "1" ? "1" : "";
+  const repoName = resolveProject(cfg).name;
+  console.error(
+    `Reconciling admin mode to ${desired === "1" ? "ON" : "off"} on ${cfg.instanceName}...`,
+  );
+  const result = runGcloud(
+    buildGcloudArgs("ssh-probe", cfg, {
+      command: buildReconcileAdminCommand(repoName, desired),
+    }),
+    { stdio: "inherit" },
+  );
+  if (result.status !== 0) {
+    throw new Error(`Failed to reconcile admin mode on ${cfg.instanceName}.`);
+  }
+  console.error(
+    `  ✓ editor service recreated; /api/config now reports admin=${desired === "1" ? "true" : "false"}.`,
+  );
+}
+
 /** Provision-time guarantee that a just-provisioned VM can actually reach
  *  GitHub. Probes the staging file + in-container `git ls-remote origin` and
  *  routes the outcome through the SAME {@link decideCredentialHeal} classifier
@@ -4072,6 +5610,7 @@ const HANDLERS = {
   "reconcile-ingress": cmdReconcileIngress,
   "wire-add-tail": cmdWireAddTail,
   "reconcile-credentials": cmdReconcileCredentials,
+  "reconcile-admin": cmdReconcileAdmin,
   access: cmdAccess,
 };
 
@@ -4094,6 +5633,10 @@ async function cloudMain() {
 
 module.exports = {
   // pure helpers
+  isSpawnTimeout,
+  gcloudCallTimeoutMs,
+  provisionFailureMessage,
+  GCLOUD_PROVISION_TIMEOUT_MS,
   agentEnvVarName,
   agentNpmPackage,
   AGENT_ENV_VARS,
@@ -4104,11 +5647,15 @@ module.exports = {
   assertAgentCliInstalled,
   probeContainerRunning,
   probeContainerState,
+  waitForEditorComposeRunning,
+  abortTeardownDecision,
+  probeAbortTeardownState,
   probeAgentBinaryInstalled,
   waitForContainerRunning,
   KNOWN_FLAGS,
   FIREWALL_RULE_NAME,
   INSTANCE_TAG,
+  DEFAULT_FLEET_MACHINE_TYPE,
   EDITOR_PORT,
   VITE_PORT,
   parseFlags,
@@ -4125,8 +5672,10 @@ module.exports = {
   resolveConfiguredAppPort,
   resolveSeedPreviewOrigin,
   previewSameOriginSafeFromStack,
+  resolveEffectiveSameOriginSafe,
   isRottedManagedPreviewOrigin,
   isWrongModePreviewOrigin,
+  isSilentlyBrokenPreview,
   resolveEditorConfig,
   validateEditorVariant,
   assertVariantProvisionable,
@@ -4135,13 +5684,19 @@ module.exports = {
   resolveGhcrToken,
   resolveGhcrPushToken,
   probeUsableEditorImage,
+  httpsManifestGet,
   resolveProject,
   clientProjectBootstrapArgs,
   cloudConfigPath,
   loadCloudConfig,
   saveCloudConfig,
   loadOrInitCloudConfig,
+  buildProvisionEnv,
+  buildReconcileAdminCommand,
+  cmdReconcileAdmin,
   buildEditorLocalEnvPatch,
+  buildGreenfieldTitlePatch,
+  mergeEditorLocalPatchB64,
   buildEditorLocalSeedWriteCommand,
   seedPreviewOrigin,
   healPreviewOriginAtReady,
@@ -4155,11 +5710,29 @@ module.exports = {
   decideBootstrapOutcome,
   projectBootstrapDoneMarker,
   projectBootstrapDoneProbeCommand,
+  projectBootstrapScriptPath,
+  projectBootstrapRunnerPath,
+  projectBootstrapLogPath,
+  projectBootstrapPidPath,
+  projectBootstrapStatusPath,
+  projectBootstrapRunnerScript,
+  projectBootstrapLaunchCommand,
+  projectBootstrapFollowCommand,
+  projectBootstrapStatusCommand,
+  parseProjectBootstrapStatus,
+  decideProjectBootstrapOutcome,
+  decideProjectBootstrapFollowAction,
+  projectBootstrapEnv,
+  PROJECT_BOOTSTRAP_LAUNCHED_MARKER,
+  PROJECT_BOOTSTRAP_FOLLOW_SECS,
+  ensureProjectBootstrapped,
   SSH_KEEPALIVE_FLAGS,
   resolveSetupForwardEnv,
   FORWARD_ENV_KEYS_ENV,
   parseEditorComposeState,
   fetchInstanceState,
+  fetchPendingOperation,
+  wedgedOperationMessage,
   formatGcloudFailure,
   isTransientSshFailure,
   runGcloudSshWithRetry,
@@ -4169,6 +5742,8 @@ module.exports = {
   checkScriptDrift,
   streamedScriptEditorBranch,
   streamedScriptMergeBase,
+  fetchStreamedScriptRef,
+  resolveRemoteScriptRev,
   gatherScriptDriftFacts,
   readStreamedScript,
   STREAMED_SCRIPTS,
@@ -4177,6 +5752,8 @@ module.exports = {
   ingressWiringPlan,
   fleetInstancePrefix,
   runVmIngress,
+  intendedVmPrincipals,
+  assertAddCanAuthorizeSomeone,
   wireVmIngressOnAdd,
   probeVmIngressVerdict,
   convergeVmIngressOnAdd,
@@ -4195,6 +5772,8 @@ module.exports = {
   cmdIngressUp,
   cmdReconcileIngress,
   sweepOrphanIngress,
+  convergeFleetFirewall,
+  reportFirewallPortGaps,
   cmdReconcileCredentials,
   cmdAccess,
   cloudMain,
@@ -4202,13 +5781,17 @@ module.exports = {
   seedLiveCredentialCache,
   assertGitPushCredentials,
   seedGithubCredentials,
+  githubCredentialLine,
   resolveGithubToken,
   resolveGithubTokenWithSource,
   MissingGitPushCredentialsError,
   classifyGitRemoteError,
   decideCredentialHeal,
   readVmAppPort,
+  buildVmAppPortReadCommand,
   resolveLaptopGitIdentity,
+  gitBranchRefExists,
+  assertBranchRefsExist,
 };
 
 if (require.main === module) {