@codeyam-editor/codeyam-editor 0.1.4 → 0.1.6

package/npm/cloud.js

@@ -11,6 +11,8 @@
 
 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");
 const {
@@ -33,12 +35,76 @@ const { FORWARD_ENV_KEYS_ENV } = require("./fleet-env");
 // stable `https://vm-<N>.preview.<domain>` previewOrigin from its number. When
 // no domain is configured these stay dormant and the legacy quick-tunnel seed
 // path runs unchanged.
-const { resolveFleetDomain, vmUrls } = require("./vm-urls");
-// Shared fleet-roster writer. `cloud:up` rosters the VM it just provisioned so
-// the dashboard, the cloudflared-monitor tunnel publisher, and the watchdog see
-// it within one poll cycle — without a manual fleet-vms.json edit (the
-// invisible-VM gap improve38 closes).
-const { addToRoster } = require("./fleet-roster");
+const { resolveFleetDomain, vmUrls, normalizeVmSlug } = require("./vm-urls");
+// Per-VM custom-slug sidecar (`.codeyam/logs/fleet-vm-slugs.json`). A slug is an
+// optional human-readable override for a VM's leftmost hostname label; Add
+// persists it (`setSlug`), Add/Destroy resolve it (`slugFor`) to route the same
+// `<slug>.<surface>.<domain>` host, and Destroy (`cmdDestroy`) clears it
+// unconditionally (`removeSlug`, decoupled from LB ingress teardown). Absent
+// ⇒ the numeric `vm-<N>` scheme is unchanged.
+const {
+  slugFor,
+  vmForSlug,
+  setSlug,
+  removeSlug,
+} = require("./fleet-vm-slugs");
+// Per-VM IAP access whitelist sidecar (`.codeyam/logs/fleet-vm-access.json`).
+// Resource-level grants so a named collaborator can reach ONE VM's surfaces:
+// Add *reconciles* the whitelist to exactly the requested list (`accessFor` +
+// `setAccess`), revoking a reused number's stale grants for a clean slate; the
+// edit CLI mutates the delta (`addAccess`/`removeAccess`); and Destroy revokes +
+// clears (`accessFor` + `clearAccess`). Independent of the owner's project-wide grant.
+const {
+  normalizeAccessList,
+  normalizePrincipal,
+  resolveDefaultOperator,
+  withDefaultOperator,
+  accessFor,
+  setAccess,
+  addAccess,
+  removeAccess,
+  clearAccess,
+} = require("./fleet-vm-access");
+// LB-ingress shell-invocation builders (pure; unit-tested in ingress-invoke.test.js).
+// `resolveIngressDomain` reads the fleet domain from cloud.json (`fleetDomain`)
+// with a FLEET_DOMAIN env fallback — null ⇒ legacy quick-tunnel mode, where the
+// Add/Destroy path is unchanged. The *Invocation builders shape the exact
+// `{ command, args, env }` cloud.js spawns for scripts/gcp/{google,vm}-ingress.sh.
+const {
+  resolveIngressDomain,
+  resolveDnsZone,
+  regionFromZone,
+  vmIngressInvocation,
+  vmIngressStatusInvocation,
+  vmIngressGrantAccessInvocation,
+  parseIngressStatusVerdict,
+  parseIngressTeardownVerdict,
+  selectIngressReconcileTargets,
+  selectIngressGrantOnlyTargets,
+  selectOrphanIngressTargets,
+  classifyOrphanDownResult,
+  backendServicesListInvocation,
+  negListInvocation,
+  instancesListInvocation,
+  ingressConvergeDecision,
+  detachedAddTailInvocation,
+  ingressInflightMarkerPath,
+  ingressFailedMarkerPath,
+  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
+// the watchdog see it within one poll cycle — without a manual fleet-vms.json
+// edit (the invisible-VM gap improve38 closes). `readRoster` enumerates the
+// fleet for `reconcile-ingress`.
+const { addToRoster, readRoster } = require("./fleet-roster");
 
 // =============================================================================
 // Pure helpers — every export here is unit-tested in cloud.test.js without
@@ -73,14 +139,62 @@ const KNOWN_FLAGS = [
   // runs setup by default when the project ships one; pass this for projects
   // where a cloud setup is genuinely wrong (the script's --skip-setup hatch).
   "skip-setup",
+  // Fleet LB-ingress domain (e.g. fleet.codeyam.com). When set + persisted in
+  // cloud.json, Add wires the VM onto the shared Google HTTPS LB and Destroy
+  // unwires it; unset = legacy quick-tunnel mode (Add/Destroy unchanged). The
+  // Cloud DNS managed-zone name defaults to fleet-zone; override with --dns-zone.
+  "fleet-domain",
+  "dns-zone",
+  // Optional human-readable hostname slug for THIS VM (single VM only). When
+  // set on a numbered fleet VM with a fleet domain, its public URLs become
+  // `<slug>.editor.<domain>` / `<slug>.preview.<domain>` instead of the
+  // number-derived `vm-<N>...`. Persisted in the slug sidecar (NOT cloud.json,
+  // like --no-tunnel), so a later bare `cloud:up` doesn't re-apply a stale slug.
+  "vm-slug",
+  // Per-VM IAP access whitelist: comma-separated principals (user:/group:/domain:,
+  // a bare email defaults to user:) granted resource-level access to THIS VM's
+  // surfaces on Add. Persisted in the access sidecar (NOT cloud.json, like
+  // --vm-slug), so a later bare `cloud:up` doesn't re-apply a stale list. Edited
+  // after the fact with `cloud:access`.
+  "vm-access",
+  // `cloud:access` edit-an-existing-VM flags: add/remove one principal, or list
+  // the current whitelist. Single-VM, resolved from --instance-name.
+  "add",
+  "remove",
+  "list",
+  // Escape hatch for an intentionally read-only VM: suppress the fail-loud /
+  // degraded-badge when no GitHub push token resolves at provision time. The
+  // 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"];
+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;
 
@@ -320,6 +434,7 @@ function resolveSeedPreviewOrigin(
   appPort = VITE_PORT,
   env = process.env,
   sameOriginSafe = true,
+  slug = null,
 ) {
   // Same-origin-safe stack (the default — Vite et al.): ALWAYS serve the app
   // same-origin under the reserved relative path, in every fleet mode. The
@@ -348,15 +463,27 @@ function resolveSeedPreviewOrigin(
   // client project (vm == null) keeps the localhost seed even with a domain set.
   if (domain && vm != null) {
     return {
-      previewOrigin: vmUrls(vm, domain).preview,
+      // A custom slug overrides the leftmost `vm-<N>` label so the iframe origin
+      // matches the slug host the LB routes; absent, this is the numeric host.
+      previewOrigin: vmUrls(vm, domain, slug).preview,
+      _managedPreviewOrigin: MANAGED_PREVIEW_ORIGIN,
+    };
+  }
+  // Quick-tunnel / domain-free mode: support both 'local' (default) and 'tunnel' modes.
+  // In 'local' mode, we use http://localhost:<15172 + VM_NUMBER> directly.
+  // In 'tunnel' mode, we prefer the operator's published quick-tunnel URL.
+  const mode = env.PREVIEW_ORIGIN_MODE || "local";
+  if (mode === "local" && vm != null) {
+    // http://localhost inside an https:// editor page is allowed.
+    // Browsers treat http://localhost as a potentially-trustworthy origin,
+    // so the mixed-content blocker does not apply.
+    const previewPort = 15172 + vm;
+    return {
+      previewOrigin: `http://localhost:${previewPort}`,
       _managedPreviewOrigin: MANAGED_PREVIEW_ORIGIN,
     };
   }
-  // Quick-tunnel / domain-free mode: prefer the operator's published
-  // `<N>-preview` quick-tunnel URL (the public origin a remote browser can
-  // actually load), else the SSH-tunnel bootstrap localhost origin
-  // (`http://localhost:<appPort>`, reached via the laptop `-L` forward). Never
-  // the same-origin subpath — that is exactly what recurses for this stack.
+  // Quick-tunnel 'tunnel' mode fallback / non-fleet project fallback:
   const previewKey = vm != null ? `${vm}-preview` : null;
   const tunnelUrl =
     previewKey &&
@@ -411,6 +538,72 @@ function isRottedManagedPreviewOrigin(localJson, sameOriginSafe) {
   );
 }
 
+// A loopback / localhost previewOrigin: `http://127.0.0.1:<port>`,
+// `http://localhost:<port>`, `http://[::1]:<port>`, with or without a port,
+// path, or query. These are reachable only from the editor host itself (or a
+// laptop `-L` forward), never from a remote browser — exactly the dead-end the
+// dedicated_preview_origin fallback lands on when the seed was wrong-moded.
+const LOOPBACK_ORIGIN_RE =
+  /^https?:\/\/(?:127\.0\.0\.1|localhost|\[::1\])(?:[:/?#]|$)/i;
+
+/** Decide whether a VM's current `editor.local.json` carries a WRONG-MODE
+ *  previewOrigin for a stack that is NOT same-origin-safe (Next.js etc.) and so
+ *  must be self-healed to a dedicated origin. This is the inverse of
+ *  `isRottedManagedPreviewOrigin`: it fires when the stack.json race froze the
+ *  same-origin-safe default (or a loopback bootstrap) onto a client-routed
+ *  stack — the VM7 failure where the iframe shows `127.0.0.1 refused to
+ *  connect`. True iff BOTH hold:
+ *    - the stack is NOT same-origin-safe (a same-origin-safe stack legitimately
+ *      keeps the `/__codeyam_preview` subpath — never heal it; that is
+ *      `isRottedManagedPreviewOrigin`'s job in the other direction); and
+ *    - the `previewOrigin` is the same-origin subpath sentinel, any other
+ *      relative path, or a loopback/localhost origin — none of which a remote
+ *      browser can load for a dedicated-origin stack. A real dedicated origin
+ *      (an absolute non-loopback URL — quick-tunnel or named-tunnel host) is
+ *      left alone, so re-running the heal once a good origin is in place is a
+ *      no-op.
+ *  Symmetric with `isRottedManagedPreviewOrigin` and tested as a pair. Pure —
+ *  `localJson` is a parsed editor.local.json object. */
+function isWrongModePreviewOrigin(localJson, sameOriginSafe) {
+  if (sameOriginSafe) return false;
+  if (!localJson || typeof localJson !== "object") return false;
+  const origin = localJson.previewOrigin;
+  if (typeof origin !== "string" || origin.length === 0) return false;
+  // The reserved same-origin subpath, or any relative path (no scheme): these
+  // recurse into the editor SPA for a client-routed stack.
+  if (origin === SAME_ORIGIN_PREVIEW_PATH) return true;
+  if (!/^[a-z][a-z0-9+.-]*:\/\//i.test(origin)) return true;
+  // An absolute loopback/localhost origin: reachable only from the host, dead
+  // for a remote browser.
+  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() {
@@ -491,9 +684,25 @@ function editorImageBootstrapArgs(cfg) {
  *  so a stale value — e.g. a prior greenfield's `newProject` left in cloud.json
  *  — can't override the new intent. Without this, launching `--repo X` after a
  *  greenfield run silently provisions the greenfield project (resolveProject
- *  prioritizes newProject). Mutates and returns cfg. */
-function reconcileProjectExclusivity(cfg, flags = {}) {
-  if (flags.repo) delete cfg.newProject;
+ *  prioritizes newProject). Mutates and returns cfg.
+ *
+ *  `prev` is the pre-merge persisted config (default `{}`). When `--repo`
+ *  SWITCHES to a different repo and no `--branch` was passed this run, the
+ *  inherited client branch is dropped: a persisted branch belongs to the OLD
+ *  repo and may not exist on the new one. (The harvardintech VM was torn down
+ *  because a `--repo harvardintech` re-up reused `editor-improvements-48` — a
+ *  branch that lives only on the editor repo — and `git clone --branch` failed.)
+ *  An explicit `--branch` this run always wins (the drop is gated on
+ *  `!flags.branch`), and a same-repo re-up keeps its persisted branch — that is
+ *  the legitimate "set the branch once, reuse it" workflow. `sameRepo` is used
+ *  for the comparison so `.git`/case differences don't trigger a spurious drop. */
+function reconcileProjectExclusivity(cfg, flags = {}, prev = {}) {
+  if (flags.repo) {
+    delete cfg.newProject;
+    if (!flags.branch && prev.repo && !sameRepo(prev.repo, flags.repo)) {
+      delete cfg.branch;
+    }
+  }
   if (flags.newProject) { delete cfg.repo; delete cfg.branch; }
   return cfg;
 }
@@ -546,14 +755,27 @@ function loadCloudConfig(projectDir) {
   try {
     return JSON.parse(raw);
   } catch (e) {
-    throw new Error(`Failed to parse ${p}: ${e.message}`);
+    try {
+      raw = fs.readFileSync(p, "utf8");
+      return JSON.parse(raw);
+    } catch (e2) {
+      throw new Error(`Failed to parse ${p}: ${e2.message}`);
+    }
   }
 }
 
 function saveCloudConfig(projectDir, cfg) {
   const p = cloudConfigPath(projectDir);
-  fs.mkdirSync(path.dirname(p), { recursive: true });
-  fs.writeFileSync(p, JSON.stringify(cfg, null, 2) + "\n");
+  const dir = path.dirname(p);
+  fs.mkdirSync(dir, { recursive: true });
+  const tmpPath = path.join(dir, `cloud.json.${process.pid}.tmp`);
+  try {
+    fs.writeFileSync(tmpPath, JSON.stringify(cfg, null, 2) + "\n");
+    fs.renameSync(tmpPath, p);
+  } catch (e) {
+    fs.rmSync(tmpPath, { force: true });
+    throw e;
+  }
 }
 
 /** Build the JSON patch to merge into the VM's `editor.local.json` so the
@@ -579,6 +801,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
@@ -621,7 +865,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",
@@ -721,11 +965,61 @@ 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.
+const GCLOUD_CALL_TIMEOUT_MS = 120000;
+
+// 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,
   });
 }
 
@@ -835,9 +1129,21 @@ function loadOrInitCloudConfig(projectDir, flags) {
   const existing = loadCloudConfig(projectDir);
   // noTunnel is a per-invocation behavior, never persisted — else a later manual
   // `cloud:up` (zero-arg, reading cloud.json) would silently skip its tunnel.
-  const persist = (c) => { const { noTunnel, ...rest } = c; return rest; };
+  // vmSlug is likewise a per-Add input that lives in the slug sidecar keyed by VM
+  // number, never in this project config — else a later bare `cloud:up` would
+  // re-stamp a stale slug onto the VM. vmAccess is the same shape: a per-Add input
+  // that lives in the access sidecar, never in cloud.json.
+  const persist = (c) => { const { noTunnel, vmSlug, vmAccess, ...rest } = c; return rest; };
   if (existing) {
-    const merged = reconcileProjectExclusivity({ ...existing, ...flags }, flags);
+    const merged = reconcileProjectExclusivity({ ...existing, ...flags }, flags, existing);
+    const { isPlaceholderProject } = require("./launch-config");
+    if (isPlaceholderProject(merged.project)) {
+      const configPath = cloudConfigPath(projectDir);
+      throw new Error(
+        `Failed to load cloud config: project '${merged.project}' in ${configPath} is a test-fixture placeholder. ` +
+          `Please configure a real GCP project or set the GCP_PROJECT environment variable.`
+      );
+    }
     const toSave = persist(merged);
     if (JSON.stringify(toSave) !== JSON.stringify(existing)) {
       saveCloudConfig(projectDir, toSave);
@@ -847,6 +1153,15 @@ function loadOrInitCloudConfig(projectDir, flags) {
 
   const cfg = reconcileProjectExclusivity({ ...flags }, flags);
   cfg.project = cfg.project || gcloudGetValue("config-get-project");
+
+  const { isPlaceholderProject } = require("./launch-config");
+  if (isPlaceholderProject(cfg.project)) {
+    throw new Error(
+      `Failed to load cloud config: resolved project '${cfg.project}' is a test-fixture placeholder. ` +
+        `Please configure a real GCP project or set the GCP_PROJECT environment variable.`
+    );
+  }
+
   cfg.zone = cfg.zone || gcloudGetValue("config-get-zone");
   cfg.agent = cfg.agent || "claude";
   agentEnvVarName(cfg.agent);
@@ -1190,7 +1505,7 @@ async function ensureBootstrapped(cfg, { sleepFn } = {}) {
   }
   console.error("  streaming scripts/gcp-bootstrap.sh to VM (this may take ~10 minutes)...");
   const scriptPath = path.join(rootDir, "scripts", "gcp-bootstrap.sh");
-  const scriptBody = fs.readFileSync(scriptPath, "utf8");
+  const scriptBody = readStreamedScript(scriptPath, cfg);
   // GITHUB_TOKEN is passed through to the bootstrap script so it can clone
   // a private editor repo (the bootstrap clones $REPO_URL to build the
   // codeyam-editor:local image). Without this the git clone hits the
@@ -1307,7 +1622,305 @@ 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) {
+  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);
+  // 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 = [
+    `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
@@ -1335,35 +1948,104 @@ 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 = fs.readFileSync(scriptPath, "utf8");
+  const scriptBody = readStreamedScript(scriptPath, 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();
-  const command = sshScriptCommand(scriptBody, scriptArgs, {
-    GITHUB_TOKEN: resolveGithubToken(),
-    CY_GIT_USER_NAME: laptopGit.name,
-    CY_GIT_USER_EMAIL: laptopGit.email,
-    ...forwardEnv,
-  });
-  const result = runGcloud(
-    buildGcloudArgs("ssh-script", cfg, { command }),
-    { stdio: "inherit" },
-  );
-  if (result.status !== 0) {
-    throw new Error("scripts/gcp-project-bootstrap.sh failed on the VM");
+  // 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);
+    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...");
   }
 }
 
@@ -1382,7 +2064,9 @@ async function ensureEditorContainerUp(cfg) {
   );
   if (probe.status === 0 && parseEditorComposeState(probe.stdout) === "running") {
     console.error("  ✓ editor container is already running");
-    await ensureAgentCliInstalled(cfg);
+    // containerStarted: the container is confirmed up, so the CLI install runs
+    // its POST-start path with no wait — see the precondition on ensureAgentCliInstalled.
+    await ensureAgentCliInstalled(cfg, { containerStarted: true });
     return;
   }
   console.error("  starting editor container (docker compose up -d)...");
@@ -1395,7 +2079,10 @@ async function ensureEditorContainerUp(cfg) {
   if (up.status !== 0) {
     throw new Error("docker compose up -d failed on the VM");
   }
-  await ensureAgentCliInstalled(cfg);
+  // 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
+  // expected and must NOT warn about mis-ordering.
+  await ensureAgentCliInstalled(cfg, { containerStarted: true });
 }
 
 // Hard gate: provisioning success REQUIRES a running editor container. Reuses
@@ -1425,6 +2112,36 @@ async function assertEditorContainerRunning(cfg) {
   }
 }
 
+// Hard gate: provisioning success ALSO REQUIRES the agent CLI present in the
+// container. The image deliberately ships without it (Dockerfile
+// INSTALL_BUILD_AGENT_CLI=none), and the in-container install is best-effort —
+// if it was skipped (container not up when it first ran), nothing else would
+// catch the absent binary and the editor's auth probe times out forever, leaving
+// the Build tab stuck on "Checking your account…" (the 2026-06-30 reprovision
+// defect). This re-probes for `command -v <binary>`, makes one more install
+// attempt if it's missing, then throws (loud non-zero exit the dashboard's
+// fail-fast path acts on) if it STILL can't be installed — never rostering a
+// CLI-less VM. Runs AFTER assertEditorContainerRunning, so the container is
+// known up by the time we probe the binary.
+async function assertAgentCliInstalled(cfg) {
+  const agent = cfg.agent;
+  const container = process.env.CONTAINER || "codeyam-editor-editor-1";
+  if (probeAgentBinaryInstalled(cfg, container, agent)) {
+    return;
+  }
+  console.error(`  build-agent CLI '${agent}' not found in ${container}; attempting install before failing...`);
+  // containerStarted: assertAgentCliInstalled runs AFTER assertEditorContainerRunning,
+  // so the container is known up; this install is a legitimate post-start retry.
+  await ensureAgentCliInstalled(cfg, { containerStarted: true });
+  if (!probeAgentBinaryInstalled(cfg, container, agent)) {
+    throw new Error(
+      `provisioning incomplete: build-agent CLI '${agent}' is not installed in ${container} on ${cfg.instanceName} ` +
+        `(image ships without it and the in-container install failed). The editor auth probe will hang until it's present. ` +
+        `Re-run: npm run cloud:up -- --instance-name ${cfg.instanceName}`,
+    );
+  }
+}
+
 /** Read the laptop's git author identity (`user.name`, `user.email`) so
  *  cloud:up can forward it to the VM's container entrypoint, which writes
  *  it to `git config --global`. Without identity in the container,
@@ -1451,13 +2168,52 @@ function resolveLaptopGitIdentity(spawnImpl = spawnSync) {
  *  intentionally not done: the cost of one `gh` subprocess per cloud:up is
  *  trivial and lets a user `gh auth login` between operations. */
 function resolveGithubToken() {
-  const env = process.env.GITHUB_TOKEN || process.env.GH_TOKEN;
-  if (env) return env;
+  return resolveGithubTokenWithSource().token;
+}
+
+/** Like {@link resolveGithubToken} but also reports WHICH channel resolved the
+ *  token (`GITHUB_TOKEN` env, `GH_TOKEN` env, or `gh auth token`). The source is
+ *  logged on a successful seed so a misconfigured add-environment — e.g. a
+ *  launchd dashboard agent whose plist lacks the token env and whose `gh` can't
+ *  reach the operator's keychain — is diagnosable from the add log instead of
+ *  surfacing days later as a fleet-wide plan-claim-sync outage. `source` is
+ *  `null` when no token resolves. */
+function resolveGithubTokenWithSource() {
+  if (process.env.GITHUB_TOKEN) {
+    return { token: process.env.GITHUB_TOKEN, source: "GITHUB_TOKEN" };
+  }
+  if (process.env.GH_TOKEN) {
+    return { token: process.env.GH_TOKEN, source: "GH_TOKEN" };
+  }
   const ghOut = spawnSync("gh", ["auth", "token"], { encoding: "utf8" });
   if (ghOut.status === 0) {
-    return ghOut.stdout.trim();
+    const token = String(ghOut.stdout || "").trim();
+    if (token) return { token, source: "gh auth token" };
+  }
+  return { token: "", source: null };
+}
+
+/** Thrown by {@link seedGithubCredentials} when no GitHub token resolves and the
+ *  caller has NOT opted into a credential-less VM. The root harm this guards is
+ *  a VM that comes up "healthy" yet cannot `git push` its plan-claim refs to
+ *  origin, silently stranding fleet-wide claim sync (observed 2026-06-29 across
+ *  all 9 VMs). `degradedReason` is the machine-readable `CY_DEGRADED` body the
+ *  add path emits so the dashboard card lands amber with a recovery command
+ *  instead of a falsely-green healthy card. */
+class MissingGitPushCredentialsError extends Error {
+  constructor() {
+    super(
+      "No GITHUB_TOKEN / GH_TOKEN set and `gh auth token` is unavailable —\n" +
+        "the cloud VM cannot git pull/push, so plan-claim sync will not reach origin.\n" +
+        "Export GITHUB_TOKEN or run `gh auth login` locally, then `cloud:up` again,\n" +
+        "or re-seed a running VM with `npm run cloud:reconcile-credentials`.\n" +
+        "Pass --allow-no-git-credentials to provision an intentionally read-only VM.",
+    );
+    this.name = "MissingGitPushCredentialsError";
+    this.degradedReason =
+      "no-git-credentials: no GitHub push token resolved — plan-claim sync will not " +
+      "reach origin. Recover: npm run cloud:reconcile-credentials";
   }
-  return "";
 }
 
 /** A PULL-ONLY (`read:packages`) token the VM bootstrap uses to `docker login
@@ -1491,6 +2247,230 @@ 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).
+ *
+ *  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, or an auth/network error that can't be
+ *            distinguished from "absent".
+ *
+ *  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 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 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 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;
+}
+
+/** JS mirror of crates/control-api/src/plan_claims_sync.rs::classify_sync_error.
+ *  Categorizes a `git ls-remote` / push stderr into the SAME buckets the Rust
+ *  sync task uses (`credential` / `git-spawn` / `network` / `other`) so the
+ *  credential self-heal only re-seeds on a real credential gap, never a
+ *  transient network blip. Deliberate duplication: cloud.js (the fleet tool)
+ *  cannot call into the Rust crate, and the category strings are a stable
+ *  contract — keep the two lists in sync if either changes. */
+function classifyGitRemoteError(stderr) {
+  const lower = String(stderr || "").toLowerCase();
+  if (
+    [
+      "could not read username",
+      "terminal prompts disabled",
+      "authentication failed",
+      "device not configured",
+    ].some((s) => lower.includes(s))
+  ) {
+    return "credential";
+  }
+  if (lower.includes("no such file") && lower.includes("git")) {
+    return "git-spawn";
+  }
+  if (
+    [
+      "could not resolve host",
+      "connection refused",
+      "connection timed out",
+      "ssl certificate problem",
+      "tls",
+    ].some((s) => lower.includes(s))
+  ) {
+    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";
+}
+
+/** Pure decision for the credential self-heal. Given a probe of a running VM —
+ *  whether the host staging file (`~/.codeyam-cloud-git-credentials`) is empty,
+ *  and the outcome of an in-container `git ls-remote origin` — decide whether to
+ *  re-seed credentials in place.
+ *
+ *  Re-seed iff the host staging file is empty (so a restart wouldn't recover) OR
+ *  `ls-remote` failed with the `credential` signature. A `network` failure must
+ *  NOT trigger a re-write (a transient blip is not a credential gap), and a
+ *  healthy VM (ls-remote ok AND staging seeded) is a no-op. Returns
+ *  `{ heal, category, reason }`. */
+function decideCredentialHeal({ stagingEmpty, lsRemoteOk, lsRemoteStderr }) {
+  if (lsRemoteOk && !stagingEmpty) {
+    return {
+      heal: false,
+      category: "ok",
+      reason: "git ls-remote origin succeeds and the staging file is seeded",
+    };
+  }
+  if (!lsRemoteOk) {
+    const category = classifyGitRemoteError(lsRemoteStderr);
+    if (category === "network") {
+      return {
+        heal: false,
+        category,
+        reason: "ls-remote failed with a network error — not re-seeding (transient)",
+      };
+    }
+    if (category === "git-spawn") {
+      return {
+        heal: false,
+        category,
+        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,
+      reason: stagingEmpty
+        ? "staging file empty and ls-remote failing — re-seeding"
+        : "ls-remote failed with a credential error — re-seeding",
+    };
+  }
+  // ls-remote ok but the durable host file is empty (live cache seeded
+  // out-of-band): re-seed so the next container restart survives.
+  return {
+    heal: true,
+    category: "credential",
+    reason: "staging file empty (re-seed for restart durability)",
+  };
+}
+
+/** 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
@@ -1498,24 +2478,47 @@ function resolveGhcrPushToken() {
  *  inlined URL) but cannot `git pull` / `git push` afterward. The file is
  *  chmod 600 and never committed; if the local environment has no token,
  *  the placeholder file from gcp-project-bootstrap.sh stays in place. */
-async function seedGithubCredentials(cfg) {
-  const token = resolveGithubToken();
+async function seedGithubCredentials(cfg, opts = {}) {
+  const { token, source } = resolveGithubTokenWithSource();
   if (!token) {
-    console.error(
-      "\nNo GITHUB_TOKEN / GH_TOKEN set and `gh auth token` is unavailable —\n" +
-        "claude inside the cloud container will not be able to git pull/push.\n" +
-        "Export GITHUB_TOKEN or run `gh auth login` locally, then `cloud:up` again.\n",
-    );
-    return;
+    if (opts.allowNoCredentials) {
+      // Explicit opt-out: an intentionally read-only VM. Warn loudly (so it is
+      // never invisible) but do not throw — the caller asked for this.
+      console.error(
+        "\n--allow-no-git-credentials: no GitHub token resolved; provisioning a\n" +
+          "read-only VM. It cannot git push, so plan-claim sync will not reach origin.\n",
+      );
+      return;
+    }
+    // Fail loud: a VM that can't push plan-claim refs is degraded by definition.
+    throw new MissingGitPushCredentialsError();
   }
-  console.error("Writing GitHub token into ~/.codeyam-cloud-git-credentials on the VM...");
-  const credLine = `https://x-access-token:${token}@github.com`;
+  console.error(
+    `Writing GitHub token (from ${source}) into ~/.codeyam-cloud-git-credentials on the VM...`,
+  );
+  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-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 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 && ` +
-    `echo ${b64} | base64 -d > $f && chmod 600 $f && echo OK`;
+    `f=$HOME/.codeyam-cloud-git-credentials && t="$f.tmp.$$" && ` +
+    `echo ${b64} | base64 -d > "$t" && chmod 600 "$t" && ` +
+    `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 }),
     { stdio: ["ignore", "pipe", "inherit"] },
@@ -1525,26 +2528,76 @@ async function seedGithubCredentials(cfg) {
   }
 }
 
+/** 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);
@@ -1642,36 +2695,63 @@ async function seedPreviewOrigin(cfg, appPort = VITE_PORT) {
     sameOriginSafe = previewSameOriginSafeFromStack(parseObj(stackJson));
   }
 
+  // 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
+  // early); for any other entry point it's resolved from the sidecar by number.
+  const seedVm = resolveFleetVmNumber(cfg.instanceName);
+  const seedSlug =
+    cfg.vmSlug && String(cfg.vmSlug).trim() !== ""
+      ? cfg.vmSlug
+      : seedVm != null
+        ? slugFor(seedVm)
+        : null;
   const seed = resolveSeedPreviewOrigin(
     cfg.instanceName,
     readCloudflaredUrls(),
     appPort,
     process.env,
     sameOriginSafe,
+    seedSlug,
   );
 
   // Skip-on-already-set guard, EXCEPT for self-heal. A non-empty previewOrigin
-  // is normally a user pin or a good prior seed and is left untouched. The one
-  // exception is a ROTTED managed cloudflared quick-tunnel URL on a
-  // same-origin-safe VM (the VM-1/2/6 leftover from before the improve38
-  // same-origin migration): that frozen URL points at a dead rotated tunnel
-  // (NXDOMAIN / blank preview), so we heal it back to the same-origin path
-  // instead of preserving it. Because every dashboard action (Reset / Update /
-  // Add / bootstrap-recovery) re-runs this seed over cloud:up, the heal reaches
-  // every touch-point without a separate per-VM hand-fix.
+  // is normally a user pin or a good prior seed and is left untouched. There are
+  // TWO symmetric heal exceptions, both of which the frozen skip-guard would
+  // otherwise pin forever:
+  //   1. a ROTTED managed cloudflared quick-tunnel URL on a same-origin-safe VM
+  //      (the VM-1/2/6 leftover from before the improve38 same-origin
+  //      migration): that frozen URL points at a dead rotated tunnel (NXDOMAIN /
+  //      blank preview), so we heal it back to the same-origin path; and
+  //   2. a WRONG-MODE previewOrigin on a NOT-same-origin-safe VM (the VM7 race:
+  //      the first seed ran before onboarding wrote stack.json, defaulted to
+  //      `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.
+  // 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
+  // provisioning, and without a separate per-VM hand-fix.
   const originAlreadySet =
     typeof current.previewOrigin === "string" && current.previewOrigin.length > 0;
   const healing =
-    originAlreadySet && isRottedManagedPreviewOrigin(current, sameOriginSafe);
+    originAlreadySet &&
+    (isRottedManagedPreviewOrigin(current, sameOriginSafe) ||
+      isWrongModePreviewOrigin(current, sameOriginSafe));
   if (originAlreadySet && !healing) {
     return;
   }
 
-  // On heal, also DROP the legacy `_managedPreviewOrigin` marker (deepMergeJson
-  // deletes any key whose overlay value is null) — the same-origin path is a
-  // constant the retired monitor push has nothing to manage, exactly matching
-  // the manual `config-override --unset _managedPreviewOrigin` fix.
-  const overlay = healing ? { ...seed, _managedPreviewOrigin: null } : seed;
+  // On heal, reconcile the `_managedPreviewOrigin` marker to the healed value's
+  // own shape. The rotted→same-origin heal (seed carries NO marker) DROPS any
+  // stale marker (deepMergeJson deletes a key whose overlay value is null) — the
+  // constant same-origin path has nothing for the monitor to manage, exactly
+  // matching the manual `config-override --unset _managedPreviewOrigin` fix. The
+  // wrong-mode→dedicated heal (seed carries the marker) KEEPS it — that origin
+  // IS managed (the monitor's gated rotation push owns it), so the marker must
+  // survive so the next respawn recognises the value as ours.
+  const overlay = healing
+    ? { ...seed, _managedPreviewOrigin: seed._managedPreviewOrigin ?? null }
+    : seed;
   console.error(
     healing
       ? `Healing rotted managed previewOrigin (${current.previewOrigin}) → ${seed.previewOrigin} in ${remotePath}...`
@@ -1691,28 +2771,107 @@ async function seedPreviewOrigin(cfg, appPort = VITE_PORT) {
   }
 }
 
-/** Write the chosen agent provider and local API keys into editor.local.json on
- *  the VM BEFORE compose up so the file exists when the bind-mount happens —
- *  the provider seed MUST run before ensureEditorContainerUp, because the editor
- *  caches config.provider at startup and reports it as currentProvider; a post-start
- *  seed leaves the running editor (and therefore the dashboard badge) on the default
- *  "claude" until a config reload. */
-async function seedAgentApiKey(cfg) {
-  // The provider seed is unconditional — `buildEditorLocalEnvPatch` always
-  // returns a patch carrying `provider`, so the chosen agent always lands on
-  // the VM. The API-key seed is opportunistic: when the matching key isn't set
-  // locally the patch carries `provider` only, and we still print the
-  // interactive-auth fallback line so the operator knows to authenticate the
-  // agent on the VM later (Gemini's normal path).
-  const patch = buildEditorLocalEnvPatch(process.env, cfg.agent);
-  const hasKey = Boolean(patch.env);
-  if (!hasKey) {
-    console.error(
-      `\nNo ${agentEnvVarName(cfg.agent)} set locally — seeding provider only.\n` +
-        `Authenticate ${cfg.agent} later with:\n` +
-        `  gcloud compute ssh ${cfg.instanceName} --project ${cfg.project} --zone ${cfg.zone} ` +
-        `--tunnel-through-iap -- ${cfg.agent} auth login\n`,
-    );
+/** READY-probe auto-heal: after the editor container is verifiably Up, ask the
+ *  running editor's own `/api/config` for its stack verdict and effective
+ *  preview origin, and heal a wrong-moded seed in place — never failing the add.
+ *
+ *  The race this closes (VM7, 2026-06-10): the pre-container `seedPreviewOrigin`
+ *  at line ~1906 runs BEFORE onboarding writes stack.json, so it defaults to
+ *  `sameOriginSafe: true` and seeds the `/__codeyam_preview` subpath. For a
+ *  client-routed stack (Next.js) the editor then reports `previewSameOriginSafe:
+ *  false` but, with only the subpath in editor.local.json, falls its
+ *  `dedicated_preview_origin` back to `http://127.0.0.1:<appPort>` — which a
+ *  remote browser renders as "refused to connect". If stack.json appeared since
+ *  the first seed (the editor reads it live from disk), we re-run the seed — now
+ *  the wrong-mode heal fires (`isWrongModePreviewOrigin`) — and POST
+ *  `/api/editor-reload-config` so the running server serves the healed origin
+ *  with no restart.
+ *
+ *  Best-effort and non-fatal by contract: a probe failure, a still-absent
+ *  stack.json (verdict stays `true`), or a heal that can only reach a loopback
+ *  bootstrap origin (the operator's `<N>-preview` tunnel not published yet) all
+ *  leave the add green. The cloudflared-monitor's periodic tick (section 2) is
+ *  the durable owner that heals post-add flips — onboarding finishing minutes
+ *  after READY. */
+async function healPreviewOriginAtReady(cfg, appPort = VITE_PORT) {
+  const probe = runGcloud(
+    buildGcloudArgs("ssh-probe", cfg, {
+      command: `curl -fsS --max-time 5 http://localhost:${EDITOR_PORT}/api/config 2>/dev/null || echo '{}'`,
+    }),
+    { stdio: ["ignore", "pipe", "ignore"] },
+  );
+  if (probe.status !== 0 || typeof probe.stdout !== "string") {
+    return;
+  }
+  let config;
+  try {
+    config = JSON.parse(probe.stdout);
+  } catch {
+    return;
+  }
+  if (!config || typeof config !== "object") return;
+
+  // The editor's own verdict (section 3's `/api/config` field) plus the
+  // wrong-mode predicate (a subpath / relative / loopback origin on a
+  // not-same-origin-safe stack) — the exact dead-end the dedicated-origin
+  // fallback lands on. Same-origin-safe stacks (verdict true) never enter here.
+  if (config.previewSameOriginSafe !== false) return;
+  if (!isWrongModePreviewOrigin(config, false)) return;
+
+  console.error(
+    `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);
+  // Tell the running server to re-read editor.local.json — no restart (the
+  // footgun that killed VM7's live Claude session).
+  const reload = runGcloud(
+    buildGcloudArgs("ssh-probe", cfg, {
+      command: `curl -fsS --max-time 5 -X POST http://localhost:${EDITOR_PORT}/api/editor-reload-config 2>/dev/null || true`,
+    }),
+    { stdio: ["ignore", "inherit", "inherit"] },
+  );
+  if (reload.status !== 0) {
+    console.error(
+      `  Warning: heal wrote editor.local.json but /api/editor-reload-config did ` +
+        `not return cleanly — the next monitor tick or cloud:up touch-point will reconcile.`,
+    );
+  }
+  console.error(
+    `  Live Preview origin healed. If the operator <N>-preview tunnel is not ` +
+      `published yet, the cloudflared-monitor's periodic tick provides the ongoing heal.`,
+  );
+}
+
+/** Write the chosen agent provider and local API keys into editor.local.json on
+ *  the VM BEFORE compose up so the file exists when the bind-mount happens —
+ *  the provider seed MUST run before ensureEditorContainerUp, because the editor
+ *  caches config.provider at startup and reports it as currentProvider; a post-start
+ *  seed leaves the running editor (and therefore the dashboard badge) on the default
+ *  "claude" until a config reload. */
+async function seedAgentApiKey(cfg) {
+  // The provider seed is unconditional — `buildEditorLocalEnvPatch` always
+  // returns a patch carrying `provider`, so the chosen agent always lands on
+  // the VM. The API-key seed is opportunistic: when the matching key isn't set
+  // locally the patch carries `provider` only, and we still print the
+  // interactive-auth fallback line so the operator knows to authenticate the
+  // agent on the VM later (Gemini's normal path).
+  const patch = buildEditorLocalEnvPatch(process.env, cfg.agent);
+  const hasKey = Boolean(patch.env);
+  if (!hasKey) {
+    console.error(
+      `\nNo ${agentEnvVarName(cfg.agent)} set locally — seeding provider only.\n` +
+        `Authenticate ${cfg.agent} on the VM by either:\n` +
+        `  • exporting ${agentEnvVarName(cfg.agent)} locally and re-running cloud:up, or\n` +
+        `  • pasting the key into the Build tab's auth gate in the editor.\n` +
+        `Either path now flows the key through to the agent process on the VM.\n` +
+        `Interactive browser-based OAuth login (e.g. \`codex login\`) is not yet ` +
+        `supported headlessly on the VM.\n`,
+    );
   }
   const repoName = resolveProject(cfg).name;
   const remotePath = `~/projects/${repoName}/.codeyam/editor.local.json`;
@@ -1752,29 +2911,234 @@ async function seedAgentApiKey(cfg) {
   if (write.status !== 0) {
     throw new Error(`Failed to write ${remotePath} on VM`);
   }
+  // NOTE: seedAgentApiKey deliberately does NOT install the build-agent CLI.
+  // The CLI install is a POST-container-start step owned solely by
+  // ensureEditorContainerUp (which runs `docker compose up -d` first). Seeding
+  // the API key runs BEFORE the container is up, so a CLI install here would
+  // enter ensureAgentCliInstalled's wait-for-container branch before any
+  // `up -d` had happened — burning the whole wait window and firing a spurious
+  // `CY_DEGRADED cli-deferred` on every add. That mis-ordering is the bug
+  // vm--no-cli-install-before-container-started removed; do not re-add it.
+}
 
-  await ensureAgentCliInstalled(cfg);
+/** 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");
 }
 
-/** Install the selected agent's CLI inside the editor container on the live VM */
-async function ensureAgentCliInstalled(cfg) {
-  const agent = cfg.agent;
-  const pkg = agentNpmPackage(agent);
-  const container = process.env.CONTAINER || "codeyam-editor-editor-1";
+/** 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}...`);
 
-  // First, check if the container is running on the VM host.
-  // If the container is not running, we do nothing and return.
+  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"`.
+ *
+ *  The distinction matters: `probeContainerState` runs `docker ps` over
+ *  gcloud/IAP-SSH, and a NON-zero exit means the probe itself couldn't run — a
+ *  transient operator-auth flap (`[operator-auth] DEGRADED: could not resolve
+ *  an account`, observed in the 2026-06-30 incident) or an SSH/transport blip —
+ *  NOT proof the container is down. That is `"unknown"` and must never count
+ *  toward a give-up/teardown decision. Only a clean `docker ps` (exit 0) is
+ *  authoritative: a non-empty line is `"running"`, an empty result is
+ *  `"not-running"`.
+ *
+ *  The format field is `{{.Names}}` (plural). `docker ps` has NO `.Name` field
+ *  (that belongs to `docker inspect`); `'{{.Name}}'` makes `docker ps` exit
+ *  non-zero with `can't evaluate field Name in type *formatter.ContainerContext`,
+ *  which — pre-fix — made every probe report a non-running container regardless
+ *  of its real state and took the whole fleet to zero on 2026-06-30. */
+function probeContainerState(cfg, container) {
   const checkProbe = runGcloud(
     buildGcloudArgs("ssh-probe", cfg, {
-      command: `docker ps --filter name=^/${container}$ --filter status=running --format '{{.Name}}'`,
+      command: `docker ps --filter name=^/${container}$ --filter status=running --format '{{.Names}}'`,
     }),
     { stdio: ["ignore", "pipe", "ignore"] },
   );
+  if (checkProbe.status !== 0) {
+    return "unknown";
+  }
+  return checkProbe.stdout.trim() !== "" ? "running" : "not-running";
+}
 
-  const isRunning = checkProbe.status === 0 && checkProbe.stdout.trim() !== "";
-  if (!isRunning) {
-    console.error(`  Container ${container} is not running. Skipping build-agent CLI install for now.`);
-    return;
+/** Boolean convenience wrapper over {@link probeContainerState}: true ONLY when
+ *  the container is definitively running. An `"unknown"` probe (auth/SSH error)
+ *  is not "running", so this returns false — callers that must distinguish a
+ *  probe failure from a down container use `probeContainerState` directly. */
+function probeContainerRunning(cfg, container) {
+  return probeContainerState(cfg, container) === "running";
+}
+
+/** Probe whether `binary` resolves on PATH inside the running container. */
+function probeAgentBinaryInstalled(cfg, container, binary) {
+  const probe = runGcloud(
+    buildGcloudArgs("ssh-probe", cfg, {
+      command: `docker exec ${container} bash -lc 'command -v ${binary}'`,
+    }),
+    { stdio: ["ignore", "pipe", "ignore"] },
+  );
+  return probe.status === 0 && probe.stdout.trim() !== "";
+}
+
+/** Poll the container's running state, returning true as soon as it's running.
+ *  The accept-on-first-success shape means the common already-running case
+ *  returns instantly with zero added latency. Parameterized so a unit test can
+ *  drive it with `sleepFn` = a no-op.
+ *
+ *  `attempts` (default 48) bounds only DEFINITIVE `"not-running"` probes — at
+ *  the capped-backoff cadence below that is a multi-minute budget (~4 min),
+ *  generous enough for a slow first-boot editor container under fleet load
+ *  (30s was far too short and guillotined healthy slow boots). An `"unknown"`
+ *  probe (auth/SSH transport failure) may clear, so it does NOT consume the
+ *  budget; a hard iteration cap (2× attempts) still prevents an infinite loop
+ *  when the probe is permanently unreachable. Backoff (delayMs → maxDelayMs)
+ *  keeps the poll cheap early and patient late. */
+async function waitForContainerRunning(
+  cfg,
+  container,
+  { attempts = 48, delayMs = 5000, maxDelayMs = 15000, sleepFn } = {},
+) {
+  const sleep = sleepFn || ((ms) => new Promise((r) => setTimeout(r, ms)));
+  let notRunning = 0;
+  const maxIterations = attempts * 2;
+  for (let i = 0; i < maxIterations && notRunning < attempts; i++) {
+    const state = probeContainerState(cfg, container);
+    if (state === "running") {
+      return true;
+    }
+    if (state === "not-running") {
+      notRunning += 1;
+      console.error(`  waiting for container ${container} to reach running (${notRunning}/${attempts})...`);
+    } else {
+      // unknown: a probe-transport failure (auth/SSH), not proof the container
+      // is down — retry without counting toward the give-up budget.
+      console.error(`  container ${container} probe inconclusive (auth/SSH?); retrying without counting toward give-up...`);
+    }
+    if (notRunning >= attempts) {
+      break;
+    }
+    await sleep(Math.min(maxDelayMs, delayMs * 2 ** Math.min(i, 3)));
+  }
+  return probeContainerRunning(cfg, container);
+}
+
+/** Install the selected agent's CLI inside the editor container on the live VM.
+ *
+ *  PRECONDITION: the caller must have already STARTED the container (via
+ *  ensureEditorContainerUp's `docker compose up -d`, or after confirming it is
+ *  already running). This is a post-start install helper, NOT a container
+ *  starter — its wait-for-container branch only exists to absorb a slow boot
+ *  *after* `up -d`. Legitimate callers signal this with `waitOpts.containerStarted`;
+ *  entering the wait branch WITHOUT that signal is almost certainly a call-ordering
+ *  regression (the mis-ordering that made every add burn the full wait window and
+ *  emit a spurious `CY_DEGRADED cli-deferred` — see
+ *  vm--no-cli-install-before-container-started) and is warned about loudly.
+ *
+ *  `waitOpts` is forwarded to {@link waitForContainerRunning} (a unit test
+ *  injects `{ attempts, delayMs, sleepFn }` so the defer path resolves without
+ *  the multi-minute real-timer wait); `waitOpts.containerStarted` is the
+ *  precondition acknowledgement described above; production start-path calls
+ *  pass `{ containerStarted: true }`. */
+async function ensureAgentCliInstalled(cfg, waitOpts = {}) {
+  const agent = cfg.agent;
+  const pkg = agentNpmPackage(agent);
+  const container = process.env.CONTAINER || "codeyam-editor-editor-1";
+
+  // The container may not be up the instant this runs — a slow `docker compose
+  // up -d` or a recreate still settling. This used to log "Skipping … for now"
+  // and RETURN, but nothing ever re-asserted it: because the image ships WITHOUT
+  // the agent CLI (Dockerfile INSTALL_BUILD_AGENT_CLI=none), a skipped install
+  // left the VM with no `claude` anywhere for its whole lifetime and stranded the
+  // Build-tab auth probe (the 2026-06-30 reprovision defect). Poll for the
+  // container, then DEGRADE LOUD (never throw) if it still isn't up.
+  if (!probeContainerRunning(cfg, container)) {
+    if (!waitOpts.containerStarted) {
+      // Precondition breach: we are about to wait for a container that no
+      // caller has started. On a healthy add this branch is unreachable
+      // (ensureEditorContainerUp starts the container, then calls us with
+      // `containerStarted: true`). Reaching it with no start recorded means an
+      // install was ordered before `docker compose up -d` — the exact
+      // mis-ordering that cost ~4 minutes and a spurious CY_DEGRADED on every
+      // add. Warn loudly so a future regression is caught at the log instead of
+      // silently burning the wait window.
+      console.error(
+        `  ⚠ build-agent CLI install ordered before any editor container start ` +
+          `(${container} is not running and no container-start was signalled). ` +
+          `The CLI install is a POST-start step and must run AFTER \`docker compose up -d\` ` +
+          `in ensureEditorContainerUp — this is very likely a call-ordering regression.`,
+      );
+    }
+    console.error(`  Container ${container} is not running yet; waiting before installing build-agent CLI...`);
+    const up = await waitForContainerRunning(cfg, container, waitOpts);
+    if (!up) {
+      // DEFENSE-IN-DEPTH: a CLI install that can't confirm the container — a
+      // genuinely slow boot, a transient operator-auth/SSH blip, or a future
+      // probe bug like the {{.Name}}→{{.Names}} regression that took the fleet
+      // to zero on 2026-06-30 — must DEFER, never throw. cloud:up's abort path
+      // catches a throw here and DELETES the instance ("no orphan"); a healthy
+      // VM with a deferred CLI install is fully recoverable (readiness flags it
+      // provision-incomplete / cli-missing; the dashboard's one-click finish-wire
+      // re-runs cloud:up, which re-asserts this install), but a deleted VM is not.
+      // Loud signal (no silent skip — the VM5 CLI-less defect stays fixed), no
+      // teardown. The `CY_DEGRADED` prefix is what the dashboard's add-job scanner
+      // keys off to land an amber card.
+      console.error(
+        `  CY_DEGRADED cli-deferred: container ${container} never reached status=running on ${cfg.instanceName} ` +
+          `within the wait window — DEFERRING build-agent CLI install (VM kept). ` +
+          `Readiness will flag cli-missing; re-run: npm run cloud:up -- --instance-name ${cfg.instanceName}`,
+      );
+      return;
+    }
   }
 
   console.error(`Ensuring build-agent CLI for '${agent}' is installed in container '${container}'...`);
@@ -1787,22 +3151,18 @@ async function ensureAgentCliInstalled(cfg) {
     `AGENT="${agent}"`,
     "",
     "if command -v \"$BINARY\" >/dev/null 2>&1; then",
-    "  if [ \"$AGENT\" = \"claude\" ]; then",
-    "    if [ -x /usr/local/bin/claude ]; then",
-    "      echo \"  ✓ $BINARY already installed and executable at /usr/local/bin/claude\"",
-    "      exit 0",
-    "    fi",
-    "  else",
-    "    echo \"  ✓ $BINARY already installed on PATH\"",
-    "    exit 0",
-    "  fi",
+    "  echo \"  ✓ $BINARY already installed on PATH\"",
+    "  exit 0",
     "fi",
     "",
     "echo \"Installing $PACKAGE globally in container...\"",
     "if [ \"$AGENT\" = \"claude\" ]; then",
     "  rm -rf /usr/lib/node_modules/@anthropic-ai/.claude-code-*",
     "  npm install -g \"$PACKAGE\"",
-    "  ln -sf /usr/lib/node_modules/@anthropic-ai/claude-code/node_modules/@anthropic-ai/claude-code-linux-x64/claude /usr/local/bin/claude",
+    "  RESOLVED=$(find /usr/lib/node_modules/@anthropic-ai -name claude -type f -path '*linux-x64*' 2>/dev/null | head -1)",
+    "  if [ -n \"$RESOLVED\" ]; then",
+    "    ln -sf \"$RESOLVED\" /usr/local/bin/claude",
+    "  fi",
     "else",
     "  npm install -g \"$PACKAGE\"",
     "fi",
@@ -1864,19 +3224,800 @@ function promptForInstanceName(expected) {
   });
 }
 
+const STREAMED_SCRIPTS = ["scripts/gcp-bootstrap.sh", "scripts/gcp-project-bootstrap.sh"];
+
+/** The configured editor branch to compare/stream streamed scripts against.
+ *  Resolved from config (`resolveEditorConfig` → `editorBranch`, itself derived
+ *  from `cfg.editorBranch`, or the client branch when self-hosting; the dashboard
+ *  feeds this from `FLEET_BRANCH` / the legacy `BRANCH` alias). Never a hardcoded
+ *  branch literal — the dashboard tracks different branches over time. */
+function streamedScriptEditorBranch(cfg) {
+  const { editorBranch = "main" } = resolveEditorConfig(cfg);
+  return editorBranch;
+}
+
+/** Merge base between HEAD and the remote tip of `editorBranch`, or null when it
+ *  can't be resolved (no remote ref, detached, etc.). */
+function streamedScriptMergeBase(editorBranch) {
+  const mbResult = spawnSync("git", ["merge-base", "HEAD", `origin/${editorBranch}`], { encoding: "utf8" });
+  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,
+ *  treated downstream as "unknown" → fail-soft (never a false STALE). Shared by the
+ *  drift guard (`checkScriptDrift`) and the streaming-source decision
+ *  (`readStreamedScript`) so both judge identical facts. `relPath` is repo-relative
+ *  (the STREAMED_SCRIPTS form) — git is invoked from the repo root. */
+function gatherScriptDriftFacts(relPath, editorBranch, mergeBase) {
+  const localHashResult = spawnSync("git", ["hash-object", relPath], { encoding: "utf8" });
+  const localHash = localHashResult.status === 0 ? localHashResult.stdout.trim() : null;
+
+  const remoteRev = resolveRemoteScriptRev("rev-parse", relPath, editorBranch);
+  const remoteHash = remoteRev.ok ? remoteRev.stdout.trim() : null;
+
+  let baseHash = null;
+  if (mergeBase) {
+    const baseHashResult = spawnSync("git", ["rev-parse", `${mergeBase}:${relPath}`], { encoding: "utf8" });
+    if (baseHashResult.status === 0) {
+      baseHash = baseHashResult.stdout.trim();
+    }
+  }
+
+  const statusResult = spawnSync("git", ["status", "--porcelain", relPath], { encoding: "utf8" });
+  const dirty = statusResult.status === 0 && statusResult.stdout.trim() !== "";
+
+  return { path: relPath, localHash, remoteHash, baseHash, dirty };
+}
+
+/** Read the canonical bytes of a streamed provisioning script for sending to a VM.
+ *  Prefers the remote tip (`git show origin/<editorBranch>:<path>`) so a checkout
+ *  merely *behind* origin streams exactly the reviewed bytes the drift guard
+ *  expects — the primary fix for the "fleet just landed a script commit → every
+ *  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 — `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);
+  const mergeBase = streamedScriptMergeBase(editorBranch);
+  const facts = gatherScriptDriftFacts(relPath, editorBranch, mergeBase);
+
+  const { streamedScriptSource } = require("./script-drift");
+  if (streamedScriptSource(facts) === "remote") {
+    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;
+    }
+    // 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");
+}
+
+/** Check if the streamed bootstrap scripts have drifted from the remote repository
+ *  and abort provisioning when the local copy carries unreviewed content, to prevent
+ *  silent container/VM failures. A checkout that is merely *behind* origin is benign:
+ *  the add streams the canonical remote-tip bytes (see `readStreamedScript`), so
+ *  "behind" no longer blocks. The guard still fires for content the remote tip does
+ *  not have — an uncommitted (dirty) local edit or a genuine divergence. */
+function checkScriptDrift(cfg) {
+  if (process.env.CODEYAM_SKIP_SCRIPT_DRIFT_CHECK === "1") {
+    console.error("  [Warning] CODEYAM_SKIP_SCRIPT_DRIFT_CHECK=1 active. Skipping streamed-script drift preflight check.");
+    return;
+  }
+
+  const editorBranch = streamedScriptEditorBranch(cfg);
+
+  console.error(`Checking streamed-script drift against origin/${editorBranch}...`);
+
+  // 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;
+  }
+
+  // 2. Find the merge base between HEAD and origin/<editorBranch>
+  const mergeBase = streamedScriptMergeBase(editorBranch);
+
+  const filesData = [];
+  for (const scriptPath of STREAMED_SCRIPTS) {
+    const facts = gatherScriptDriftFacts(scriptPath, editorBranch, mergeBase);
+    if (facts.localHash === null) {
+      console.error(`  [Warning] Failed to compute local hash for ${scriptPath}. Skipping drift check.`);
+      return;
+    }
+    filesData.push(facts);
+  }
+
+  const { classifyScriptDrift, scriptDriftGuardAction } = require("./script-drift");
+  const verdictResult = classifyScriptDrift({ files: filesData });
+  const dirtyFiles = filesData.filter((f) => f.dirty).map((f) => f.path);
+  const action = scriptDriftGuardAction({
+    verdict: verdictResult.verdict,
+    staleFiles: verdictResult.staleFiles,
+    dirtyFiles,
+  });
+
+  if (action.block) {
+    const label = action.reason === "diverged" ? "DIVERGED" : "UNCOMMITTED LOCAL EDITS";
+    console.error("");
+    console.error("================================================================================");
+    console.error(`✗ ERROR: Streamed scripts carry unreviewed local content (origin/${editorBranch})!`);
+    console.error(`  Verdict: ${label}`);
+    console.error("  The following files differ locally from the reviewed remote tip:");
+    for (const f of action.blockedFiles) {
+      console.error(`    - ${f}`);
+    }
+    console.error("");
+    console.error("  Commit and push these changes, or discard them, before provisioning:");
+    console.error(`    git checkout -- <file>        # discard local edits`);
+    console.error(`    git pull --no-rebase origin ${editorBranch}`);
+    console.error("");
+    console.error("  If you must bypass this check (emergency provisioning), set:");
+    console.error("    CODEYAM_SKIP_SCRIPT_DRIFT_CHECK=1");
+    console.error("================================================================================");
+    console.error("");
+    process.exit(1);
+  } else if (action.reason === "behind") {
+    console.error("  ✓ Checkout is behind origin; streaming canonical remote-tip scripts (no pull needed).");
+  } else if (action.reason === "local-ahead") {
+    console.error("  [Warning] Streaming locally-committed scripts to VM (developer mode).");
+  } else {
+    console.error("  ✓ Streamed scripts are in sync with remote.");
+  }
+}
+
 // =============================================================================
 // Subcommand handlers
 // =============================================================================
 
-async function cmdUp(args) {
+/** Decide whether a VM's Add/Destroy should wire LB ingress, and with what
+ *  coordinates. Wiring fires iff a fleet domain is configured (cloud.json
+ *  `fleetDomain` or FLEET_DOMAIN env) AND the instance is a numbered fleet VM
+ *  (`resolveFleetVmNumber` → non-null). A non-fleet client project, or no domain,
+ *  returns `{ wire: false }` so the legacy quick-tunnel path is untouched. A
+ *  malformed domain throws (via resolveIngressDomain) — a typo must fail loud.
+ *  `env` is injectable for tests. Pure decision; the spawn lives in runVmIngress. */
+function ingressWiringPlan(cfg = {}, env = process.env) {
+  const domain = resolveIngressDomain(cfg, env);
+  if (!domain) return { wire: false, reason: "no-domain" };
+  const vmNumber = resolveFleetVmNumber(cfg.instanceName);
+  if (vmNumber == null) return { wire: false, reason: "not-fleet-vm", domain };
+  // Resolve the custom hostname slug, if any: the Add-time --vm-slug flag on cfg
+  // wins (validated/normalized in cmdUp), else the persisted sidecar entry (the
+  // Destroy path, where cfg carries no slug). null ⇒ the numeric vm-<N> host.
+  const slug =
+    cfg.vmSlug && String(cfg.vmSlug).trim() !== ""
+      ? normalizeVmSlug(cfg.vmSlug)
+      : slugFor(vmNumber);
+  return { wire: true, domain, vmNumber, slug };
+}
+
+/** The fleet instance-name prefix vm-ingress.sh expects (`<base>-`, e.g.
+ *  `codeyam-editor-codeyam-editor-`). Derived from the canonical editor repo so
+ *  it stays in lockstep with `resolveFleetVmNumber`'s base, rather than relying
+ *  on the script's hard-coded default. */
+function fleetInstancePrefix() {
+  return `${deriveInstanceName(CANONICAL_EDITOR_REPO)}-`;
+}
+
+/** Wire (`up`) or unwire (`down`) one VM's LB backends by spawning
+ *  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) {
+  const scriptPath = path.join(rootDir, "scripts", "gcp", "vm-ingress.sh");
+  const inv = vmIngressInvocation({
+    scriptPath,
+    vmNumber,
+    action,
+    domain,
+    project: cfg.project,
+    zone: cfg.zone,
+    appPort,
+    instancePrefix: fleetInstancePrefix(),
+    slug,
+  });
+  return spawnSync(inv.command, inv.args, {
+    stdio: "inherit",
+    env: { ...process.env, ...inv.env },
+  });
+}
+
+/** 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 },
+  });
+}
+
+/** 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. */
+function wireVmIngressOnAdd(cfg, appPort, env = process.env) {
+  const plan = ingressWiringPlan(cfg, env);
+  if (!plan.wire) return;
+  const label = plan.slug || `vm-${plan.vmNumber}`;
+  console.error(`  wiring LB ingress for VM-${plan.vmNumber} on ${plan.domain}...`);
+  const res = runVmIngress(cfg, "up", plan.vmNumber, plan.domain, appPort, plan.slug);
+  if (res.status === 0) {
+    console.error(`  ✓ LB ingress wired: https://${label}.editor.${plan.domain}`);
+  } else {
+    const rewire =
+      `FLEET_DOMAIN=${plan.domain}${plan.slug ? ` VM_SLUG=${plan.slug}` : ""} ` +
+      `bash scripts/gcp/vm-ingress.sh ${plan.vmNumber} up`;
+    console.error(
+      `  ⚠ LB ingress wiring for VM-${plan.vmNumber} did not complete cleanly. ` +
+        `The VM is provisioned; re-wire with:\n      ${rewire}`,
+    );
+    // Machine-readable degraded marker so the unwired VM lands an amber card with
+    // its remediation instead of a falsely-green "+ wired" (the VM7-10 bug). The
+    // dashboard's add-job scanner (server.js) keys off `CY_DEGRADED <reason>`,
+    // exactly as it does for a failed creds copy / `npm run setup`. Best-effort:
+    // the Add stays green (the VM is reachable operator-side) — the marker makes
+    // the missing public ingress VISIBLE, it doesn't abort provisioning.
+    console.log(
+      `CY_DEGRADED ingress-not-wired: VM-${plan.vmNumber} has no public LB ingress ` +
+        `(vm-ingress.sh up exited ${res.status == null ? "abnormally" : res.status}). Re-wire: ${rewire}`,
+    );
+  }
+}
+
+/** Destroy-time hook: unwire VM-N's LB backends before the instance is deleted,
+ *  mirroring the destroy-time quick-tunnel cleanup so no orphaned NEG / backend
+ *  service / host rule is left behind. Best-effort + loud, and wrapped so a
+ *  malformed-domain throw can't block the instance deletion the operator asked
+ *  for. No-op in legacy mode / for a non-fleet project. Purely LB ingress
+ *  teardown — slug cleanup is NOT done here (it was, but that coupled slug
+ *  release to `plan.wire` and stranded non-wired VMs' slugs); `cmdDestroy` now
+ *  owns the unconditional `removeSlug`. */
+function unwireVmIngressOnDestroy(cfg, env = process.env) {
+  let plan;
+  try {
+    plan = ingressWiringPlan(cfg, env);
+  } catch (e) {
+    console.error(`  Warning: skipped LB ingress teardown (${e.message}).`);
+    return;
+  }
+  if (!plan.wire) return;
+  console.error(`  unwiring LB ingress for VM-${plan.vmNumber} on ${plan.domain}...`);
+  // Pass the SAME slug the host rule was wired with so the slug host (not a stale
+  // vm-<N> one) is removed; resolved from the sidecar by ingressWiringPlan.
+  const res = runVmIngress(cfg, "down", plan.vmNumber, plan.domain, undefined, plan.slug);
+  if (res.status !== 0) {
+    console.error(
+      `  Warning: LB ingress teardown for VM-${plan.vmNumber} did not complete; ` +
+        `orphaned LB resources may remain. Re-run: ` +
+        `FLEET_DOMAIN=${plan.domain}${plan.slug ? ` VM_SLUG=${plan.slug}` : ""} bash scripts/gcp/vm-ingress.sh ${plan.vmNumber} down`,
+    );
+  }
+}
+
+/** Grant or revoke per-VM IAP access by spawning scripts/gcp/iap-access.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;
+ *  access can be re-applied), Destroy likewise warns so a teardown still removes
+ *  the instance. `principals` is the validated list to grant/revoke. */
+function runIapAccess(cfg, vmNumber, action, principals) {
+  const scriptPath = path.join(rootDir, "scripts", "gcp", "iap-access.sh");
+  const inv = iapAccessInvocation({
+    scriptPath,
+    vmNumber,
+    action,
+    principals,
+    project: cfg.project,
+    zone: cfg.zone,
+  });
+  return spawnSync(inv.command, inv.args, {
+    stdio: "inherit",
+    env: { ...process.env, ...inv.env },
+  });
+}
+
+/** Add-time hook: reconcile VM-N's access whitelist to *exactly* the requested
+ *  list, making provision the authoritative clean-slate point so a freed-and-
+ *  reused VM number never inherits the previous tenant's grants. Computes the
+ *  principals the prior tenant had that this Add does not want (`staleOnly`) and
+ *  revokes them from the per-VM backend services, grants the requested list, then
+ *  rewrites the sidecar to exactly the desired list (clearing the entry when the
+ *  list is empty). The gcloud revoke/grant only fire when the VM is wired onto the
+ *  LB (a fleet domain is set) — the backend services the bindings target exist
+ *  only then — but the sidecar is reconciled regardless, so a domain-less project
+ *  still starts clean and a later domain'd re-add inherits nothing stale. Add no
+ *  longer depends on Destroy having cleaned up (a dashboard destroy bypasses the
+ *  CLI revoke path). Best-effort + loud, the same posture as wireVmIngressOnAdd:
+ *  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) {
+  const desired = normalizeAccessList(cfg.vmAccess || []);
+  let plan;
+  try {
+    plan = ingressWiringPlan(cfg, env);
+  } catch {
+    // A malformed domain must not block an otherwise-green Add; fall back to the
+    // name-derived number so the sidecar still reconciles to a clean slate.
+    plan = { wire: false };
+  }
+  const vmNumber = plan.wire ? plan.vmNumber : resolveFleetVmNumber(cfg.instanceName);
+  if (vmNumber == null) return; // not a fleet VM — nothing to reconcile
+  // The list we GRANT always unions in the configured default operator, so an
+  // empty `vmAccess` still yields access for the operator — an IAP-enabled VM is
+  // 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 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));
+
+  if (plan.wire) {
+    if (staleOnly.length > 0) {
+      console.error(`  revoking ${staleOnly.length} stale IAP principal(s) from VM-${vmNumber} (prior tenant)...`);
+      const res = runIapAccess(cfg, vmNumber, "revoke", staleOnly);
+      if (res.status !== 0) {
+        console.error(
+          `  ⚠ IAP access revoke for VM-${vmNumber} did not complete cleanly. ` +
+            `The sidecar is reconciled; re-revoke with:\n` +
+            `      VM_ACCESS=${staleOnly.join(",")} bash scripts/gcp/iap-access.sh ${vmNumber} revoke`,
+        );
+      }
+    }
+    if (toGrant.length > 0) {
+      console.error(`  granting IAP access to VM-${vmNumber} for ${toGrant.length} principal(s)...`);
+      const res = runIapAccess(cfg, vmNumber, "grant", toGrant);
+      if (res.status === 0) {
+        console.error(`  ✓ IAP access granted: ${toGrant.join(", ")}`);
+      } else {
+        console.error(
+          `  ⚠ IAP access grant for VM-${vmNumber} did not complete cleanly. ` +
+            `The VM is provisioned; re-grant with:\n` +
+            `      VM_ACCESS=${toGrant.join(",")} bash scripts/gcp/iap-access.sh ${vmNumber} grant`,
+        );
+      }
+    }
+  } else if (toGrant.length > 0) {
+    console.error(
+      `  (no fleet domain / not a fleet VM — IAP access for ${toGrant.length} principal(s) not applied; ` +
+        `set a fleet domain and re-run, or use cloud:access)`,
+    );
+  }
+
+  // Sidecar reconcile (always, for a fleet VM): record the explicit collaborator
+  // list (`desired`) when wired, or empty when not (nothing was applied without
+  // backend services). The default operator is deliberately excluded — it is a
+  // standing grant re-applied on every wire, not a per-VM collaborator, so the
+  // sidecar display + a reused number's stale-revoke stay about collaborators
+  // only. setAccess deletes the entry on empty, so a reused number never carries a
+  // prior tenant's stale entry forward into the dashboard display or a re-add.
+  const granted = plan.wire ? desired : [];
+  try {
+    setAccess(vmNumber, granted);
+  } catch (e) {
+    console.error(`  ⚠ could not persist VM-${vmNumber} access list (${e.message}).`);
+  }
+}
+
+// The directory the add-tail in-flight marker lives in — `os.tmpdir()` (not a
+// hard-coded `/tmp`) so the windows-portability static check stays happy and the
+// dashboard reads the same path via the shared `ingressInflightMarkerPath` builder.
+const INGRESS_INFLIGHT_DIR = os.tmpdir();
+
+// Add-time ingress CONVERGE loop bounds (vm--add-time-url-wiring-converges-
+// reliably). The detached add-tail re-runs `vm-ingress.sh up`+`status` on its own
+// TIGHT cadence (seconds, not the ~15-min INGRESS_RECONCILE_MS sweep) until the
+// verdict is `wired` or the deadline elapses — so a fresh VM's public URL is live
+// in ~a minute rather than whenever the next roster-wide sweep lands. Overridable
+// via env for tests / operator tuning; the sweep stays the long-run safety net.
+const INGRESS_CONVERGE_DEADLINE_MS = 8 * 60 * 1000;
+const INGRESS_CONVERGE_BASE_MS = 5000;
+const INGRESS_CONVERGE_MAX_MS = 30000;
+
+/** Read a positive-integer env override, falling back to `fallback` on absent /
+ *  non-numeric / non-positive input. Keeps the converge bounds tunable without
+ *  scattering `Number(...)||default` guards through the loop. */
+function envPosInt(env, key, fallback) {
+  const v = Number(env && env[key]);
+  return Number.isInteger(v) && v > 0 ? v : fallback;
+}
+
+/** Read one VM's LB-ingress `verdict` (`wired`|`partial`|`unwired`|null) by
+ *  spawning `vm-ingress.sh <N> status` and parsing its output — the read-only
+ *  probe the converge loop polls between `up` attempts. Best-effort: a script
+ *  error / missing verdict line returns null (parsed as "keep converging"),
+ *  never throws. */
+function probeVmIngressVerdict(cfg, plan) {
+  const scriptPath = path.join(rootDir, "scripts", "gcp", "vm-ingress.sh");
+  const inv = vmIngressStatusInvocation({
+    scriptPath,
+    vmNumber: plan.vmNumber,
+    domain: plan.domain,
+    project: cfg.project,
+    zone: cfg.zone,
+    slug: plan.slug,
+  });
+  const res = spawnSync(inv.command, inv.args, {
+    env: { ...process.env, ...inv.env },
+    encoding: "utf8",
+  });
+  return parseIngressStatusVerdict(res.stdout || "");
+}
+
+/** Drive a just-added VM's LB-ingress wiring to `verdict=wired` — the reliable
+ *  replacement for the old fire-once-and-trust-the-sweep add path
+ *  (vm--add-time-url-wiring-converges-reliably). Re-runs `vm-ingress.sh up`
+ *  (idempotent: creates only what's absent, healing a `partial`/orphaned state)
+ *  then re-probes `status`, looping with exponential backoff (`ingressConverge-
+ *  Decision`) until `wired` or the bounded deadline. On success it unlinks any
+ *  stale `wiring-failed` marker and returns `{ wired: true }`; on deadline it
+ *  drops the failed marker + a `CY_DEGRADED ingress-wiring-failed` line (a REAL
+ *  attention reason with the re-run command) rather than leaving a silent
+ *  `partial`. A no-op wire (legacy quick-tunnel / non-fleet) delegates to the
+ *  inline `wireVmIngressOnAdd`. All slow I/O (`runUp`, `probeVerdict`, `sleep`,
+ *  `now`, marker dir, and the loop bounds) is injectable via `deps` so the loop
+ *  is unit-testable without spawning the script or actually sleeping. */
+async function convergeVmIngressOnAdd(cfg, appPort, env = process.env, deps = {}) {
+  let plan;
+  try {
+    plan = ingressWiringPlan(cfg, env);
+  } catch (e) {
+    console.error(`  ⚠ skipped LB ingress converge (${e && e.message}).`);
+    return { wired: false, reason: "plan-error" };
+  }
+  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 runUp =
+    deps.runUp || ((p) => runVmIngress(cfg, "up", p.vmNumber, p.domain, appPort, p.slug));
+  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());
+  const dir = deps.markerDir || INGRESS_INFLIGHT_DIR;
+  const deadlineMs =
+    deps.deadlineMs != null
+      ? deps.deadlineMs
+      : envPosInt(env, "INGRESS_CONVERGE_DEADLINE_MS", INGRESS_CONVERGE_DEADLINE_MS);
+  const baseDelayMs =
+    deps.baseDelayMs != null
+      ? deps.baseDelayMs
+      : envPosInt(env, "INGRESS_CONVERGE_BASE_MS", INGRESS_CONVERGE_BASE_MS);
+  const maxDelayMs =
+    deps.maxDelayMs != null
+      ? deps.maxDelayMs
+      : envPosInt(env, "INGRESS_CONVERGE_MAX_MS", INGRESS_CONVERGE_MAX_MS);
+
+  const label = plan.slug || `vm-${plan.vmNumber}`;
+  const failedMarker = ingressFailedMarkerPath(dir, plan.vmNumber);
+  // Clear any failed marker a prior add/self-heal left behind before we re-attempt,
+  // so a converge that now succeeds doesn't read as still-failed.
+  try { fs.unlinkSync(failedMarker); } catch { /* not present — fine */ }
+
+  console.error(
+    `  wiring LB ingress for VM-${plan.vmNumber} on ${plan.domain} (converge until wired)...`,
+  );
+  const start = now();
+  let attempt = 0;
+  for (;;) {
+    runUp(plan);
+    const verdict = probeVerdict(plan);
+    const decision = ingressConvergeDecision({
+      verdict,
+      elapsedMs: now() - start,
+      attempt,
+      deadlineMs,
+      baseDelayMs,
+      maxDelayMs,
+    });
+    if (decision.done) {
+      if (decision.wired) {
+        console.error(`  ✓ LB ingress wired: https://${label}.editor.${plan.domain}`);
+        return { wired: true, reason: "wired", attempts: attempt + 1 };
+      }
+      const rewire =
+        `FLEET_DOMAIN=${plan.domain}${plan.slug ? ` VM_SLUG=${plan.slug}` : ""} ` +
+        `bash scripts/gcp/vm-ingress.sh ${plan.vmNumber} up`;
+      try { fs.writeFileSync(failedMarker, String(now())); } catch { /* best-effort */ }
+      console.error(
+        `  ⚠ LB ingress for VM-${plan.vmNumber} did not converge to wired within the ` +
+          `add window (last verdict=${verdict || "unknown"}). Re-wire:\n      ${rewire}`,
+      );
+      // Machine-readable marker so the card lands a genuine `wiring-failed`
+      // attention state with its remediation, not a silent partial the sweep may
+      // never reach. Keyed the same way as the other CY_DEGRADED add markers.
+      console.log(
+        `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 };
+    }
+    attempt += 1;
+    await sleep(decision.delayMs);
+  }
+}
+
+/** Start the slow LB-ingress wiring (+ IAP access grant) for a just-added VM as a
+ *  DETACHED background child and return immediately, so the Add completes at
+ *  container-healthy instead of blocking ~10 min on the wiring tail. The detached
+ *  child re-execs THIS cloud.js as `wire-add-tail` in its OWN session
+ *  (`detached: true` + `unref`), so when the dashboard reaps `cloud:up` the wiring
+ *  — and any in-flight `backend-services create` — is never SIGTERMed (the add-time
+ *  503 strand). cmdUp writes the in-flight marker BEFORE the spawn so it exists the
+ *  instant this returns (the dashboard auto-rewire gather then skips this VM until
+ *  its first wiring finishes); the child unlinks it on completion. A no-op when the
+ *  add wouldn't wire anyway (legacy quick-tunnel / non-fleet) — there the cheap
+ *  sidecar reconcile runs inline. Best-effort + loud: a spawn failure falls back to
+ *  running the tail inline rather than dropping the wiring on the floor. */
+function startDetachedAddWiring(cfg, appPort, env = process.env) {
+  let plan;
+  try {
+    plan = ingressWiringPlan(cfg, env);
+  } catch {
+    plan = { wire: false };
+  }
+  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);
+    return;
+  }
+  const marker = ingressInflightMarkerPath(INGRESS_INFLIGHT_DIR, plan.vmNumber);
+  const logPath = path.join(INGRESS_INFLIGHT_DIR, `cy-wire-add-vm-${plan.vmNumber}.log`);
+  try {
+    fs.writeFileSync(marker, String(Date.now()));
+    const out = fs.openSync(logPath, "a");
+    const inv = detachedAddTailInvocation({
+      nodePath: process.execPath,
+      scriptPath: __filename,
+      cfg,
+      appPort,
+    });
+    const child = spawn(inv.command, inv.args, {
+      detached: true,
+      stdio: ["ignore", out, out],
+      env: { ...process.env, ...inv.env },
+    });
+    child.unref();
+    fs.closeSync(out);
+    console.error(
+      `  LB ingress wiring for VM-${plan.vmNumber} on ${plan.domain} continues in the ` +
+        `background (pid ${child.pid}; log ${logPath}). The Add is complete at ` +
+        `container-healthy; the dashboard reconcile loop converges the public URL.`,
+    );
+  } catch (e) {
+    console.error(
+      `  ⚠ could not detach LB ingress wiring for VM-${plan.vmNumber} (${e && e.message}); ` +
+        `running it inline instead.`,
+    );
+    try { fs.unlinkSync(marker); } catch { /* marker may not exist */ }
+    wireVmIngressOnAdd(cfg, appPort, env);
+    applyVmAccessOnAdd(cfg, env);
+  }
+}
+
+/** `wire-add-tail` (internal): the DETACHED background continuation
+ *  `startDetachedAddWiring` spawns. Reads the Add's `cfg`/`appPort` back out of the
+ *  env (so it wires EXACTLY what the foreground Add resolved), CONVERGES the wiring
+ *  to `verdict=wired` (retry-until-wired via convergeVmIngressOnAdd, not a lossy
+ *  single-shot) then runs the IAP access grant in the SAME order cmdUp ran them
+ *  inline, and ALWAYS unlinks the in-flight marker on the way out — even on a
+ *  wiring failure — so the dashboard's auto-rewire backstop takes over instead of
+ *  being pinned off. Not a user-facing subcommand; invoked only via re-exec. */
+async function cmdWireAddTail() {
+  let cfg = {};
+  try {
+    cfg = JSON.parse(process.env.CY_WIRE_ADD_CFG || "{}");
+  } catch (e) {
+    console.error(`wire-add-tail: could not parse CY_WIRE_ADD_CFG (${e && e.message}).`);
+    return;
+  }
+  const appPort = process.env.CY_WIRE_ADD_PORT || undefined;
+  let marker = null;
+  try {
+    const vmNumber = resolveFleetVmNumber(cfg.instanceName);
+    if (vmNumber != null) {
+      marker = ingressInflightMarkerPath(INGRESS_INFLIGHT_DIR, vmNumber);
+    }
+  } catch { /* fall through — marker cleanup is best-effort */ }
+  try {
+    // 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);
+  } finally {
+    if (marker) {
+      try { fs.unlinkSync(marker); } catch { /* already gone — fine */ }
+    }
+  }
+}
+
+/** Destroy-time hook: revoke VM-N's per-backend IAP bindings and clear its access
+ *  sidecar entry so a freed-and-reused VM number doesn't inherit a stale
+ *  whitelist. Runs BEFORE unwireVmIngressOnDestroy (which deletes the backend
+ *  services the bindings live on) so the revoke targets resources that still
+ *  exist. Best-effort + loud; the sidecar is always cleared even if the gcloud
+ *  revoke warns. No-op for a non-fleet instance or an empty whitelist. */
+function revokeVmAccessOnDestroy(cfg, env = process.env) {
+  let vmNumber;
+  try {
+    const plan = ingressWiringPlan(cfg, env);
+    vmNumber = plan.wire ? plan.vmNumber : resolveFleetVmNumber(cfg.instanceName);
+  } catch {
+    // A malformed domain must not block teardown — fall back to the name-derived
+    // number so the sidecar still gets cleared.
+    vmNumber = resolveFleetVmNumber(cfg.instanceName);
+  }
+  if (vmNumber == null) return;
+  const list = accessFor(vmNumber);
+  if (list.length > 0) {
+    console.error(`  revoking IAP access for VM-${vmNumber} (${list.length} principal(s))...`);
+    const res = runIapAccess(cfg, vmNumber, "revoke", list);
+    if (res.status !== 0) {
+      console.error(
+        `  Warning: IAP access revoke for VM-${vmNumber} did not complete; ` +
+          `bindings are removed when the backend service is deleted, but verify with: ` +
+          `VM_ACCESS=${list.join(",")} bash scripts/gcp/iap-access.sh ${vmNumber} revoke`,
+      );
+    }
+  }
+  try {
+    clearAccess(vmNumber);
+  } catch (e) {
+    console.error(`  Warning: could not clear access list for VM-${vmNumber} (${e.message}).`);
+  }
+}
+
+/** Destroy-time hook: free the VM's custom slug so a freed-and-reused VM number
+ *  doesn't inherit a stale slug — and, critically, so the name is re-Addable.
+ *  Resolved purely from the instance name (NOT the ingress plan) so a non-wired /
+ *  legacy / quick-tunnel VM still releases its slug; coupling this to
+ *  `plan.wire` was the bug that stranded VM-7's `harvardintech`. Best-effort +
+ *  loud so a sidecar write hiccup can't block the teardown. No-op for a
+ *  non-fleet instance. Returns the released VM number, or null when none. */
+function releaseVmSlugOnDestroy(cfg) {
+  const vmNumber = resolveFleetVmNumber(cfg.instanceName);
+  if (vmNumber == null) return null;
+  try {
+    removeSlug(vmNumber);
+  } catch (e) {
+    console.error(`  Warning: could not clear slug for VM-${vmNumber} (${e.message}).`);
+  }
+  return vmNumber;
+}
+
+async function cmdUp(args, projectDir = rootDir) {
   ensureGcloud();
   const flags = parseFlags(args);
-  const cfg = loadOrInitCloudConfig(rootDir, flags);
+  const cfg = loadOrInitCloudConfig(projectDir, flags);
   // Fail loud BEFORE creating a GCE instance if an unprovisionable editor
   // variant was requested — otherwise we'd spin up a VM, build a dev image,
   // and silently ignore the operator's staging/production intent.
   assertVariantProvisionable(resolveEditorConfig(cfg).editorVariant);
 
+  // Validate a custom --vm-slug BEFORE creating any GCE instance so a bad or
+  // duplicate name fails loud at the boundary, never after a VM is provisioned.
+  // A slug is only meaningful for a numbered fleet VM; on a non-fleet client
+  // project it's dropped (with a note) so the legacy path is untouched.
+  if (cfg.vmSlug != null && String(cfg.vmSlug).trim() !== "") {
+    const slug = normalizeVmSlug(cfg.vmSlug); // throws on bad format/reserved/vm-N
+    const vmNumber = resolveFleetVmNumber(cfg.instanceName);
+    if (vmNumber == null) {
+      console.error(
+        `  (instance '${cfg.instanceName}' is not a fleet VM — ignoring --vm-slug ${slug})`,
+      );
+      delete cfg.vmSlug;
+    } else {
+      const owner = vmForSlug(slug);
+      if (owner != null && owner !== vmNumber) {
+        throw new Error(
+          `VM slug "${slug}" is already assigned to VM-${owner} — pick another name`,
+        );
+      }
+      cfg.vmSlug = slug; // carry the normalized form for seeding + wiring
+    }
+  }
+
+  // Validate a custom --vm-access BEFORE creating any GCE instance so a malformed
+  // principal fails loud at the boundary, never after a VM is provisioned (and
+  // never reaches gcloud). Like --vm-slug it's only meaningful for a numbered
+  // fleet VM; on a non-fleet client project it's dropped with a note. The
+  // normalized array is carried on cfg for the post-provision grant.
+  if (cfg.vmAccess != null && String(cfg.vmAccess).trim() !== "") {
+    const principals = normalizeAccessList(cfg.vmAccess); // throws on malformed
+    const vmNumber = resolveFleetVmNumber(cfg.instanceName);
+    if (vmNumber == null) {
+      console.error(
+        `  (instance '${cfg.instanceName}' is not a fleet VM — ignoring --vm-access)`,
+      );
+      delete cfg.vmAccess;
+    } else {
+      cfg.vmAccess = principals; // carry the normalized list for the grant hook
+    }
+  }
+
+  checkScriptDrift(cfg);
+
   await ensureFirewallRule(cfg);
   const { createdThisRun } = await ensureInstance(cfg);
 
@@ -1890,25 +4031,111 @@ async function cmdUp(args) {
     // Write the GitHub token BEFORE compose up so the credentials file exists
     // when the bind-mount happens — bind-mounting a missing file would silently
     // create a directory instead and the agent's first `git pull` would fail.
-    await seedGithubCredentials(cfg);
+    try {
+      await seedGithubCredentials(cfg, { allowNoCredentials: cfg.allowNoGitCredentials });
+    } catch (credErr) {
+      if (credErr instanceof MissingGitPushCredentialsError) {
+        // Never silently healthy: land an amber `CY_DEGRADED` card with the
+        // recovery command (same machine-readable channel the dashboard scanner
+        // reads for ingress-not-wired / failed setup) instead of aborting the
+        // whole add. The VM is otherwise reachable + the Claude session works;
+        // `cloud:reconcile-credentials` heals the push gap in place.
+        console.log(`CY_DEGRADED ${credErr.degradedReason}`);
+        console.error(credErr.message);
+      } else {
+        throw credErr;
+      }
+    }
     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
+    // cache) is up; re-seed-then-re-assert on a stale cache, and land a loud
+    // CY_DEGRADED on a persistent gap rather than a silently-green VM that
+    // cannot push (VM5's 2026-06-30 could-not-read-Username symptom). Skipped
+    // for an intentionally read-only VM (--allow-no-git-credentials).
+    if (!cfg.allowNoGitCredentials) {
+      await assertGitPushCredentials(cfg);
+    }
     // Roster the VM into the fleet dashboard NOW that it's provisioned and the
     // editor container is up. Runs BEFORE the --no-tunnel early-return so the
     // dashboard's own `cloud:up --no-tunnel` Add path also rosters (idempotent
     // with the dashboard's onSuccess roster — a double-add is a harmless no-op).
     rosterProvisionedVm(cfg.instanceName);
+    // Persist this VM's custom slug into the slug sidecar so the dashboard, the
+    // ingress wiring below, and a later Destroy all resolve the same hostname.
+    // Best-effort + loud (matching the roster-write posture): a sidecar-write
+    // failure warns but never aborts an otherwise-green Add — the URLs simply
+    // fall back to the numeric vm-<N> scheme. Only fires for a slug supplied on
+    // a numbered fleet VM (the early validation already dropped a non-fleet one).
+    if (cfg.vmSlug) {
+      const slugVm = resolveFleetVmNumber(cfg.instanceName);
+      try {
+        setSlug(slugVm, cfg.vmSlug);
+        console.error(`  ✓ assigned slug "${cfg.vmSlug}" to VM-${slugVm}`);
+      } catch (e) {
+        console.error(
+          `  ⚠ failed to persist slug "${cfg.vmSlug}" for VM-${slugVm} (${e && e.message}); ` +
+            `URLs fall back to vm-${slugVm}.`,
+        );
+        delete cfg.vmSlug; // keep wiring + display consistent with what was persisted
+      }
+    }
     // Terminal gate: provisioning is NOT "done" until the editor container is
     // verifiably Up. Placed BEFORE the --no-tunnel early-return so the dashboard's
     // own `cloud:up --no-tunnel` Add path is covered too (it's the path that bit
     // us — a run reported success with no container). A failure here is a loud
     // non-zero exit, which the dashboard fail-fast-on-nonzero path acts on.
     await assertEditorContainerRunning(cfg);
+    // Terminal gate #2: the editor container is up, but the agent CLI is what the
+    // Build-tab auth probe actually needs. Assert it's present (install + re-check
+    // if not), failing loud rather than rostering a CLI-less VM.
+    await assertAgentCliInstalled(cfg);
+    // Wire this VM onto the shared Google HTTPS LB when a fleet domain is
+    // configured — the stable-URL replacement for the quick-tunnel mint. Runs
+    // AFTER the terminal container gate so the editor/preview ports the NEG
+    // targets are live, and is best-effort (the VM is reachable over SSH
+    // regardless). The wiring (+ the IAP access grant that depends on it) is kicked
+    // off DETACHED so the Add returns at container-healthy instead of blocking
+    // ~10 min on the EXTERNAL_MANAGED backend-services create + propagation tail;
+    // the detached child outlives this process so the dashboard's reap of cloud:up
+    // can't SIGTERM an in-flight `backend-services create` (the add-time 503
+    // strand), and the dashboard's auto-rewire gather converges the public URL in
+    // the background. A no-op in legacy quick-tunnel mode / for a non-fleet project
+    // (there the cheap sidecar reconcile runs inline). See
+    // startDetachedAddWiring → wire-add-tail.
+    startDetachedAddWiring(cfg, appPort);
+    // Now that the editor answers on its own surface, ask it whether the
+    // pre-container seed wrong-moded the previewOrigin (the stack.json race) and
+    // heal it in place. Best-effort, never fatal — wrapped so a probe hiccup
+    // can't abort an otherwise-green add.
+    try {
+      await healPreviewOriginAtReady(cfg, appPort);
+    } catch (healErr) {
+      console.error(
+        `  Warning: READY preview-origin auto-heal probe failed (${healErr.message}); ` +
+          `the cloudflared-monitor tick will reconcile.`,
+      );
+    }
   } catch (err) {
     if (createdThisRun) {
       console.error(
         `✗ provisioning aborted — tearing down the VM cloud:up created this run (no orphan left behind)`,
       );
+      // Drop the slug + access sidecar entries for this brand-new VM so a
+      // torn-down number doesn't leave a dangling slug or whitelist behind
+      // (best-effort — never block teardown).
+      const torndownVm = resolveFleetVmNumber(cfg.instanceName);
+      if (cfg.vmSlug && torndownVm != null) {
+        try { removeSlug(torndownVm); } catch { /* best-effort cleanup */ }
+      }
+      if (cfg.vmAccess && torndownVm != null) {
+        try { clearAccess(torndownVm); } catch { /* best-effort cleanup */ }
+      }
       try {
         console.error(`Deleting instance ${cfg.instanceName}...`);
         const del = runGcloud(buildGcloudArgs("instances-delete", cfg));
@@ -1940,10 +4167,10 @@ async function cmdUp(args) {
   attachKeepAliveAndTeardown(tunnelChild);
 }
 
-async function cmdTunnel(args) {
+async function cmdTunnel(args, projectDir = rootDir) {
   ensureGcloud();
   const flags = parseFlags(args);
-  const existing = loadCloudConfig(rootDir);
+  const existing = loadCloudConfig(projectDir);
   if (!existing) {
     throw new Error(
       "No .codeyam/cloud.json found. Run `npm run cloud:up -- --repo <url>` first.",
@@ -1971,10 +4198,10 @@ async function cmdTunnel(args) {
   attachKeepAliveAndTeardown(tunnelChild);
 }
 
-async function cmdStop(args) {
+async function cmdStop(args, projectDir = rootDir) {
   ensureGcloud();
   parseFlags(args);
-  const cfg = loadCloudConfig(rootDir);
+  const cfg = loadCloudConfig(projectDir);
   if (!cfg) {
     throw new Error("No .codeyam/cloud.json found. Nothing to stop.");
   }
@@ -1990,10 +4217,10 @@ async function cmdStop(args) {
   );
 }
 
-async function cmdDestroy(args) {
+async function cmdDestroy(args, projectDir = rootDir) {
   ensureGcloud();
   parseFlags(args);
-  const cfg = loadCloudConfig(rootDir);
+  const cfg = loadCloudConfig(projectDir);
   if (!cfg) {
     throw new Error("No .codeyam/cloud.json found. Nothing to destroy.");
   }
@@ -2004,12 +4231,28 @@ async function cmdDestroy(args) {
     return;
   }
 
+  // Revoke the VM's per-backend IAP access + clear its whitelist sidecar BEFORE
+  // unwiring, so the revoke targets backend services that still exist (unwire
+  // deletes them). No-op for a non-fleet instance / empty whitelist.
+  revokeVmAccessOnDestroy(cfg);
+
+  // Unwire the VM's LB backends BEFORE deleting the instance (when a fleet
+  // domain is set) so no orphaned NEG / backend service / host rule survives —
+  // mirrors the destroy-time quick-tunnel cleanup. No-op in legacy mode.
+  unwireVmIngressOnDestroy(cfg);
+
   console.error(`Deleting instance ${cfg.instanceName}...`);
   const del = runGcloud(buildGcloudArgs("instances-delete", cfg));
   if (del.status !== 0) {
     throw new Error(`Failed to delete instance ${cfg.instanceName}`);
   }
 
+  // Free the VM's custom slug now that the instance is gone, so the name is
+  // re-Addable. Decoupled from unwireVmIngressOnDestroy (whose `plan.wire` gate
+  // used to strand non-wired VMs' slugs); a sibling destroy-time hook like the
+  // access/ingress teardown above.
+  releaseVmSlugOnDestroy(cfg);
+
   const list = runGcloud(buildGcloudArgs("instances-list-tagged", cfg), {
     stdio: ["ignore", "pipe", "ignore"],
   });
@@ -2027,17 +4270,17 @@ async function cmdDestroy(args) {
   }
 
   try {
-    fs.unlinkSync(cloudConfigPath(rootDir));
+    fs.unlinkSync(cloudConfigPath(projectDir));
     console.error("Deleted .codeyam/cloud.json");
   } catch (e) {
     if (e.code !== "ENOENT") throw e;
   }
 }
 
-async function cmdStatus(args) {
+async function cmdStatus(args, projectDir = rootDir) {
   ensureGcloud();
   parseFlags(args);
-  const cfg = loadCloudConfig(rootDir);
+  const cfg = loadCloudConfig(projectDir);
   if (!cfg) {
     console.error("No .codeyam/cloud.json found. Run `npm run cloud:up` first.");
     return;
@@ -2079,12 +4322,710 @@ async function cmdStatus(args) {
   );
 }
 
+/** `cloud:ingress-up` — provision the SHARED, VM-independent LB infra (static
+ *  IP, wildcard managed cert, Cloud DNS records, URL map, IAP brand) once for the
+ *  fleet by spawning scripts/gcp/google-ingress.sh. Idempotent: re-running against
+ *  already-provisioned infra is a safe no-op. Requires a fleet domain (cloud.json
+ *  `fleetDomain` or FLEET_DOMAIN env); the per-VM backends are wired by cloud:up's
+ *  Add path. Run this before the first fleetDomain Add (or after flipping it on). */
+async function cmdIngressUp(args, projectDir = rootDir) {
+  ensureGcloud();
+  parseFlags(args);
+  const cfg = loadCloudConfig(projectDir);
+  if (!cfg) {
+    throw new Error(
+      "No .codeyam/cloud.json found. Run `npm run cloud:up -- --repo <url>` first.",
+    );
+  }
+  const domain = resolveIngressDomain(cfg, process.env);
+  if (!domain) {
+    throw new Error(
+      "No fleet domain configured. Set `fleetDomain` in .codeyam/cloud.json " +
+        "(e.g. via `cloud:up -- --fleet-domain fleet.example.com`) or export FLEET_DOMAIN.",
+    );
+  }
+  const dnsZone = resolveDnsZone(cfg, process.env);
+  const scriptPath = path.join(rootDir, "scripts", "gcp", "google-ingress.sh");
+  const inv = sharedIngressInvocation({
+    scriptPath,
+    domain,
+    project: cfg.project,
+    zone: cfg.zone,
+    dnsZone,
+    region: regionFromZone(cfg.zone),
+  });
+  console.error(
+    `Provisioning shared LB ingress for ${domain} (project ${cfg.project}, DNS zone ${dnsZone})...`,
+  );
+  const res = spawnSync(inv.command, inv.args, {
+    stdio: "inherit",
+    env: { ...process.env, ...inv.env },
+  });
+  if (res.status !== 0) {
+    throw new Error("scripts/gcp/google-ingress.sh failed; see output above.");
+  }
+  console.error(
+    "✓ shared LB ingress provisioned. Per-VM backends are wired automatically by " +
+      "`cloud:up` (Add) once `fleetDomain` is set in cloud.json.",
+  );
+}
+
+/** Detect unwired / half-wired rostered VMs and re-wire them idempotently.
+ *  Enumerates the fleet roster (the same source the dashboard reads), runs the
+ *  read-only `vm-ingress.sh <N> status` probe per VM, and for any reporting
+ *  `unwired` or `partial` re-runs `vm-ingress.sh <N> up` — which skips the
+ *  resources already present and creates only the missing backend / host rule.
+ *  A no-op in legacy quick-tunnel mode (no fleet domain). Invoked on demand and
+ *  automatically at dashboard boot so a fleet that lost ingress self-heals. */
+async function cmdReconcileIngress(args, projectDir = rootDir) {
+  ensureGcloud();
+  parseFlags(args);
+  const cfg = loadCloudConfig(projectDir) || {};
+  const domain = resolveIngressDomain(cfg, process.env);
+  if (!domain) {
+    console.error(
+      "No fleet domain configured — ingress reconcile is a no-op (legacy quick-tunnel mode).",
+    );
+    return;
+  }
+  const roster = readRoster() || [];
+  if (!roster.length) {
+    console.error("Fleet roster is empty — nothing to reconcile.");
+    return;
+  }
+  const scriptPath = path.join(rootDir, "scripts", "gcp", "vm-ingress.sh");
+  console.error(`Reconciling LB ingress for ${roster.length} rostered VM(s) on ${domain}...`);
+  const statuses = roster.map((n) => {
+    const slug = slugFor(n);
+    const inv = vmIngressStatusInvocation({
+      scriptPath,
+      vmNumber: n,
+      domain,
+      project: cfg.project,
+      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)) 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`);
+    }
+  }
+  for (const t of targets) {
+    const label = t.slug || `vm-${t.vmNumber}`;
+    // Resolve the VM's real dev-server port so a re-created preview NEG targets
+    // the right port (not the 5173 bootstrap fallback). Best-effort — readVmAppPort
+    // itself falls back to VITE_PORT on any SSH/parse failure.
+    const perVmCfg = { ...cfg, instanceName: `${fleetInstancePrefix()}${t.vmNumber}` };
+    const appPort = await readVmAppPort(perVmCfg);
+    const res = runVmIngress(perVmCfg, "up", t.vmNumber, domain, appPort, t.slug);
+    console.error(
+      `  VM-${t.vmNumber} ${label}: ${t.verdict} → ${res.status === 0 ? "re-wired" : "re-wire FAILED"}`,
+    );
+  }
+
+  // Converge each rostered backend-service's timeout to 86400 (24h). A fully-wired
+  // BES still at GCP's 30s default reports `wired` above and is skipped by the
+  // re-wire loop, yet on an External HTTPS LB that 30s is the MAX WebSocket lifetime
+  // — the editor's /ws/terminal socket is guillotined every 30s (the Build-tab
+  // "Reconnecting…" loop). Assert the timeout per rostered BES so the running fleet
+  // self-heals without a manual sweep — idempotent (a no-op when already 86400). The
+  // durable per-`up` converge lives in vm-ingress.sh; this catches already-wired VMs
+  // the periodic reconcile never re-`up`s. See plan vm--lb-backend-service-websocket-timeout.
+  const gi = require("./google-ingress.js");
+  for (const n of roster) {
+    for (const surface of gi.SURFACES) {
+      const bes = gi.backendServiceName(n, surface);
+      const inv = backendServiceTimeoutInvocation({ bes, project: cfg.project });
+      // 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 {
+        const tail = (res.stderr || "").trim().split("\n").pop() || "error";
+        console.error(`  ${bes}: timeout converge skipped (${tail})`);
+      }
+    }
+  }
+
+  // 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
+  // operator never sees a manual `vm-ingress.sh <N> down` command. Rides the same
+  // boot + periodic cadence as the wiring reconcile above.
+  sweepOrphanIngress({ cfg, domain, roster, projectDir });
+}
+
+/** Auto-clean orphaned LB ingress (vm--auto-clean-orphaned-lb-ingress): LB
+ *  resources whose owning VM number is gone from the roster (a destroyed VM) and
+ *  has no in-flight add. Enumerates the live backend services AND zonal NEGs,
+ *  UNIONs their owning VM numbers (so a partial teardown whose NEG outlived its
+ *  backend service — the VM-5/6 case — still surfaces its VM as a candidate),
+ *  maps each name back to its VM number, subtracts the roster + in-flight adds +
+ *  live instances (the false-orphan guards), and runs the VERIFIED
+ *  `vm-ingress.sh <N> down` (asserts neg=no bes=no host=no, with retries) for
+ *  each orphan — so an orphan is genuinely cleared or surfaced as a real failure,
+ *  never a silent leak and never a manual command. Emits a machine-readable
+ *  `CY_ORPHAN_SWEEP <json>` summary line the dashboard parses to reconcile its
+ *  orphan-attention banner; the summary carries `stillPresent` (VM numbers that
+ *  still own ≥1 LB resource after the sweep) so the dashboard can clear a stale
+ *  banner for a VM that is now back in the roster or has no residual resources.
+ *  Best-effort per VM: one `down` failing never aborts the rest of the sweep.
+ *  Fail-safe: if the live-instance list can't be fetched, teardown is skipped for
+ *  this pass (a live-but-unrostered VM must never be torn down) while the banner
+ *  reconcile still runs. Returns the `{ cleaned, failed, skipped, stillPresent }`
+ *  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");
+  const frecon = deps.fleetReconcile || require("./fleet-reconcile.js");
+  const run = deps.spawnSync || spawnSync;
+
+  const listInv = backendServicesListInvocation({ project: cfg && cfg.project });
+  const listRes = run(listInv.command, listInv.args, { encoding: "utf8" });
+  if (!listRes || listRes.status !== 0) {
+    const tail = (
+      (listRes && (listRes.stderr || (listRes.error && listRes.error.message))) || ""
+    ).toString().trim().split("\n").pop() || "error";
+    console.error(`  orphan sweep skipped — could not list backend services (${tail}).`);
+    return null;
+  }
+  const besVmNumbers = String(listRes.stdout || "")
+    .split("\n")
+    .map((line) => gi.vmNumberFromResourceName(line.trim()))
+    .filter((n) => n != null);
+
+  // Also enumerate zonal NEGs and union their owners in: a partial teardown can
+  // leave a `vm-<N>-<surface>-neg` behind after its backend service is already
+  // gone, so a backend-service-only candidate set misses that residue. Best-effort
+  // — a NEG-list failure never aborts the backend-service-driven sweep.
+  let negVmNumbers = [];
+  const negInv = negListInvocation({ project: cfg && cfg.project });
+  const negRes = run(negInv.command, negInv.args, { encoding: "utf8" });
+  if (negRes && negRes.status === 0) {
+    negVmNumbers = String(negRes.stdout || "")
+      .split("\n")
+      .map((line) => gi.vmNumberFromResourceName(line.trim()))
+      .filter((n) => n != null);
+  } else {
+    const tail = (
+      (negRes && (negRes.stderr || (negRes.error && negRes.error.message))) || ""
+    ).toString().trim().split("\n").pop() || "error";
+    console.error(`  orphan sweep: could not list NEGs (${tail}) — sweeping backend services only.`);
+  }
+  const ingressVmNumbers = [...new Set([...besVmNumbers, ...negVmNumbers])].sort((a, b) => a - b);
+
+  // A VM in the roster, or with an in-flight `add-<n>.json` sidecar (provisioning,
+  // not yet rostered), is live — never an orphan.
+  const pendingDir = process.env.PENDING_JOBS_DIR || path.join(projectDir, ".codeyam/logs/pending-jobs");
+  const inFlightAdds = fcl
+    .listPendingJobs(pendingDir)
+    .filter((j) => j.action === "add")
+    .map((j) => j.n);
+
+  // Defensive live-instance guard: never tear down a VM whose GCP instance is
+  // actually running (a roster drift could leave a live VM unrostered; a teardown
+  // that SUCCEEDED against it would knock it offline). `liveVmNumbers === null`
+  // means the list couldn't be fetched — fail safe by skipping teardown this pass
+  // (below) rather than risk a false teardown. The banner reconcile still runs.
+  let liveVmNumbers = null;
+  const instInv = instancesListInvocation({ project: cfg && cfg.project });
+  const instRes = run(instInv.command, instInv.args, { encoding: "utf8" });
+  if (instRes && instRes.status === 0) {
+    liveVmNumbers = frecon.parseRunningFleetVms(instRes.stdout, fleetInstancePrefix());
+  } else {
+    const tail = (
+      (instRes && (instRes.stderr || (instRes.error && instRes.error.message))) || ""
+    ).toString().trim().split("\n").pop() || "error";
+    console.error(`  orphan sweep: could not list instances (${tail}) — skipping teardown this pass (banners still reconciled).`);
+  }
+
+  const orphans = liveVmNumbers === null
+    ? []
+    : selectOrphanIngressTargets({ ingressVmNumbers, roster, inFlightAdds, liveVmNumbers });
+
+  // stillPresent = every VM that owned an LB resource going in, minus the ones we
+  // verifiably clean below. The dashboard clears a banner for any orphan VM not in
+  // this set (or now back in the roster). Computed up front so the no-orphans and
+  // fail-safe-skip paths report it too — that is what unfreezes a VM-3-style banner
+  // (re-rostered, so never a sweep target) with no teardown at all.
+  const summary = { cleaned: [], failed: [], skipped: inFlightAdds.slice(), stillPresent: ingressVmNumbers.slice() };
+  if (!orphans.length) {
+    console.error("  orphan sweep: no orphaned LB ingress found.");
+    console.log(`CY_ORPHAN_SWEEP ${JSON.stringify(summary)}`);
+    return summary;
+  }
+
+  console.error(`  orphan sweep: auto-cleaning ${orphans.length} orphaned VM ingress (${orphans.join(", ")})...`);
+  const scriptPath = path.join(projectDir, "scripts", "gcp", "vm-ingress.sh");
+  for (const n of orphans) {
+    // A destroyed VM's slug is normally already released, so slugFor(n) is null and
+    // the numeric vm-<N> host rules are torn down; if a destroy left the slug behind,
+    // slugFor(n) resolves it so the <slug>.<surface> host rules go too.
+    const slug = slugFor(n) || undefined;
+    const inv = vmIngressInvocation({
+      scriptPath,
+      vmNumber: n,
+      action: "down",
+      domain,
+      project: cfg && cfg.project,
+      zone: cfg && cfg.zone,
+      instancePrefix: fleetInstancePrefix(),
+      slug,
+    });
+    const res = run(inv.command, inv.args, { encoding: "utf8", env: { ...process.env, ...inv.env } });
+    const verdict = parseIngressTeardownVerdict((res && res.stdout) || "");
+    // 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)`);
+    } else {
+      const tail = `${(res && res.stdout) || ""}${(res && res.stderr) || ""}`
+        .trim().split("\n").pop() || "no verdict";
+      summary.failed.push({ n, cause: outcome.cause });
+      console.error(`  VM-${n}: orphaned ingress → auto-clean FAILED (${tail.slice(-200)})`);
+    }
+  }
+  // A verifiably-cleaned VM no longer owns any LB resource — drop it from
+  // stillPresent so the dashboard clears its banner (failed VMs stay, keeping
+  // their real attention item).
+  const cleanedSet = new Set(summary.cleaned);
+  summary.stillPresent = ingressVmNumbers.filter((n) => !cleanedSet.has(n));
+  console.log(`CY_ORPHAN_SWEEP ${JSON.stringify(summary)}`);
+  return summary;
+}
+
+/** `cloud:reconcile-credentials` — self-heal a running VM that came up (or
+ *  drifted) without git push credentials, WITHOUT a container restart so a live
+ *  Claude session survives. Probes the host staging file + an in-container
+ *  `git ls-remote origin`, classifies any failure via {@link decideCredentialHeal}
+ *  (so a transient network blip never triggers a needless re-write), and on a
+ *  credential gap re-seeds BOTH the durable host file (survives restart via the
+ *  entrypoint) and the live in-memory credential-cache daemon (immediate, no
+ *  restart). This codifies the manual recovery run on all 9 fleet VMs on
+ *  2026-06-29. */
+/** One SSH round-trip probe of a running VM's git push credentials: reports
+ *  whether the host staging file (`~/.codeyam-cloud-git-credentials`) is empty
+ *  and the in-container `git ls-remote origin` outcome, parsed into the exact
+ *  shape {@link decideCredentialHeal} consumes (`{ stagingEmpty, lsRemoteOk,
+ *  lsRemoteStderr }`). Shared by {@link cmdReconcileCredentials} (the manual
+ *  self-heal verb) and {@link assertGitPushCredentials} (the provision-time
+ *  guarantee) so the two never drift on probe wire-format. Throws on an SSH
+ *  error — the caller decides whether that is fatal or best-effort. */
+async function probeGitCredentials(cfg) {
+  const repoName = resolveProject(cfg).name;
+  const projectCd = `cd ~/projects/${repoName}`;
+  const composeExec = `docker compose -f docker-compose.cloud.yml exec -T editor`;
+  const probeCmd =
+    `f=$HOME/.codeyam-cloud-git-credentials; ` +
+    `if [ -s "$f" ]; then echo STAGING=nonempty; else echo STAGING=empty; fi; ` +
+    `${projectCd} && if ${composeExec} git -C /workspace ls-remote origin -h HEAD ` +
+    `>/dev/null 2>/tmp/cy-lsr.err; then echo LSREMOTE=ok; ` +
+    `else echo LSREMOTE=fail; sed 's/^/LSRERR:/' /tmp/cy-lsr.err; fi`;
+  const probe = runGcloud(
+    buildGcloudArgs("ssh-probe", cfg, { command: probeCmd }),
+    { stdio: ["ignore", "pipe", "ignore"] },
+  );
+  if (probe.status !== 0 || typeof probe.stdout !== "string") {
+    throw new Error(`Failed to probe credentials on ${cfg.instanceName} (SSH error).`);
+  }
+  const out = probe.stdout;
+  return {
+    stagingEmpty: /STAGING=empty/.test(out),
+    lsRemoteOk: /LSREMOTE=ok/.test(out),
+    lsRemoteStderr: out
+      .split("\n")
+      .filter((l) => l.startsWith("LSRERR:"))
+      .map((l) => l.slice("LSRERR:".length))
+      .join("\n"),
+  };
+}
+
+/** 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. 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} ` +
+    `git -c 'credential.helper=cache --timeout=31536000 --socket=${socket}' ` +
+    `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"] },
+  );
+  if (seed.status !== 0 || !/APPROVED/.test(String(seed.stdout || ""))) {
+    throw new Error(
+      `Failed to seed the live credential cache on ${cfg.instanceName}.`,
+    );
+  }
+}
+
+async function cmdReconcileCredentials(args, projectDir = rootDir) {
+  ensureGcloud();
+  parseFlags(args);
+  const cfg = loadCloudConfig(projectDir);
+  if (!cfg) {
+    throw new Error("No .codeyam/cloud.json found. Run `npm run cloud:up` first.");
+  }
+
+  console.error(`Probing git push credentials on ${cfg.instanceName}...`);
+  const decision = decideCredentialHeal(await probeGitCredentials(cfg));
+  console.error(`  category=${decision.category}: ${decision.reason}`);
+  if (!decision.heal) {
+    console.error("  ✓ no re-seed needed.");
+    return;
+  }
+
+  // Re-seed needs a token. Reuse seedGithubCredentials for the durable host-file
+  // write (it throws MissingGitPushCredentialsError when none resolves — the
+  // honest "can't heal without a token" outcome), then seed the live cache.
+  await seedGithubCredentials(cfg);
+  await seedLiveCredentialCache(cfg, resolveGithubTokenWithSource().token);
+  console.error(
+    `  ✓ re-seeded host file + live credential cache on ${cfg.instanceName}; ` +
+      `plan-claim sync will recover on the next tick.`,
+  );
+}
+
+/** `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
+ *  the manual `cloud:reconcile-credentials` verb uses (no parallel logic). On a
+ *  credential gap it re-seeds the durable host file + live cache daemon and
+ *  re-asserts ONCE. A failure that persists after the re-seed — or no token to
+ *  seed with — ends in a loud `CY_DEGRADED git push credentials missing` marker
+ *  (the dashboard's amber-card channel), never a silently-green VM that cannot
+ *  push (VM5's 2026-06-30 "could not read Username for github.com" symptom).
+ *  Best-effort on infra errors: an SSH-probe failure is logged and skipped
+ *  rather than aborting an otherwise-green Add, matching seedGithubCredentials'
+ *  degraded posture. */
+async function assertGitPushCredentials(cfg) {
+  let probe;
+  try {
+    probe = await probeGitCredentials(cfg);
+  } catch (err) {
+    // Probe itself failed (SSH error) — can't classify; log loud, don't abort.
+    console.error(`  (could not verify git push credentials: ${err.message})`);
+    return;
+  }
+  const decision = decideCredentialHeal(probe);
+  console.error(`  git push credentials: category=${decision.category}: ${decision.reason}`);
+  if (!decision.heal) {
+    // Healthy, or a transient network blip that re-seeding wouldn't fix anyway.
+    return;
+  }
+
+  // A re-seed needs a token. Without one we cannot heal — land the loud marker
+  // instead of throwing inside seedGithubCredentials (which would abort the Add).
+  const { token } = resolveGithubTokenWithSource();
+  if (!token) {
+    console.log(
+      "CY_DEGRADED git push credentials missing: no token resolved to seed the VM. " +
+        "Recover: npm run cloud:reconcile-credentials",
+    );
+    return;
+  }
+
+  // Best-effort heal: the container is already up and the VM is otherwise
+  // reachable, so a re-seed/approve/probe error must DEGRADE (loud CY_DEGRADED),
+  // never throw out of cmdUp and abort an otherwise-green Add. Mirrors the
+  // seedGithubCredentials catch in cmdUp.
+  try {
+    await seedGithubCredentials(cfg);
+    await seedLiveCredentialCache(cfg, token);
+
+    // Re-assert once: a stale/incomplete cache should now ls-remote cleanly.
+    const reprobe = await probeGitCredentials(cfg);
+    if (!reprobe.lsRemoteOk) {
+      console.log(
+        "CY_DEGRADED git push credentials missing: git ls-remote still fails after re-seed. " +
+          "Recover: npm run cloud:reconcile-credentials",
+      );
+      return;
+    }
+    console.error(`  ✓ git push credentials verified after re-seed on ${cfg.instanceName}.`);
+  } catch (err) {
+    console.log(
+      `CY_DEGRADED git push credentials missing: re-seed failed (${err.message}). ` +
+        "Recover: npm run cloud:reconcile-credentials",
+    );
+  }
+}
+
+/** `cloud:access` — edit an existing VM's IAP access whitelist without
+ *  re-provisioning. Resolves the VM number from --instance-name (or cloud.json),
+ *  mutates the access sidecar, and applies just the delta against the live
+ *  backend services via scripts/gcp/iap-access.sh:
+ *    --add <principal>     grant one principal (idempotent)
+ *    --remove <principal>  revoke one principal
+ *    --list                print the current whitelist (no gcloud call)
+ *  Exactly one of the three is required. */
+async function cmdAccess(args, projectDir = rootDir) {
+  const flags = parseFlags(args);
+  const cfg = { ...(loadCloudConfig(projectDir) || {}), ...flags };
+  const instanceName = cfg.instanceName;
+  if (!instanceName) {
+    throw new Error(
+      "cloud:access requires --instance-name <name> (or a .codeyam/cloud.json with one).",
+    );
+  }
+  const vmNumber = resolveFleetVmNumber(instanceName);
+  if (vmNumber == null) {
+    throw new Error(`'${instanceName}' is not a numbered fleet VM — per-VM access does not apply.`);
+  }
+
+  if (flags.list) {
+    const list = accessFor(vmNumber);
+    console.error(`VM-${vmNumber} IAP access whitelist (${list.length}):`);
+    if (list.length === 0) console.error("  (none — only the owner's project-wide grant applies)");
+    for (const p of list) console.error(`  ${p}`);
+    return;
+  }
+
+  const adding = flags.add != null && String(flags.add).trim() !== "";
+  const removing = flags.remove != null && String(flags.remove).trim() !== "";
+  if (adding === removing) {
+    throw new Error("cloud:access requires exactly one of --add <principal> / --remove <principal> / --list.");
+  }
+
+  ensureGcloud();
+  const principal = normalizePrincipal(adding ? flags.add : flags.remove); // throws on malformed
+  const action = adding ? "grant" : "revoke";
+  // Mutate the sidecar first so the source of truth reflects intent even if the
+  // gcloud apply later warns; both calls are idempotent.
+  if (adding) addAccess(vmNumber, principal);
+  else removeAccess(vmNumber, principal);
+
+  console.error(`${action === "grant" ? "Granting" : "Revoking"} IAP access for VM-${vmNumber}: ${principal}`);
+  const res = runIapAccess(cfg, vmNumber, action, [principal]);
+  if (res.status === 0) {
+    console.error(`  ✓ ${action}ed. Current whitelist: ${accessFor(vmNumber).join(", ") || "(none)"}`);
+  } else {
+    console.error(
+      `  ⚠ gcloud ${action} did not complete cleanly; the sidecar was updated. Re-run:\n` +
+        `      VM_ACCESS=${principal} bash scripts/gcp/iap-access.sh ${vmNumber} ${action}`,
+    );
+  }
+}
+
 const HANDLERS = {
   up: cmdUp,
   tunnel: cmdTunnel,
   stop: cmdStop,
   destroy: cmdDestroy,
   status: cmdStatus,
+  "ingress-up": cmdIngressUp,
+  "reconcile-ingress": cmdReconcileIngress,
+  "wire-add-tail": cmdWireAddTail,
+  "reconcile-credentials": cmdReconcileCredentials,
+  "reconcile-admin": cmdReconcileAdmin,
+  access: cmdAccess,
 };
 
 async function cloudMain() {
@@ -2106,14 +5047,23 @@ async function cloudMain() {
 
 module.exports = {
   // pure helpers
+  isSpawnTimeout,
   agentEnvVarName,
   agentNpmPackage,
   AGENT_ENV_VARS,
   AGENT_NPM_PACKAGES,
   ensureAgentCliInstalled,
+  ensureEditorContainerUp,
+  seedAgentApiKey,
+  assertAgentCliInstalled,
+  probeContainerRunning,
+  probeContainerState,
+  probeAgentBinaryInstalled,
+  waitForContainerRunning,
   KNOWN_FLAGS,
   FIREWALL_RULE_NAME,
   INSTANCE_TAG,
+  DEFAULT_FLEET_MACHINE_TYPE,
   EDITOR_PORT,
   VITE_PORT,
   parseFlags,
@@ -2131,6 +5081,8 @@ module.exports = {
   resolveSeedPreviewOrigin,
   previewSameOriginSafeFromStack,
   isRottedManagedPreviewOrigin,
+  isWrongModePreviewOrigin,
+  isSilentlyBrokenPreview,
   resolveEditorConfig,
   validateEditorVariant,
   assertVariantProvisionable,
@@ -2138,14 +5090,23 @@ module.exports = {
   reconcileProjectExclusivity,
   resolveGhcrToken,
   resolveGhcrPushToken,
+  probeUsableEditorImage,
+  httpsManifestGet,
   resolveProject,
   clientProjectBootstrapArgs,
   cloudConfigPath,
   loadCloudConfig,
   saveCloudConfig,
+  loadOrInitCloudConfig,
+  buildProvisionEnv,
+  buildReconcileAdminCommand,
+  cmdReconcileAdmin,
   buildEditorLocalEnvPatch,
+  buildGreenfieldTitlePatch,
+  mergeEditorLocalPatchB64,
   buildEditorLocalSeedWriteCommand,
   seedPreviewOrigin,
+  healPreviewOriginAtReady,
   buildGcloudArgs,
   sshScriptCommand,
   bootstrapRunnerScript,
@@ -2156,6 +5117,22 @@ 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,
@@ -2167,15 +5144,54 @@ module.exports = {
   ensureInstance,
   ensureBootstrapped,
   assertEditorContainerRunning,
+  checkScriptDrift,
+  streamedScriptEditorBranch,
+  streamedScriptMergeBase,
+  fetchStreamedScriptRef,
+  resolveRemoteScriptRev,
+  gatherScriptDriftFacts,
+  readStreamedScript,
+  STREAMED_SCRIPTS,
+  // ingress wiring (pure decision + spawn wrappers)
+  envPosInt,
+  ingressWiringPlan,
+  fleetInstancePrefix,
+  runVmIngress,
+  wireVmIngressOnAdd,
+  probeVmIngressVerdict,
+  convergeVmIngressOnAdd,
+  unwireVmIngressOnDestroy,
+  // per-VM IAP access (spawn wrapper + Add/Destroy hooks)
+  runIapAccess,
+  applyVmAccessOnAdd,
+  revokeVmAccessOnDestroy,
+  releaseVmSlugOnDestroy,
   // side-effecting handlers
   cmdUp,
   cmdTunnel,
   cmdStop,
   cmdDestroy,
   cmdStatus,
+  cmdIngressUp,
+  cmdReconcileIngress,
+  sweepOrphanIngress,
+  convergeFleetFirewall,
+  reportFirewallPortGaps,
+  cmdReconcileCredentials,
+  cmdAccess,
   cloudMain,
+  probeGitCredentials,
+  seedLiveCredentialCache,
+  assertGitPushCredentials,
   seedGithubCredentials,
+  githubCredentialLine,
+  resolveGithubToken,
+  resolveGithubTokenWithSource,
+  MissingGitPushCredentialsError,
+  classifyGitRemoteError,
+  decideCredentialHeal,
   readVmAppPort,
+  buildVmAppPortReadCommand,
   resolveLaptopGitIdentity,
 };