@codeyam-editor/codeyam-editor 0.1.1 → 0.1.3

package/npm/cloud.js

@@ -0,0 +1,1929 @@
+#!/usr/bin/env node
+
+/**
+ * cloud.js — one-command orchestrator for hosting a codeyam-editor session
+ * on a GCE VM. Reuses `scripts/gcp-bootstrap.sh` and
+ * `scripts/gcp-project-bootstrap.sh` verbatim by streaming them over
+ * `gcloud compute ssh`. Per-project state lives in `.codeyam/cloud.json`
+ * (gitignored) so the second invocation is zero-arg. See
+ * `docs/cloud-gcp.md` for the runbook this wraps.
+ */
+
+const { spawn, spawnSync } = require("child_process");
+const fs = require("fs");
+const path = require("path");
+const readline = require("readline");
+const {
+  rootDir,
+  isPortInUse,
+  waitForPort,
+  deepMergeJson,
+  killChildProcess,
+} = require("./utils");
+const { open } = require("./open");
+// `FORWARD_ENV_KEYS_ENV` is the env-var name (`CY_FORWARD_ENV_KEYS`) the
+// fleet dashboard sets on `cloud:up`'s child to name the subset of
+// `process.env` keys that came from the operator-supplied launch form.
+// Imported from `fleet-env` (single source of truth) so the dashboard and
+// cloud:up can never drift on the contract — a string mismatch would
+// silently disable the forwarding.
+const { FORWARD_ENV_KEYS_ENV } = require("./fleet-env");
+// Deterministic fleet-ingress URL derivation. `resolveFleetDomain` reads the
+// operator's owned domain from env (null when unset); `vmUrls` derives a VM's
+// 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");
+
+// =============================================================================
+// Pure helpers — every export here is unit-tested in cloud.test.js without
+// touching `gcloud` or the network.
+// =============================================================================
+
+const AGENT_ENV_VARS = {
+  claude: "ANTHROPIC_API_KEY",
+  codex: "OPENAI_API_KEY",
+  gemini: "GEMINI_API_KEY",
+};
+
+const KNOWN_FLAGS = [
+  "repo", "branch", "instance-name", "project", "zone", "agent",
+  // Editor-source selection, decoupled from the client project (repo/branch):
+  "editor-repo", "editor-branch", "editor-variant",
+  // Greenfield: launch against a NEW empty folder (no repo to clone) named
+  // <name>; the bootstrap mkdir+git-init+inits it and the editor's onboarding
+  // workflow takes over. Mutually exclusive with --repo.
+  "new-project",
+  // Provisioning-only: skip cloud:up's own laptop tunnel (the caller opens its
+  // own). Lets cloud:up exit cleanly + avoids parallel runs contending on the
+  // fixed local ports 14199/5173.
+  "no-tunnel",
+  // Opt out of the project's `npm run setup` at provision time. The bootstrap
+  // 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",
+];
+
+// 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 FIREWALL_RULE_NAME = "codeyam-editor-iap-ssh";
+const INSTANCE_TAG = "codeyam-editor";
+const EDITOR_PORT = 14199;
+const VITE_PORT = 5173;
+
+// Sentinel stamped into editor.local.json's `_managedPreviewOrigin` whenever
+// WE (cloud:up's seed, or the operator's cloudflared-monitor) write the
+// previewOrigin. It lets the monitor tell its own writes (overwrite freely on
+// respawn) apart from a user-pinned origin (never clobber). Must match the
+// literal the bash monitor writes — see scripts/operator/cloudflared-monitor.sh.
+const MANAGED_PREVIEW_ORIGIN = "cloudflared-monitor";
+
+// The reserved same-origin path the Live Preview is served under. Seeded as the
+// quick-tunnel `previewOrigin` so the iframe loads the app from the editor's own
+// origin (relative path, no `localhost:<port>` URL) — killing Chrome's Private
+// Network Access block and any cross-VM port collision. A constant relative path
+// never rotates, so the cloudflared-monitor has nothing to push for it. Mirrors
+// the Rust `preview_proxy_route::PREVIEW_PATH_PREFIX`.
+const SAME_ORIGIN_PREVIEW_PATH = "/__codeyam_preview";
+
+// Operator-laptop sidecar the cloudflared-monitor writes per-VM tunnel URLs
+// into. cloud:up reads it to seed a VM's previewOrigin with the public
+// `<N>-preview` URL when the monitor has already published one. Same default
+// path + env override the monitor and fleet dashboard use.
+const CLOUDFLARED_URLS_FILE =
+  process.env.URLS_FILE ||
+  path.join(rootDir, ".codeyam", "logs", "cloudflared-urls.json");
+
+// Canonical codeyam-editor repository — the default source for the editor
+// IMAGE, independent of the CLIENT project being edited (cfg.repo). Decoupling
+// these is what lets one VM edit client project A while running the editor
+// built from codeyam-editor branch B. Before this split, cfg.repo/cfg.branch
+// fed BOTH the image build and the /workspace clone, so only the self-host case
+// (client === editor) worked; a non-self-host VM tried to build the editor
+// image out of the client repo.
+const CANONICAL_EDITOR_REPO = "https://github.com/codeyam-ai/codeyam-editor.git";
+
+// The editor distribution channels an operator can pick per VM. All three are
+// provisionable (gcp-bootstrap dispatches on --editor-variant):
+//   dev        — build the editor image from the editor repo @ editorBranch
+//   staging    — run the published `@codeyam-editor/codeyam-editor@staging` image
+//   production — run the published `@codeyam-editor/codeyam-editor` (latest) image
+const EDITOR_VARIANTS = ["dev", "staging", "production"];
+
+/** Map an agent name to its API-key env var. Throws on unknown agents so
+ *  adding an agent is a one-entry change in `AGENT_ENV_VARS`, never a
+ *  silent fallthrough that ships unauthenticated. */
+function agentEnvVarName(agent) {
+  if (!Object.prototype.hasOwnProperty.call(AGENT_ENV_VARS, agent)) {
+    throw new Error(
+      `Unknown agent: ${agent}. Supported: ${Object.keys(AGENT_ENV_VARS).join(", ")}`,
+    );
+  }
+  return AGENT_ENV_VARS[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. */
+function parseFlags(argv) {
+  const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (!arg.startsWith("--")) {
+      throw new Error(
+        `Unexpected positional argument: ${arg}\n` +
+          `Usage: npm run cloud:<up|tunnel|stop|destroy|status> -- [${KNOWN_FLAGS
+            .map((f) => `--${f} <value>`)
+            .join("] [")}]`,
+      );
+    }
+    const key = arg.slice(2);
+    if (!KNOWN_FLAGS.includes(key)) {
+      throw new Error(`Unknown flag: ${arg}. Known: --${KNOWN_FLAGS.join(", --")}`);
+    }
+    const camel = key.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+    if (BOOLEAN_FLAGS.includes(key)) {
+      flags[camel] = true;
+      continue;
+    }
+    const value = argv[i + 1];
+    if (value === undefined || value.startsWith("--")) {
+      throw new Error(`${arg} requires a value`);
+    }
+    flags[camel] = value;
+    i++;
+  }
+  return flags;
+}
+
+/** Strip `.git`, take the basename, lowercase, collapse non-alphanumerics to
+ *  hyphens. Mirrors the existing `scripts/gcp-project-bootstrap.sh` derivation
+ *  so the directory layout on the VM matches the instance name 1:1. */
+function repoBasename(repoUrl) {
+  const stripped = repoUrl.replace(/\.git$/i, "");
+  const parts = stripped.split(/[/:]+/).filter(Boolean);
+  return parts[parts.length - 1] || "project";
+}
+
+/** Construct a deterministic instance name from a repo URL. GCE caps
+ *  instance names at 63 chars; we cap at 40 to keep room for hyphen
+ *  separators and stay well below the limit. */
+function deriveInstanceName(repoUrl) {
+  const base = repoBasename(repoUrl);
+  let slug = base
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  if (!slug) slug = "project";
+  let name = `codeyam-editor-${slug}`;
+  if (name.length > 40) name = name.slice(0, 40).replace(/-+$/g, "");
+  return name;
+}
+
+/** Normalize two repo URLs for equality: strip a trailing `.git`, lowercase.
+ *  Used to detect the self-host case (client repo IS the editor repo). */
+function sameRepo(a, b) {
+  const norm = (s) => String(s || "").replace(/\.git$/i, "").toLowerCase();
+  return !!a && !!b && norm(a) === norm(b);
+}
+
+/** Pick the default GCE instance name a freshly launched `cloud:up` should
+ *  mint for `repoUrl`. The canonical fleet repo (`codeyam-editor`) is part of
+ *  the numbered fleet — VM-1 must match the dashboard's `INSTANCE_PREFIX + 1`
+ *  shape (`<base>-1`), every VM is `<base>-<n>`. A client repo (single-VM)
+ *  keeps the un-suffixed base (`codeyam-editor-<slug>`). Pure / disk-free so
+ *  the convention is testable without going through loadOrInitCloudConfig. */
+function defaultInstanceNameFor(repoUrl) {
+  const base = deriveInstanceName(repoUrl);
+  return sameRepo(repoUrl, CANONICAL_EDITOR_REPO) ? `${base}-1` : base;
+}
+
+/** Resolve the fleet VM number from an instance name, or null when the name
+ *  isn't a fleet self-host instance. The fleet base is the instance name
+ *  `deriveInstanceName` returns for the canonical editor repo; every VM is
+ *  `<base>-<n>` (VM-1 = `<base>-1`, VM-N = `<base>-N`), matching the
+ *  dashboard's INSTANCE_PREFIX + n. As a back-compat read path the bare
+ *  `<base>` (no suffix) also resolves to VM-1, so any lingering legacy
+ *  instance or old log is still recognized. A non-fleet client project
+ *  (`codeyam-editor-<slug>`) returns null so its previewOrigin seed never
+ *  picks up a fleet tunnel URL. */
+function resolveFleetVmNumber(instanceName) {
+  const base = deriveInstanceName(CANONICAL_EDITOR_REPO);
+  const name = String(instanceName || "");
+  if (name === base) return 1;
+  const m = new RegExp(`^${base}-(\\d+)$`).exec(name);
+  return m ? Number(m[1]) : null;
+}
+
+/** Roster a just-provisioned VM into the fleet dashboard's view so it (and the
+ *  cloudflared-monitor + watchdog that read the same roster) pick it up within
+ *  one poll cycle — closing the invisible-VM gap where a CLI `cloud:up` left the
+ *  VM out of `fleet-vms.json` until a manual edit.
+ *
+ *  Best-effort and non-fatal: a roster-write failure warns loudly (surfacing it
+ *  is the whole point of this fix) but never aborts an otherwise-successful
+ *  provision. A non-fleet instance name (`resolveFleetVmNumber` → null, e.g. a
+ *  guest/standalone editor) is skipped — only fleet-numbered VMs roster.
+ *
+ *  Returns `{ status, vm }` where `status` is `"rostered" | "skipped" |
+ *  "failed"`. `deps` is injectable so the unit test drives every branch without
+ *  touching the real roster file. */
+function rosterProvisionedVm(instanceName, deps = {}) {
+  const resolve = deps.resolveFleetVmNumber || resolveFleetVmNumber;
+  const add = deps.addToRoster || addToRoster;
+  const log = deps.log || ((m) => console.error(m));
+  const n = resolve(instanceName);
+  if (n == null) {
+    log(`(instance '${instanceName}' is not a fleet VM — skipping dashboard roster)`);
+    return { status: "skipped", vm: null };
+  }
+  try {
+    add(n);
+    log(`✓ rostered VM-${n} into the fleet dashboard`);
+    return { status: "rostered", vm: n };
+  } catch (e) {
+    log(
+      `⚠ failed to roster VM-${n} (${e && e.message}). The VM is provisioned ` +
+        "but the dashboard won't show it until it's rostered — add it via the " +
+        "dashboard's Adopt action or re-run cloud:up.",
+    );
+    return { status: "failed", vm: n };
+  }
+}
+
+/** Resolve the app's dev-server port from a parsed editor.json plus an optional
+ *  editor.local.json overlay, mirroring `EditorConfig::resolved_port()`:
+ *  `apps[0].port` wins, then the top-level `port`, then `VITE_PORT` (5173) as
+ *  the final fallback for a config that specifies neither. editor.local.json
+ *  fields override editor.json (deep-merge precedence — the same rule the editor
+ *  applies via `load_config_with_overrides`). The runtime env override
+ *  (`CODEYAM_APP_PORT_OVERRIDE`) is intentionally NOT consulted here: cloud:up
+ *  reads the static, committed config at provision time. */
+function resolveConfiguredAppPort(editorJson = {}, editorLocalJson = {}) {
+  const merged = deepMergeJson(editorJson || {}, editorLocalJson || {});
+  const apps0 =
+    Array.isArray(merged.apps) && merged.apps[0] ? merged.apps[0] : {};
+  const raw = apps0.port != null ? apps0.port : merged.port;
+  const n = Number(raw);
+  return Number.isInteger(n) && n > 0 && n < 65536 ? n : VITE_PORT;
+}
+
+/** Decide the previewOrigin patch to seed into a VM's editor.local.json.
+ *
+ *  Named-tunnel mode (FLEET_DOMAIN set, the VM is a fleet self-host VM): the
+ *  previewOrigin is the VM's *deterministic* preview hostname
+ *  (`https://vm-<N>.preview.<domain>`), derived purely from the VM number. It
+ *  never rotates, so there is no monitor URL to look up and — crucially — no
+ *  `http://localhost:<port>` fallback that could silently point the iframe at an
+ *  unreachable origin (the failure class improve38 closes). The named tunnel
+ *  fronts the dev server on whatever port it serves, so the seed stays
+ *  port-agnostic in this mode.
+ *
+ *  Legacy quick-tunnel mode (no FLEET_DOMAIN, or a non-fleet client project):
+ *  when the operator's cloudflared-monitor has already published a `<N>-preview`
+ *  quick-tunnel URL in cloudflared-urls.json, that URL is the steady-state
+ *  origin; otherwise fall back to the in-VM dev-server port (`appPort`, defaults
+ *  to 5173) — the bootstrap value for the window before the monitor's first
+ *  tick. This is the unchanged behavior for any fleet that hasn't adopted a
+ *  named-tunnel domain yet.
+ *
+ *  Either way we stamp `_managedPreviewOrigin` so the (legacy) monitor
+ *  recognises the value as ours and won't mistake the cloud:up seed for a user
+ *  pin. `env` is injectable so the unit test can drive both modes. */
+function resolveSeedPreviewOrigin(
+  instanceName,
+  urls = {},
+  appPort = VITE_PORT,
+  env = process.env,
+  sameOriginSafe = true,
+) {
+  // 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
+  // editor mounts `/__codeyam_preview` on its own origin and forwards to the
+  // in-VM app-port reverse proxy, so the iframe loads from the exact origin the
+  // editor is served on (public quick-tunnel, named tunnel, SSH-tunnel
+  // localhost, anything). It is a CONSTANT relative path: it never rotates and
+  // depends only on the editor's own origin being reachable, so it can never rot
+  // the way a frozen managed quick-tunnel URL does (the VM-1/2/6 leftover this
+  // plan fixes). No `_managedPreviewOrigin` marker is stamped — the marker is
+  // reserved for the genuinely-managed dedicated origins below, so the self-heal
+  // predicate can tell a rotting managed URL apart from this constant path.
+  if (sameOriginSafe) {
+    return { previewOrigin: SAME_ORIGIN_PREVIEW_PATH };
+  }
+
+  // NOT same-origin-safe (client-routed stacks — Next.js etc.): the client
+  // router breaks the same-origin subpath proxy (it pushState's to root-absolute
+  // paths and recurses into the editor), so the preview must come from a
+  // DEDICATED origin. We stamp `_managedPreviewOrigin` so the (legacy) monitor
+  // recognises the value as ours and won't mistake it for a user pin.
+  const vm = resolveFleetVmNumber(instanceName);
+  const domain = resolveFleetDomain(env);
+  // Named-tunnel mode: the deterministic `vm-<N>.preview.<domain>` host is a
+  // dedicated sibling subdomain of the editor and never rotates. A non-fleet
+  // client project (vm == null) keeps the localhost seed even with a domain set.
+  if (domain && vm != null) {
+    return {
+      previewOrigin: vmUrls(vm, domain).preview,
+      _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.
+  const previewKey = vm != null ? `${vm}-preview` : null;
+  const tunnelUrl =
+    previewKey &&
+    typeof urls[previewKey] === "string" &&
+    urls[previewKey].length > 0
+      ? urls[previewKey]
+      : `http://localhost:${appPort}`;
+  return {
+    previewOrigin: tunnelUrl,
+    _managedPreviewOrigin: MANAGED_PREVIEW_ORIGIN,
+  };
+}
+
+/** Extract the stack's `preview.sameOriginSafe` flag from a parsed
+ *  `.codeyam/stack.json` object. Absent / non-object / non-boolean ⇒ `true`
+ *  (the same-origin default), mirroring `PreviewConfig::same_origin_safe()` on
+ *  the Rust side so the seeder and the editor agree on the truth table. Pure. */
+function previewSameOriginSafeFromStack(stackJson) {
+  const preview =
+    stackJson && typeof stackJson === "object" ? stackJson.preview : null;
+  const flag =
+    preview && typeof preview === "object" ? preview.sameOriginSafe : undefined;
+  return typeof flag === "boolean" ? flag : true;
+}
+
+// Matches an absolute cloudflared quick-tunnel origin
+// (`https://<sub>.trycloudflare.com`, optionally with a port/path/query). These
+// URLs ROTATE on every tunnel respawn, which is exactly why a frozen one rots.
+const TRYCLOUDFLARE_ORIGIN_RE =
+  /^https:\/\/[a-z0-9-]+\.trycloudflare\.com(?:[:/?#]|$)/i;
+
+/** Decide whether a VM's current `editor.local.json` carries a ROTTED managed
+ *  cloudflared previewOrigin that must be self-healed back to the same-origin
+ *  path. True iff ALL hold:
+ *    - the stack is same-origin-safe (a client-routed stack legitimately keeps a
+ *      dedicated origin — never heal it);
+ *    - the value is stamped `_managedPreviewOrigin: cloudflared-monitor` (WE
+ *      wrote it, not a user pin); and
+ *    - the `previewOrigin` is an absolute `*.trycloudflare.com` quick-tunnel URL
+ *      (the rotating kind that goes dead — a deterministic named-tunnel host or
+ *      the constant `/__codeyam_preview` path is left alone).
+ *  Idempotent by construction: a VM already on `/__codeyam_preview` (or any
+ *  non-trycloudflare origin) returns false, so re-running the heal is a no-op.
+ *  Pure — `localJson` is a parsed editor.local.json object. */
+function isRottedManagedPreviewOrigin(localJson, sameOriginSafe) {
+  if (!sameOriginSafe) return false;
+  if (!localJson || typeof localJson !== "object") return false;
+  if (localJson._managedPreviewOrigin !== MANAGED_PREVIEW_ORIGIN) return false;
+  return (
+    typeof localJson.previewOrigin === "string" &&
+    TRYCLOUDFLARE_ORIGIN_RE.test(localJson.previewOrigin)
+  );
+}
+
+/** 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() {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(CLOUDFLARED_URLS_FILE, "utf8"));
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+      ? parsed
+      : {};
+  } catch {
+    return {};
+  }
+}
+
+/** Resolve the editor-source config (repo/branch/variant) from cfg, applying
+ *  defaults. `editorRepo` defaults to CANONICAL_EDITOR_REPO so a non-self-host
+ *  client project still builds its editor image from the editor source, not the
+ *  client repo. Self-host back-compat: when the client repo IS the editor repo
+ *  and no explicit editorBranch was given, the client branch doubles as the
+ *  editor source branch — so `cloud:up --repo codeyam-editor --branch X` still
+ *  builds the editor at X, exactly as it did before the decoupling. */
+function resolveEditorConfig(cfg = {}) {
+  const editorRepo = cfg.editorRepo || CANONICAL_EDITOR_REPO;
+  let editorBranch = cfg.editorBranch;
+  if ((editorBranch == null || editorBranch === "") && sameRepo(cfg.repo, editorRepo)) {
+    editorBranch = cfg.branch;
+  }
+  const editorVariant = cfg.editorVariant || "dev";
+  return { editorRepo, editorBranch: editorBranch || undefined, editorVariant };
+}
+
+/** Throw on an unknown editor variant (a typo'd `--editor-variant` should fail,
+ *  not silently fall through to dev). */
+function validateEditorVariant(variant) {
+  if (!EDITOR_VARIANTS.includes(variant)) {
+    throw new Error(
+      `Unknown editor variant: ${variant}. Supported: ${EDITOR_VARIANTS.join(", ")}`,
+    );
+  }
+  return variant;
+}
+
+/** Assert a variant can be provisioned onto a cloud VM. Every known variant is
+ *  provisionable now — `dev` builds the editor image from source, while
+ *  `staging`/`production` run the published npm-package image (gcp-bootstrap
+ *  pulls/builds Dockerfile.npm keyed off the variant). So this collapses to the
+ *  unknown-variant guard: a typo'd `--editor-variant` fails loud rather than
+ *  silently launching the wrong (or no) image. */
+function assertVariantProvisionable(variant) {
+  return validateEditorVariant(variant);
+}
+
+/** Args for scripts/gcp-bootstrap.sh, which produces the codeyam-editor:local
+ *  image. For the `dev` variant that image is built from the EDITOR source
+ *  (--repo/--branch); for packaged variants (staging/production) it comes from
+ *  the published npm package, so the editor source repo/branch is irrelevant and
+ *  omitted — gcp-bootstrap pulls/builds Dockerfile.npm keyed off --editor-variant.
+ *  The CLIENT project repo/branch is unaffected: it flows through cloud:up's own
+ *  project bootstrap, not this function. */
+function editorImageBootstrapArgs(cfg) {
+  const { editorRepo, editorBranch, editorVariant } = resolveEditorConfig(cfg);
+  const args = ["--agent", cfg.agent, "--editor-variant", editorVariant];
+  // Stack assumption: only the `dev` variant builds the editor image from source,
+  // so only it needs the editor repo/branch plumbing gcp-bootstrap's source path
+  // consumes. Packaged variants install the binary from the published npm package.
+  if (editorVariant === "dev") {
+    args.push("--repo", editorRepo);
+    if (editorBranch) args.push("--branch", editorBranch);
+  }
+  return args;
+}
+
+/** Resolve the CLIENT project from cfg: either an existing repo to clone, or a
+ *  greenfield new folder to scaffold. `name` is the on-VM directory basename
+ *  (under ~/projects/) — derived from the repo for the clone case, or the
+ *  given folder name for greenfield. */
+/** --repo and --new-project are mutually exclusive. When one is explicitly
+ *  passed THIS run, drop the other from the (possibly cloud.json-merged) config
+ *  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;
+  if (flags.newProject) { delete cfg.repo; delete cfg.branch; }
+  return cfg;
+}
+
+function resolveProject(cfg = {}) {
+  if (cfg.newProject) {
+    return { greenfield: true, name: cfg.newProject, repo: null, branch: null };
+  }
+  return {
+    greenfield: false,
+    name: cfg.repo ? repoBasename(cfg.repo) : null,
+    repo: cfg.repo || null,
+    branch: cfg.branch || null,
+  };
+}
+
+/** Args for scripts/gcp-project-bootstrap.sh. For an existing repo: the repo URL
+ *  (+ optional --branch) to clone. For greenfield: --new-project <name>, so the
+ *  bootstrap creates an empty git-init'd folder and inits it instead of cloning. */
+function clientProjectBootstrapArgs(cfg) {
+  const p = resolveProject(cfg);
+  // The bootstrap now runs `npm run setup` by default when the project ships
+  // one; --skip-setup is the opt-out, threaded from the cloud:up flag. (A
+  // greenfield launch starts from an empty git-init'd folder with no setup
+  // script, so the flag is a harmless no-op there.)
+  const setupArgs = cfg.skipSetup ? ["--skip-setup"] : [];
+  if (p.greenfield) return ["--new-project", p.name, ...setupArgs];
+  const args = [cfg.repo];
+  if (cfg.branch) args.push("--branch", cfg.branch);
+  args.push(...setupArgs);
+  return args;
+}
+
+function cloudConfigPath(projectDir) {
+  return path.join(projectDir, ".codeyam", "cloud.json");
+}
+
+/** Returns the parsed config, or `null` when the file is absent. Throws
+ *  with the full path on malformed JSON so the user knows which file to
+ *  fix — silently returning `null` would mask corruption as "no config". */
+function loadCloudConfig(projectDir) {
+  const p = cloudConfigPath(projectDir);
+  if (!fs.existsSync(p)) return null;
+  let raw;
+  try {
+    raw = fs.readFileSync(p, "utf8");
+  } catch (e) {
+    throw new Error(`Failed to read ${p}: ${e.message}`);
+  }
+  try {
+    return JSON.parse(raw);
+  } catch (e) {
+    throw new Error(`Failed to parse ${p}: ${e.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");
+}
+
+/** 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. */
+function buildEditorLocalEnvPatch(localEnv, agent) {
+  const varName = agentEnvVarName(agent);
+  const value = localEnv[varName];
+  if (!value) return null;
+  return { env: { [varName]: value } };
+}
+
+/** Parse `docker compose ps --format json` (compose v2 — one JSON object per
+ *  line) and return the editor service's `State` string, or null when the
+ *  service is absent / output is unparseable. Two callers shared an identical
+ *  inline parser; this centralizes the shape so a compose-output change is
+ *  one update, not two. */
+function parseEditorComposeState(stdout) {
+  if (!stdout) return null;
+  const lines = String(stdout).trim().split("\n").filter(Boolean);
+  for (const line of lines) {
+    let svc;
+    try {
+      svc = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (svc && svc.Service === "editor") {
+      return svc.State || null;
+    }
+  }
+  return null;
+}
+
+/** Translate one of the wrapper's verbs into the exact `gcloud` argv. The
+ *  switch's job is to keep every per-verb command shape in one reviewable
+ *  place — tests assert the arrays without ever spawning a process. */
+function buildGcloudArgs(verb, cfg = {}, extras = {}) {
+  const { project, zone, instanceName } = cfg;
+  switch (verb) {
+    case "config-get-project":
+      return ["config", "get-value", "project"];
+    case "config-get-zone":
+      return ["config", "get-value", "compute/zone"];
+    case "instances-create":
+      // The VM keeps the default ephemeral external IP so apt / docker /
+      // NodeSource / npm can reach the public internet during bootstrap.
+      // Inbound is still IAP-SSH-only via the firewall rule above; the
+      // external IP is for egress, not exposure. `--no-address` was the
+      // earlier default but produced a VM that could not install Docker
+      // without a Cloud NAT + Cloud Router pair the wrapper does not set up.
+      return [
+        "compute", "instances", "create", instanceName,
+        "--project", project, "--zone", zone,
+        "--machine-type=e2-standard-4",
+        "--image-family=debian-12",
+        "--image-project=debian-cloud",
+        "--boot-disk-size=100GB",
+        "--boot-disk-type=pd-balanced",
+        `--tags=${INSTANCE_TAG}`,
+      ];
+    case "instances-start":
+      return ["compute", "instances", "start", instanceName, "--project", project, "--zone", zone];
+    case "instances-stop":
+      return ["compute", "instances", "stop", instanceName, "--project", project, "--zone", zone];
+    case "instances-delete":
+      return ["compute", "instances", "delete", instanceName, "--project", project, "--zone", zone, "--quiet"];
+    case "instances-describe":
+      return ["compute", "instances", "describe", instanceName, "--project", project, "--zone", zone, "--format=json"];
+    case "instances-list-tagged":
+      return [
+        "compute", "instances", "list",
+        "--project", project,
+        `--filter=tags.items:${INSTANCE_TAG}`,
+        "--format=value(name)",
+      ];
+    case "firewall-describe":
+      return ["compute", "firewall-rules", "describe", FIREWALL_RULE_NAME, "--project", project, "--format=json"];
+    case "firewall-create":
+      return [
+        "compute", "firewall-rules", "create", FIREWALL_RULE_NAME,
+        "--project", project,
+        "--direction=INGRESS",
+        "--action=ALLOW",
+        "--rules=tcp:22",
+        "--source-ranges=35.235.240.0/20",
+        `--target-tags=${INSTANCE_TAG}`,
+      ];
+    case "firewall-delete":
+      return ["compute", "firewall-rules", "delete", FIREWALL_RULE_NAME, "--project", project, "--quiet"];
+    case "ssh-probe":
+      return [
+        "compute", "ssh", instanceName,
+        "--project", project, "--zone", zone,
+        "--tunnel-through-iap",
+        "--command", extras.command,
+      ];
+    case "ssh-script":
+      // Stream a script body as base64 over --command so we don't fight
+      // shell-quoting through gcloud → ssh → remote bash. The script body
+      // is delivered as one argument; the wrapper feeds the base64 into
+      // `extras.command` and the caller sets `input` to the script body.
+      //
+      // Keepalive flags are defense-in-depth for the long-running bootstrap
+      // follow session: a quiet stretch during `cargo build` (no stdout for
+      // minutes) must not trip an idle disconnect. ServerAliveInterval pings
+      // the VM every 30s and ServerAliveCountMax tolerates 6 missed replies
+      // (~3 min) before giving up, while TCPKeepAlive keeps NAT mappings warm.
+      // The detached server-side runner (bootstrapLaunchCommand) makes a real
+      // drop non-fatal; keepalive just makes spurious drops rarer.
+      return [
+        "compute", "ssh", instanceName,
+        "--project", project, "--zone", zone,
+        "--tunnel-through-iap",
+        ...SSH_KEEPALIVE_FLAGS,
+        "--command", extras.command,
+      ];
+    case "ssh-tunnel": {
+      // Bind BOTH IPv4 and IPv6 loopback for each port. The IPv4 `-L` is
+      // load-bearing for everything that explicitly dials 127.0.0.1; the
+      // `[::1]` `-L` exists because cloudflared (`tunnel --url
+      // http://localhost:N`) resolves `localhost` to `[::1]` first and,
+      // with an IPv4-only forward, hits connect:connection-refused until
+      // the QUIC stream cancels and the tunnel proc exits (~80% of
+      // cloudflared deaths in the 2026-05-21 fleet session). Binding the
+      // IPv6 loopback too lets that first dial succeed.
+      //
+      // The preview forward uses the resolved app port (extras.appPort,
+      // default VITE_PORT) on BOTH ends — laptop:<appPort> → VM:<appPort> —
+      // so the whole single-user path uses one number for a Vite 5173, a
+      // Next.js 3000, anything. The editor `-L` (14199) is unconditional.
+      const appPort = extras.appPort != null ? extras.appPort : VITE_PORT;
+      return [
+        "compute", "ssh", instanceName,
+        "--project", project, "--zone", zone,
+        "--tunnel-through-iap",
+        "--",
+        "-L", `${EDITOR_PORT}:127.0.0.1:${EDITOR_PORT}`,
+        "-L", `[::1]:${EDITOR_PORT}:127.0.0.1:${EDITOR_PORT}`,
+        "-L", `${appPort}:127.0.0.1:${appPort}`,
+        "-L", `[::1]:${appPort}:127.0.0.1:${appPort}`,
+        "-N",
+      ];
+    }
+    default:
+      throw new Error(`Unknown gcloud verb: ${verb}`);
+  }
+}
+
+// =============================================================================
+// Side-effecting helpers — exercised end-to-end by `npm run cloud:up` in
+// real use. Unit tests pin their exports so a refactor cannot drop them.
+// =============================================================================
+
+function runGcloud(args, opts = {}) {
+  return spawnSync("gcloud", args, {
+    stdio: opts.stdio || "inherit",
+    input: opts.input,
+    encoding: opts.encoding || "utf8",
+  });
+}
+
+function ensureGcloud() {
+  const result = spawnSync("gcloud", ["version"], { stdio: "ignore" });
+  if (result.error || result.status !== 0) {
+    console.error(
+      "gcloud is not on PATH. Install: https://cloud.google.com/sdk/docs/install",
+    );
+    process.exit(1);
+  }
+}
+
+function gcloudGetValue(verb) {
+  const result = runGcloud(buildGcloudArgs(verb), { stdio: ["ignore", "pipe", "ignore"] });
+  if (result.error || result.status !== 0) return null;
+  const val = String(result.stdout || "").trim();
+  if (!val || val === "(unset)") return null;
+  return val;
+}
+
+/** Run `gcloud compute instances describe ... --format=json` and return the
+ *  parsed `.status` field (e.g. "RUNNING", "TERMINATED", "PROVISIONING"), or
+ *  null when the instance is absent or describe returned unparseable output.
+ *  Centralizes the describe-and-parse pattern shared by ensureInstance (used
+ *  twice — initial probe + poll), cmdTunnel, and cmdStatus. */
+function fetchInstanceState(cfg) {
+  const result = runGcloud(buildGcloudArgs("instances-describe", cfg), {
+    stdio: ["ignore", "pipe", "ignore"],
+  });
+  if (result.status !== 0) return null;
+  try {
+    const parsed = JSON.parse(result.stdout);
+    return parsed && typeof parsed.status === "string" ? parsed.status : null;
+  } catch {
+    return null;
+  }
+}
+
+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; };
+  if (existing) {
+    const merged = reconcileProjectExclusivity({ ...existing, ...flags }, flags);
+    const toSave = persist(merged);
+    if (JSON.stringify(toSave) !== JSON.stringify(existing)) {
+      saveCloudConfig(projectDir, toSave);
+    }
+    return merged;
+  }
+
+  const cfg = reconcileProjectExclusivity({ ...flags }, flags);
+  cfg.project = cfg.project || gcloudGetValue("config-get-project");
+  cfg.zone = cfg.zone || gcloudGetValue("config-get-zone");
+  cfg.agent = cfg.agent || "claude";
+  agentEnvVarName(cfg.agent);
+
+  if (!cfg.repo && !cfg.newProject) {
+    throw new Error(
+      "--repo <url> (clone an existing project) or --new-project <name> (greenfield) " +
+        "is required on first run. Subsequent runs read .codeyam/cloud.json.",
+    );
+  }
+  if (!cfg.project) {
+    throw new Error(
+      "--project not provided and `gcloud config get-value project` returned no default.\n" +
+        "Run `gcloud config set project <id>` or pass --project <id>.",
+    );
+  }
+  if (!cfg.zone) {
+    throw new Error(
+      "--zone not provided and `gcloud config get-value compute/zone` returned no default.\n" +
+        "Run `gcloud config set compute/zone <zone>` or pass --zone <zone>.",
+    );
+  }
+
+  cfg.instanceName = cfg.instanceName || defaultInstanceNameFor(cfg.repo || cfg.newProject);
+  saveCloudConfig(projectDir, persist(cfg));
+  return cfg;
+}
+
+async function ensureFirewallRule(cfg) {
+  console.error(`Checking firewall rule ${FIREWALL_RULE_NAME}...`);
+  const describe = runGcloud(buildGcloudArgs("firewall-describe", cfg), {
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  if (describe.status === 0) {
+    console.error(`  ✓ ${FIREWALL_RULE_NAME} already exists`);
+    return;
+  }
+  console.error(`  creating ${FIREWALL_RULE_NAME}...`);
+  const create = runGcloud(buildGcloudArgs("firewall-create", cfg));
+  if (create.status !== 0) {
+    throw new Error(`Failed to create firewall rule ${FIREWALL_RULE_NAME}`);
+  }
+}
+
+async function ensureInstance(cfg) {
+  console.error(`Checking instance ${cfg.instanceName}...`);
+  const initialState = fetchInstanceState(cfg);
+  if (initialState === "RUNNING") {
+    console.error(`  ✓ ${cfg.instanceName} is RUNNING`);
+    return;
+  }
+  if (initialState === "TERMINATED") {
+    console.error(`  ${cfg.instanceName} is TERMINATED — starting...`);
+    const start = runGcloud(buildGcloudArgs("instances-start", cfg));
+    if (start.status !== 0) {
+      throw new Error(`Failed to start instance ${cfg.instanceName}`);
+    }
+  } else if (initialState === null) {
+    console.error(`  ${cfg.instanceName} not found — creating...`);
+    const create = runGcloud(buildGcloudArgs("instances-create", cfg));
+    if (create.status !== 0) {
+      throw new Error(`Failed to create instance ${cfg.instanceName}`);
+    }
+  } else {
+    console.error(`  ${cfg.instanceName} is ${initialState}; waiting...`);
+  }
+
+  for (let i = 0; i < 60; i++) {
+    if (fetchInstanceState(cfg) === "RUNNING") {
+      console.error(`  ✓ ${cfg.instanceName} is RUNNING`);
+      await waitForIapReady(cfg);
+      return;
+    }
+    await new Promise((r) => setTimeout(r, 2000));
+  }
+  throw new Error(`Instance ${cfg.instanceName} did not reach RUNNING within 2 minutes`);
+}
+
+/** GCE reports the instance as RUNNING the moment the boot disk is attached,
+ *  but the IAP control plane has its own catalog that updates a few seconds
+ *  later. The first `gcloud compute ssh --tunnel-through-iap` after a fresh
+ *  create races that catalog and fails with `[4047: 'Failed to lookup
+ *  instance']`. Probe an IAP-tunneled SSH that just runs `true` until it
+ *  succeeds — cheap on the warm path (one ~1s round-trip) and bounded so a
+ *  genuinely unreachable VM fails loud rather than silently. */
+async function waitForIapReady(cfg) {
+  console.error(`  waiting for IAP to register ${cfg.instanceName}...`);
+  // 180s, not 60s: on a fresh instance the IAP catalog + SSH-key (osLogin)
+  // propagation can take well over a minute under fleet load, and each failed
+  // probe burns ~25-30s before gcloud gives up — so a 60s budget fit only ~2
+  // probes and aborted cloud:up before the VM was ever reachable, leaving a
+  // RUNNING-but-unbootstrapped instance.
+  const deadline = Date.now() + 180_000;
+  let attempts = 0;
+  let lastErr = "";
+  while (Date.now() < deadline) {
+    attempts++;
+    const probe = runGcloud(
+      buildGcloudArgs("ssh-probe", cfg, { command: "true" }),
+      { stdio: ["ignore", "pipe", "pipe"] },
+    );
+    if (probe.status === 0) {
+      console.error(`  ✓ IAP ready (${attempts} ${attempts === 1 ? "probe" : "probes"})`);
+      return;
+    }
+    lastErr = String(probe.stderr || "").trim().split("\n").slice(-1)[0] || "";
+    // Exponential-ish backoff: 2s, 3s, 5s, 8s, then cap at 8s.
+    const delay = Math.min(2000 * Math.pow(1.5, attempts - 1), 8000);
+    await new Promise((r) => setTimeout(r, delay));
+  }
+  throw new Error(
+    `IAP did not become ready for ${cfg.instanceName} within 180s ` +
+      `(${attempts} probes; last error: ${lastErr || "unknown"})`,
+  );
+}
+
+/** Read `process.env[FORWARD_ENV_KEYS_ENV]` (comma-separated key list set by
+ *  the fleet dashboard) and return the subset of `process.env` that should
+ *  ride along into the VM's project-bootstrap shell. Whitelisted to the
+ *  named keys: a fork of the dashboard's launch-form env, never the whole
+ *  laptop env (which would leak PATH / NODE_OPTIONS / unrelated secrets).
+ *  Empty / unset → {} so the standalone `cloud:up` path is unchanged. */
+function resolveSetupForwardEnv(env = process.env) {
+  const list = env[FORWARD_ENV_KEYS_ENV];
+  if (!list) return {};
+  const out = {};
+  for (const raw of String(list).split(",")) {
+    const k = raw.trim();
+    if (!k) continue;
+    const v = env[k];
+    if (v == null || v === "") continue;
+    out[k] = v;
+  }
+  return out;
+}
+
+// --ssh-flag values gcloud forwards verbatim to the underlying `ssh`. Shaped as
+// `-o Key=Value` so they survive the gcloud → ssh hop unchanged. Used by the
+// ssh-script verb (the long bootstrap follow session) — short ssh-probe calls
+// don't need them. See the ssh-script case in buildGcloudArgs for the rationale.
+const SSH_KEEPALIVE_FLAGS = [
+  "--ssh-flag=-o ServerAliveInterval=30",
+  "--ssh-flag=-o ServerAliveCountMax=6",
+  "--ssh-flag=-o TCPKeepAlive=yes",
+];
+
+// Canonical VM-side paths for the detached bootstrap. The build runs from
+// BOOTSTRAP_RUNNER_PATH (a tiny wrapper that execs the real script), streams to
+// BOOTSTRAP_LOG_PATH, and writes its exit status into BOOTSTRAP_DONE_PATH on
+// completion. Completion + success are derived from these files (plus the
+// docker image), NOT from the SSH exit code — so a dropped follow-session over
+// a healthy VM is no longer misreported as "failed on the VM".
+const BOOTSTRAP_SCRIPT_PATH = "$HOME/.codeyam-bootstrap.sh";
+const BOOTSTRAP_RUNNER_PATH = "$HOME/.codeyam-bootstrap-run.sh";
+const BOOTSTRAP_LOG_PATH = "$HOME/.codeyam-bootstrap.log";
+const BOOTSTRAP_DONE_PATH = "$HOME/.codeyam-bootstrap.done";
+const BOOTSTRAP_PID_PATH = "$HOME/.codeyam-bootstrap.pid";
+const BOOTSTRAP_LAUNCHED_MARKER = "CODEYAM_BOOTSTRAP_LAUNCHED";
+const BOOTSTRAP_STATUS_MARKER = "CYBOOT";
+// improve40 — VM-side path of the PROJECT-bootstrap terminal completion marker.
+// gcp-project-bootstrap.sh writes this as its very last step (only reached after
+// `set -euo pipefail` carried every provisioning step to success), and
+// ensureProjectBootstrapped's done-probe gates on it so a half-finished
+// bootstrap is correctly re-run instead of false-skipped (the VM-7 incident).
+// Lives outside the project's git tree (a $HOME dotfile, keyed by repo name) so
+// it never churns the repo. Pure so the bash writer and the JS probe derive the
+// EXACT same path; tested without a live VM.
+function projectBootstrapDoneMarker(repoName) {
+  return `$HOME/.codeyam-project-bootstrap-${repoName}.done`;
+}
+// improve40 — the VM-side shell `test` chain ensureProjectBootstrapped runs to
+// decide "is this project already bootstrapped?". Gates on the terminal `.done`
+// marker FIRST (the VM-7 false-skip fix — both structural artifacts can exist on
+// a half-done bootstrap), then keeps the `.codeyam/` + docker-compose.cloud.yml
+// checks as belt-and-suspenders for a legacy VM whose marker predates this change.
+// Pure (just the command string) so the gating is unit-testable without gcloud.
+function projectBootstrapDoneProbeCommand(repoName) {
+  return (
+    `test -f ${projectBootstrapDoneMarker(repoName)} ` +
+    `&& test -d ~/projects/${repoName}/.codeyam ` +
+    `&& test -f ~/projects/${repoName}/docker-compose.cloud.yml`
+  );
+}
+// One follow session caps at 30 min (comfortably over the ~14-min source
+// build); the overall wait caps at 40 min across re-attaches before we bail
+// loudly with the VM-side log location.
+const BOOTSTRAP_FOLLOW_SECS = 1800;
+const BOOTSTRAP_DEADLINE_MS = 40 * 60 * 1000;
+
+// Quote a shell value the same way scriptArgs are quoted: single-quote it and
+// escape any embedded apostrophe. Shared by the env-prefix and arg encoders so
+// a token with an exotic character can't break out of its quoting.
+function shQuote(v) {
+  return `'${String(v).replace(/'/g, "'\\''")}'`;
+}
+
+// Encode env vars as a shell-assignment PREFIX (`KEY='value' …`). Assignment
+// prefixes set the variable in the launched command's environment only — never
+// in its argv — so tokens stay out of `ps` on the VM. Empty / nullish values
+// are dropped so the no-token path is unchanged.
+function envAssignmentPrefix(envVars) {
+  const s = Object.entries(envVars)
+    .filter(([, v]) => v !== undefined && v !== null && v !== "")
+    .map(([k, v]) => `${k}=${shQuote(v)}`)
+    .join(" ");
+  return s ? `${s} ` : "";
+}
+
+// The tiny VM-side wrapper the detached launch execs. It runs the real
+// bootstrap, redirects all output to the log, and records the exit status in
+// the sentinel — the single source of truth for "did the build finish, and
+// did it succeed?" once the SSH follow-session is gone. Contains NO secrets
+// (tokens arrive via the launch env prefix, never written to disk).
+function bootstrapRunnerScript() {
+  return [
+    "#!/usr/bin/env bash",
+    "# Detached bootstrap runner (written by npm/cloud.js ensureBootstrapped).",
+    "# Survives SSH disconnect: the laptop only *follows* the log below; this",
+    "# process keeps running under its own session if the follow drops.",
+    "# Records its own PID so the status probe can check liveness via `kill -0`",
+    "# (a `pgrep` on the script path would also match the probe command itself).",
+    `echo "$$" > "$HOME/.codeyam-bootstrap.pid"`,
+    `bash "$HOME/.codeyam-bootstrap.sh" "$@" > "$HOME/.codeyam-bootstrap.log" 2>&1`,
+    "status=$?",
+    `echo "$status" > "$HOME/.codeyam-bootstrap.done"`,
+    `rm -f "$HOME/.codeyam-bootstrap.pid"`,
+    "",
+  ].join("\n");
+}
+
+// Build the remote command that (1) materializes the bootstrap script + runner
+// on the VM, (2) clears any stale sentinel, (3) launches the runner DETACHED
+// (`nohup setsid`, new session, stdio to /dev/null) so it outlives the SSH
+// session, and (4) prints a launched marker. The detach is the durable fix:
+// the build no longer dies when the laptop's SSH pipe breaks.
+function bootstrapLaunchCommand(scriptBody, scriptArgs = [], envVars = {}) {
+  const scriptB64 = Buffer.from(scriptBody, "utf8").toString("base64");
+  const runnerB64 = Buffer.from(bootstrapRunnerScript(), "utf8").toString("base64");
+  const argsString = scriptArgs.map(shQuote).join(" ");
+  const envPrefix = envAssignmentPrefix(envVars);
+  // Writes run synchronously (fast, before any backgrounding) so a decode error
+  // aborts before launch; then the runner is detached. The env prefix is on the
+  // setsid command so the tokens are inherited through nohup→setsid→bash but
+  // never appear in any argv. `& echo MARKER` (no `;` before echo) keeps the
+  // launch in the background while still confirming it fired.
+  const writes = [
+    `echo '${scriptB64}' | base64 -d > ${BOOTSTRAP_SCRIPT_PATH}`,
+    `echo '${runnerB64}' | base64 -d > ${BOOTSTRAP_RUNNER_PATH}`,
+    `rm -f ${BOOTSTRAP_DONE_PATH}`,
+  ].join(" && ");
+  const launch =
+    `${envPrefix}nohup setsid bash ${BOOTSTRAP_RUNNER_PATH} ${argsString}`.trimEnd() +
+    ` </dev/null >/dev/null 2>&1 &`;
+  return `${writes}; ${launch} echo ${BOOTSTRAP_LAUNCHED_MARKER}`;
+}
+
+// Build the remote command that FOLLOWS the detached build: tail the log live
+// for the operator, polling for the sentinel, and exit when the build finishes
+// OR a per-session deadline elapses. If the SSH session drops mid-follow this
+// command dies but the detached build keeps going — the caller then re-attaches.
+function bootstrapFollowCommand(deadlineSecs = BOOTSTRAP_FOLLOW_SECS) {
+  return [
+    `touch ${BOOTSTRAP_LOG_PATH}`,
+    `tail -n +1 -F ${BOOTSTRAP_LOG_PATH} 2>/dev/null & TP=$!`,
+    `waited=0`,
+    `while [ ! -f ${BOOTSTRAP_DONE_PATH} ]; do ` +
+      `sleep 3; waited=$((waited+3)); ` +
+      `if [ "$waited" -ge ${deadlineSecs} ]; then kill "$TP" 2>/dev/null; exit 0; fi; ` +
+      `done`,
+    `sleep 1`,
+    `kill "$TP" 2>/dev/null`,
+  ].join("; ");
+}
+
+// Build the remote command that reports terminal VM state in one parseable
+// line: whether the image exists, the sentinel's exit code (or `none`), and
+// whether a bootstrap process is still alive. Cheap — runs over ssh-probe.
+function bootstrapStatusCommand() {
+  // Liveness via the runner's PID file + `kill -0`, NOT pgrep: the status
+  // command's own argv contains the bootstrap path, so a `pgrep -f` on it would
+  // match this very probe and always report running. A stale PID file from a
+  // killed runner reads as not-running because `kill -0` fails.
+  return [
+    `img=absent; docker image inspect codeyam-editor:local >/dev/null 2>&1 && img=present`,
+    `done=none; [ -f ${BOOTSTRAP_DONE_PATH} ] && done=$(cat ${BOOTSTRAP_DONE_PATH} 2>/dev/null)`,
+    `run=no; if [ -f ${BOOTSTRAP_PID_PATH} ]; then p=$(cat ${BOOTSTRAP_PID_PATH} 2>/dev/null); ` +
+      `{ [ -n "$p" ] && kill -0 "$p" 2>/dev/null; } && run=yes; fi`,
+    `echo "${BOOTSTRAP_STATUS_MARKER} img=$img done=$done running=$run"`,
+  ].join("; ");
+}
+
+// Parse the single status line emitted by bootstrapStatusCommand. Returns
+// `{ img, done, running }` or null when no status line is present (e.g. the
+// probe ssh itself failed and produced no stdout).
+function parseBootstrapStatus(stdout) {
+  const m = String(stdout || "").match(
+    new RegExp(`${BOOTSTRAP_STATUS_MARKER} img=(\\S+) done=(\\S+) running=(\\S+)`),
+  );
+  if (!m) return null;
+  return { img: m[1], done: m[2], running: m[3] };
+}
+
+// Decide the bootstrap outcome from VM-side state alone — never the SSH exit
+// code. The image is the real artifact, so its presence is success regardless
+// of how the follow session ended. A live process means "re-attach". A sentinel
+// without an image means the build ran and failed. Nothing at all means it was
+// never started (or the probe couldn't see it).
+function decideBootstrapOutcome(status) {
+  if (!status) return "absent";
+  const { img, done, running } = status;
+  if (img === "present") return "success";
+  if (running === "yes") return "running";
+  if (done && done !== "none") return "failed";
+  return "absent";
+}
+
+function sshScriptCommand(scriptBody, scriptArgs = [], envVars = {}) {
+  const b64 = Buffer.from(scriptBody, "utf8").toString("base64");
+  // Args + env share the quoting/encoding helpers with bootstrapLaunchCommand:
+  // single-quoted args (shQuote) and a `KEY='value'` assignment prefix
+  // (envAssignmentPrefix) that sets the vars for the `bash -s` process only —
+  // no persistence in the VM's shell history, no argv exposure of tokens.
+  const argsString = scriptArgs.map(shQuote).join(" ");
+  const envPrefix = envAssignmentPrefix(envVars);
+  return `echo '${b64}' | base64 -d | ${envPrefix}bash -s -- ${argsString}`.trim();
+}
+
+async function ensureBootstrapped(cfg) {
+  console.error("Checking VM bootstrap state...");
+  const probe = runGcloud(
+    buildGcloudArgs("ssh-probe", cfg, {
+      command: "command -v docker >/dev/null && docker image inspect codeyam-editor:local >/dev/null 2>&1",
+    }),
+    { stdio: ["ignore", "pipe", "pipe"] },
+  );
+  if (probe.status === 0) {
+    console.error("  ✓ VM already bootstrapped (docker + codeyam-editor:local present)");
+    return;
+  }
+  console.error("  streaming scripts/gcp-bootstrap.sh to VM (this may take ~10 minutes)...");
+  const scriptPath = path.join(rootDir, "scripts", "gcp-bootstrap.sh");
+  const scriptBody = fs.readFileSync(scriptPath, "utf8");
+  // GITHUB_TOKEN is passed through to the bootstrap script so it can clone
+  // a private editor repo (the bootstrap clones $REPO_URL to build the
+  // codeyam-editor:local image). Without this the git clone hits the
+  // "could not read Username for 'https://github.com'" wall whenever the
+  // repo isn't public — codeyam-editor itself today.
+  //
+  // Build the editor image from the EDITOR source (cfg.editorRepo/editorBranch),
+  // decoupled from the client project (cfg.repo/branch) which gets cloned into
+  // /workspace by ensureProjectBootstrapped. --branch matters when testing
+  // wrapper / Dockerfile patches from a feature branch; without it the image
+  // build uses the editor repo's default branch.
+  const bootstrapArgs = editorImageBootstrapArgs(cfg);
+  // Token threading into the bootstrap env (assignment prefix, never argv):
+  //   CODEYAM_GHCR_TOKEN  — read:packages, for `docker login` + the PRIVATE
+  //     prebuilt base/binary PULLS. Without it every pull 403s and the
+  //     bootstrap slow-builds (~14 min) from source.
+  //   CODEYAM_GHCR_PUSH_TOKEN — write:packages, used ONLY by the post-compile
+  //     publish step's push. Distinct from the read token because a push needs
+  //     a strictly broader scope; reusing the read token guarantees a 403.
+  //     Absent → the bootstrap skips the publish cleanly (no doomed push).
+  //   CODEYAM_GHCR_USER / CODEYAM_GHCR_PUSH_USER — optional login-username
+  //     overrides. Empty values are dropped, so the no-registry path is
+  //     unchanged.
+  const bootstrapEnv = {
+    GITHUB_TOKEN: resolveGithubToken(),
+    CODEYAM_GHCR_TOKEN: resolveGhcrToken(),
+    CODEYAM_GHCR_USER: process.env.CODEYAM_GHCR_USER || "",
+    CODEYAM_GHCR_PUSH_TOKEN: resolveGhcrPushToken(),
+    CODEYAM_GHCR_PUSH_USER: process.env.CODEYAM_GHCR_PUSH_USER || "",
+  };
+
+  // Idempotent re-attach: a prior cloud:up whose follow-session dropped may
+  // have left a detached build still running (or already finished). Converge
+  // on it instead of starting over.
+  const initial = probeBootstrapOutcome(cfg);
+  if (initial === "success") {
+    console.error("  ✓ a previous detached bootstrap already completed");
+    return;
+  }
+  if (initial === "running") {
+    console.error("  ↺ a detached bootstrap is already in progress — re-attaching to its log...");
+  } else {
+    // "absent" (never started) OR "failed" (a prior run died) → (re)launch a
+    // 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"] },
+    );
+    if (launched.status !== 0) {
+      throw new Error("failed to launch the detached bootstrap on the VM");
+    }
+  }
+
+  // Follow the live log, re-attaching across any follow-session drops, until
+  // the VM reports a terminal state or the overall deadline elapses. Success
+  // and failure are read from VM state (image + sentinel), never the SSH exit
+  // code — so "my laptop's SSH dropped" no longer masquerades as a build error.
+  const deadline = Date.now() + BOOTSTRAP_DEADLINE_MS;
+  for (;;) {
+    runGcloud(
+      buildGcloudArgs("ssh-script", cfg, { command: bootstrapFollowCommand() }),
+      { stdio: "inherit" },
+    );
+    const outcome = probeBootstrapOutcome(cfg);
+    if (outcome === "success") {
+      console.error("  ✓ VM bootstrap complete");
+      return;
+    }
+    if (outcome === "failed") {
+      const tail = bootstrapLogTail(cfg);
+      throw new Error(
+        "scripts/gcp-bootstrap.sh failed on the VM. " +
+          `Last lines of ~/.codeyam-bootstrap.log:\n${tail}`,
+      );
+    }
+    if (Date.now() >= deadline) {
+      throw new Error(
+        "Timed out waiting for the VM bootstrap. It may still be running — " +
+          "re-run cloud:up to re-attach, or inspect ~/.codeyam-bootstrap.log on the VM.",
+      );
+    }
+    // outcome === "running": the follow session ended but the build is alive.
+    console.error("  ↺ follow session ended but the build is still running — re-attaching...");
+  }
+}
+
+// Probe the VM for the detached bootstrap's terminal state and reduce it to a
+// single outcome string ("success" | "failed" | "running" | "absent"). Used
+// both for the idempotent re-attach decision and after each follow session.
+function probeBootstrapOutcome(cfg) {
+  const r = runGcloud(
+    buildGcloudArgs("ssh-probe", cfg, { command: bootstrapStatusCommand() }),
+    { stdio: ["ignore", "pipe", "pipe"] },
+  );
+  return decideBootstrapOutcome(parseBootstrapStatus(r.stdout));
+}
+
+// Fetch the tail of the VM-side bootstrap log for an actionable failure
+// message — the operator sees WHY the build failed, not a bare exit code.
+function bootstrapLogTail(cfg, lines = 40) {
+  const r = runGcloud(
+    buildGcloudArgs("ssh-probe", cfg, {
+      command: `tail -n ${lines} ${BOOTSTRAP_LOG_PATH} 2>/dev/null`,
+    }),
+    { stdio: ["ignore", "pipe", "pipe"] },
+  );
+  return String(r.stdout || "").trim() || "(log unavailable)";
+}
+
+async function ensureProjectBootstrapped(cfg) {
+  const repoName = resolveProject(cfg).name;
+  console.error(`Checking project bootstrap state for ${repoName}...`);
+  // Gate on the TERMINAL completion marker the script writes as its very last
+  // step (scripts/gcp-project-bootstrap.sh → ~/.codeyam-project-bootstrap-<repo>.done),
+  // not on intermediate structural artifacts. Earlier this probed only `.codeyam/`
+  // + `docker-compose.cloud.yml` — but BOTH can exist while the bootstrap is
+  // still incomplete (init scaffolds `.codeyam/` and the compose render happens
+  // mid-script, before the creds/claude-dir setup and `npm install`/`setup`
+  // finish). The improve40 VM-7 incident hit exactly this: a recovery re-run saw
+  // the two markers, declared "already bootstrapped", and SKIPPED the unfinished
+  // work. The `.done` marker is written only after `set -euo pipefail` has
+  // carried every step to success, so an interrupted bootstrap lacks it and is
+  // correctly re-run (the re-run is idempotent — skip-on-exists per step). The
+  // two structural checks stay as belt-and-suspenders for a legacy VM whose
+  // marker predates this change but is otherwise wired.
+  const probe = runGcloud(
+    buildGcloudArgs("ssh-probe", cfg, {
+      command: projectBootstrapDoneProbeCommand(repoName),
+    }),
+    { stdio: ["ignore", "pipe", "pipe"] },
+  );
+  if (probe.status === 0) {
+    console.error(`  ✓ ${repoName} already bootstrapped on VM`);
+    return;
+  }
+  console.error(`  streaming scripts/gcp-project-bootstrap.sh to VM for ${cfg.repo}...`);
+  const scriptPath = path.join(rootDir, "scripts", "gcp-project-bootstrap.sh");
+  const scriptBody = fs.readFileSync(scriptPath, "utf8");
+  const scriptArgs = clientProjectBootstrapArgs(cfg);
+  // Forward the laptop's git author identity so the rendered compose file
+  // carries CY_GIT_USER_{NAME,EMAIL} → the entrypoint writes them to
+  // `git config --global` → plan_claim_refs::create_claim's commit-tree call
+  // succeeds. Empty strings are fine (laptop has no identity, e.g. a CI
+  // runner); the entrypoint warns and proceeds.
+  const laptopGit = resolveLaptopGitIdentity();
+  // Forward the operator's launch-form env keys (DATABASE_URL, etc.) into the
+  // bootstrap shell so the bootstrap-time `npm run setup` sees them on the
+  // first try — without this, Prisma `db:push`/`db:seed` fail for lack of
+  // env and the bootstrap's fail-soft branch leaves the app schema-less until
+  // the post-add `reapplyVmEnv` re-fires setup. See
+  // `improve37-launch-form-env-injected-into-cloud-up-bootstrap-not-just-applied-after`.
+  // Whitelisted by the dashboard via CY_FORWARD_ENV_KEYS — empty on the
+  // standalone `cloud:up` path, so that flow is unchanged.
+  const forwardEnv = resolveSetupForwardEnv();
+  const command = sshScriptCommand(scriptBody, scriptArgs, {
+    GITHUB_TOKEN: resolveGithubToken(),
+    CY_GIT_USER_NAME: laptopGit.name,
+    CY_GIT_USER_EMAIL: laptopGit.email,
+    ...forwardEnv,
+  });
+  const result = runGcloud(
+    buildGcloudArgs("ssh-script", cfg, { command }),
+    { stdio: "inherit" },
+  );
+  if (result.status !== 0) {
+    throw new Error("scripts/gcp-project-bootstrap.sh failed on the VM");
+  }
+}
+
+async function ensureEditorContainerUp(cfg) {
+  const repoName = resolveProject(cfg).name;
+  // -f docker-compose.cloud.yml everywhere: the editor repo's own
+  // docker-compose.yml does `build: .` from source and would shadow the
+  // cloud variant when self-hosting (see gcp-project-bootstrap.sh).
+  const composeCmd = `docker compose -f docker-compose.cloud.yml`;
+  console.error("Checking editor container state...");
+  const probe = runGcloud(
+    buildGcloudArgs("ssh-probe", cfg, {
+      command: `cd ~/projects/${repoName} && ${composeCmd} ps --format json 2>/dev/null || true`,
+    }),
+    { stdio: ["ignore", "pipe", "ignore"] },
+  );
+  if (probe.status === 0 && parseEditorComposeState(probe.stdout) === "running") {
+    console.error("  ✓ editor container is already running");
+    return;
+  }
+  console.error("  starting editor container (docker compose up -d)...");
+  const up = runGcloud(
+    buildGcloudArgs("ssh-probe", cfg, {
+      command: `cd ~/projects/${repoName} && ${composeCmd} up -d`,
+    }),
+    { stdio: "inherit" },
+  );
+  if (up.status !== 0) {
+    throw new Error("docker compose up -d failed on the VM");
+  }
+}
+
+/** Read the laptop's git author identity (`user.name`, `user.email`) so
+ *  cloud:up can forward it to the VM's container entrypoint, which writes
+ *  it to `git config --global`. Without identity in the container,
+ *  plan_claim_refs::create_claim's `git commit-tree` fails with "Author
+ *  identity unknown" and plan-claim refs are silently never created — the
+ *  In-Flight panel goes blind to that VM's work. Returns `{ name, email }`
+ *  with empty strings for whichever field is unset locally; the entrypoint
+ *  fails-soft on either-empty, so a CI runner without git config simply
+ *  warns and boots. The two `git config` calls are cheap (single fs read)
+ *  and not memoized so a user can `git config --global user.email …`
+ *  between operations and have it picked up on the next cloud:up. */
+function resolveLaptopGitIdentity(spawnImpl = spawnSync) {
+  const read = (key) => {
+    const r = spawnImpl("git", ["config", "--get", key], { encoding: "utf8" });
+    if (r.status !== 0) return "";
+    return String(r.stdout || "").trim();
+  };
+  return { name: read("user.name"), email: read("user.email") };
+}
+
+/** Look up a GitHub token from local environment, falling back to `gh auth
+ *  token`. Returns empty string if neither is available — callers should
+ *  treat empty as "no auth" and either skip or print a hint. Memoizing
+ *  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;
+  const ghOut = spawnSync("gh", ["auth", "token"], { encoding: "utf8" });
+  if (ghOut.status === 0) {
+    return ghOut.stdout.trim();
+  }
+  return "";
+}
+
+/** A PULL-ONLY (`read:packages`) token the VM bootstrap uses to `docker login
+ *  ghcr.io` and pull the PRIVATE prebuilt cloud-smoke base + branch-binary
+ *  packages. Prefer an explicit CODEYAM_GHCR_TOKEN (the operator's scoped
+ *  fleet secret); fall back to the same GitHub token already used for the
+ *  git clone, which carries read:packages for a classic PAT / `gh auth token`
+ *  in the common fleet setup. Empty string when neither is available — the
+ *  bootstrap then skips login and the private pulls fall back to a source
+ *  build (today's behavior, never worse). Threaded into gcp-bootstrap.sh via
+ *  the env channel in ensureBootstrapped; never passed as an argv.
+ *
+ *  This token is NOT sufficient for the post-compile PUBLISH — a `docker push`
+ *  needs write:packages. Reusing it for the push is exactly the 403 that kept
+ *  publish-on-compile from ever priming the fast path. Use resolveGhcrPushToken
+ *  for that. */
+function resolveGhcrToken() {
+  return process.env.CODEYAM_GHCR_TOKEN || resolveGithubToken();
+}
+
+/** A WRITE-scoped (`write:packages`) token used ONLY for the post-compile
+ *  publish — `publish_compiled_binary`'s `docker push` of the just-built
+ *  binary. Deliberately has NO fallback to the read/clone token: a `docker
+ *  push` with a read-only token 403s, so silently reusing the read token would
+ *  reintroduce the exact failure that kept the fast path from priming. Returns
+ *  the empty string when CODEYAM_GHCR_PUSH_TOKEN is unset — the bootstrap then
+ *  SKIPS the publish loudly (no doomed push, no 403 spam) and the next VM
+ *  simply recompiles that commit. Threaded into gcp-bootstrap.sh via the env
+ *  channel in ensureBootstrapped; never passed as an argv. */
+function resolveGhcrPushToken() {
+  return process.env.CODEYAM_GHCR_PUSH_TOKEN || "";
+}
+
+/** 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
+ *  initial repo (the wrapper does that step out-of-band with a one-shot
+ *  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();
+  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;
+  }
+  console.error("Writing GitHub token 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.
+  const b64 = Buffer.from(`${credLine}\n`).toString("base64");
+  const remoteCmd =
+    `f=$HOME/.codeyam-cloud-git-credentials && ` +
+    `echo ${b64} | base64 -d > $f && chmod 600 $f && echo OK`;
+  const result = runGcloud(
+    buildGcloudArgs("ssh-probe", cfg, { command: remoteCmd }),
+    { stdio: ["ignore", "pipe", "inherit"] },
+  );
+  if (result.status !== 0) {
+    throw new Error("Failed to write ~/.codeyam-cloud-git-credentials on the VM");
+  }
+}
+
+/** Best-effort read of the VM's resolved app dev-server port so cloud:up's
+ *  laptop `-L` forward, readiness probe, and previewOrigin seed all target the
+ *  port the app actually serves on instead of a hardcoded 5173. Cats the VM's
+ *  editor.json and editor.local.json in one SSH round-trip and resolves via
+ *  `resolveConfiguredAppPort`. Any failure (SSH error, missing/corrupt JSON)
+ *  falls back to `VITE_PORT` — the same default `resolved_port()` lands on for
+ *  a portless config, so a 5173/greenfield project sees no behavior change. */
+async function readVmAppPort(cfg) {
+  const repoName = resolveProject(cfg).name;
+  const base = `~/projects/${repoName}/.codeyam`;
+  const read = runGcloud(
+    buildGcloudArgs("ssh-probe", cfg, {
+      command:
+        `cat ${base}/editor.json 2>/dev/null || echo '{}'; ` +
+        `echo '<<<LOCAL>>>'; ` +
+        `cat ${base}/editor.local.json 2>/dev/null || echo '{}'`,
+    }),
+    { stdio: ["ignore", "pipe", "ignore"] },
+  );
+  if (read.status !== 0 || typeof read.stdout !== "string") return VITE_PORT;
+  const parse = (s) => {
+    try {
+      const v = JSON.parse(s);
+      return v && typeof v === "object" && !Array.isArray(v) ? v : {};
+    } catch {
+      return {};
+    }
+  };
+  const [baseJson = "", localJson = ""] = read.stdout.split("<<<LOCAL>>>");
+  return resolveConfiguredAppPort(parse(baseJson), parse(localJson));
+}
+
+/** Build the shell command that seeds a JSON patch into a host-side
+ *  `editor.local.json` over SSH. The pre-chown matters: the file lives at
+ *  `~/projects/<repo>/.codeyam/editor.local.json` on the VM host, but it is
+ *  bind-mounted into the running container at `/workspace/.codeyam/`. When
+ *  the container writes the file (e.g. provider-auth updates, dashboard
+ *  edits), the write runs as root inside the container, so the host file
+ *  lands `root:root 0600` on the bind-mount. The next `cloud:up` —
+ *  triggered by dashboard Reconfigure — runs as the unprivileged SSH user
+ *  (`jaredcosulich` on fleet) and EACCES'es trying to overwrite it. The
+ *  `sudo chown $USER:$USER ${remotePath} 2>/dev/null || true` flips
+ *  ownership back when the file is root-owned, no-ops when the file
+ *  doesn't exist yet (`|| true` swallows the missing-file error), and
+ *  silently fails on the rare missing-sudo misconfig (so we never make
+ *  things worse than they were). Leaving the file under SSH-user
+ *  ownership permanently also keeps subsequent host-side reads
+ *  (`docker compose` `.env` interpolation, operator scripts) from
+ *  EACCESsing. Sister fix to `buildEnvApplyCommand` in launch-config.js
+ *  (which solves the symmetric `.env` problem with
+ *  `chown --reference=/workspace`). Pure; no I/O. */
+function buildEditorLocalSeedWriteCommand({ repoName, remotePath, b64 }) {
+  return (
+    `sudo chown $USER:$USER ${remotePath} 2>/dev/null || true && ` +
+    `mkdir -p ~/projects/${repoName}/.codeyam && ` +
+    `echo '${b64}' | base64 -d > ${remotePath}`
+  );
+}
+
+/** Seed a *bootstrap* `previewOrigin` into the VM's `editor.local.json` so the
+ *  Live Preview iframe URL the laptop browser loads is decoupled from the
+ *  in-VM dev-server port. `appPort` is the VM's resolved app port (see
+ *  readVmAppPort); it defaults to `VITE_PORT` for a Vite/greenfield app or any
+ *  unresolvable config. Two topologies:
+ *
+ *  - SSH-tunneled laptop user: the seed is `http://localhost:${appPort}`,
+ *    which the user's `-L ${appPort}:…` tunnel (openTunnel) forwards into the
+ *    VM. Works for a Vite 5173, a Next.js 3000, anything.
+ *  - Operator public trycloudflare URL: a localhost origin points at the laptop
+ *    itself, not the VM, so the iframe sticks on "Reconnecting Live Preview"
+ *    forever. The fix is a sibling `<N>-preview` cloudflared tunnel; once the
+ *    operator's cloudflared-monitor publishes its URL, that public origin is
+ *    seeded instead (see resolveSeedPreviewOrigin).
+ *
+ *  This is the bootstrap value only — the cloudflared-monitor owns the
+ *  steady-state value and rewrites it on every respawn (matching our
+ *  `_managedPreviewOrigin` sentinel). We stamp the sentinel here too so the
+ *  monitor doesn't mistake the cloud:up seed for a user pin. The
+ *  skip-on-already-set guard stays: a non-empty previewOrigin (whether a user
+ *  pin or a monitor write) is left untouched on every `cloud:up`. */
+async function seedPreviewOrigin(cfg, appPort = VITE_PORT) {
+  const repoName = resolveProject(cfg).name;
+  const remotePath = `~/projects/${repoName}/.codeyam/editor.local.json`;
+  const stackPath = `~/projects/${repoName}/.codeyam/stack.json`;
+
+  // One round-trip reads both the current editor.local.json (for the
+  // skip-on-already-set guard) and stack.json (for the sameOriginSafe flag that
+  // decides same-origin subpath vs dedicated origin). Mirrors readVmAppPort's
+  // separator-delimited cat.
+  const read = runGcloud(
+    buildGcloudArgs("ssh-probe", cfg, {
+      command:
+        `cat ${remotePath} 2>/dev/null || echo '{}'; ` +
+        `echo '<<<STACK>>>'; ` +
+        `cat ${stackPath} 2>/dev/null || echo '{}'`,
+    }),
+    { stdio: ["ignore", "pipe", "ignore"] },
+  );
+  const parseObj = (s) => {
+    try {
+      const v = JSON.parse(s);
+      return v && typeof v === "object" && !Array.isArray(v) ? v : {};
+    } catch {
+      // Unparseable remote content is treated as `{}` — overwriting a
+      // corrupt local override file with a known-good one is the safer
+      // move than refusing to seed at all.
+      return {};
+    }
+  };
+  let current = {};
+  let sameOriginSafe = true;
+  if (read.status === 0 && typeof read.stdout === "string") {
+    const [localJson = "", stackJson = ""] = read.stdout.split("<<<STACK>>>");
+    current = parseObj(localJson);
+    sameOriginSafe = previewSameOriginSafeFromStack(parseObj(stackJson));
+  }
+
+  const seed = resolveSeedPreviewOrigin(
+    cfg.instanceName,
+    readCloudflaredUrls(),
+    appPort,
+    process.env,
+    sameOriginSafe,
+  );
+
+  // 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.
+  const originAlreadySet =
+    typeof current.previewOrigin === "string" && current.previewOrigin.length > 0;
+  const healing =
+    originAlreadySet && isRottedManagedPreviewOrigin(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;
+  console.error(
+    healing
+      ? `Healing rotted managed previewOrigin (${current.previewOrigin}) → ${seed.previewOrigin} in ${remotePath}...`
+      : `Seeding previewOrigin=${seed.previewOrigin} into ${remotePath}...`,
+  );
+  const merged = deepMergeJson(current, overlay);
+  const mergedJson = JSON.stringify(merged, null, 2);
+  const b64 = Buffer.from(mergedJson, "utf8").toString("base64");
+  const write = runGcloud(
+    buildGcloudArgs("ssh-probe", cfg, {
+      command: buildEditorLocalSeedWriteCommand({ repoName, remotePath, b64 }),
+    }),
+    { stdio: ["ignore", "inherit", "inherit"] },
+  );
+  if (write.status !== 0) {
+    throw new Error(`Failed to write ${remotePath} on VM`);
+  }
+}
+
+async function seedAgentApiKey(cfg) {
+  const patch = buildEditorLocalEnvPatch(process.env, cfg.agent);
+  if (!patch) {
+    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`,
+    );
+    return;
+  }
+  const repoName = resolveProject(cfg).name;
+  const remotePath = `~/projects/${repoName}/.codeyam/editor.local.json`;
+  console.error(`Seeding ${agentEnvVarName(cfg.agent)} into ${remotePath}...`);
+
+  const read = runGcloud(
+    buildGcloudArgs("ssh-probe", cfg, {
+      command: `cat ${remotePath} 2>/dev/null || echo '{}'`,
+    }),
+    { stdio: ["ignore", "pipe", "ignore"] },
+  );
+  let current = {};
+  if (read.status === 0) {
+    try {
+      const parsed = JSON.parse(read.stdout);
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+        current = parsed;
+      }
+    } catch {
+      // Treat unparseable remote content as `{}` — overwriting a corrupt
+      // local override file with a known-good one is the safer move than
+      // refusing to seed at all.
+    }
+  }
+  const merged = deepMergeJson(current, patch);
+  const mergedJson = JSON.stringify(merged, null, 2);
+  const b64 = Buffer.from(mergedJson, "utf8").toString("base64");
+  const write = runGcloud(
+    buildGcloudArgs("ssh-probe", cfg, {
+      command: buildEditorLocalSeedWriteCommand({ repoName, remotePath, b64 }),
+    }),
+    { stdio: ["ignore", "inherit", "inherit"] },
+  );
+  if (write.status !== 0) {
+    throw new Error(`Failed to write ${remotePath} on VM`);
+  }
+}
+
+async function openTunnel(cfg, appPort = VITE_PORT) {
+  console.error(`Opening IAP tunnel to ${cfg.instanceName}...`);
+  const child = spawn("gcloud", buildGcloudArgs("ssh-tunnel", cfg, { appPort }), { stdio: "inherit" });
+  const readyEditor = await waitForPort(EDITOR_PORT, 30000, 500);
+  const readyApp = await waitForPort(appPort, 30000, 500);
+  if (!readyEditor || !readyApp) {
+    console.error(
+      `Warning: tunnel ports not reachable on localhost (${EDITOR_PORT}=${readyEditor}, ${appPort}=${readyApp}).`,
+    );
+  }
+  console.error(`  Editor UI:    http://localhost:${EDITOR_PORT}`);
+  console.error(`  Live Preview: http://localhost:${appPort}`);
+  console.error("  (Ctrl+C to tear down the tunnel)");
+  return child;
+}
+
+function attachKeepAliveAndTeardown(child) {
+  const keepAlive = setInterval(() => {}, 60_000);
+  process.on("SIGINT", () => {
+    clearInterval(keepAlive);
+    killChildProcess(child);
+    process.exit(0);
+  });
+}
+
+function promptForInstanceName(expected) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stderr,
+    });
+    rl.question(
+      `Type the instance name '${expected}' to confirm destroy: `,
+      (ans) => {
+        rl.close();
+        resolve(ans.trim() === expected);
+      },
+    );
+  });
+}
+
+// =============================================================================
+// Subcommand handlers
+// =============================================================================
+
+async function cmdUp(args) {
+  ensureGcloud();
+  const flags = parseFlags(args);
+  const cfg = loadOrInitCloudConfig(rootDir, 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);
+
+  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);
+  // --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
+  // invocations all contending on the fixed local ports 14199/5173.
+  if (cfg.noTunnel) {
+    console.error("--no-tunnel: provisioning complete; skipping local tunnel + browser open.");
+    return;
+  }
+  const tunnelChild = await openTunnel(cfg, appPort);
+  open(`http://localhost:${EDITOR_PORT}`);
+  attachKeepAliveAndTeardown(tunnelChild);
+}
+
+async function cmdTunnel(args) {
+  ensureGcloud();
+  const flags = parseFlags(args);
+  const existing = loadCloudConfig(rootDir);
+  if (!existing) {
+    throw new Error(
+      "No .codeyam/cloud.json found. Run `npm run cloud:up -- --repo <url>` first.",
+    );
+  }
+  const cfg = { ...existing, ...flags };
+
+  const state = fetchInstanceState(cfg);
+  if (state === null) {
+    throw new Error(
+      `Instance ${cfg.instanceName} not found in project ${cfg.project} / zone ${cfg.zone}. ` +
+        "Has it been deleted? Try `npm run cloud:up`.",
+    );
+  }
+  if (state !== "RUNNING") {
+    throw new Error(
+      `Instance ${cfg.instanceName} is ${state}; run \`npm run cloud:up\` to start it.`,
+    );
+  }
+
+  // Forward the laptop preview `-L` to the VM's resolved app port, not 5173.
+  const appPort = await readVmAppPort(cfg);
+  const tunnelChild = await openTunnel(cfg, appPort);
+  open(`http://localhost:${EDITOR_PORT}`);
+  attachKeepAliveAndTeardown(tunnelChild);
+}
+
+async function cmdStop(args) {
+  ensureGcloud();
+  parseFlags(args);
+  const cfg = loadCloudConfig(rootDir);
+  if (!cfg) {
+    throw new Error("No .codeyam/cloud.json found. Nothing to stop.");
+  }
+  console.error(`Stopping ${cfg.instanceName}...`);
+  const result = runGcloud(buildGcloudArgs("instances-stop", cfg));
+  if (result.status !== 0) {
+    throw new Error(`Failed to stop instance ${cfg.instanceName}`);
+  }
+  console.error(
+    `\n  ✓ ${cfg.instanceName} is stopped.\n` +
+      "  Persistent-disk billing continues (~$10/month for 100 GB pd-balanced).\n" +
+      "  Resume with `npm run cloud:up`.\n",
+  );
+}
+
+async function cmdDestroy(args) {
+  ensureGcloud();
+  parseFlags(args);
+  const cfg = loadCloudConfig(rootDir);
+  if (!cfg) {
+    throw new Error("No .codeyam/cloud.json found. Nothing to destroy.");
+  }
+
+  const confirmed = await promptForInstanceName(cfg.instanceName);
+  if (!confirmed) {
+    console.error("Aborted.");
+    return;
+  }
+
+  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}`);
+  }
+
+  const list = runGcloud(buildGcloudArgs("instances-list-tagged", cfg), {
+    stdio: ["ignore", "pipe", "ignore"],
+  });
+  const others = String(list.stdout || "").trim().split("\n").filter(Boolean);
+  if (others.length === 0) {
+    console.error(`No other ${INSTANCE_TAG}-tagged instances remain — deleting firewall rule...`);
+    const fwDel = runGcloud(buildGcloudArgs("firewall-delete", cfg));
+    if (fwDel.status !== 0) {
+      console.error(`  Warning: failed to delete firewall rule ${FIREWALL_RULE_NAME}.`);
+    }
+  } else {
+    console.error(
+      `Leaving ${FIREWALL_RULE_NAME} in place (${others.length} other ${INSTANCE_TAG}-tagged instance(s) still use it).`,
+    );
+  }
+
+  try {
+    fs.unlinkSync(cloudConfigPath(rootDir));
+    console.error("Deleted .codeyam/cloud.json");
+  } catch (e) {
+    if (e.code !== "ENOENT") throw e;
+  }
+}
+
+async function cmdStatus(args) {
+  ensureGcloud();
+  parseFlags(args);
+  const cfg = loadCloudConfig(rootDir);
+  if (!cfg) {
+    console.error("No .codeyam/cloud.json found. Run `npm run cloud:up` first.");
+    return;
+  }
+
+  const vmState = fetchInstanceState(cfg) || "NOT_FOUND";
+  console.error(`VM: ${cfg.instanceName} (${cfg.zone}) — ${vmState}`);
+
+  if (vmState !== "RUNNING") {
+    console.error("  (image / container / tunnel checks skipped — VM is not RUNNING)");
+    return;
+  }
+
+  const imgProbe = runGcloud(
+    buildGcloudArgs("ssh-probe", cfg, {
+      command:
+        "docker image inspect codeyam-editor:local >/dev/null 2>&1 && echo built || echo missing",
+    }),
+    { stdio: ["ignore", "pipe", "ignore"] },
+  );
+  const imgStatus = String(imgProbe.stdout || "").trim() || "?";
+  console.error(`  image:            ${imgStatus}`);
+
+  const repoName = resolveProject(cfg).name;
+  const containerProbe = runGcloud(
+    buildGcloudArgs("ssh-probe", cfg, {
+      command: `cd ~/projects/${repoName} 2>/dev/null && docker compose -f docker-compose.cloud.yml ps --format json 2>/dev/null || echo`,
+    }),
+    { stdio: ["ignore", "pipe", "ignore"] },
+  );
+  const containerStatus = parseEditorComposeState(containerProbe.stdout) || "missing";
+  console.error(`  editor container: ${containerStatus}`);
+
+  const appPort = await readVmAppPort(cfg);
+  const pEditor = await isPortInUse(EDITOR_PORT);
+  const pApp = await isPortInUse(appPort);
+  console.error(
+    `  tunnel:           ${EDITOR_PORT} ${pEditor ? "✓" : "✗"}   ${appPort} ${pApp ? "✓" : "✗"}`,
+  );
+}
+
+const HANDLERS = {
+  up: cmdUp,
+  tunnel: cmdTunnel,
+  stop: cmdStop,
+  destroy: cmdDestroy,
+  status: cmdStatus,
+};
+
+async function cloudMain() {
+  const subcmd = process.argv[2];
+  const args = process.argv.slice(3);
+  if (!subcmd || !Object.prototype.hasOwnProperty.call(HANDLERS, subcmd)) {
+    console.error(
+      `Usage: npm run cloud:<${Object.keys(HANDLERS).join("|")}> [-- flags]`,
+    );
+    process.exit(2);
+  }
+  try {
+    await HANDLERS[subcmd](args);
+  } catch (e) {
+    console.error(`Error: ${e.message}`);
+    process.exit(1);
+  }
+}
+
+module.exports = {
+  // pure helpers
+  agentEnvVarName,
+  AGENT_ENV_VARS,
+  KNOWN_FLAGS,
+  FIREWALL_RULE_NAME,
+  INSTANCE_TAG,
+  EDITOR_PORT,
+  VITE_PORT,
+  parseFlags,
+  repoBasename,
+  deriveInstanceName,
+  defaultInstanceNameFor,
+  CANONICAL_EDITOR_REPO,
+  EDITOR_VARIANTS,
+  MANAGED_PREVIEW_ORIGIN,
+  SAME_ORIGIN_PREVIEW_PATH,
+  sameRepo,
+  resolveFleetVmNumber,
+  rosterProvisionedVm,
+  resolveConfiguredAppPort,
+  resolveSeedPreviewOrigin,
+  previewSameOriginSafeFromStack,
+  isRottedManagedPreviewOrigin,
+  resolveEditorConfig,
+  validateEditorVariant,
+  assertVariantProvisionable,
+  editorImageBootstrapArgs,
+  reconcileProjectExclusivity,
+  resolveGhcrToken,
+  resolveGhcrPushToken,
+  resolveProject,
+  clientProjectBootstrapArgs,
+  cloudConfigPath,
+  loadCloudConfig,
+  saveCloudConfig,
+  buildEditorLocalEnvPatch,
+  buildEditorLocalSeedWriteCommand,
+  seedPreviewOrigin,
+  buildGcloudArgs,
+  sshScriptCommand,
+  bootstrapRunnerScript,
+  bootstrapLaunchCommand,
+  bootstrapFollowCommand,
+  bootstrapStatusCommand,
+  parseBootstrapStatus,
+  decideBootstrapOutcome,
+  projectBootstrapDoneMarker,
+  projectBootstrapDoneProbeCommand,
+  SSH_KEEPALIVE_FLAGS,
+  resolveSetupForwardEnv,
+  FORWARD_ENV_KEYS_ENV,
+  parseEditorComposeState,
+  fetchInstanceState,
+  // side-effecting handlers
+  cmdUp,
+  cmdTunnel,
+  cmdStop,
+  cmdDestroy,
+  cmdStatus,
+  cloudMain,
+  seedGithubCredentials,
+  readVmAppPort,
+  resolveLaptopGitIdentity,
+};
+
+if (require.main === module) {
+  cloudMain();
+}