@codeyam-editor/codeyam-editor 0.1.4 → 0.1.6

package/npm/launch-config.js

@@ -9,6 +9,8 @@
 // and past launches one click to re-run.
 
 const { CANONICAL_EDITOR_REPO, EDITOR_VARIANTS, repoBasename, AGENT_ENV_VARS } = require("./cloud");
+const { normalizeVmSlug } = require("./vm-urls");
+const { normalizeAccessList } = require("./fleet-vm-access");
 
 /** The build agents a VM's editor terminal can run, as the keys of cloud.js's
  *  AGENT_ENV_VARS. Deriving the selectable set from that map keeps it a single
@@ -28,8 +30,30 @@ const EMPTY_CONFIG = Object.freeze({
   // Build agent provider the VM's editor terminal runs (claude | codex | gemini).
   // Defaults to claude; cloudUpArgs forwards it as cloud:up's --agent flag.
   agent: "claude",
+  // Optional human-readable hostname slug for a SINGLE VM. When set, cloudUpArgs
+  // forwards it as cloud:up's --vm-slug flag so the VM's public URLs become
+  // `<slug>.editor.<domain>`. Empty ⇒ the numeric vm-<N> scheme (unchanged).
+  vmSlug: "",
+  // Optional per-VM IAP access whitelist for a SINGLE VM: a comma-separated list
+  // of principals (user:/group:/domain:, a bare email defaults to user:) granted
+  // resource-level access to this VM's surfaces. cloudUpArgs forwards it as
+  // cloud:up's --vm-access flag. Empty ⇒ only the owner's project-wide grant.
+  vmAccess: "",
 });
 
+/** Collapse a free-text access list (the add-form textarea, where the operator
+ *  may separate principals by newlines or commas) into the canonical
+ *  comma-separated string cloud:up's --vm-access expects. Pure + never throws —
+ *  shape validation is validateLaunchConfig's job. */
+function normalizeAccessText(raw) {
+  if (typeof raw !== "string") return "";
+  return raw
+    .split(/[\n,]+/)
+    .map((s) => s.trim())
+    .filter(Boolean)
+    .join(",");
+}
+
 /** Coerce a raw form/query object into the canonical launch-config shape: trim
  *  strings, default the variant to a known value. Never throws — validation is
  *  a separate, explicit step. */
@@ -47,6 +71,8 @@ function normalizeLaunchConfig(input = {}) {
     editorVariant,
     editorBranch: str(input.editorBranch),
     agent,
+    vmSlug: str(input.vmSlug),
+    vmAccess: normalizeAccessText(input.vmAccess),
   };
 }
 
@@ -70,6 +96,72 @@ function validateLaunchConfig(cfg) {
   if (!EDITOR_VARIANTS.includes(cfg.editorVariant)) {
     return { ok: false, msg: `unknown editor variant: ${cfg.editorVariant}` };
   }
+  // A custom slug, when supplied, must be a single DNS label (same rule cloud:up
+  // enforces) — surface a friendly reason here rather than letting the spawned
+  // job fail loud later. Empty ⇒ numeric vm-<N>, no check.
+  if (cfg.vmSlug) {
+    try {
+      normalizeVmSlug(cfg.vmSlug);
+    } catch (e) {
+      return { ok: false, msg: e.message };
+    }
+  }
+  // A per-VM access whitelist, when supplied, must be a list of valid principals
+  // (same rule cloud:up enforces) — surface a friendly reason here rather than
+  // letting the spawned job fail loud later. Empty ⇒ no check.
+  if (cfg.vmAccess) {
+    try {
+      normalizeAccessList(cfg.vmAccess);
+    } catch (e) {
+      return { ok: false, msg: e.message };
+    }
+  }
+  return { ok: true };
+}
+
+/** Pre-flight the operator-host CONFIG a dashboard Add depends on, BEFORE
+ *  spawning the ~20-min cloud:up. Pure classifier: it takes the ALREADY-resolved
+ *  zone, project, and GitHub token (the side-effecting resolution — env lookups,
+ *  `gh auth token`, gcloud defaults — is the caller's job) and returns { ok, msg }
+ *  naming the exact fix for the FIRST blocking gap. This turns a config fault into
+ *  a seconds-fast, actionable add-rejection instead of a cryptic `cloud:up FAILED
+ *  (exit 1)` the operator has to dig out of a 20-min job log.
+ *
+ *  It guards the two config faults that silently broke every fleet add on
+ *  2026-07-20:
+ *   - no resolvable compute zone → cloud:up aborts at its own --zone check in ~15s
+ *     before creating any instance;
+ *   - no GitHub token → the fresh VM's bootstrap dies cloning the PRIVATE editor
+ *     repo at `could not read Username for 'https://github.com'`.
+ *  `allowNoGitCredentials` mirrors cloud:up's --allow-no-git-credentials opt-out
+ *  for an intentionally read-only VM (no push token needed). Pure; no I/O. */
+function addPreflight({ zone, project, token, allowNoGitCredentials = false } = {}) {
+  const blank = (v) => typeof v !== "string" || v.trim() === "";
+  if (blank(zone)) {
+    return {
+      ok: false,
+      msg:
+        "no compute zone configured — set ZONE in /etc/codeyam/operator-host.env " +
+        "(or `gcloud config set compute/zone <zone>`) before adding a VM.",
+    };
+  }
+  if (blank(project)) {
+    return {
+      ok: false,
+      msg:
+        "no GCP project configured — set GCP_PROJECT (or a non-placeholder " +
+        "project in .codeyam/cloud.json) before adding a VM.",
+    };
+  }
+  if (!allowNoGitCredentials && blank(token)) {
+    return {
+      ok: false,
+      msg:
+        "no GitHub token — set GITHUB_TOKEN/GH_TOKEN in /etc/codeyam/operator-host.env " +
+        "(the VM bootstrap needs it to clone the private editor repo), or provision a " +
+        "read-only VM with --allow-no-git-credentials.",
+    };
+  }
   return { ok: true };
 }
 
@@ -123,13 +215,27 @@ function variantImageTag(variant) {
   return null; // dev / unknown — no packaged image
 }
 
+/** Return true if the value matches a known test-fixture placeholder (e.g., "gcp-proj"),
+ *  is null, empty, or whitespace, signaling that it is not a valid GCP project name.
+ *  Documented as the home for future fixture sentinels. Pure; no I/O. */
+function isPlaceholderProject(value) {
+  if (!value) return true;
+  if (typeof value !== "string") return true;
+  const trimmed = value.trim();
+  if (trimmed === "") return true;
+  if (trimmed.toLowerCase() === "gcp-proj") return true;
+  return false;
+}
+
 /** Build the `cloud:up` flag array for a launch config + instance name. The
  *  editor source is the canonical codeyam-editor repo (dev variant builds the
  *  image from editorBranch); the client repo/branch is what lands in
  *  /workspace. The build agent rides on `cfg.agent` (normalizeLaunchConfig
  *  guarantees a known value, defaulting to claude), so a single config object
- *  carries every launch choice. Decoupled exactly as cloud.js consumes them. */
-function cloudUpArgs(cfg, instanceName, project) {
+ *  carries every launch choice. Decoupled exactly as cloud.js consumes them.
+ *  `zone` is the resolved compute zone (the dashboard's ZONE); passing it
+ *  explicitly is what keeps an add off the ambient gcloud default. */
+function cloudUpArgs(cfg, instanceName, project, zone) {
   const args = ["--instance-name", instanceName];
   // Pass the authoritative GCP project (the dashboard's resolved PROJECT)
   // explicitly so cloud:up never relies on the spawning shell's ambient
@@ -137,16 +243,33 @@ function cloudUpArgs(cfg, instanceName, project) {
   // a persisted .codeyam/cloud.json `project` (cloud.js merges
   // `{ ...existing, ...flags }`), which a bare cloud:up reuses verbatim with no
   // gcloud fallback — the sticky-wrong-project failure mode where a stale
-  // "gcp-proj" in cloud.json wedges every re-provision with a firewall-create
-  // PERMISSION_DENIED. Omitted when unset to preserve the pre-existing arg shape
-  // (cloud.js then falls back to the gcloud default, as before).
+  // placeholder in cloud.json (validated via isPlaceholderProject) wedges every
+  // re-provision with a firewall-create PERMISSION_DENIED. Omitted when unset to
+  // preserve the pre-existing arg shape (cloud.js then falls back to the gcloud
+  // default, as before).
   if (project) args.push("--project", project);
+  // Pass the resolved compute zone explicitly, for the SAME reason as --project:
+  // a bare cloud:up otherwise falls back to `gcloud config get-value
+  // compute/zone`, and an operator host with no default compute/zone aborts
+  // EVERY add at cloud:up's own --zone check in ~15s, before any instance is
+  // created (the 2026-07-20 fleet-wide add failure). Omitted only when the caller
+  // resolves no zone, preserving the pre-existing arg shape for legacy callers.
+  if (zone) args.push("--zone", zone);
   // Greenfield (new folder) vs clone an existing repo.
   if (cfg.newProjectName) args.push("--new-project", cfg.newProjectName);
   else args.push("--repo", cfg.clientRepo);
   args.push("--agent", cfg.agent || "claude", "--editor-repo", CANONICAL_EDITOR_REPO, "--editor-variant", cfg.editorVariant);
   if (!cfg.newProjectName && cfg.clientBranch) args.push("--branch", cfg.clientBranch);
   if (cfg.editorBranch) args.push("--editor-branch", cfg.editorBranch);
+  // Forward an optional custom hostname slug. Only single-VM Adds carry one (the
+  // dashboard strips it for batch count > 1 — N VMs can't share one hostname), so
+  // cloudUpArgs simply emits it when present and trusts the caller's batch guard.
+  if (cfg.vmSlug) args.push("--vm-slug", cfg.vmSlug);
+  // Forward an optional per-VM access whitelist. Like the slug, only single-VM
+  // Adds carry one (the dashboard strips it for batch count > 1 — the same guard
+  // actionAdd applies to vmSlug), so cloudUpArgs emits it when present and trusts
+  // the caller's batch guard.
+  if (cfg.vmAccess) args.push("--vm-access", cfg.vmAccess);
   // The dashboard opens its own per-VM tunnel, so cloud:up must NOT open one:
   // it lets cloud:up exit cleanly and avoids parallel batches colliding on the
   // fixed local ports 14199/5173 (the cause of multi-add "false failures").
@@ -313,6 +436,28 @@ function configForVm(history, n) {
   return h && h.config ? { ...EMPTY_CONFIG, ...h.config } : null;
 }
 
+/** The most-recent launch timestamp for VM `n`, or null when it has no recorded
+ *  launch. The history is newest-first (pushHistory unshifts), so the FIRST entry
+ *  for the VM is its latest launch — the same lookup shape configForVm uses.
+ *  Powers the editor-starting grace window (server.js's deriveStatus): "was this
+ *  unreachable VM launched recently enough to still be starting up?" Pure. */
+function latestLaunchTs(history, n) {
+  const h = (Array.isArray(history) ? history : []).find((e) => e && e.vm === n);
+  return h && typeof h.ts === "string" ? h.ts : null;
+}
+
+/** True when ISO launch timestamp `ts` is within `graceMs` of `nowMs` — the
+ *  editor-starting grace window. A null/unparseable `ts` (no launch on record) is
+ *  never "recent", so a VM with no history never reads as starting. Half-open
+ *  window: exactly at the boundary (`nowMs - ts === graceMs`) is NOT recent, so
+ *  the calm-blue window has a crisp, testable end. Pure; caller owns `nowMs`. */
+function recentlyLaunchedWithin(ts, nowMs, graceMs) {
+  if (typeof ts !== "string") return false;
+  const t = Date.parse(ts);
+  if (Number.isNaN(t)) return false;
+  return nowMs - t < graceMs;
+}
+
 /** Resolve the card's display identity, preferring LIVE truth (the editor's
  *  `/api/session-info` `clientProject` + `editorIdentity`) over STALE launch
  *  history. This is the fix for fragility #33's lying label: a CLI branch
@@ -382,6 +527,86 @@ function stickyClientProject(prev, info) {
   return prev || null;
 }
 
+/** Resolve a VM's app dev-server port stickily: prefer the freshly-polled
+ *  numeric port, else retain the last-known-good `prevAppPort`, so a transient
+ *  null poll (timeout / partial probe) never blanks a port the VM has already
+ *  reported. Mirrors `stickyClientProject` — a populated `prev` survives a
+ *  null/absent fresh poll, a genuinely-changed fresh poll always wins
+ *  (stickiness must NOT pin a stale port: a real 3000→4321 move is honored),
+ *  and `null` results ONLY when neither a polled nor a previous port exists —
+ *  the true first-provision case, where the caller applies its 5173 bootstrap
+ *  fallback.
+ *
+ *  Without this, `appPort` was `(info && info.appPort) || null`, so one
+ *  timed-out poll blanked the resolved port; the tunnel-open fallback then
+ *  re-seeded the hardcoded 5173 Vite default and the next poll saw a 5173→3000
+ *  drift and re-wired — a churn loop that never converged. Pure; no I/O.
+ *
+ *  @param prevAppPort  the previous `state.vms[n].appPort` (null/undefined ok)
+ *  @param info         the fresh poll result object (null when the probe failed)
+ *  @returns the app port to store: fresh numeric port when present, else the
+ *           last-known-good `prevAppPort`, else null. */
+function stickyAppPort(prevAppPort, info) {
+  const fresh = info && info.appPort;
+  if (typeof fresh === 'number' && !Number.isNaN(fresh)) return fresh;
+  return typeof prevAppPort === 'number' && !Number.isNaN(prevAppPort) ? prevAppPort : null;
+}
+
+/** Resolve a VM's preview-tunnel reachability stickily, mirroring `stickyAppPort`.
+ *  A single flaky preview probe must not blink the 👁 Live Preview link off:
+ *  an explicit `true`/`false` from the fresh poll passes through (a genuine
+ *  dead/alive transition always wins), but a missing / null / undefined
+ *  `info.previewReachable` (transient poll — the probe was skipped, timed out,
+ *  or the whole probe object is absent) retains the last-known-good
+ *  `prevPreviewReachable` instead of blanking it to null. `null` results only
+ *  when neither a fresh boolean nor a previous boolean exists — the true
+ *  never-probed first-poll case. Pure; no I/O.
+ *
+ *  @param prevPreviewReachable the previous `state.vms[n].previewReachable`
+ *  @param info                 the fresh probe result ({ previewReachable } | null)
+ *  @returns true | false | null per the rules above. */
+function stickyPreviewReachable(prevPreviewReachable, info) {
+  const fresh = info && info.previewReachable;
+  if (fresh === true || fresh === false) return fresh;
+  return prevPreviewReachable === true || prevPreviewReachable === false
+    ? prevPreviewReachable
+    : null;
+}
+
+/** Resolve a VM's preview-SERVING signal — "is the VM's dev server up?" —
+ *  stickily from the `previewState` field the editor already emits on
+ *  `/api/session-info`. This is the operator-host-safe replacement for the
+ *  loopback-only `previewReachable` probe: session-info reaches every VM over
+ *  the IAP-LB seam on the GCE operator host, where the `127.0.0.1` preview
+ *  forward `previewReachable` depended on cannot exist (so it read `false`
+ *  fleet-wide there). It measures the SAME thing the old loopback probe did —
+ *  "the dev server serves" — not public LB ingress; that is `previewIngress`'s job.
+ *
+ *  `compute_preview_state` classifies it authoritatively from inside the VM
+ *  (immune to tunnel flakiness, with a recompile-grace debounce):
+ *    `"forwarding"`   → true  (dev server up / serving).
+ *    `"placeholder"`  → false (dev server down or never started).
+ *    anything else    → sticky: a missing field (legacy editor predating
+ *                       `previewState`, or `info` null on a transient/failed
+ *                       poll) retains the last-known-good `prevPreviewServing`
+ *                       rather than blinking the 👁 link off. `null` only when
+ *                       neither a fresh state nor a previous boolean exists —
+ *                       the true never-probed first-poll case. Pure; no I/O.
+ *
+ *  Mirrors `stickyPreviewReachable`'s tri-state stickiness exactly.
+ *
+ *  @param prevPreviewServing the previous `state.vms[n].previewServing`
+ *  @param info               the fresh `/api/session-info` result ({ previewState } | null)
+ *  @returns true | false | null per the rules above. */
+function stickyPreviewServing(prevPreviewServing, info) {
+  const state = info && info.previewState;
+  if (state === 'forwarding') return true;
+  if (state === 'placeholder') return false;
+  return prevPreviewServing === true || prevPreviewServing === false
+    ? prevPreviewServing
+    : null;
+}
+
 /** Classify a VM's project KIND as `"self-host"` vs `"guest"` from the live
  *  identity reported in `/api/session-info` (`clientProject.repo`), with
  *  launch-history `clientRepo` as a fallback when live is absent. A guest is
@@ -540,10 +765,80 @@ function resolveCredsSource({ reachableDonors = [], claudeCredsSrc = "", githubT
   return { mode: "none", donor: null };
 }
 
+/** True when the resolved creds `mode` (see `resolveCredsSource`) carries a real
+ *  Claude-auth seed source, so the add path can seed it automatically and must
+ *  NOT raise the `claude-auth-not-seeded` setup step:
+ *    - "donor"      — copies the donor's `.credentials.json` + `.claude.json`.
+ *    - "host-stash" — pushes the operator's CLAUDE_CREDS_SRC `.credentials.json`.
+ *  The token-only and none modes carry NO Claude credentials — a GITHUB_TOKEN
+ *  seeds *git* auth at boot but not Claude, so those genuinely have nothing to
+ *  seed Claude from and the add path raises `claude-auth-not-seeded` (rendered
+ *  as the calm Plan-1 `auth` setup step with the one-click Login). Branching on
+ *  this instead of unconditionally landing degraded is what keeps the reason from
+ *  appearing when a donor/stash WAS available. Pure; no I/O. */
+function claudeAuthSeeded(mode) {
+  return mode === "donor" || mode === "host-stash";
+}
+
 // Single-quote a string for safe inclusion in a remote shell command. Mirrors
 // the server.js helper so callers don't have to thread one through.
 function _shq(s) { return `'${String(s).replace(/'/g, `'\\''`)}'`; }
 
+/** Build a `docker exec … bash -c` sink that stages stdin to a same-directory
+ *  `.cytmp` sibling and only `mv`s it onto `target` when the staged file is
+ *  NON-EMPTY — exiting 1 (so the caller's `… || echo CY_DEGRADED` fires) and
+ *  leaving any existing `target` UNTOUCHED on empty/unreadable input.
+ *
+ *  Closes the truncate-to-0 hazard the plan targets: an empty/unreadable donor's
+ *  `base64 -d > /root/.claude/.credentials.json` used to clobber the live creds
+ *  to a 0-byte file AND still report success, because the pipeline's exit status
+ *  is the sink's, not the empty upstream's. This mirrors the non-empty `-s` guard
+ *  the git-cred cache path already uses (scripts/cloud-editor-entrypoint.sh).
+ *
+ *  `decode:true` base64-decodes stdin (the donor / host-stash cred copies);
+ *  `decode:false` copies stdin verbatim (the Rebuild onboarding-state re-seed).
+ *
+ *  `requireCredentialShape:true` adds, ON TOP of the non-empty guard, a Claude
+ *  `.credentials.json` shape check before the `mv`: a positive plausible
+ *  `expiresAt` (rejects the observed corrupt-write `expiresAt: 0`) AND non-empty
+ *  access/refresh tokens. A non-empty-but-malformed donor (valid-looking file
+ *  with a sentinel expiry or empty tokens) therefore never overwrites the
+ *  target — closing the remaining gap the non-empty `[ -s ]` guard alone leaves.
+ *  The checks are quote-free single-quoted ERE patterns (no `"`), which stay
+ *  intact through the ssh→docker→`bash -c "…"` quoting layers without escaping.
+ *  The editor-side self-heal (control-api `creds_refresh` / `auth_session`)
+ *  remains the durable defense against a bad credential from ANY writer; this
+ *  hardens the in-repo copy path so it is not itself a source.
+ *
+ *  Deliberately uses NO shell variables or command substitution: a fixed
+ *  `<target>.cytmp` sibling keeps the script free of `$var`, which the VM-host
+ *  shell that runs the `gcloud … --command` would otherwise expand (to empty)
+ *  before docker exec ever sees it. The `.cytmp` sibling sits in the same
+ *  directory as `target`, so the `mv` is an atomic same-filesystem rename. */
+function verifyBeforeMoveSink(
+  container,
+  target,
+  { decode = true, requireCredentialShape = false } = {},
+) {
+  const tmp = `${target}.cytmp`;
+  const read = decode ? "base64 -d" : "cat";
+  // Positive plausible `expiresAt` (13+ digit millis, first digit non-zero — so
+  // `0`/negatives/tiny values fail), plus non-empty access + refresh tokens
+  // (≥20 token-ish chars). `[^0-9-]*` / `[^A-Za-z0-9]*` bridge the `":"`
+  // punctuation without literal quotes; the value `0` in a corrupt file is a
+  // digit that blocks the skip, so the pattern can't false-match a later field.
+  const shape = requireCredentialShape
+    ? ` && grep -Eq 'expiresAt[^0-9-]*[1-9][0-9]{12,}' ${tmp}` +
+      ` && grep -Eq 'accessToken[^A-Za-z0-9]*[A-Za-z0-9_-]{20,}' ${tmp}` +
+      ` && grep -Eq 'refreshToken[^A-Za-z0-9]*[A-Za-z0-9_-]{20,}' ${tmp}`
+    : "";
+  const script =
+    `umask 077; ${read} > ${tmp}; ` +
+    `if [ -s ${tmp} ]${shape}; then mv ${tmp} ${target} && chmod 600 ${target}; ` +
+    `else rm -f ${tmp}; exit 1; fi`;
+  return `docker exec -i ${container} bash -c "${script}"`;
+}
+
 /** Build the shell steps that seed a freshly-added VM's claude + git credentials,
  *  for the resolved `mode` (see `resolveCredsSource`). Returns an array of shell
  *  strings the caller newline-joins into the larger provisioning script — each
@@ -569,15 +864,22 @@ function _shq(s) { return `'${String(s).replace(/'/g, `'\\''`)}'`; }
  *
  *  Pure; no I/O. */
 function buildCredsSteps({ mode, refInst = "", inst, container, gcloud, zone, n, claudeCredsSrc = "" } = {}) {
-  const claudeSink = `docker exec -i ${container} bash -c "umask 077; base64 -d > /root/.claude/.credentials.json && chmod 600 /root/.claude/.credentials.json"`;
-  const claudeJsonSink = `docker exec -i ${container} bash -c "umask 077; base64 -d > /root/.claude.json && chmod 600 /root/.claude.json"`;
+  // The `.credentials.json` copy additionally validates the donor's credential
+  // shape (positive `expiresAt`, non-empty tokens) before overwriting — a
+  // non-empty-but-corrupt donor must not clobber a working target. The
+  // `.claude.json` (onboarding-state) copy has a different shape, so it keeps
+  // the plain non-empty guard.
+  const claudeSink = verifyBeforeMoveSink(container, "/root/.claude/.credentials.json", {
+    requireCredentialShape: true,
+  });
+  const claudeJsonSink = verifyBeforeMoveSink(container, "/root/.claude.json");
   const loginHint = `run: docker exec -it ${container} claude /login on ${inst}`;
   if (mode === "donor") {
     return [
       `echo "copying git creds from ${refInst}..."`,
       `${gcloud} compute ssh ${refInst} --tunnel-through-iap --zone=${zone} --command='cat $HOME/.codeyam-cloud-git-credentials' 2>/dev/null | ${gcloud} compute ssh ${inst} --tunnel-through-iap --zone=${zone} --command='umask 077; cat > $HOME/.codeyam-cloud-git-credentials' 2>/dev/null || echo "CY_DEGRADED git creds copy failed on VM-${n} — re-copy creds from a live donor (the agent can't git pull/push until then)"`,
       `echo "copying claude auth from ${refInst} (container->container)..."`,
-      `${gcloud} compute ssh ${refInst} --tunnel-through-iap --zone=${zone} --command='docker exec ${container} base64 /root/.claude/.credentials.json' 2>/dev/null | ${gcloud} compute ssh ${inst} --tunnel-through-iap --zone=${zone} --command=${_shq(claudeSink)} 2>/dev/null && echo "claude auth copied" || echo "CY_DEGRADED claude auth copy failed on VM-${n} — ${loginHint}"`,
+      `${gcloud} compute ssh ${refInst} --tunnel-through-iap --zone=${zone} --command='docker exec ${container} base64 /root/.claude/.credentials.json' 2>/dev/null | ${gcloud} compute ssh ${inst} --tunnel-through-iap --zone=${zone} --command=${_shq(claudeSink)} 2>/dev/null && echo "claude auth copied" || echo "CY_DEGRADED claude auth copy failed on VM-${n} (empty/unreadable/malformed donor — existing creds left untouched, not overwritten with a corrupt credential) — ${loginHint}"`,
       `echo "copying claude.json (onboarding state) from ${refInst} (container->container)..."`,
       `${gcloud} compute ssh ${refInst} --tunnel-through-iap --zone=${zone} --command='docker exec ${container} base64 /root/.claude.json' 2>/dev/null | ${gcloud} compute ssh ${inst} --tunnel-through-iap --zone=${zone} --command=${_shq(claudeJsonSink)} 2>/dev/null && echo "claude.json copied" || echo "CY_DEGRADED claude.json copy failed on VM-${n} — first interactive claude launch may show 'Select login method' menu; ${loginHint} once to complete onboarding"`,
     ];
@@ -628,7 +930,7 @@ function buildClaudeJsonPreserveSteps({ container, n = "", bakVar = "CY_CLAUDE_J
     `if docker exec ${container} cat /root/.claude.json > "$${bakVar}" 2>/dev/null && [ -s "$${bakVar}" ]; then echo "captured /root/.claude.json ($(wc -c < "$${bakVar}") bytes) to preserve onboarding state across recreate"; else echo "no /root/.claude.json to preserve (new container will use the image baseline)"; : > "$${bakVar}"; fi`,
   ];
   const restore = [
-    `if [ -s "$${bakVar}" ]; then docker exec -i ${container} bash -c 'umask 077; cat > /root/.claude.json && chmod 600 /root/.claude.json' < "$${bakVar}" && echo "re-seeded /root/.claude.json (onboarding state preserved across recreate)" || echo "CY_DEGRADED claude.json re-seed failed on VM-${n} after Rebuild — first interactive claude launch may show 'Select login method'; ${loginHint} once to complete onboarding"; else echo "no preserved /root/.claude.json; ${loginHint} if the Build tab shows the welcome menu"; fi`,
+    `if [ -s "$${bakVar}" ]; then ${verifyBeforeMoveSink(container, "/root/.claude.json", { decode: false })} < "$${bakVar}" && echo "re-seeded /root/.claude.json (onboarding state preserved across recreate)" || echo "CY_DEGRADED claude.json re-seed failed on VM-${n} after Rebuild — first interactive claude launch may show 'Select login method'; ${loginHint} once to complete onboarding"; else echo "no preserved /root/.claude.json; ${loginHint} if the Build tab shows the welcome menu"; fi`,
     `rm -f "$${bakVar}"`,
   ];
   return { capture, restore };
@@ -652,6 +954,69 @@ function buildEnvApplyCommand({ gcloud, instance, zone, envFile, container, edit
   return `base64 < ${_shq(envFile)} | ${gcloud} compute ssh ${instance} --tunnel-through-iap --zone=${zone} --command=${_shq(sink)}`;
 }
 
+/** Build the `nohup … gcloud compute ssh … -N -L …` shell string that opens the
+ *  EDITOR reachability forward (`editorPort` → VM:14199) as its OWN ssh process,
+ *  logging to `/tmp/ssh-tunnel-vm-<n>.log`. The editor forward is the dashboard's
+ *  reachability signal — the probe to `PORT_BASE+N` connects through it — so it
+ *  must have a lifetime INDEPENDENT of the preview forward (whose port legitimately
+ *  changes as the app's dev server is resolved). Splitting the two forwards into
+ *  separate ssh processes is what makes a preview re-wire non-disruptive: a
+ *  preview-port change restarts only the preview tunnel and never blips :14199, so
+ *  the reachability probe can't flip the VM to a false "unreachable" (the
+ *  VM-1/2/3 flapping observed 2026-06-22). Pairs with `previewTunnelCmd`; the two
+ *  builders are the single source of truth for the attach (addVm) and re-wire call
+ *  sites so neither forward's `-L` spec can drift back into the other's process.
+ *  Pure; no I/O. */
+function editorTunnelCmd({ gcloud, inst, zone, editorPort, n } = {}) {
+  return `nohup ${gcloud} compute ssh ${inst} --tunnel-through-iap --zone=${zone} -- -N -L ${editorPort}:127.0.0.1:14199 > /tmp/ssh-tunnel-vm-${n}.log 2>&1 &`;
+}
+
+/** Build the `nohup … gcloud compute ssh … -N -L …` shell string that opens the
+ *  LIVE-PREVIEW forward (`previewPort` → VM:<appPort>) as its OWN ssh process,
+ *  logging to `/tmp/ssh-preview-vm-<n>.log`. The preview forward's target port
+ *  changes whenever the app's dev-server port is (re)resolved, so it lives apart
+ *  from the editor reachability forward (`editorTunnelCmd`): a preview re-wire
+ *  pkills + respawns ONLY this process, leaving the editor :14199 forward — and
+ *  the reachability probe riding it — untouched. The preview local port is unique
+ *  per VM and never collides with the editor port, so the re-wire/destroy
+ *  `pkill -f "<previewPort>:127.0.0.1:"` targets exactly this process. Pure; no
+ *  I/O. */
+function previewTunnelCmd({ gcloud, inst, zone, previewPort, appPort, n } = {}) {
+  return `nohup ${gcloud} compute ssh ${inst} --tunnel-through-iap --zone=${zone} -- -N -L ${previewPort}:127.0.0.1:${appPort} > /tmp/ssh-preview-vm-${n}.log 2>&1 &`;
+}
+
+/** Build the shell snippet the Add script runs to AWAIT cloud:up's clean exit at
+ *  container-healthy instead of reaping it mid-flight.
+ *
+ *  History — two bugs, one helper: (1) vm-add-ingress-survives-bes-create: the Add
+ *  used to `kill $UP_PID` ~15s after the container was Up, SIGTERMing
+ *  `backend-services create` mid-flight (the 503 strand), so this began polling
+ *  `cloud:up` to exit on its own rather than reaping it. (2)
+ *  vm--async-add-time-lb-ingress-wiring: `cloud:up` no longer BLOCKS on the wiring
+ *  tail — it kicks the EXTERNAL_MANAGED `backend-services create` + propagation off
+ *  DETACHED (see cloud.js startDetachedAddWiring) and returns at container-healthy,
+ *  so the detached child can no longer be reaped by anything that kills `cloud:up`.
+ *  This poll therefore now resolves in ~seconds on the happy path (cloud:up has
+ *  already exited); it stays only as the bounded backstop that reaps a `cloud:up`
+ *  genuinely wedged BEFORE the early return (e.g. a stuck container gate). The
+ *  background wiring converges via the dashboard's auto-rewire gather, so
+ *  `deadlineSec` shrinks from the old 900s wiring budget to a container-readiness
+ *  bound. `pidVar` is referenced by name so it expands at run time. Pure; no I/O. */
+function awaitWiringCmd({ inst, deadlineSec = 180, pidVar = "UP_PID" } = {}) {
+  return [
+    `echo "awaiting cloud:up exit at container-healthy for ${inst} (up to ${deadlineSec}s; LB wiring converges in the background)..."`,
+    `__cy_wiring_waited=0`,
+    `while kill -0 $${pidVar} 2>/dev/null; do`,
+    `  if [ "$__cy_wiring_waited" -ge ${deadlineSec} ]; then`,
+    `    echo "WARN cloud:up still running after ${deadlineSec}s (wedged before the container-healthy early return) — reaping it (the dashboard self-heal will converge any half-wired backend)"`,
+    `    kill $${pidVar} 2>/dev/null; pkill -f "cloud.js up --instance-name ${inst}" 2>/dev/null; break`,
+    `  fi`,
+    `  sleep 5; __cy_wiring_waited=$((__cy_wiring_waited + 5))`,
+    `done`,
+    `wait $${pidVar} 2>/dev/null || true`,
+  ].join("\n");
+}
+
 /** Get authenticated Git URL for checking client branch. */
 function getAuthRepoUrl(repo, token) {
   if (!repo) return "";
@@ -697,6 +1062,7 @@ module.exports = {
   EMPTY_CONFIG,
   normalizeLaunchConfig,
   validateLaunchConfig,
+  addPreflight,
   isVariantProvisionable,
   isVariantRebuildable,
   variantNpmDistTag,
@@ -711,17 +1077,28 @@ module.exports = {
   recentLaunchDisplay,
   defaultConfig,
   configForVm,
+  latestLaunchTs,
+  recentlyLaunchedWithin,
   resolveCardIdentity,
   stickyClientProject,
+  stickyAppPort,
+  stickyPreviewReachable,
+  stickyPreviewServing,
   classifyProjectKind,
   resolveCredsSource,
+  claudeAuthSeeded,
   buildCredsSteps,
+  verifyBeforeMoveSink,
   buildClaudeJsonPreserveSteps,
   buildEnvApplyCommand,
   resolveEditorSource,
   editorSourceShellResolve,
   rebuildStrategy,
   decideStartJob,
+  editorTunnelCmd,
+  previewTunnelCmd,
+  awaitWiringCmd,
   getAuthRepoUrl,
   interpretLsRemote,
+  isPlaceholderProject,
 };