@codeyam-editor/codeyam-editor 0.1.2 → 0.1.3

package/npm/cloud.js

@@ -110,11 +110,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
@@ -302,33 +302,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 +435,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;
 }
 
@@ -568,10 +640,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": {
@@ -807,19 +888,194 @@ 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();
 }
 
@@ -850,42 +1106,124 @@ 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 = 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}...`);
-  // 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"] },
   );
@@ -991,7 +1329,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 +1337,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 +1477,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(
@@ -1485,12 +1880,15 @@ module.exports = {
   rosterProvisionedVm,
   resolveConfiguredAppPort,
   resolveSeedPreviewOrigin,
+  previewSameOriginSafeFromStack,
+  isRottedManagedPreviewOrigin,
   resolveEditorConfig,
   validateEditorVariant,
   assertVariantProvisionable,
   editorImageBootstrapArgs,
   reconcileProjectExclusivity,
   resolveGhcrToken,
+  resolveGhcrPushToken,
   resolveProject,
   clientProjectBootstrapArgs,
   cloudConfigPath,
@@ -1498,8 +1896,18 @@ 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,