@codeyam-editor/codeyam-editor 0.1.3 → 0.1.5

package/npm/cloud.js

@@ -11,6 +11,7 @@
 
 const { spawn, spawnSync } = require("child_process");
 const fs = require("fs");
+const os = require("os");
 const path = require("path");
 const readline = require("readline");
 const {
@@ -33,12 +34,58 @@ 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,
+  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,
+  parseIngressStatusVerdict,
+  selectIngressReconcileTargets,
+  detachedAddTailInvocation,
+  ingressInflightMarkerPath,
+  iapAccessInvocation,
+  sharedIngressInvocation,
+} = 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
@@ -51,6 +98,12 @@ const AGENT_ENV_VARS = {
   gemini: "GEMINI_API_KEY",
 };
 
+const AGENT_NPM_PACKAGES = {
+  claude: "@anthropic-ai/claude-code",
+  codex: "@openai/codex",
+  gemini: "@google/gemini-cli",
+};
+
 const KNOWN_FLAGS = [
   "repo", "branch", "instance-name", "project", "zone", "agent",
   // Editor-source selection, decoupled from the client project (repo/branch):
@@ -67,11 +120,39 @@ 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",
 ];
 
 // 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"];
 
 const FIREWALL_RULE_NAME = "codeyam-editor-iap-ssh";
 const INSTANCE_TAG = "codeyam-editor";
@@ -129,6 +210,17 @@ function agentEnvVarName(agent) {
   return AGENT_ENV_VARS[agent];
 }
 
+/** Map an agent name to its global npm package. Throws on unknown agents so
+ *  adding an agent is a one-entry change in `AGENT_NPM_PACKAGES`. */
+function agentNpmPackage(agent) {
+  if (!Object.prototype.hasOwnProperty.call(AGENT_NPM_PACKAGES, agent)) {
+    throw new Error(
+      `Unknown agent: ${agent}. Supported: ${Object.keys(AGENT_NPM_PACKAGES).join(", ")}`,
+    );
+  }
+  return AGENT_NPM_PACKAGES[agent];
+}
+
 /** Parse `--flag value` argv into an object. Unknown flags or missing values
  *  throw with a usage hint — silently dropping them would let typos like
  *  `--branchh main` succeed with no branch flag at all. */
@@ -303,6 +395,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
@@ -331,15 +424,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 &&
@@ -394,6 +499,46 @@ 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);
+}
+
 /** 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() {
@@ -474,9 +619,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;
 }
@@ -529,25 +690,50 @@ 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
- *  configured agent picks up the user's local API key on first launch.
- *  Returns `null` when the key isn't set locally — the wrapper then prints
- *  the interactive-auth fallback line instead of writing an empty patch. */
+ *  configured agent becomes the editor's build-agent provider AND (when the
+ *  key is available) picks up the user's local API key on first launch. The
+ *  top-level `provider` field (lowercase — matching `BuildAgentProvider`'s
+ *  serde) makes the VM's editor default to the chosen agent instead of Claude;
+ *  `editor.local.json` is deep-merged over `editor.json` on the VM, so this
+ *  overrides the packaged default.
+ *
+ *  The patch ALWAYS carries `provider` — the agent is a launch *choice* that
+ *  must persist on the VM regardless of whether the operator happens to have
+ *  the agent's API key exported locally (Gemini, for instance, is normally
+ *  authenticated interactively on the VM). `env.<KEY>` is the separate,
+ *  opportunistic seed: it's included only when the matching key is set in
+ *  `localEnv`. The function never returns `null`. Writing `provider: "claude"`
+ *  when claude is the default deep-merges to a no-op, so the provider can be
+ *  written unconditionally without special-casing the default. */
 function buildEditorLocalEnvPatch(localEnv, agent) {
   const varName = agentEnvVarName(agent);
   const value = localEnv[varName];
-  if (!value) return null;
-  return { env: { [varName]: value } };
+  if (!value) return { provider: agent };
+  return { provider: agent, env: { [varName]: value } };
 }
 
 /** Parse `docker compose ps --format json` (compose v2 — one JSON object per
@@ -700,6 +886,72 @@ function runGcloud(args, opts = {}) {
   });
 }
 
+// Build a bounded, de-noised failure detail from a runGcloud (spawnSync)
+// result: prefer stderr, fall back to stdout, and surface a spawn-level error
+// (e.g. ENOENT when gcloud is not on PATH) when there is no captured output.
+// Trims the known gcloud noise lines — the same `/WARNING|NumPy|google.com/iap/`
+// filter the dashboard's tailLog applies — and keeps the last ~15 lines so the
+// actionable message is not buried under auth/IAP warnings. Pure: result in,
+// string out, so it is unit-testable without spawning gcloud.
+function formatGcloudFailure(result) {
+  const denoise = (text) =>
+    String(text || "")
+      .split("\n")
+      .map((l) => l.replace(/\r$/, ""))
+      .filter((l) => l.trim() !== "")
+      .filter((l) => !/WARNING|NumPy|google\.com\/iap/.test(l))
+      .slice(-15)
+      .join("\n");
+
+  const stderr = denoise(result && result.stderr);
+  if (stderr) return stderr;
+  const stdout = denoise(result && result.stdout);
+  if (stdout) return stdout;
+  if (result && result.error && result.error.message) {
+    return result.error.message;
+  }
+  return "(no output captured from gcloud)";
+}
+
+// A bounded, pure classifier that keys on status === 255 (gcloud-ssh's exit
+// for an ssh failure) and a signature match against known transient strings.
+function isTransientSshFailure(result) {
+  if (!result || result.status !== 255) {
+    return false;
+  }
+  const output = String(result.stderr || "") + String(result.stdout || "");
+  const transientRegex = /kex_exchange_identification|Connection closed|failed to connect to backend|Failed to connect to port 22|Connection refused|Connection reset|Connection timed out|4003|4047/i;
+  return transientRegex.test(output);
+}
+
+// A retry wrapper for gcloud ssh-script calls that handles transient connection drops
+// with exponential backoff, mimicking the IAP ready backoff.
+async function runGcloudSshWithRetry(verb, cfg, extras, { stdio, retries = 5, label, sleepFn } = {}) {
+  let lastResult;
+  for (let attempt = 1; attempt <= retries; attempt++) {
+    const result = runGcloud(buildGcloudArgs(verb, cfg, extras), { stdio });
+    if (result.status === 0) {
+      return result;
+    }
+    lastResult = result;
+    if (isTransientSshFailure(result)) {
+      if (attempt < retries) {
+        const delay = Math.min(2000 * Math.pow(1.5, attempt - 1), 8000);
+        console.error(`  ↺ transient SSH failure (attempt ${attempt}/${retries}) [${label || verb}] ... retrying in ${delay / 1000}s`);
+        if (sleepFn) {
+          await sleepFn(delay);
+        } else {
+          await new Promise((r) => setTimeout(r, delay));
+        }
+        continue;
+      }
+    }
+    // For non-transient failure, return immediately, or if we exhausted our attempts.
+    return result;
+  }
+  return lastResult;
+}
+
 function ensureGcloud() {
   const result = spawnSync("gcloud", ["version"], { stdio: "ignore" });
   if (result.error || result.status !== 0) {
@@ -740,9 +992,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);
@@ -752,6 +1016,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);
@@ -799,9 +1072,11 @@ async function ensureFirewallRule(cfg) {
 async function ensureInstance(cfg) {
   console.error(`Checking instance ${cfg.instanceName}...`);
   const initialState = fetchInstanceState(cfg);
+  const createdThisRun = initialState === null;
+
   if (initialState === "RUNNING") {
     console.error(`  ✓ ${cfg.instanceName} is RUNNING`);
-    return;
+    return { createdThisRun };
   }
   if (initialState === "TERMINATED") {
     console.error(`  ${cfg.instanceName} is TERMINATED — starting...`);
@@ -823,7 +1098,7 @@ async function ensureInstance(cfg) {
     if (fetchInstanceState(cfg) === "RUNNING") {
       console.error(`  ✓ ${cfg.instanceName} is RUNNING`);
       await waitForIapReady(cfg);
-      return;
+      return { createdThisRun };
     }
     await new Promise((r) => setTimeout(r, 2000));
   }
@@ -1079,7 +1354,7 @@ function sshScriptCommand(scriptBody, scriptArgs = [], envVars = {}) {
   return `echo '${b64}' | base64 -d | ${envPrefix}bash -s -- ${argsString}`.trim();
 }
 
-async function ensureBootstrapped(cfg) {
+async function ensureBootstrapped(cfg, { sleepFn } = {}) {
   console.error("Checking VM bootstrap state...");
   const probe = runGcloud(
     buildGcloudArgs("ssh-probe", cfg, {
@@ -1140,12 +1415,17 @@ async function ensureBootstrapped(cfg) {
     // fresh detached build that will survive an SSH disconnect.
     console.error("  launching detached bootstrap on the VM (survives SSH disconnect; ~1-14 min)...");
     const launch = bootstrapLaunchCommand(scriptBody, bootstrapArgs, bootstrapEnv);
-    const launched = runGcloud(
-      buildGcloudArgs("ssh-script", cfg, { command: launch }),
-      { stdio: ["ignore", "pipe", "pipe"] },
+    const launched = await runGcloudSshWithRetry(
+      "ssh-script",
+      cfg,
+      { command: launch },
+      { stdio: ["ignore", "pipe", "pipe"], label: "bootstrap launch", sleepFn }
     );
     if (launched.status !== 0) {
-      throw new Error("failed to launch the detached bootstrap on the VM");
+      const detail = formatGcloudFailure(launched);
+      throw new Error(
+        `failed to launch the detached bootstrap on the VM (gcloud ssh exit ${launched.status}).\n${detail}`,
+      );
     }
   }
 
@@ -1250,10 +1530,19 @@ async function ensureProjectBootstrapped(cfg) {
   // Whitelisted by the dashboard via CY_FORWARD_ENV_KEYS — empty on the
   // standalone `cloud:up` path, so that flow is unchanged.
   const forwardEnv = resolveSetupForwardEnv();
+  // Forward the fleet domain so the bootstrap's compose render publishes the
+  // editor/app ports on 0.0.0.0 (the LB NEG reaches them on the VM's internal
+  // IP) instead of loopback-only. Only when a fleet domain is configured AND
+  // this is a numbered fleet VM — a non-fleet client project keeps the
+  // loopback-only publish (legacy parity). Absent ⇒ key omitted entirely.
+  const ingressEnv = {};
+  const ingressPlan = ingressWiringPlan(cfg);
+  if (ingressPlan.wire) ingressEnv.FLEET_DOMAIN = ingressPlan.domain;
   const command = sshScriptCommand(scriptBody, scriptArgs, {
     GITHUB_TOKEN: resolveGithubToken(),
     CY_GIT_USER_NAME: laptopGit.name,
     CY_GIT_USER_EMAIL: laptopGit.email,
+    ...ingressEnv,
     ...forwardEnv,
   });
   const result = runGcloud(
@@ -1280,6 +1569,7 @@ async function ensureEditorContainerUp(cfg) {
   );
   if (probe.status === 0 && parseEditorComposeState(probe.stdout) === "running") {
     console.error("  ✓ editor container is already running");
+    await ensureAgentCliInstalled(cfg);
     return;
   }
   console.error("  starting editor container (docker compose up -d)...");
@@ -1292,6 +1582,34 @@ async function ensureEditorContainerUp(cfg) {
   if (up.status !== 0) {
     throw new Error("docker compose up -d failed on the VM");
   }
+  await ensureAgentCliInstalled(cfg);
+}
+
+// Hard gate: provisioning success REQUIRES a running editor container. Reuses
+// the exact compose-ps probe ensureEditorContainerUp uses, but as a TERMINAL
+// re-check rather than a precondition — `docker compose up -d` can exit 0 over
+// a container that then crash-loops or exits, and an upstream phase that never
+// ran leaves no /workspace at all. Either way `cmdUp` would otherwise report
+// success. This throws (non-zero exit) when the editor service isn't
+// `running`, converting a silent partial provision into a loud, actionable
+// failure the operator (and the dashboard's fail-fast-on-nonzero path) can act
+// on. The `|| true` keeps the probe's exit status 0 so the real signal is the
+// parsed compose state, not the SSH/cd exit code.
+async function assertEditorContainerRunning(cfg) {
+  const repoName = resolveProject(cfg).name;
+  const composeCmd = `docker compose -f docker-compose.cloud.yml`;
+  const probe = runGcloud(
+    buildGcloudArgs("ssh-probe", cfg, {
+      command: `cd ~/projects/${repoName} 2>/dev/null && ${composeCmd} ps --format json 2>/dev/null || true`,
+    }),
+    { stdio: ["ignore", "pipe", "ignore"] },
+  );
+  if (!(probe.status === 0 && parseEditorComposeState(probe.stdout) === "running")) {
+    throw new Error(
+      `provisioning incomplete: editor container is not running on ${cfg.instanceName} ` +
+        `(no /workspace or container). Re-run: npm run cloud:up -- --instance-name ${cfg.instanceName}`,
+    );
+  }
 }
 
 /** Read the laptop's git author identity (`user.name`, `user.email`) so
@@ -1320,13 +1638,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
@@ -1360,6 +1717,139 @@ function resolveGhcrPushToken() {
   return process.env.CODEYAM_GHCR_PUSH_TOKEN || "";
 }
 
+/** Read-only probe: does a usable prebuilt editor image already exist on the
+ *  registry for `branch`? Used by the fleet dashboard BEFORE a concurrent batch
+ *  add to decide whether to pace one VM ahead of the rest (see
+ *  npm/fleet-prewarm.js::decideBatchPrewarm). A `docker manifest inspect` is a
+ *  HEAD-equivalent — it reads the manifest without pulling the (multi-GB) image.
+ *
+ *  Returns:
+ *    true  — at least one of the usable tags exists (a cold add can pull; no pacer)
+ *    false — every tag was checked and none exists (known-absent; pacing pays)
+ *    null  — undetermined: no read token, docker missing, or a probe error that
+ *            can't be distinguished from "absent". The caller treats null as
+ *            "fan out" (today's behavior, never worse) rather than risk a
+ *            10-min serialization that might buy nothing.
+ *
+ *  The private packages require auth, so we `docker login` with the read token
+ *  first; without a token we can't tell absent from forbidden, so → null.
+ *  `spawnImpl` is injectable for unit tests. */
+function probeUsableEditorImage({ branch, registry, token, spawnImpl } = {}) {
+  const fp = require("./fleet-prewarm");
+  const spawn = spawnImpl || spawnSync;
+  const reg = registry || process.env.CODEYAM_REGISTRY || "ghcr.io/codeyam-ai";
+  const readToken = token || resolveGhcrToken();
+  if (!readToken) return null; // can't auth → can't distinguish absent from forbidden
+  const host = String(reg).split("/")[0];
+  const login = spawn(
+    "docker",
+    ["login", host, "-u", process.env.CODEYAM_GHCR_USER || "codeyam", "--password-stdin"],
+    { input: readToken, encoding: "utf8" },
+  );
+  // spawn error (docker missing) or a non-zero login → undetermined.
+  if (!login || login.error || login.status !== 0) return null;
+  const tags = fp.usableImageTags({ registry: reg, branch });
+  let allClean = true;
+  for (const tag of tags) {
+    const res = spawn("docker", ["manifest", "inspect", tag], { encoding: "utf8" });
+    if (!res || res.error) {
+      allClean = false; // probe itself failed to run — can't claim "absent"
+      continue;
+    }
+    if (res.status === 0) return true; // a usable image exists
+  }
+  // Every tag inspected cleanly and none existed → definitively absent. If any
+  // probe failed to run, we can't be sure → undetermined.
+  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";
+  }
+  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",
+      };
+    }
+    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)",
+  };
+}
+
 /** 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
@@ -1367,17 +1857,24 @@ 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...");
+  console.error(
+    `Writing GitHub token (from ${source}) into ~/.codeyam-cloud-git-credentials on the VM...`,
+  );
   const credLine = `https://x-access-token:${token}@github.com`;
   // Quote the token through one shell layer (gcloud ssh --command); the
   // value is base64'd to keep it out of the shell history.
@@ -1511,36 +2008,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}...`
@@ -1560,20 +2084,114 @@ async function seedPreviewOrigin(cfg, appPort = VITE_PORT) {
   }
 }
 
+/** 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);
-  if (!patch) {
+  const hasKey = Boolean(patch.env);
+  if (!hasKey) {
     console.error(
-      `\nNo ${agentEnvVarName(cfg.agent)} set locally — skipping agent auth seed.\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`,
+      `\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`,
     );
-    return;
   }
   const repoName = resolveProject(cfg).name;
   const remotePath = `~/projects/${repoName}/.codeyam/editor.local.json`;
-  console.error(`Seeding ${agentEnvVarName(cfg.agent)} into ${remotePath}...`);
+  const seedLabel = hasKey
+    ? `Seeding ${agentEnvVarName(cfg.agent)} into ${remotePath}...`
+    : `Seeding provider '${cfg.agent}' into ${remotePath}...`;
+  console.error(seedLabel);
 
   const read = runGcloud(
     buildGcloudArgs("ssh-probe", cfg, {
@@ -1606,6 +2224,71 @@ async function seedAgentApiKey(cfg) {
   if (write.status !== 0) {
     throw new Error(`Failed to write ${remotePath} on VM`);
   }
+
+  await ensureAgentCliInstalled(cfg);
+}
+
+/** 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";
+
+  // First, check if the container is running on the VM host.
+  // If the container is not running, we do nothing and return.
+  const checkProbe = runGcloud(
+    buildGcloudArgs("ssh-probe", cfg, {
+      command: `docker ps --filter name=^/${container}$ --filter status=running --format '{{.Name}}'`,
+    }),
+    { stdio: ["ignore", "pipe", "ignore"] },
+  );
+
+  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;
+  }
+
+  console.error(`Ensuring build-agent CLI for '${agent}' is installed in container '${container}'...`);
+
+  const containerScript = [
+    "#!/usr/bin/env bash",
+    "set -euo pipefail",
+    `BINARY="${agent}"`,
+    `PACKAGE="${pkg}"`,
+    `AGENT="${agent}"`,
+    "",
+    "if command -v \"$BINARY\" >/dev/null 2>&1; then",
+    "  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\"",
+    "  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",
+    "echo \"  ✓ Successfully installed $BINARY\"",
+  ].join("\n");
+
+  const hostCommand = `docker exec -i ${container} bash -s <<'EOF'\n${containerScript}\nEOF`;
+
+  const installCmd = runGcloud(
+    buildGcloudArgs("ssh-probe", cfg, {
+      command: hostCommand,
+    }),
+    { stdio: ["ignore", "inherit", "inherit"] }
+  );
+
+  if (installCmd.status !== 0) {
+    throw new Error(`Failed to install build-agent CLI in container for agent: ${agent}`);
+  }
 }
 
 async function openTunnel(cfg, appPort = VITE_PORT) {
@@ -1649,38 +2332,644 @@ function promptForInstanceName(expected) {
   });
 }
 
+const STREAMED_SCRIPTS = ["scripts/gcp-bootstrap.sh", "scripts/gcp-project-bootstrap.sh"];
+
+/** Check if the streamed bootstrap scripts have drifted from the remote repository
+ *  and abort provisioning if they are out of date to prevent silent container/VM failures. */
+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 = "main" } = resolveEditorConfig(cfg);
+
+  console.error(`Checking streamed-script drift against origin/${editorBranch}...`);
+
+  // 1. git fetch origin <editorBranch>
+  const fetchResult = spawnSync("git", ["fetch", "origin", editorBranch], { encoding: "utf8" });
+  if (fetchResult.status !== 0) {
+    console.error(`  [Warning] Failed to fetch origin ${editorBranch} (${(fetchResult.stderr || "").trim() || "unknown error"}). Skipping drift check.`);
+    return;
+  }
+
+  // 2. Find the merge base between HEAD and origin/<editorBranch>
+  const mbResult = spawnSync("git", ["merge-base", "HEAD", `origin/${editorBranch}`], { encoding: "utf8" });
+  let mergeBase = null;
+  if (mbResult.status === 0) {
+    mergeBase = mbResult.stdout.trim();
+  }
+
+  const filesData = [];
+
+  for (const scriptPath of STREAMED_SCRIPTS) {
+    // a. localHash
+    const localHashResult = spawnSync("git", ["hash-object", scriptPath], { encoding: "utf8" });
+    if (localHashResult.status !== 0) {
+      console.error(`  [Warning] Failed to compute local hash for ${scriptPath}. Skipping drift check.`);
+      return;
+    }
+    const localHash = localHashResult.stdout.trim();
+
+    // b. remoteHash (from origin/<editorBranch>)
+    let remoteHash = null;
+    const remoteHashResult = spawnSync("git", ["rev-parse", `origin/${editorBranch}:${scriptPath}`], { encoding: "utf8" });
+    if (remoteHashResult.status === 0) {
+      remoteHash = remoteHashResult.stdout.trim();
+    }
+
+    // c. baseHash (from mergeBase)
+    let baseHash = null;
+    if (mergeBase) {
+      const baseHashResult = spawnSync("git", ["rev-parse", `${mergeBase}:${scriptPath}`], { encoding: "utf8" });
+      if (baseHashResult.status === 0) {
+        baseHash = baseHashResult.stdout.trim();
+      }
+    }
+
+    // d. dirty status
+    const statusResult = spawnSync("git", ["status", "--porcelain", scriptPath], { encoding: "utf8" });
+    const dirty = statusResult.status === 0 && statusResult.stdout.trim() !== "";
+
+    filesData.push({
+      path: scriptPath,
+      localHash,
+      remoteHash,
+      baseHash,
+      dirty
+    });
+  }
+
+  const { classifyScriptDrift } = require("./script-drift");
+  const verdictResult = classifyScriptDrift({ files: filesData });
+
+  if (verdictResult.verdict === "stale" || verdictResult.verdict === "diverged") {
+    console.error("");
+    console.error("================================================================================");
+    console.error(`✗ ERROR: Streamed scripts have drifted from origin/${editorBranch}!`);
+    console.error(`  Verdict: ${verdictResult.verdict.toUpperCase()}`);
+    console.error("  The following files are out of date on your machine:");
+    for (const f of verdictResult.staleFiles) {
+      console.error(`    - ${f}`);
+    }
+    console.error("");
+    console.error("  To proceed safely, please update your local checkout first:");
+    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 (verdictResult.verdict === "local-ahead") {
+    console.error("  [Warning] Streaming locally-modified 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 },
+  });
+}
+
+/** 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
+  const stale = accessFor(vmNumber);
+  const staleOnly = stale.filter((p) => !desired.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 (desired.length > 0) {
+      console.error(`  granting IAP access to VM-${vmNumber} for ${desired.length} principal(s)...`);
+      const res = runIapAccess(cfg, vmNumber, "grant", desired);
+      if (res.status === 0) {
+        console.error(`  ✓ IAP access granted: ${desired.join(", ")}`);
+      } else {
+        console.error(
+          `  ⚠ IAP access grant for VM-${vmNumber} did not complete cleanly. ` +
+            `The VM is provisioned; re-grant with:\n` +
+            `      VM_ACCESS=${desired.join(",")} bash scripts/gcp/iap-access.sh ${vmNumber} grant`,
+        );
+      }
+    }
+  } else if (desired.length > 0) {
+    console.error(
+      `  (no fleet domain / not a fleet VM — IAP access for ${desired.length} principal(s) not applied; ` +
+        `set a fleet domain and re-run, or use cloud:access)`,
+    );
+  }
+
+  // Sidecar reconcile (always, for a fleet VM): record exactly what was granted —
+  // the desired list when wired, or empty when not (nothing was applied without
+  // backend services). Either way 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 later domain'd 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();
+
+/** 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), runs the wiring then
+ *  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. */
+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 {
+    wireVmIngressOnAdd(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);
-  await ensureInstance(cfg);
-  await ensureBootstrapped(cfg);
-  await ensureProjectBootstrapped(cfg);
-  // Resolve the app's dev-server port from the VM's now-bootstrapped config so
-  // the previewOrigin seed and the laptop tunnel both target it (not 5173).
-  const appPort = await readVmAppPort(cfg);
-  await seedPreviewOrigin(cfg, appPort);
-  // 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);
-  await ensureEditorContainerUp(cfg);
-  await seedAgentApiKey(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);
+  const { createdThisRun } = await ensureInstance(cfg);
+
+  try {
+    await ensureBootstrapped(cfg);
+    await ensureProjectBootstrapped(cfg);
+    // Resolve the app's dev-server port from the VM's now-bootstrapped config so
+    // the previewOrigin seed and the laptop tunnel both target it (not 5173).
+    const appPort = await readVmAppPort(cfg);
+    await seedPreviewOrigin(cfg, appPort);
+    // 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.
+    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);
+    await ensureEditorContainerUp(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);
+    // 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));
+        if (del.status !== 0) {
+          console.error(
+            `  Warning: failed to delete instance ${cfg.instanceName} during abort teardown. ` +
+              `Please delete it manually with 'npm run cloud:destroy'.`,
+          );
+        }
+      } catch (delErr) {
+        console.error(
+          `  Warning: error deleting instance ${cfg.instanceName} during abort teardown: ${delErr.message}. ` +
+            `Please delete it manually with 'npm run cloud:destroy'.`,
+        );
+      }
+    }
+    throw err;
+  }
   // --no-tunnel: provisioning-only mode (the fleet dashboard opens its own
   // per-VM tunnel). Skipping openTunnel lets cloud:up EXIT cleanly instead of
   // hanging on a tunnel, and — critically for parallel multi-add — avoids N
@@ -1694,10 +2983,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.",
@@ -1725,10 +3014,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.");
   }
@@ -1744,10 +3033,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.");
   }
@@ -1758,12 +3047,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"],
   });
@@ -1781,17 +3086,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;
@@ -1833,12 +3138,269 @@ 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,
+    });
+    const res = spawnSync(inv.command, inv.args, {
+      env: { ...process.env, ...inv.env },
+      encoding: "utf8",
+    });
+    return { vmNumber: n, slug, verdict: parseIngressStatusVerdict(res.stdout || "") };
+  });
+  const targets = selectIngressReconcileTargets(statuses);
+  const targetNums = new Set(targets.map((t) => t.vmNumber));
+  for (const s of statuses) {
+    if (!targetNums.has(s.vmNumber)) {
+      const label = s.slug || `vm-${s.vmNumber}`;
+      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"}`,
+    );
+  }
+}
+
+/** `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. */
+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.");
+  }
+  const repoName = resolveProject(cfg).name;
+  const projectCd = `cd ~/projects/${repoName}`;
+  const composeExec = `docker compose -f docker-compose.cloud.yml exec -T editor`;
+
+  // One SSH round-trip: report staging-file emptiness and the in-container
+  // ls-remote outcome with stable markers we parse below.
+  console.error(`Probing git push credentials on ${cfg.instanceName}...`);
+  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;
+  const stagingEmpty = /STAGING=empty/.test(out);
+  const lsRemoteOk = /LSREMOTE=ok/.test(out);
+  const lsRemoteStderr = out
+    .split("\n")
+    .filter((l) => l.startsWith("LSRERR:"))
+    .map((l) => l.slice("LSRERR:".length))
+    .join("\n");
+
+  const decision = decideCredentialHeal({ stagingEmpty, lsRemoteOk, lsRemoteStderr });
+  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).
+  await seedGithubCredentials(cfg);
+
+  // Seed the LIVE in-memory credential-cache daemon over the socket — the same
+  // `git credential approve` shape the entrypoint uses
+  // (scripts/cloud-editor-entrypoint.sh) — so push works immediately with no
+  // container restart. base64 keeps the token out of the shell history across
+  // the gcloud-ssh → docker layers.
+  const { token } = resolveGithubTokenWithSource();
+  const socket = "/run/codeyam/git-credential-cache.socket";
+  const approveStdin = `protocol=https\nhost=github.com\nusername=x-access-token\npassword=${token}\n\n`;
+  const b64 = Buffer.from(approveStdin).toString("base64");
+  const seedCmd =
+    `${projectCd} && echo ${b64} | base64 -d | ${composeExec} ` +
+    `git -c 'credential.helper=cache --timeout=31536000 --socket=${socket}' ` +
+    `credential approve && 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(
+      `Re-seeded the host file but failed to seed the live credential cache on ${cfg.instanceName}.`,
+    );
+  }
+  console.error(
+    `  ✓ re-seeded host file + live credential cache on ${cfg.instanceName}; ` +
+      `plan-claim sync will recover on the next tick.`,
+  );
+}
+
+/** `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,
+  access: cmdAccess,
 };
 
 async function cloudMain() {
@@ -1861,7 +3423,10 @@ async function cloudMain() {
 module.exports = {
   // pure helpers
   agentEnvVarName,
+  agentNpmPackage,
   AGENT_ENV_VARS,
+  AGENT_NPM_PACKAGES,
+  ensureAgentCliInstalled,
   KNOWN_FLAGS,
   FIREWALL_RULE_NAME,
   INSTANCE_TAG,
@@ -1882,6 +3447,7 @@ module.exports = {
   resolveSeedPreviewOrigin,
   previewSameOriginSafeFromStack,
   isRottedManagedPreviewOrigin,
+  isWrongModePreviewOrigin,
   resolveEditorConfig,
   validateEditorVariant,
   assertVariantProvisionable,
@@ -1889,14 +3455,17 @@ module.exports = {
   reconcileProjectExclusivity,
   resolveGhcrToken,
   resolveGhcrPushToken,
+  probeUsableEditorImage,
   resolveProject,
   clientProjectBootstrapArgs,
   cloudConfigPath,
   loadCloudConfig,
   saveCloudConfig,
+  loadOrInitCloudConfig,
   buildEditorLocalEnvPatch,
   buildEditorLocalSeedWriteCommand,
   seedPreviewOrigin,
+  healPreviewOriginAtReady,
   buildGcloudArgs,
   sshScriptCommand,
   bootstrapRunnerScript,
@@ -1912,14 +3481,42 @@ module.exports = {
   FORWARD_ENV_KEYS_ENV,
   parseEditorComposeState,
   fetchInstanceState,
+  formatGcloudFailure,
+  isTransientSshFailure,
+  runGcloudSshWithRetry,
+  ensureInstance,
+  ensureBootstrapped,
+  assertEditorContainerRunning,
+  checkScriptDrift,
+  STREAMED_SCRIPTS,
+  // ingress wiring (pure decision + spawn wrappers)
+  ingressWiringPlan,
+  fleetInstancePrefix,
+  runVmIngress,
+  wireVmIngressOnAdd,
+  unwireVmIngressOnDestroy,
+  // per-VM IAP access (spawn wrapper + Add/Destroy hooks)
+  runIapAccess,
+  applyVmAccessOnAdd,
+  revokeVmAccessOnDestroy,
+  releaseVmSlugOnDestroy,
   // side-effecting handlers
   cmdUp,
   cmdTunnel,
   cmdStop,
   cmdDestroy,
   cmdStatus,
+  cmdIngressUp,
+  cmdReconcileIngress,
+  cmdReconcileCredentials,
+  cmdAccess,
   cloudMain,
   seedGithubCredentials,
+  resolveGithubToken,
+  resolveGithubTokenWithSource,
+  MissingGitPushCredentialsError,
+  classifyGitRemoteError,
+  decideCredentialHeal,
   readVmAppPort,
   resolveLaptopGitIdentity,
 };