@codeyam-editor/codeyam-editor 0.1.4 → 0.1.5

package/npm/ingress-invoke.js

@@ -0,0 +1,292 @@
+'use strict';
+// Pure builders for the LOCAL shell invocations that wire the fleet's Google
+// HTTPS Load Balancer ingress: the shared, VM-independent infra
+// (scripts/gcp/google-ingress.sh) and one VM's per-surface backends
+// (scripts/gcp/vm-ingress.sh). cloud.js calls these to decide WHEN to wire and
+// to build the exact `{ command, args, env }` it spawns — keeping the decision
+// and the argv/env shape unit-testable without ever spawning a process, exactly
+// like npm/vm-urls.js and npm/google-ingress.js single-source their derivations.
+//
+// Pure logic only — no I/O, no env reads beyond the explicit `env`/`cfg`
+// arguments callers pass in. The fleet domain governing ingress comes from the
+// project's `.codeyam/cloud.json` (`fleetDomain`, persisted by cloud.js) with a
+// `FLEET_DOMAIN` env fallback; when neither is set every builder reports the
+// legacy quick-tunnel mode (resolveIngressDomain → null) and cloud.js leaves the
+// Add/Destroy path byte-for-byte unchanged.
+//
+// Stack note: this is fleet-operator infrastructure (the cloud GCE fleet that
+// runs codeyam-editor itself), GCP-specific by design — the same posture as the
+// scripts it invokes. A project that never joins the fleet never sets
+// fleetDomain and never reaches a builder here.
+
+const { resolveFleetDomain } = require('./vm-urls');
+
+// Cloud DNS managed-zone name google-ingress.sh defaults to. Mirrored here so a
+// cloud.json without an explicit `dnsZone` resolves to the same zone the script
+// would, rather than passing an empty DNS_ZONE that shadows the script default.
+const DEFAULT_DNS_ZONE = 'fleet-zone';
+
+/** Resolve the fleet domain that governs ingress wiring, or null when none is
+ *  configured (legacy quick-tunnel mode). `cfg.fleetDomain` (persisted in
+ *  cloud.json) wins; the `FLEET_DOMAIN` env value is the fallback. Both paths go
+ *  through vm-urls.js::resolveFleetDomain, so a present-but-malformed value
+ *  throws here (a typo'd domain must fail loud, never bake a dead host into the
+ *  URL map) and a blank value reads as "unset". */
+function resolveIngressDomain(cfg = {}, env = {}) {
+  const fromCfg = cfg.fleetDomain;
+  if (fromCfg != null && String(fromCfg).trim() !== '') {
+    return resolveFleetDomain({ FLEET_DOMAIN: fromCfg });
+  }
+  return resolveFleetDomain(env);
+}
+
+/** Resolve the Cloud DNS managed-zone name: `cfg.dnsZone`, then a `DNS_ZONE`
+ *  env override, then the `fleet-zone` default google-ingress.sh itself uses. */
+function resolveDnsZone(cfg = {}, env = {}) {
+  const fromCfg = cfg.dnsZone;
+  if (fromCfg != null && String(fromCfg).trim() !== '') return String(fromCfg).trim();
+  const fromEnv = env.DNS_ZONE;
+  if (fromEnv != null && String(fromEnv).trim() !== '') return String(fromEnv).trim();
+  return DEFAULT_DNS_ZONE;
+}
+
+/** Derive the GCE region from a zone (`us-central1-a` → `us-central1`), or null
+ *  when the zone is missing/unparseable so the caller omits REGION and lets
+ *  google-ingress.sh apply its own default. A GCE zone is a region plus a
+ *  trailing `-<letter>`. */
+function regionFromZone(zone) {
+  if (zone == null) return null;
+  const z = String(zone).trim();
+  if (z === '') return null;
+  const m = /^(.+)-[a-z]$/.exec(z);
+  return m ? m[1] : null;
+}
+
+/** Build the local invocation for `scripts/gcp/vm-ingress.sh <N> <up|down>` —
+ *  one VM's per-surface NEG → IAP backend → URL-map host rule. Returns
+ *  `{ command, args, env }`; `env` carries only the keys the script reads beyond
+ *  its own defaults (GCP_PROJECT, ZONE, FLEET_DOMAIN, APP_PORT, INSTANCE_PREFIX,
+ *  VM_SLUG). `appPort` is the resolved per-project dev-server port the preview
+ *  NEG targets; omit it (down, or unknown) to let the script's bootstrap default
+ *  stand. An optional `slug` becomes `VM_SLUG`, which makes the script route the
+ *  VM's custom `<slug>.<surface>.<domain>` host (the same slug must be passed on
+ *  `down` so the matching host rule is removed); omit it to keep the numeric
+ *  `vm-<N>` host. */
+function vmIngressInvocation({
+  scriptPath,
+  vmNumber,
+  action,
+  domain,
+  project,
+  zone,
+  appPort,
+  instancePrefix,
+  slug,
+} = {}) {
+  if (!scriptPath) throw new Error('vmIngressInvocation requires scriptPath');
+  if (action !== 'up' && action !== 'down') {
+    throw new Error(`vm-ingress action must be 'up' or 'down', got: ${action}`);
+  }
+  const n = Number(vmNumber);
+  if (!Number.isInteger(n) || n <= 0) {
+    throw new Error(`vm-ingress requires a positive VM number, got: ${vmNumber}`);
+  }
+  if (!domain) throw new Error('vmIngressInvocation requires a fleet domain');
+  const env = { FLEET_DOMAIN: domain };
+  if (project) env.GCP_PROJECT = project;
+  if (zone) env.ZONE = zone;
+  if (appPort != null && String(appPort).trim() !== '') env.APP_PORT = String(appPort);
+  if (instancePrefix) env.INSTANCE_PREFIX = instancePrefix;
+  if (slug != null && String(slug).trim() !== '') env.VM_SLUG = String(slug).trim();
+  return { command: 'bash', args: [scriptPath, String(n), action], env };
+}
+
+/** Build the local invocation for `scripts/gcp/vm-ingress.sh <N> status` — the
+ *  read-only probe that reports which of {NEG, backend service, host rule} exist
+ *  per surface plus an overall `verdict=wired|partial|unwired`. Returns
+ *  `{ command, args, env }`. Like `vmIngressInvocation` but the action is fixed
+ *  to `status` and APP_PORT is omitted — status describes resources by NAME, and
+ *  names key off the VM number, never the port. An optional `slug` rides through
+ *  as VM_SLUG so the host-rule presence check matches the VM's custom
+ *  `<slug>.<surface>.<domain>` host rather than the numeric `vm-<N>` one. */
+function vmIngressStatusInvocation({
+  scriptPath,
+  vmNumber,
+  domain,
+  project,
+  zone,
+  slug,
+} = {}) {
+  if (!scriptPath) throw new Error('vmIngressStatusInvocation requires scriptPath');
+  const n = Number(vmNumber);
+  if (!Number.isInteger(n) || n <= 0) {
+    throw new Error(`vm-ingress status requires a positive VM number, got: ${vmNumber}`);
+  }
+  if (!domain) throw new Error('vmIngressStatusInvocation requires a fleet domain');
+  const env = { FLEET_DOMAIN: domain };
+  if (project) env.GCP_PROJECT = project;
+  if (zone) env.ZONE = zone;
+  if (slug != null && String(slug).trim() !== '') env.VM_SLUG = String(slug).trim();
+  return { command: 'bash', args: [scriptPath, String(n), 'status'], env };
+}
+
+/** Parse the `verdict=<wired|partial|unwired>` line vm-ingress.sh `status`
+ *  prints, returning that verdict or null when the output carries none (e.g. the
+ *  script errored before emitting it). Pure string parsing so the reconcile
+ *  decision below stays unit-testable without spawning the script. */
+function parseIngressStatusVerdict(stdout) {
+  if (typeof stdout !== 'string') return null;
+  for (const line of stdout.split('\n')) {
+    const m = /^verdict=(wired|partial|unwired)\s*$/.exec(line.trim());
+    if (m) return m[1];
+  }
+  return null;
+}
+
+/** Pick which rostered VMs reconcile must re-wire from their status verdicts.
+ *  `statuses` is `[{ vmNumber, verdict, ... }]`; a VM is selected iff its verdict
+ *  is `unwired` or `partial` (it has missing LB resources). `wired` VMs are left
+ *  untouched — no redundant gcloud churn — and an unknown/null verdict (the probe
+ *  failed) is conservatively SKIPPED rather than blindly re-wired. Returns the
+ *  selected entries in their input order, preserving any extra fields (slug) the
+ *  caller threads through. Pure. */
+function selectIngressReconcileTargets(statuses) {
+  if (!Array.isArray(statuses)) return [];
+  return statuses.filter((s) => s && (s.verdict === 'unwired' || s.verdict === 'partial'));
+}
+
+// =============================================================================
+// Async add-time wiring (vm--async-add-time-lb-ingress-wiring)
+// =============================================================================
+// The Add used to BLOCK ~10 min on synchronous LB ingress wiring even after the
+// container was healthy and serving. The fix returns the Add at container-healthy
+// and converges the wiring in a DETACHED background tail (wire → access, the same
+// ordering cmdUp ran inline) that outlives `cloud:up` — so the dashboard's reap of
+// `cloud:up` can never SIGTERM an in-flight `backend-services create` (the add-time
+// 503 strand the old 900s synchronous await was protecting against). The
+// already-existing per-VM auto-rewire gather is the convergence backstop; it must
+// NOT race the in-flight detached tail, so the tail drops an in-flight marker the
+// dashboard reads via the pure `isWiringInflight` below.
+
+/** Build the local invocation that re-execs THIS node entry (`scriptPath`, i.e.
+ *  cloud.js) as a DETACHED `wire-add-tail` child: it runs the slow wiring + access
+ *  grant in the background so the Add returns at container-healthy. Returns
+ *  `{ command, args, env }`; the child reads `cfg`/`appPort` back out of the env
+ *  (`CY_WIRE_ADD_CFG` JSON, `CY_WIRE_ADD_PORT`) rather than re-deriving them, so the
+ *  background tail wires EXACTLY what the foreground Add would have. `nodePath` is
+ *  the node executable to re-exec (caller passes `process.execPath`); kept a
+ *  parameter so this stays pure/testable without reading the ambient env. */
+function detachedAddTailInvocation({ nodePath, scriptPath, cfg, appPort } = {}) {
+  if (!nodePath) throw new Error('detachedAddTailInvocation requires nodePath');
+  if (!scriptPath) throw new Error('detachedAddTailInvocation requires scriptPath');
+  const env = { CY_WIRE_ADD_CFG: JSON.stringify(cfg || {}) };
+  if (appPort != null && String(appPort).trim() !== '') {
+    env.CY_WIRE_ADD_PORT = String(appPort);
+  }
+  return { command: nodePath, args: [scriptPath, 'wire-add-tail'], env };
+}
+
+/** The per-VM marker file the detached add-tail holds while its wiring is still
+ *  running, so the dashboard's auto-rewire gather skips a VM whose FIRST wiring
+ *  attempt is in flight (never firing a competing `vm-ingress.sh up`). Pure path
+ *  derivation; the create/unlink/stat I/O lives at the call sites (cloud.js writes
+ *  it, server.js reads it), mirroring how the status/verdict split keeps the
+ *  decision testable without touching the filesystem. */
+function ingressInflightMarkerPath(dir, vmNumber) {
+  const n = Number(vmNumber);
+  if (!Number.isInteger(n) || n <= 0) {
+    throw new Error(`ingressInflightMarkerPath requires a positive VM number, got: ${vmNumber}`);
+  }
+  return `${dir.replace(/\/+$/, '')}/cy-ingress-inflight-vm-${n}`;
+}
+
+/** Decide whether a freshly-added VM's detached wiring is still in flight, given
+ *  the marker file's CONTENTS (the unix-ms start timestamp the tail wrote) and the
+ *  current time. Returns false when the marker is missing/empty (`content` null) —
+ *  no tail running — or STALE (older than `maxAgeMs`): a tail that crashed without
+ *  unlinking its marker must not pin auto-rewire off forever, so once the staleness
+ *  bound (comfortably past the ~10-min worst-case wiring) elapses the backstop takes
+ *  over. Pure: the caller does the `readFileSync`/`existsSync`. */
+function isWiringInflight(content, now, maxAgeMs) {
+  if (content == null) return false;
+  const started = Number(String(content).trim());
+  if (!Number.isFinite(started) || started <= 0) return false;
+  return (Number(now) - started) < Number(maxAgeMs);
+}
+
+/** Build the local invocation for `scripts/gcp/iap-access.sh <N> <grant|revoke>`
+ *  — grant or revoke `roles/iap.httpsResourceAccessor` on one VM's per-surface
+ *  backend services for a set of principals (the per-VM access whitelist).
+ *  Returns `{ command, args, env }`; `env.VM_ACCESS` is the comma-joined,
+ *  trimmed principal list the script reads (omitted when empty, so a revoke with
+ *  nothing to remove is a clean no-op), plus GCP_PROJECT / ZONE when supplied.
+ *  Mirrors `vmIngressInvocation` so the spawn shape stays unit-testable without
+ *  ever invoking gcloud. The principal STRINGS are passed through verbatim —
+ *  validation/normalization is the sidecar's job (npm/fleet-vm-access.js); this
+ *  builder only shapes the argv/env. */
+function iapAccessInvocation({
+  scriptPath,
+  vmNumber,
+  action,
+  principals,
+  project,
+  zone,
+} = {}) {
+  if (!scriptPath) throw new Error('iapAccessInvocation requires scriptPath');
+  if (action !== 'grant' && action !== 'revoke') {
+    throw new Error(`iap-access action must be 'grant' or 'revoke', got: ${action}`);
+  }
+  const n = Number(vmNumber);
+  if (!Number.isInteger(n) || n <= 0) {
+    throw new Error(`iap-access requires a positive VM number, got: ${vmNumber}`);
+  }
+  const list = Array.isArray(principals)
+    ? principals
+    : String(principals == null ? '' : principals).split(',');
+  const joined = list.map((p) => String(p).trim()).filter(Boolean).join(',');
+  const env = {};
+  if (joined) env.VM_ACCESS = joined;
+  if (project) env.GCP_PROJECT = project;
+  if (zone) env.ZONE = zone;
+  return { command: 'bash', args: [scriptPath, String(n), action], env };
+}
+
+/** Build the local invocation for `scripts/gcp/google-ingress.sh` — the shared,
+ *  VM-independent LB infra (static IP, wildcard cert, Cloud DNS, URL map, IAP
+ *  brand). Returns `{ command, args, env }`; `env` carries only the keys the
+ *  script reads beyond its defaults (GCP_PROJECT, REGION, ZONE, FLEET_DOMAIN,
+ *  DNS_ZONE). The script is idempotent, so re-invoking against existing infra is
+ *  a safe no-op. */
+function sharedIngressInvocation({
+  scriptPath,
+  domain,
+  project,
+  zone,
+  dnsZone,
+  region,
+} = {}) {
+  if (!scriptPath) throw new Error('sharedIngressInvocation requires scriptPath');
+  if (!domain) throw new Error('sharedIngressInvocation requires a fleet domain');
+  const env = { FLEET_DOMAIN: domain };
+  if (project) env.GCP_PROJECT = project;
+  if (region) env.REGION = region;
+  if (zone) env.ZONE = zone;
+  if (dnsZone) env.DNS_ZONE = dnsZone;
+  return { command: 'bash', args: [scriptPath], env };
+}
+
+module.exports = {
+  DEFAULT_DNS_ZONE,
+  resolveIngressDomain,
+  resolveDnsZone,
+  regionFromZone,
+  vmIngressInvocation,
+  vmIngressStatusInvocation,
+  parseIngressStatusVerdict,
+  selectIngressReconcileTargets,
+  detachedAddTailInvocation,
+  ingressInflightMarkerPath,
+  isWiringInflight,
+  iapAccessInvocation,
+  sharedIngressInvocation,
+};

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,26 @@ 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 };
 }
 
@@ -123,6 +169,18 @@ 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
@@ -137,9 +195,10 @@ 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);
   // Greenfield (new folder) vs clone an existing repo.
   if (cfg.newProjectName) args.push("--new-project", cfg.newProjectName);
@@ -147,6 +206,15 @@ function cloudUpArgs(cfg, instanceName, project) {
   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 +381,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 +472,31 @@ 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;
+}
+
 /** 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,6 +655,21 @@ 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, `'\\''`)}'`; }
@@ -652,6 +782,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 "";
@@ -711,10 +904,14 @@ module.exports = {
   recentLaunchDisplay,
   defaultConfig,
   configForVm,
+  latestLaunchTs,
+  recentlyLaunchedWithin,
   resolveCardIdentity,
   stickyClientProject,
+  stickyAppPort,
   classifyProjectKind,
   resolveCredsSource,
+  claudeAuthSeeded,
   buildCredsSteps,
   buildClaudeJsonPreserveSteps,
   buildEnvApplyCommand,
@@ -722,6 +919,10 @@ module.exports = {
   editorSourceShellResolve,
   rebuildStrategy,
   decideStartJob,
+  editorTunnelCmd,
+  previewTunnelCmd,
+  awaitWiringCmd,
   getAuthRepoUrl,
   interpretLsRemote,
+  isPlaceholderProject,
 };