@codeyam-editor/codeyam-editor 0.1.2 → 0.1.4

package/npm/cloud.js

@@ -51,6 +51,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):
@@ -110,11 +116,11 @@ const CLOUDFLARED_URLS_FILE =
 // 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:
+// 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
-//                (today's path; the only one wired into provisioning so far)
-//   staging    — `npm i -g @codeyam-editor/codeyam-editor@staging` (Phase 2)
-//   production — `npm i -g @codeyam-editor/codeyam-editor`          (Phase 2)
+//   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
@@ -129,6 +135,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. */
@@ -302,33 +319,98 @@ function resolveSeedPreviewOrigin(
   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 tunnels are per fleet-VM; a non-fleet client project (vm == null)
-  // keeps the legacy localhost seed even when a domain is configured.
+  // 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: serve the app same-origin under the
-  // reserved relative path. 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,
-  // SSH-tunnel localhost, anything). This replaces the prior
-  // `http://localhost:${appPort}` seed — a loopback URL a public editor page
-  // could not load (Private Network Access block) — and the monitor's rotating
-  // `<N>-preview` quick-tunnel URL, which a constant relative path makes moot.
-  // `appPort` / `urls` are retained in the signature for callers but no longer
-  // seeded — the same-origin path is a constant.
+  // 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: SAME_ORIGIN_PREVIEW_PATH,
+    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() {
@@ -370,26 +452,33 @@ function validateEditorVariant(variant) {
   return variant;
 }
 
-/** Phase-1 gate: only `dev` is wired into cloud provisioning. The
- *  staging/production npm-install container image lands in Phase 2. Fails loud
- *  with an actionable message rather than silently building a dev image. */
+/** 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) {
-  validateEditorVariant(variant);
-  if (variant !== "dev") {
-    throw new Error(
-      `Editor variant '${variant}' is not yet wired for cloud provisioning ` +
-        `(Phase 2 — the @staging/production npm-install image). Use --editor-variant dev.`,
-    );
-  }
-  return variant;
+  return validateEditorVariant(variant);
 }
 
-/** Args for scripts/gcp-bootstrap.sh, which builds the codeyam-editor:local
- *  image from the EDITOR source — NOT the client project. */
+/** 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 } = resolveEditorConfig(cfg);
-  const args = ["--agent", cfg.agent, "--repo", editorRepo];
-  if (editorBranch) args.push("--branch", editorBranch);
+  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;
 }
 
@@ -468,14 +557,26 @@ function saveCloudConfig(projectDir, cfg) {
 }
 
 /** 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
@@ -568,10 +669,19 @@ function buildGcloudArgs(verb, cfg = {}, extras = {}) {
       // 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": {
@@ -619,6 +729,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) {
@@ -718,9 +894,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...`);
@@ -742,7 +920,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));
   }
@@ -807,23 +985,198 @@ function resolveSetupForwardEnv(env = process.env) {
   return out;
 }
 
-function sshScriptCommand(scriptBody, scriptArgs = [], envVars = {}) {
-  const b64 = Buffer.from(scriptBody, "utf8").toString("base64");
-  const argsString = scriptArgs.map((a) => `'${String(a).replace(/'/g, "'\\''")}'`).join(" ");
-  // Prefix each env var as `KEY='value'` so they're set for the bash -s
-  // process only — no persistence in the VM's shell history, no /etc/environment
-  // edit. Single-quoted values are safe against shell metacharacters; an
-  // embedded apostrophe in the value would be exotic for these (token,
-  // bool flag), but escape it the same way as scriptArgs for symmetry.
-  const envString = Object.entries(envVars)
+// --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}='${String(v).replace(/'/g, "'\\''")}'`)
+    .map(([k, v]) => `${k}=${shQuote(v)}`)
     .join(" ");
-  const envPrefix = envString ? `${envString} ` : "";
+  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) {
+async function ensureBootstrapped(cfg, { sleepFn } = {}) {
   console.error("Checking VM bootstrap state...");
   const probe = runGcloud(
     buildGcloudArgs("ssh-probe", cfg, {
@@ -850,42 +1203,129 @@ async function ensureBootstrapped(cfg) {
   // wrapper / Dockerfile patches from a feature branch; without it the image
   // build uses the editor repo's default branch.
   const bootstrapArgs = editorImageBootstrapArgs(cfg);
-  // CODEYAM_GHCR_TOKEN lets the bootstrap `docker login ghcr.io` and pull the
-  // PRIVATE prebuilt base + branch-binary packages — without it every pull
-  // 403s and the bootstrap silently slow-builds (~14 min) from source.
-  // CODEYAM_GHCR_USER is an optional login-username override (the bootstrap
-  // otherwise derives it from the registry owner). Empty values are dropped by
-  // sshScriptCommand, so the no-registry / local-only path is unchanged.
-  const command = sshScriptCommand(scriptBody, bootstrapArgs, {
+  // 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 || "",
-  });
-  const result = runGcloud(
-    buildGcloudArgs("ssh-script", cfg, { command }),
-    { stdio: "inherit" },
-  );
-  if (result.status !== 0) {
-    throw new Error("scripts/gcp-bootstrap.sh failed on the VM");
+    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 = await runGcloudSshWithRetry(
+      "ssh-script",
+      cfg,
+      { command: launch },
+      { stdio: ["ignore", "pipe", "pipe"], label: "bootstrap launch", sleepFn }
+    );
+    if (launched.status !== 0) {
+      const detail = formatGcloudFailure(launched);
+      throw new Error(
+        `failed to launch the detached bootstrap on the VM (gcloud ssh exit ${launched.status}).\n${detail}`,
+      );
+    }
+  }
+
+  // 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}...`);
-  // Probe both .codeyam/ (created by `editor init`) AND
-  // docker-compose.cloud.yml (written near the end of the script). A previous
-  // run that crashed between init and the compose write would leave the
-  // first marker but not the second; the old probe wrongly considered the
-  // project bootstrapped and the next `cloud:up` then hit
-  // "open docker-compose.cloud.yml: no such file or directory".
-  // The probe is the seam where idempotency lives — make sure it gates on
-  // the LAST artifact the script produces, not the first.
+  // 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:
-        `test -d ~/projects/${repoName}/.codeyam ` +
-        `&& test -f ~/projects/${repoName}/docker-compose.cloud.yml`,
+      command: projectBootstrapDoneProbeCommand(repoName),
     }),
     { stdio: ["ignore", "pipe", "pipe"] },
   );
@@ -942,6 +1382,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)...");
@@ -954,6 +1395,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
@@ -991,7 +1460,7 @@ function resolveGithubToken() {
   return "";
 }
 
-/** A `read:packages`-scoped token the VM bootstrap uses to `docker login
+/** 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
@@ -999,11 +1468,29 @@ function resolveGithubToken() {
  *  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. */
+ *  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
@@ -1121,37 +1608,76 @@ function buildEditorLocalSeedWriteCommand({ repoName, remotePath, b64 }) {
 async function seedPreviewOrigin(cfg, appPort = VITE_PORT) {
   const repoName = resolveProject(cfg).name;
   const remotePath = `~/projects/${repoName}/.codeyam/editor.local.json`;
-  const seed = resolveSeedPreviewOrigin(
-    cfg.instanceName,
-    readCloudflaredUrls(),
-    appPort,
-  );
+  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 '{}'`,
+      command:
+        `cat ${remotePath} 2>/dev/null || echo '{}'; ` +
+        `echo '<<<STACK>>>'; ` +
+        `cat ${stackPath} 2>/dev/null || echo '{}'`,
     }),
     { stdio: ["ignore", "pipe", "ignore"] },
   );
-  let current = {};
-  if (read.status === 0) {
+  const parseObj = (s) => {
     try {
-      const parsed = JSON.parse(read.stdout);
-      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-        current = parsed;
-      }
+      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));
   }
-  if (typeof current.previewOrigin === "string" && current.previewOrigin.length > 0) {
+
+  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;
   }
 
-  console.error(`Seeding previewOrigin=${seed.previewOrigin} into ${remotePath}...`);
-  const merged = deepMergeJson(current, seed);
+  // 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(
@@ -1165,20 +1691,35 @@ async function seedPreviewOrigin(cfg, appPort = VITE_PORT) {
   }
 }
 
+/** Write the chosen agent provider and local API keys into editor.local.json on
+ *  the VM BEFORE compose up so the file exists when the bind-mount happens —
+ *  the provider seed MUST run before ensureEditorContainerUp, because the editor
+ *  caches config.provider at startup and reports it as currentProvider; a post-start
+ *  seed leaves the running editor (and therefore the dashboard badge) on the default
+ *  "claude" until a config reload. */
 async function seedAgentApiKey(cfg) {
+  // The provider seed is unconditional — `buildEditorLocalEnvPatch` always
+  // returns a patch carrying `provider`, so the chosen agent always lands on
+  // the VM. The API-key seed is opportunistic: when the matching key isn't set
+  // locally the patch carries `provider` only, and we still print the
+  // interactive-auth fallback line so the operator knows to authenticate the
+  // agent on the VM later (Gemini's normal path).
   const patch = buildEditorLocalEnvPatch(process.env, cfg.agent);
-  if (!patch) {
+  const hasKey = Boolean(patch.env);
+  if (!hasKey) {
     console.error(
-      `\nNo ${agentEnvVarName(cfg.agent)} set locally — skipping agent auth seed.\n` +
+      `\nNo ${agentEnvVarName(cfg.agent)} set locally — seeding provider only.\n` +
         `Authenticate ${cfg.agent} later with:\n` +
         `  gcloud compute ssh ${cfg.instanceName} --project ${cfg.project} --zone ${cfg.zone} ` +
         `--tunnel-through-iap -- ${cfg.agent} auth login\n`,
     );
-    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, {
@@ -1211,6 +1752,75 @@ 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",
+    "  if [ \"$AGENT\" = \"claude\" ]; then",
+    "    if [ -x /usr/local/bin/claude ]; then",
+    "      echo \"  ✓ $BINARY already installed and executable at /usr/local/bin/claude\"",
+    "      exit 0",
+    "    fi",
+    "  else",
+    "    echo \"  ✓ $BINARY already installed on PATH\"",
+    "    exit 0",
+    "  fi",
+    "fi",
+    "",
+    "echo \"Installing $PACKAGE globally in container...\"",
+    "if [ \"$AGENT\" = \"claude\" ]; then",
+    "  rm -rf /usr/lib/node_modules/@anthropic-ai/.claude-code-*",
+    "  npm install -g \"$PACKAGE\"",
+    "  ln -sf /usr/lib/node_modules/@anthropic-ai/claude-code/node_modules/@anthropic-ai/claude-code-linux-x64/claude /usr/local/bin/claude",
+    "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) {
@@ -1268,24 +1878,55 @@ async function cmdUp(args) {
   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);
+  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.
+    await seedGithubCredentials(cfg);
+    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);
+    // 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);
+  } catch (err) {
+    if (createdThisRun) {
+      console.error(
+        `✗ provisioning aborted — tearing down the VM cloud:up created this run (no orphan left behind)`,
+      );
+      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
@@ -1466,7 +2107,10 @@ async function cloudMain() {
 module.exports = {
   // pure helpers
   agentEnvVarName,
+  agentNpmPackage,
   AGENT_ENV_VARS,
+  AGENT_NPM_PACKAGES,
+  ensureAgentCliInstalled,
   KNOWN_FLAGS,
   FIREWALL_RULE_NAME,
   INSTANCE_TAG,
@@ -1485,12 +2129,15 @@ module.exports = {
   rosterProvisionedVm,
   resolveConfiguredAppPort,
   resolveSeedPreviewOrigin,
+  previewSameOriginSafeFromStack,
+  isRottedManagedPreviewOrigin,
   resolveEditorConfig,
   validateEditorVariant,
   assertVariantProvisionable,
   editorImageBootstrapArgs,
   reconcileProjectExclusivity,
   resolveGhcrToken,
+  resolveGhcrPushToken,
   resolveProject,
   clientProjectBootstrapArgs,
   cloudConfigPath,
@@ -1498,12 +2145,28 @@ module.exports = {
   saveCloudConfig,
   buildEditorLocalEnvPatch,
   buildEditorLocalSeedWriteCommand,
+  seedPreviewOrigin,
   buildGcloudArgs,
   sshScriptCommand,
+  bootstrapRunnerScript,
+  bootstrapLaunchCommand,
+  bootstrapFollowCommand,
+  bootstrapStatusCommand,
+  parseBootstrapStatus,
+  decideBootstrapOutcome,
+  projectBootstrapDoneMarker,
+  projectBootstrapDoneProbeCommand,
+  SSH_KEEPALIVE_FLAGS,
   resolveSetupForwardEnv,
   FORWARD_ENV_KEYS_ENV,
   parseEditorComposeState,
   fetchInstanceState,
+  formatGcloudFailure,
+  isTransientSshFailure,
+  runGcloudSshWithRetry,
+  ensureInstance,
+  ensureBootstrapped,
+  assertEditorContainerRunning,
   // side-effecting handlers
   cmdUp,
   cmdTunnel,