mango-cms 0.3.31 → 0.3.34

package/default/mango/config/settings.json

@@ -19,11 +19,6 @@
 	"mongoURI": "mongodb://127.0.0.1:27017",
 	"database": "exampleMongoDB",
 
-	"s3AccessKeyId": null,
-	"s3AccessKeySecret": null,
-	"s3Region": null,
-	"s3Bucket": "exampleBucket",
-
 	"emailProvider": "resend",
     "emailFrom": "Example <info@example.com>",
 	"resendKey": null,

package/lib/devProxyGateway.js

@@ -27,6 +27,14 @@
 
 export const DEFAULT_STAGING_PREFIX = 'staging.'
 
+// HAP-1188 (Option B): the container shell points its iframe at
+// `<branch>--<baseStagingHost>` so the branch travels in the Host header on the
+// iframe's document AND every one of its sub-resource + HMR-WS requests — sticky
+// per-branch with zero cookie pollution. This is the separator between the
+// branch prefix and the base staging host. The front builds it from
+// VITE_VIBE_SHELL_HOST_TEMPLATE="{branch}--staging-vibe.<site>".
+export const DEFAULT_BRANCH_HOST_SEPARATOR = '--'
+
 // Header / cookie the editing surface (and the orchestrator) use to carry the
 // SELECTED BRANCH with a staging request (HAP-1164). The branch — not the session
 // identity — is what the resolver demuxes on, so it must travel with every
@@ -120,37 +128,84 @@ export function hasBranchSignal(req) {
     return false
 }
 
-// Pure: does this request's Host header look like a staging request, and what
-// site slug does it resolve to?
+// Internal: match an already-normalized (port-stripped, trimmed, lowercased)
+// hostname as a staging host, returning { hostname, slug } | null. This is the
+// pre-HAP-1188 matcher, factored out so the branch-in-hostname peeling below can
+// reuse it on the host's remainder.
 //
 // Matches in this order:
-//   1. exact match against opts.stagingDomain (when configured) — slug is the
-//      part of the hostname after the staging prefix, or the full hostname if
-//      it doesn't have one.
-//   2. any hostname starting with opts.stagingHostPrefix (defaults to
-//      "staging.") — slug is the part after that prefix.
-//
-// Returns null when no match, or when the slug would be empty. Port suffixes
-// (":80") and case are normalized away so the matcher is stable across
-// browsers, curl, and the Vite HMR upgrade.
-export function parseStagingHost(hostHeader, opts = {}) {
-    if (!hostHeader) return null
-    const prefix = String(opts.stagingHostPrefix || DEFAULT_STAGING_PREFIX).toLowerCase()
-    const hostname = String(hostHeader).split(':')[0].trim().toLowerCase()
+//   1. exact match against `configured` (opts.stagingDomain, when set) — slug is
+//      the part after the staging prefix, or the full hostname if it has none.
+//   2. any hostname starting with `prefix` (defaults to "staging.") — slug is the
+//      part after that prefix.
+function matchStagingBase(hostname, prefix, configured) {
     if (!hostname) return null
-
-    const configured = opts.stagingDomain ? String(opts.stagingDomain).toLowerCase() : null
     if (configured && hostname === configured) {
         const slug = hostname.startsWith(prefix) ? hostname.slice(prefix.length) : hostname
         if (!slug) return null
         return { hostname, slug }
     }
-
     if (hostname.startsWith(prefix)) {
         const slug = hostname.slice(prefix.length)
         if (!slug) return null
         return { hostname, slug }
     }
+    return null
+}
+
+// Pure: does this request's Host header look like a staging request, what site
+// slug does it resolve to, and — when the container shell encodes the branch in
+// the hostname (HAP-1188, Option B) — which branch?
+//
+// Returns null when no match, or when the slug would be empty. Port suffixes
+// (":80") and case are normalized away so the matcher is stable across
+// browsers, curl, and the Vite HMR upgrade.
+//
+// Branch-in-hostname (HAP-1188): a host of the form `<branch>--<baseStagingHost>`
+// resolves to the same { hostname, slug } as `<baseStagingHost>` PLUS a `branch`
+// field. The gateway treats that host-branch as a deliberate branch signal, so
+// the iframe's document, modules, AND HMR WebSocket all demux to the one branch's
+// dev server — no `?branch=` on sub-resources, no origin-wide cookie. The shell
+// host (`<baseStagingHost>`, no `--` prefix) carries no branch and is unaffected.
+export function parseStagingHost(hostHeader, opts = {}) {
+    if (!hostHeader) return null
+    const prefix = String(opts.stagingHostPrefix || DEFAULT_STAGING_PREFIX).toLowerCase()
+    const sep = String(opts.branchHostSeparator ?? DEFAULT_BRANCH_HOST_SEPARATOR)
+    const raw = String(hostHeader).split(':')[0].trim()
+    if (!raw) return null
+    const hostname = raw.toLowerCase()
+    const configured = opts.stagingDomain ? String(opts.stagingDomain).toLowerCase() : null
+
+    // Fast path: the shell host and every pre-HAP-1188 staging host (no branch
+    // prefix) match directly. This also means a plain host is never misread as a
+    // branch-prefixed one.
+    const direct = matchStagingBase(hostname, prefix, configured)
+    if (direct) return direct
+
+    // Branch-in-hostname: peel a leading `<branch>--` and match the REMAINDER as
+    // an ordinary staging host. Scan separator positions left→right and accept
+    // the first split whose remainder is a valid base host — so a branch whose
+    // sanitized form itself contains `--` (e.g. two non-git chars in a row) still
+    // resolves to the real base host rather than splitting in the middle.
+    if (sep) {
+        let from = 0
+        let idx
+        while ((idx = hostname.indexOf(sep, from)) > 0) {
+            const base = matchStagingBase(hostname.slice(idx + sep.length), prefix, configured)
+            if (base) {
+                // Slice the ORIGINAL-case host for the branch (toLowerCase keeps
+                // length, so `idx` is valid in both). Browsers usually lowercase
+                // the whole Host, but don't assume it. Percent-decode because the
+                // front builds the prefix with encodeURIComponent(sanitizeBranch()).
+                const rawBranch = raw.slice(0, idx)
+                let branch = rawBranch
+                try { branch = decodeURIComponent(rawBranch) } catch { /* keep raw */ }
+                branch = branch.trim()
+                return branch ? { ...base, branch } : base
+            }
+            from = idx + sep.length
+        }
+    }
 
     return null
 }
@@ -170,7 +225,7 @@ export function parseStagingHost(hostHeader, opts = {}) {
 //   no_workspace      (404) — resolver returned nothing for (user, slug)
 //   resolver_error    (502) — resolver threw / returned a bad shape
 //   forbidden         (403) — resolver explicitly refused (e.g. wrong site)
-export async function resolveStagingTarget({ req, slug, resolve }) {
+export async function resolveStagingTarget({ req, slug, resolve, branch }) {
     if (typeof resolve !== 'function') {
         return { error: 'resolver_error', status: 502, message: 'No staging resolver configured' }
     }
@@ -184,13 +239,19 @@ export async function resolveStagingTarget({ req, slug, resolve }) {
         }
     }
 
-    // The SELECTED BRANCH (HAP-1164) travels with the request and is what the
-    // resolver demuxes on. Absent → resolver falls back to the configured default.
-    const branch = parseBranchFromReq(req)
+    // The SELECTED BRANCH (HAP-1164) is what the resolver demuxes on. It travels
+    // either in the Host header (HAP-1188 branch-in-hostname, passed in here as
+    // `branch` by the gateway) or on the request itself (x-vibe-branch / ?branch=
+    // / vibe_branch cookie). An explicit host-branch wins — it's the most
+    // deliberate signal and is what keeps the iframe's sub-resources sticky.
+    // Absent → resolver falls back to the configured default.
+    const selectedBranch = (branch != null && String(branch).trim())
+        ? String(branch).trim()
+        : parseBranchFromReq(req)
 
     let result
     try {
-        result = await resolve({ slug, branch, cookieHeader, authHeader, req })
+        result = await resolve({ slug, branch: selectedBranch, cookieHeader, authHeader, req })
     } catch (err) {
         return { error: 'resolver_error', status: 502, message: `Vibe staging resolver error: ${err?.message || err}` }
     }
@@ -330,6 +391,107 @@ export function createHttpResolver({
     }
 }
 
+/**
+ * Build a single-shot TCP readiness probe from node's `net` module (HAP-1215).
+ *
+ * Returns `probe(port) -> Promise<boolean>` that resolves `true` iff a TCP
+ * connection to 127.0.0.1:<port> succeeds within `connectTimeoutMs`, else
+ * `false` (never rejects). A per-branch `mango dev` binds its port only once
+ * Vite has finished booting, so "can I open a socket" is the cheapest accurate
+ * signal that the workspace is ready to be proxied to. `net` is injected so the
+ * module stays import-free and unit-testable with a plain fake.
+ */
+export function createTcpReadinessProbe(net, { connectTimeoutMs = 1000 } = {}) {
+    if (!net || typeof net.connect !== 'function') {
+        throw new Error('createTcpReadinessProbe: net module with connect() is required')
+    }
+    return function probe(port) {
+        return new Promise((resolve) => {
+            let done = false
+            const finish = (ready, sock) => {
+                if (done) return
+                done = true
+                try { sock && sock.destroy() } catch { /* noop */ }
+                resolve(ready)
+            }
+            let sock
+            try {
+                sock = net.connect({ host: '127.0.0.1', port })
+            } catch {
+                return resolve(false)
+            }
+            sock.setTimeout(connectTimeoutMs, () => finish(false, sock))
+            sock.once('connect', () => finish(true, sock))
+            sock.once('error', () => finish(false, sock))
+        })
+    }
+}
+
+/**
+ * Branded "your branch preview is starting" interstitial (HAP-1215).
+ *
+ * Served (HTTP 503 + Retry-After) when a request resolved to a real per-branch
+ * workspace but that workspace's dev server has not bound its port within the
+ * bounded readiness window — a genuinely cold `mango dev` start on the 1vcpu
+ * droplet. This REPLACES the raw "Bad gateway: ECONNREFUSED" 502 the proxy would
+ * otherwise emit, so the owner sees a clear, self-refreshing status instead of an
+ * unbounded white/coffee screen. The page auto-reloads, and each reload re-probes
+ * with the same bounded budget — so the user converges to the live preview the
+ * instant the server is up, or keeps seeing a clear, actionable error if it never
+ * comes up. Never an indefinite hang.
+ */
+export function renderBootingPage({ branch = '', retryAfterSeconds = 5 } = {}) {
+    const safeBranch = String(branch).replace(/[<>&"]/g, (c) => (
+        { '<': '&lt;', '>': '&gt;', '&': '&amp;', '"': '&quot;' }[c]
+    ))
+    const branchLine = safeBranch
+        ? `<p class="branch">branch <code>${safeBranch}</code></p>`
+        : ''
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta http-equiv="refresh" content="${retryAfterSeconds}">
+<title>Starting your preview…</title>
+<style>
+  :root { color-scheme: light dark; }
+  html, body { height: 100%; margin: 0; }
+  body {
+    display: flex; align-items: center; justify-content: center;
+    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+    background: #0f1115; color: #e8eaed;
+  }
+  .card { max-width: 28rem; padding: 2.5rem 2rem; text-align: center; }
+  .spinner {
+    width: 38px; height: 38px; margin: 0 auto 1.5rem;
+    border: 3px solid rgba(255,255,255,0.18); border-top-color: #7aa2f7;
+    border-radius: 50%; animation: spin 0.9s linear infinite;
+  }
+  @keyframes spin { to { transform: rotate(360deg); } }
+  h1 { font-size: 1.25rem; font-weight: 600; margin: 0 0 0.5rem; }
+  p { margin: 0.35rem 0; color: #9aa0ac; font-size: 0.95rem; line-height: 1.5; }
+  .branch code { color: #c0caf5; background: rgba(122,162,247,0.12); padding: 0.1rem 0.4rem; border-radius: 4px; }
+  button {
+    margin-top: 1.5rem; padding: 0.6rem 1.4rem; font-size: 0.95rem; cursor: pointer;
+    color: #0f1115; background: #7aa2f7; border: 0; border-radius: 8px; font-weight: 600;
+  }
+  button:hover { background: #93b4ff; }
+</style>
+</head>
+<body>
+  <main class="card">
+    <div class="spinner" role="status" aria-label="Loading"></div>
+    <h1>Your preview is starting…</h1>
+    <p>The branch server is booting. This usually takes a few seconds on first load.</p>
+    ${branchLine}
+    <p>This page refreshes automatically. If it doesn't load shortly, the branch may have failed to start — retry below.</p>
+    <button type="button" onclick="location.reload()">Retry now</button>
+  </main>
+</body>
+</html>`
+}
+
 /**
  * Standalone staging-gateway server factory (HAP-1165).
  *
@@ -348,6 +510,9 @@ export function createHttpResolver({
  *   - Non-staging host → 404 with a clear message (no misroute).
  *   - Resolver errors (403/404/502) → surfaced as the resolver's HTTP status.
  *   - Upgrade-time resolver failure → socket destroyed (Vite retries the WS).
+ *   - Cold workspace not yet listening (HAP-1215) → bounded readiness poll, then a
+ *     branded self-refreshing "starting" page (503) instead of a raw ECONNREFUSED
+ *     502. Opt-in via `readinessProbe` (off → proxy immediately, legacy behavior).
  *
  * Page-load auth (HAP-1175, supersedes HAP-1173): a top-level browser navigation
  * MUST never 401, regardless of what cookies it carries. Real browsers attach
@@ -374,6 +539,13 @@ export function createStagingGatewayServer({
     timeoutMs,
     fallbackPort,
     onError,
+    // HAP-1215 cold-boot bounded-readiness (all optional — gating is OFF unless a
+    // probe is supplied, so existing callers/tests are unaffected):
+    readinessProbe,             // (port) => Promise<boolean readyNow>; e.g. createTcpReadinessProbe(net)
+    readinessTimeoutMs = 25000, // total bounded wait for a cold workspace to bind its port
+    readinessIntervalMs = 500,  // delay between probe attempts
+    renderBootPage = renderBootingPage, // injectable for tests
+    setTimeoutFn = setTimeout,  // injectable for deterministic tests
 } = {}) {
     if (!http || typeof http.createServer !== 'function') {
         throw new Error('createStagingGatewayServer: http module with createServer() is required')
@@ -387,6 +559,9 @@ export function createStagingGatewayServer({
     if (fallbackPort != null && (!Number.isInteger(fallbackPort) || fallbackPort <= 0 || fallbackPort > 65535)) {
         throw new Error('createStagingGatewayServer: fallbackPort, if set, must be an integer in 1..65535')
     }
+    if (readinessProbe != null && typeof readinessProbe !== 'function') {
+        throw new Error('createStagingGatewayServer: readinessProbe, if set, must be a function')
+    }
 
     const resolve = createHttpResolver({ backendPort, resolverPath, timeoutMs, http })
     const proxy = httpProxy.createProxyServer({ ws: true, xfwd: true })
@@ -396,6 +571,54 @@ export function createStagingGatewayServer({
         if (typeof onError === 'function') onError(where, err, req)
     }
 
+    // HAP-1215: a genuinely cold per-branch `mango dev` can take ~10–60s to bind
+    // its port on the 1vcpu droplet. Without this, the first request after resolve
+    // hits a not-yet-listening port and the proxy emits a raw ECONNREFUSED 502 (an
+    // unbounded "coffee screen" as the browser/owner keep retrying into 502s). This
+    // polls the resolved port for a bounded window; the caller serves the live
+    // proxy the instant it's up, or a clear branded error if the budget elapses.
+    // Returns true if the port became connectable within the window, false on timeout.
+    async function waitForReady(port) {
+        if (typeof readinessProbe !== 'function') return true // gating disabled
+        const maxAttempts = Math.max(1, Math.ceil(readinessTimeoutMs / Math.max(1, readinessIntervalMs)))
+        for (let attempt = 0; attempt < maxAttempts; attempt++) {
+            let ready = false
+            try {
+                ready = await readinessProbe(port)
+            } catch {
+                ready = false
+            }
+            if (ready) return true
+            if (attempt < maxAttempts - 1) {
+                await new Promise((r) => setTimeoutFn(r, readinessIntervalMs))
+            }
+        }
+        return false
+    }
+
+    function sendBootingPage(req, res, branch) {
+        if (!res || res.headersSent) return
+        const wantsHtml = /\btext\/html\b/.test(String(req?.headers?.accept || ''))
+        const retryAfter = Math.max(1, Math.round(readinessIntervalMs / 1000) || 3)
+        if (wantsHtml) {
+            const html = renderBootPage({ branch, retryAfterSeconds: retryAfter })
+            res.writeHead(503, {
+                'Content-Type': 'text/html; charset=utf-8',
+                'Retry-After': String(retryAfter),
+                'Cache-Control': 'no-store',
+            })
+            res.end(html)
+        } else {
+            // Non-navigation (asset/XHR): a short, bounded 503 the client can retry.
+            res.writeHead(503, {
+                'Content-Type': 'text/plain; charset=utf-8',
+                'Retry-After': String(retryAfter),
+                'Cache-Control': 'no-store',
+            })
+            res.end('Vibe staging: branch preview is starting — retry shortly')
+        }
+    }
+
     proxy.on('error', (err, req, res) => {
         log('proxy', err, req)
         if (res && typeof res.writeHead === 'function' && !res.headersSent) {
@@ -424,12 +647,15 @@ export function createStagingGatewayServer({
             sendError(res, 404, `Unknown host: ${req?.headers?.host || '(missing Host header)'}`)
             return
         }
-        // HAP-1175: default route is the shared fallback front. Only requests
-        // that carry a deliberate branch signal (vibe_branch cookie, x-vibe-branch
-        // header, or ?branch= URL param) attempt per-branch resolution. A returning
-        // browser with stale session cookies but no branch signal — the case that
-        // re-broke staging in HAP-1175 — passes straight through here.
-        if (!hasBranchSignal(req)) {
+        // HAP-1175 / HAP-1188: default route is the shared fallback front. Only
+        // requests that carry a DELIBERATE branch signal attempt per-branch
+        // resolution — the branch in the Host header (HAP-1188, `<branch>--<host>`),
+        // a vibe_branch cookie, an x-vibe-branch header, or a ?branch= URL param.
+        // A returning browser with stale session cookies but no branch signal —
+        // the case that re-broke staging in HAP-1175 — passes straight through to
+        // the fallback. The shell host has no host-branch, so it lands here too.
+        const hostBranch = parsed.branch || ''
+        if (!hostBranch && !hasBranchSignal(req)) {
             if (fallbackTarget) {
                 proxy.web(req, res, { target: fallbackTarget })
                 return
@@ -437,7 +663,7 @@ export function createStagingGatewayServer({
             sendError(res, 401, 'Vibe staging: no branch signal and no fallback configured')
             return
         }
-        const outcome = await resolveStagingTarget({ req, slug: parsed.slug, resolve })
+        const outcome = await resolveStagingTarget({ req, slug: parsed.slug, resolve, branch: hostBranch })
         if (outcome.error) {
             // HAP-1175: even with a branch signal, a failed resolve falls back
             // to the shared front rather than 401-ing the page load. Hard errors
@@ -449,6 +675,17 @@ export function createStagingGatewayServer({
             sendError(res, outcome.status || 502, outcome.message || outcome.error)
             return
         }
+        // HAP-1215: the resolve succeeded, but a cold per-branch dev server may not
+        // have bound its port yet. Briefly poll (bounded) before proxying; on
+        // timeout serve a branded self-refreshing "starting" page instead of the
+        // raw ECONNREFUSED 502 the proxy would otherwise emit. Gating is a no-op
+        // (returns true immediately) when no readinessProbe is configured.
+        const ready = await waitForReady(outcome.port)
+        if (!ready) {
+            log('readiness', new Error(`workspace port ${outcome.port} not ready within ${readinessTimeoutMs}ms`), req)
+            sendBootingPage(req, res, hostBranch || parseBranchFromReq(req))
+            return
+        }
         proxy.web(req, res, { target: outcome.target })
     }
 
@@ -458,11 +695,14 @@ export function createStagingGatewayServer({
             try { socket.destroy() } catch { /* noop */ }
             return
         }
-        // HAP-1175: same default-to-fallback rule as handleRequest. The Vite
-        // HMR upgrade for the shared shell rides without a branch signal; only
-        // after the picker fires does the next upgrade carry x-vibe-branch and
-        // resolve per-branch.
-        if (!hasBranchSignal(req)) {
+        // HAP-1175 / HAP-1188: same default-to-fallback rule as handleRequest.
+        // The shell's own HMR upgrade rides without a branch signal → fallback.
+        // The iframe's HMR WebSocket carries the branch in the Host header
+        // (`<branch>--<host>`), so it resolves to the SAME per-branch dev server
+        // as the iframe's document — this is what closes the dual-Vue / white-
+        // screen gap (HAP-1177 class) that `?branch=`-on-document-only left open.
+        const hostBranch = parsed.branch || ''
+        if (!hostBranch && !hasBranchSignal(req)) {
             if (fallbackTarget) {
                 proxy.ws(req, socket, head, { target: fallbackTarget })
                 return
@@ -470,7 +710,7 @@ export function createStagingGatewayServer({
             try { socket.destroy() } catch { /* noop */ }
             return
         }
-        const outcome = await resolveStagingTarget({ req, slug: parsed.slug, resolve })
+        const outcome = await resolveStagingTarget({ req, slug: parsed.slug, resolve, branch: hostBranch })
         if (outcome.error) {
             // Failed resolve on an upgrade: prefer the fallback over destroying
             // the socket so HMR keeps working through the shared front.

package/lib/staging-gateway.js

@@ -25,6 +25,13 @@
  *                                        request whose resolution fails. The
  *                                        shared front (HAP-1175). Set to 0 to
  *                                        disable and 401 those requests instead.
+ *   READINESS_TIMEOUT_MS (default 25000, int)  HAP-1215: after a successful
+ *                                        per-branch resolve, poll the workspace
+ *                                        port for up to this long before proxying,
+ *                                        so a cold `mango dev` boot shows a branded
+ *                                        "starting" page instead of a raw 502.
+ *                                        Set to 0 to disable readiness gating.
+ *   READINESS_INTERVAL_MS (default 500, int)   Delay between readiness probes.
  *
  * Usage (typical droplet pm2):
  *   BACKEND_PORT=7122 LISTEN_PORT=7123 \
@@ -33,8 +40,9 @@
  */
 
 import http from 'http'
+import net from 'net'
 import httpProxy from 'http-proxy'
-import { createStagingGatewayServer } from './devProxyGateway.js'
+import { createStagingGatewayServer, createTcpReadinessProbe } from './devProxyGateway.js'
 
 function intEnv(name, fallback) {
     const raw = process.env[name]
@@ -73,6 +81,11 @@ const STAGING_HOST_PREFIX = process.env.STAGING_HOST_PREFIX || undefined
 const RESOLVER_PATH = process.env.RESOLVER_PATH || undefined
 const RESOLVER_TIMEOUT_MS = intEnv('RESOLVER_TIMEOUT_MS', 2000)
 const FALLBACK_PORT = fallbackPortEnv()
+// HAP-1215: READINESS_TIMEOUT_MS=0 (or empty) disables cold-boot readiness gating.
+const READINESS_TIMEOUT_MS = (process.env.READINESS_TIMEOUT_MS === '0' || process.env.READINESS_TIMEOUT_MS === '')
+    ? 0
+    : intEnv('READINESS_TIMEOUT_MS', 25000)
+const READINESS_INTERVAL_MS = intEnv('READINESS_INTERVAL_MS', 500)
 
 const { server, close } = createStagingGatewayServer({
     http,
@@ -83,6 +96,10 @@ const { server, close } = createStagingGatewayServer({
     resolverPath: RESOLVER_PATH,
     timeoutMs: RESOLVER_TIMEOUT_MS,
     fallbackPort: FALLBACK_PORT,
+    // HAP-1215: only enable readiness gating when the window is > 0.
+    readinessProbe: READINESS_TIMEOUT_MS > 0 ? createTcpReadinessProbe(net) : undefined,
+    readinessTimeoutMs: READINESS_TIMEOUT_MS,
+    readinessIntervalMs: READINESS_INTERVAL_MS,
     onError: (where, err) => {
         console.error(`[staging-gateway] ${where} error: ${err?.message || err}`)
     },
@@ -97,6 +114,11 @@ server.listen(LISTEN_PORT, LISTEN_HOST, () => {
     } else {
         console.log('[staging-gateway]   fallback disabled (no branch signal → 401, failed resolve → resolver status)')
     }
+    if (READINESS_TIMEOUT_MS > 0) {
+        console.log(`[staging-gateway]   cold-boot readiness: poll workspace port ≤${READINESS_TIMEOUT_MS}ms (every ${READINESS_INTERVAL_MS}ms) → branded "starting" page on timeout`)
+    } else {
+        console.log('[staging-gateway]   cold-boot readiness gating disabled (proxy immediately; cold boots may 502)')
+    }
 })
 
 function shutdown(signal) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mango-cms",
-  "version": "0.3.31",
+  "version": "0.3.34",
   "type": "module",
   "main": "./index.js",
   "exports": {