cyberia 3.2.22 → 3.2.70

package/src/runtime/nginx/Nginx.js

@@ -0,0 +1,250 @@
+/**
+ * Exported singleton instance of the NginxService class.
+ * Manages dynamic generation of nginx reverse-proxy router configuration used
+ * by the Docker Compose development stack. Mirrors the conventions of
+ * {@link module:src/runtime/lampp/Lampp.js LamppService}.
+ * @module src/runtime/nginx/Nginx.js
+ * @namespace NginxService
+ */
+
+import fs from 'fs-extra';
+import path from 'path';
+import { loggerFactory } from '../../server/logger.js';
+
+const logger = loggerFactory(import.meta);
+
+/**
+ * @class NginxService
+ * @description Builds nginx `server` blocks (the router) for fronting upstream
+ * application services and writes the rendered configuration to disk. The
+ * router is accumulated in memory via {@link NginxService#createApp} and
+ * flushed with {@link NginxService#writeConf}, keeping config generation
+ * decoupled from the filesystem location it is written to.
+ * @memberof NginxService
+ */
+class NginxService {
+  /**
+   * @type {string}
+   * @description Accumulated nginx `server { ... }` blocks (the router definition).
+   * @memberof NginxService
+   */
+  router = '';
+
+  /**
+   * @type {Set<string>}
+   * @description Upstream blocks keyed by upstream name to avoid duplicates.
+   * @memberof NginxService
+   */
+  upstreams;
+
+  /**
+   * @type {boolean}
+   * @description Whether a default_server catch-all block has been emitted.
+   * @memberof NginxService
+   */
+  hasDefaultServer;
+
+  constructor() {
+    this.reset();
+  }
+
+  /**
+   * Resets the in-memory router, upstreams, and default-server flag.
+   * @method reset
+   * @returns {void}
+   * @memberof NginxService
+   */
+  reset() {
+    this.router = '';
+    this.upstreams = new Map();
+    this.hasDefaultServer = false;
+  }
+
+  /**
+   * Appends a raw render fragment to the router string.
+   * @method appendRouter
+   * @param {string} render - The configuration fragment to append.
+   * @returns {string} The complete, updated router configuration string.
+   * @memberof NginxService
+   */
+  appendRouter(render) {
+    if (!this.router) return (this.router = render);
+    return (this.router += render);
+  }
+
+  /**
+   * Clears the in-memory router configuration.
+   * @method removeRouter
+   * @returns {void}
+   * @memberof NginxService
+   */
+  removeRouter() {
+    this.reset();
+  }
+
+  /**
+   * Registers a named upstream pointing at a container service:port.
+   * Idempotent: repeated names with the same target are collapsed.
+   * @method addUpstream
+   * @param {string} name - The upstream identifier.
+   * @param {string} service - The Docker service name (resolved via service discovery).
+   * @param {number} port - The upstream container port.
+   * @returns {string} The upstream name.
+   * @memberof NginxService
+   */
+  addUpstream(name, service, port) {
+    this.upstreams.set(name, `upstream ${name} { server ${service}:${port}; }`);
+    return name;
+  }
+
+  /**
+   * Renders the standard proxy directive block shared by all locations,
+   * including websocket upgrade headers and forwarded headers.
+   * @method proxyLocation
+   * @param {string} location - The location path (e.g. '/', '/peer').
+   * @param {string} upstream - The upstream name to proxy to.
+   * @returns {string} The rendered `location { ... }` block.
+   * @memberof NginxService
+   */
+  proxyLocation(location, upstream) {
+    return `
+    location ${location} {
+        proxy_pass http://${upstream};
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection $connection_upgrade;
+        proxy_read_timeout 3600s;
+    }
+`;
+  }
+
+  /**
+   * Renders the `/healthz` location used by the proxy container healthcheck.
+   * @method healthLocation
+   * @returns {string} The rendered health-check location block.
+   * @memberof NginxService
+   */
+  healthLocation() {
+    return `
+    location = /healthz {
+        access_log off;
+        return 200 "ok\\n";
+        add_header Content-Type text/plain;
+    }
+`;
+  }
+
+  /**
+   * Creates an nginx virtual-host (`server`) entry for a host and appends it to
+   * the router. Each route maps a URL prefix to an upstream service:port with
+   * websocket support, mirroring the Contour HTTPProxy route model.
+   *
+   * @method createApp
+   * @param {object} options - Virtual host options.
+   * @param {string} options.host - The `server_name` (e.g. 'default.net').
+   * @param {number} [options.listen=80] - The listen port.
+   * @param {Array<{location: string, service: string, port: number}>} options.routes
+   *   - Route table. Longer prefixes should precede '/' for correct matching.
+   * @param {boolean} [options.resetRouter] - Clear the router before appending.
+   * @returns {string} The complete, updated router configuration string.
+   * @memberof NginxService
+   */
+  createApp({ host, listen = 80, routes = [], resetRouter = false }) {
+    if (resetRouter) this.removeRouter();
+
+    const safeHost = host.replace(/[^a-zA-Z0-9]/g, '_');
+    const locationBlocks = routes
+      .map(({ location, service, port }) => {
+        const upstreamName = this.addUpstream(`up_${safeHost}_${port}`, service, port);
+        return this.proxyLocation(location, upstreamName);
+      })
+      .join('');
+
+    this.appendRouter(`
+server {
+    listen ${listen};
+    server_name ${host};
+${this.healthLocation()}${locationBlocks}}
+`);
+
+    return this.router;
+  }
+
+  /**
+   * Emits a `default_server` catch-all that forwards to the given upstream and
+   * answers the health probe for unmatched Host headers. Safe to call once.
+   *
+   * @method createDefaultServer
+   * @param {object} options - Default server options.
+   * @param {string} options.service - The Docker service name to fall back to.
+   * @param {number} options.port - The upstream container port.
+   * @param {number} [options.listen=80] - The listen port.
+   * @returns {string} The complete, updated router configuration string.
+   * @memberof NginxService
+   */
+  createDefaultServer({ service, port, listen = 80 }) {
+    if (this.hasDefaultServer) return this.router;
+    this.hasDefaultServer = true;
+    const upstreamName = this.addUpstream('up_default', service, port);
+    this.appendRouter(`
+server {
+    listen ${listen} default_server;
+    server_name _;
+${this.healthLocation()}${this.proxyLocation('/', upstreamName)}}
+`);
+    return this.router;
+  }
+
+  /**
+   * Renders the full nginx config document: the websocket connection map, all
+   * upstream blocks, the global `proxy_http_version`, and the accumulated router.
+   * @method render
+   * @returns {string} The complete nginx configuration file content.
+   * @memberof NginxService
+   */
+  render() {
+    const upstreamBlocks = Array.from(this.upstreams.values()).join('\n');
+    return `# Generated by src/runtime/nginx/Nginx.js — do not hand-edit.
+# Reverse proxy derived from manifests/deployment/*/proxy.yaml (Contour HTTPProxy).
+# Upstreams resolve container services via the Docker internal network.
+
+map $http_upgrade $connection_upgrade {
+    default upgrade;
+    ''      close;
+}
+
+${upstreamBlocks}
+
+proxy_http_version 1.1;
+${this.router}`;
+  }
+
+  /**
+   * Writes the rendered configuration to the given path, creating parent
+   * directories as needed. Idempotent and safe to rerun.
+   * @method writeConf
+   * @param {string} confPath - Absolute or relative destination path.
+   * @returns {string} The path written.
+   * @memberof NginxService
+   */
+  writeConf(confPath) {
+    const target = path.resolve(confPath);
+    fs.mkdirpSync(path.dirname(target));
+    fs.writeFileSync(target, this.render(), 'utf8');
+    logger.info(`nginx config written`, { path: target, upstreams: this.upstreams.size });
+    return target;
+  }
+}
+
+/**
+ * @description Exported singleton instance of the NginxService class.
+ * @type {NginxService}
+ * @memberof NginxService
+ */
+const Nginx = new NginxService();
+
+export { Nginx, NginxService };
+export default Nginx;

package/src/server/catalog.js

@@ -18,14 +18,14 @@ import fs from 'fs-extra';
 import { fileURLToPath } from 'node:url';
 import * as path from 'node:path';
 
-const catalogDir = path.dirname(fileURLToPath(import.meta.url));
-
 /** Empty product catalog returned for deploy ids without a dedicated module. */
 const EMPTY_CATALOG = {
   sourceMoves: [],
   privateConfPaths: [],
   templatePaths: [],
   stripPaths: [],
+  moves: [],
+  copies: [],
   keywords: [],
   description: '',
 };
@@ -43,12 +43,11 @@ const EMPTY_CATALOG = {
 const loadDeployCatalog = async (deployId) => {
   const suffix = (deployId ?? '').split('dd-')[1];
   if (!suffix) return EMPTY_CATALOG;
-  try {
-    const mod = await import(`./catalog-${suffix}.js`);
+  if (fs.existsSync(`./src/projects/${suffix}/catalog-${suffix}.js`)) {
+    const mod = await import(`../projects/${suffix}/catalog-${suffix}.js`);
     return { ...EMPTY_CATALOG, ...(mod.default ?? {}) };
-  } catch {
-    return EMPTY_CATALOG;
   }
+  return EMPTY_CATALOG;
 };
 
 /**
@@ -62,14 +61,10 @@ const loadDeployCatalog = async (deployId) => {
  */
 const loadProductCatalogs = async () => {
   const catalogs = [];
-  for (const file of fs.readdirSync(catalogDir)) {
-    if (!/^catalog-.+\.js$/.test(file) || file === 'catalog-underpost.js') continue;
-    try {
-      const mod = await import(`./${file}`);
-      if (mod.default) catalogs.push({ ...EMPTY_CATALOG, ...mod.default });
-    } catch {
-      /* a malformed/removed product catalog must not break the base build */
-    }
+  for (const file of await fs.readdir('./src/projects')) {
+    if (file === 'underpost') continue;
+    const mod = await import(`../projects/${file}/catalog-${file}.js`);
+    if (mod.default) catalogs.push({ ...EMPTY_CATALOG, ...mod.default });
   }
   return catalogs;
 };

package/src/server/conf.js

@@ -476,9 +476,6 @@ const loadConf = (deployId = DEFAULT_DEPLOY_ID, subConf) => {
     fs.removeSync(`${path}/.env.production`);
     fs.removeSync(`${path}/.env.development`);
     fs.removeSync(`${path}/.env.test`);
-    if (fs.existsSync(`${path}/typedoc.json`)) shellExec(`git checkout ${path}/typedoc.json`);
-    shellExec(`git checkout ${path}/package.json`);
-    shellExec(`git checkout ${path}/package-lock.json`);
     return;
   }
   const folder = getConfFolder(deployId);
@@ -1337,7 +1334,7 @@ const mergeFile = async (parts = [], outputFilePath) => {
  * @memberof ServerConfBuilder
  */
 const getPathsSSR = (conf) => {
-  const paths = ['src/client/ssr/Render.js'];
+  const paths = ['src/client/ssr/RootDocument.js'];
   for (const o of conf.head) paths.push(`src/client/ssr/head/${o}.js`);
   for (const o of conf.body) paths.push(`src/client/ssr/body/${o}.js`);
   for (const o of Object.keys(conf.mailer)) paths.push(`src/client/ssr/mailer/${conf.mailer[o]}.js`);
@@ -1928,7 +1925,8 @@ const syncDeployIdSources = (sourceMoves = []) => {
  */
 const buildTemplate = async ({ srcPath = './', toPath = '../pwa-microservices-template' } = {}) => {
   const walk = (await import('ignore-walk')).default;
-  const { TEMPLATE_RESTORE_PATHS, TEMPLATE_KEYWORDS, TEMPLATE_DESCRIPTION } = await import('./catalog-underpost.js');
+  const { TEMPLATE_RESTORE_PATHS, TEMPLATE_KEYWORDS, TEMPLATE_DESCRIPTION } =
+    await import('../projects/underpost/catalog-underpost.js');
   const { loadProductCatalogs } = await import('./catalog.js');
   const githubUsername = process.env.GITHUB_USERNAME;
 
@@ -1974,7 +1972,6 @@ const buildTemplate = async ({ srcPath = './', toPath = '../pwa-microservices-te
   }
   shellExec(`rm -rf ${toPath}/.github`);
   shellExec(`rm -rf ${toPath}/manifests/deployment/dd-*`);
-  shellExec(`rm -rf ${toPath}/src/server/catalog-*`);
 
   fs.mkdirSync(`${toPath}/.github/workflows`, { recursive: true });
   for (const restorePath of TEMPLATE_RESTORE_PATHS) {

package/src/server/runtime-status.js

@@ -40,6 +40,7 @@ const RUNTIME_STATUS = {
 };
 
 const CONTAINER_STATUS_KEY = 'container-status';
+const START_CONTAINER_STATUS_KEY = 'start-container-status';
 const INTERNAL_STATUS_PATH = '/_internal/status';
 const INTERNAL_READY_PATH = '/_internal/ready';
 const INTERNAL_HEALTH_PATH = '/_internal/health';
@@ -118,6 +119,20 @@ const normalizeContainerStatus = (raw) => {
 const getRuntimeStatus = () =>
   normalizeContainerStatus(Underpost.env.get(CONTAINER_STATUS_KEY, undefined, { disableLog: true }));
 
+/**
+ * Reads the start-container-status env key — an insulated marker set by the
+ * start pipeline after it completes the running phase. Unlike container-status
+ * (which external scripts / backup failures may clobber), this key is written
+ * once and survives globalSecretClean. Used exclusively by the readinessProbe
+ * endpoint so K8s pod readiness is never derailed by lifecycle noise.
+ * @memberof RuntimeStatus
+ * @returns {string|undefined}
+ */
+const getStartContainerStatus = () => {
+  const raw = Underpost.env.get(START_CONTAINER_STATUS_KEY, undefined, { disableLog: true });
+  return raw && typeof raw === 'string' && raw.trim() ? raw.trim() : undefined;
+};
+
 /**
  * Minimal, secret-free payload served by the internal status endpoint and used
  * by the monitor for failure classification and observability.
@@ -188,7 +203,7 @@ const startInternalStatusServer = (port = resolveInternalStatusPort()) => {
       case INTERNAL_HEALTH_PATH:
         return sendJson(200, { status: 'ok' });
       case INTERNAL_READY_PATH:
-        return getRuntimeStatus() === RUNTIME_STATUS.RUNNING
+        return getStartContainerStatus()
           ? sendJson(200, { status: RUNTIME_STATUS.RUNNING })
           : sendJson(503, { status: getRuntimeStatus() ?? null });
       case INTERNAL_STATUS_PATH:
@@ -220,6 +235,7 @@ const stopInternalStatusServer = () =>
 export {
   RUNTIME_STATUS,
   CONTAINER_STATUS_KEY,
+  START_CONTAINER_STATUS_KEY,
   INTERNAL_STATUS_PATH,
   INTERNAL_READY_PATH,
   INTERNAL_HEALTH_PATH,
@@ -228,6 +244,7 @@ export {
   containerStatusValue,
   normalizeContainerStatus,
   getRuntimeStatus,
+  getStartContainerStatus,
   runtimeStatusPayload,
   setRuntimeStatus,
   startInternalStatusServer,

package/src/server/start.js

@@ -8,7 +8,14 @@ import fs from 'fs-extra';
 import { awaitDeployMonitor } from './conf.js';
 import { actionInitLog, loggerFactory } from './logger.js';
 import { shellCd, shellExec } from './process.js';
-import { RUNTIME_STATUS, setRuntimeStatus, startInternalStatusServer, deployStatusPort } from './runtime-status.js';
+import {
+  RUNTIME_STATUS,
+  START_CONTAINER_STATUS_KEY,
+  setRuntimeStatus,
+  startInternalStatusServer,
+  deployStatusPort,
+  containerStatusValue,
+} from './runtime-status.js';
 import Underpost from '../index.js';
 const logger = loggerFactory(import.meta);
 
@@ -241,7 +248,10 @@ class UnderpostStartUp {
       const result = await awaitDeployMonitor(true);
       if (result === true) {
         if (env === 'production' && Underpost.env.isInsideContainer()) Underpost.secret.globalSecretClean();
-        setRuntimeStatus(deployId, env, RUNTIME_STATUS.RUNNING);
+        setTimeout(() => {
+          setRuntimeStatus(deployId, env, RUNTIME_STATUS.RUNNING);
+          Underpost.env.set(START_CONTAINER_STATUS_KEY, containerStatusValue(deployId, env, RUNTIME_STATUS.RUNNING));
+        });
       } else {
         setRuntimeStatus(deployId, env, RUNTIME_STATUS.ERROR);
       }

package/src/server.js

@@ -3,18 +3,22 @@
 // https://nodejs.org/api
 // https://expressjs.com/en/4x/api.html
 
+import dotenv from 'dotenv';
 import { loggerFactory } from './server/logger.js';
-import { buildClient } from './server/client-build.js';
+import { buildClient } from './client-builder/client-build.js';
 import { buildRuntime } from './server/runtime.js';
 import { ProcessController } from './server/process.js';
 import { Config } from './server/conf.js';
+
+dotenv.config();
+
 await Config.build();
 
 const logger = loggerFactory(import.meta);
 
 await logger.setUpInfo();
 
-await buildClient();
+if (process.env.NODE_ENV === 'development') await buildClient();
 
 await buildRuntime();
 

package/test/cyberia-instance-conf-defaults.test.js

@@ -0,0 +1,140 @@
+'use strict';
+
+import { expect } from 'chai';
+import {
+  fillInstanceConfDefaults,
+  CYBERIA_INSTANCE_CONF_DEFAULTS,
+} from '../src/api/cyberia-server-defaults/cyberia-server-defaults.js';
+
+// The CyberiaInstanceConfSchema fields that must always be present after a
+// backfill. Mirrors cyberia-instance-conf.model.js (minus instanceCode, which
+// is the lookup key and is only present when the source doc carries it).
+const SCHEMA_FIELDS = [
+  'tickRate',
+  'snapshotRate',
+  'aoiRadius',
+  'portalHoldTimeMs',
+  'portalSpawnRadius',
+  'entityBaseSpeed',
+  'entityBaseMaxLife',
+  'entityBaseActionCooldownMs',
+  'entityBaseMinActionCooldownMs',
+  'botAggroRange',
+  'defaultPlayerWidth',
+  'defaultPlayerHeight',
+  'playerBaseLifeRegenMin',
+  'playerBaseLifeRegenMax',
+  'sumStatsLimit',
+  'maxActiveLayers',
+  'initialLifeFraction',
+  'respawnDurationMs',
+  'collisionLifeLoss',
+  'economyRules',
+  'lifeRegenChance',
+  'maxChance',
+  'entityDefaults',
+  'statusIcons',
+  'skillConfig',
+  'skillRules',
+  'equipmentRules',
+];
+
+describe('fillInstanceConfDefaults', () => {
+  it('fills every schema field from canonical defaults for an empty doc', () => {
+    const out = fillInstanceConfDefaults({});
+    for (const field of SCHEMA_FIELDS) {
+      expect(out, `missing field: ${field}`).to.have.property(field);
+      expect(out[field], `null/undefined field: ${field}`).to.not.equal(undefined);
+      expect(out[field], `null field: ${field}`).to.not.equal(null);
+    }
+    expect(out.tickRate).to.equal(CYBERIA_INSTANCE_CONF_DEFAULTS.tickRate);
+    expect(out.economyRules).to.deep.equal(CYBERIA_INSTANCE_CONF_DEFAULTS.economyRules);
+    expect(out.skillRules).to.deep.equal(CYBERIA_INSTANCE_CONF_DEFAULTS.skillRules);
+    expect(out.equipmentRules).to.deep.equal(CYBERIA_INSTANCE_CONF_DEFAULTS.equipmentRules);
+  });
+
+  it('handles undefined / non-object input as an empty doc', () => {
+    for (const bad of [undefined, null, 42, 'x']) {
+      const out = fillInstanceConfDefaults(bad);
+      for (const field of SCHEMA_FIELDS) expect(out).to.have.property(field);
+    }
+  });
+
+  it('preserves author-set scalar values, including falsy 0 / false / empty string', () => {
+    const out = fillInstanceConfDefaults({
+      tickRate: 30,
+      collisionLifeLoss: 0,
+      portalFee: 0,
+    });
+    expect(out.tickRate).to.equal(30);
+    expect(out.collisionLifeLoss).to.equal(0);
+    // Fields not overridden still come from defaults.
+    expect(out.snapshotRate).to.equal(CYBERIA_INSTANCE_CONF_DEFAULTS.snapshotRate);
+  });
+
+  it('backfills a missing nested sub-document (economyRules)', () => {
+    const out = fillInstanceConfDefaults({ tickRate: 60 });
+    expect(out.economyRules).to.deep.equal(CYBERIA_INSTANCE_CONF_DEFAULTS.economyRules);
+  });
+
+  it('fills only the missing keys of a partial nested sub-document', () => {
+    const out = fillInstanceConfDefaults({
+      economyRules: { botSpawnCoins: 999 },
+    });
+    expect(out.economyRules.botSpawnCoins).to.equal(999);
+    expect(out.economyRules.playerSpawnCoins).to.equal(
+      CYBERIA_INSTANCE_CONF_DEFAULTS.economyRules.playerSpawnCoins,
+    );
+    expect(out.economyRules.portalFee).to.equal(CYBERIA_INSTANCE_CONF_DEFAULTS.economyRules.portalFee);
+  });
+
+  it('keeps a present non-empty array and does not merge defaults into it', () => {
+    const custom = [{ entityType: 'player', liveItemIds: ['anon'], deadItemIds: [], dropItemIds: [] }];
+    const out = fillInstanceConfDefaults({ entityDefaults: custom });
+    expect(out.entityDefaults).to.deep.equal(custom);
+  });
+
+  it('populates an empty skillConfig from defaults, normalised to schema shape (no `skills`)', () => {
+    for (const input of [{}, { skillConfig: [] }, { skillConfig: null }]) {
+      const out = fillInstanceConfDefaults(input);
+      expect(out.skillConfig.length, JSON.stringify(input)).to.be.greaterThan(0);
+      for (const entry of out.skillConfig) {
+        expect(entry).to.have.property('triggerItemId');
+        expect(entry).to.have.property('logicEventIds');
+        expect(entry).to.not.have.property('skills');
+      }
+    }
+  });
+
+  it('keeps an author-set non-empty skillConfig verbatim', () => {
+    const custom = [{ triggerItemId: 'custom-weapon', logicEventIds: ['projectile'] }];
+    const out = fillInstanceConfDefaults({ skillConfig: custom });
+    expect(out.skillConfig).to.deep.equal(custom);
+  });
+
+  it('fills an empty config array (entityDefaults) from defaults', () => {
+    const out = fillInstanceConfDefaults({ entityDefaults: [] });
+    expect(out.entityDefaults.length).to.be.greaterThan(0);
+    expect(out.entityDefaults).to.deep.equal(CYBERIA_INSTANCE_CONF_DEFAULTS.entityDefaults);
+  });
+
+  it('preserves DB metadata (_id, instanceCode, timestamps)', () => {
+    const now = new Date().toISOString();
+    const out = fillInstanceConfDefaults({
+      _id: 'abc123',
+      instanceCode: 'amethyst-strata-expansion',
+      createdAt: now,
+      updatedAt: now,
+    });
+    expect(out._id).to.equal('abc123');
+    expect(out.instanceCode).to.equal('amethyst-strata-expansion');
+    expect(out.createdAt).to.equal(now);
+  });
+
+  it('does not mutate the input document', () => {
+    const input = { economyRules: { botSpawnCoins: 5 } };
+    const snapshot = JSON.parse(JSON.stringify(input));
+    fillInstanceConfDefaults(input);
+    expect(input).to.deep.equal(snapshot);
+  });
+});

package/test/deploy-monitor.test.js

@@ -69,12 +69,10 @@ describe('Deploy monitor — two-phase state machine (e2e, real HTTP transport)'
     process.env.npm_config_prefix = tmpPrefix;
 
     Underpost.env.set('container-status', 'init');
+    Underpost.env.set('start-container-status', '');
     const npmRoot = shellExec('npm root -g', { stdout: true, silent: true, disableLog: true }).trim();
     envFile = path.join(npmRoot, 'underpost', '.env');
 
-    // Real in-pod internal status server: serves container-status from the same
-    // env file the runtime writes. Bound in this test process; the monitor's
-    // port-forward tunnel (localPort == INTERNAL_PORT) resolves straight to it.
     process.env.UNDERPOST_INTERNAL_PORT = String(INTERNAL_PORT);
     startInternalStatusServer(INTERNAL_PORT);
 
@@ -148,10 +146,11 @@ try {
   beforeEach(() => {
     // Deploy in flight: app not yet reporting running.
     Underpost.env.set('container-status', INIT_STATUS);
+    // start-container-status is unset (empty) — the readinessProbe
+    // sees 503 until the start pipeline completes and stamps this key.
+    Underpost.env.set('start-container-status', '');
   });
 
-  // Spawns the real monitorReadyRunner with the fake cluster on PATH; resolves
-  // with its exit code. `overrides` inject deterministic timing / target port.
   const spawnMonitor = (overrides = {}) =>
     new Promise((resolve) => {
       const envVars = {
@@ -160,9 +159,6 @@ try {
         POD_NAME,
         npm_config_prefix: tmpPrefix,
         UNDERPOST_INTERNAL_PORT: String(INTERNAL_PORT),
-        // Pin the tunnel's local port so the no-op fake port-forward + the real
-        // internal server (bound to INTERNAL_PORT in this process) resolve to the
-        // same address the monitor's HTTP GET targets.
         UNDERPOST_PF_LOCAL_PORT: String(INTERNAL_PORT),
         UNDERPOST_MONITOR_DELAY_MS: '100',
         UNDERPOST_MONITOR_MAX_ITERATIONS: '60',
@@ -183,12 +179,15 @@ try {
 
   it('success (default exec transport): both phases satisfied → monitor exits 0', async () => {
     Underpost.env.set('container-status', RUNNING_STATUS);
+    // start-container-status not needed for monitor (reads container-status);
+    // this test exercises the default exec transport path.
     const code = await spawnMonitor({ FAKE_POD_READY: 'True' });
     expect(code).to.equal(0);
   });
 
   it('success (opt-in http transport): both phases satisfied → monitor exits 0', async () => {
     Underpost.env.set('container-status', RUNNING_STATUS);
+    Underpost.env.set('start-container-status', RUNNING_STATUS);
     const code = await spawnMonitor({ FAKE_POD_READY: 'True', MON_TRANSPORT: 'http' });
     expect(code).to.equal(0);
   });
@@ -202,13 +201,13 @@ try {
   it('readiness mismatch: runtime running but pod not Ready → never succeeds (exits 1)', async () => {
     // Phase 2 satisfied, Phase 1 not: success requires BOTH, so it must time out.
     Underpost.env.set('container-status', RUNNING_STATUS);
+    // start-container-status is NOT set — the readinessProbe would fail,
+    // but the monitor only checks container-status via exec/http transport.
     const code = await spawnMonitor({ FAKE_POD_READY: 'False', UNDERPOST_MONITOR_MAX_ITERATIONS: '4' });
     expect(code).to.equal(1);
   });
 
   it('transport failure (http): endpoint unreachable is never success (exits 1)', async () => {
-    // Opt into http and point the monitor at a port with no internal server; the
-    // HTTP read always fails, so runtime readiness is never confirmed → timeout.
     Underpost.env.set('container-status', RUNNING_STATUS);
     const code = await spawnMonitor({
       MON_TRANSPORT: 'http',
@@ -221,6 +220,8 @@ try {
 
   it('timeout: runtime stuck initializing → monitor exits 1', async () => {
     Underpost.env.set('container-status', INIT_STATUS);
+    // start-container-status remains unset — readinessProbe returns 503
+    // (correct, since the runtime is still initializing).
     const code = await spawnMonitor({ FAKE_POD_READY: 'True', UNDERPOST_MONITOR_MAX_ITERATIONS: '4' });
     expect(code).to.equal(1);
   });
@@ -235,6 +236,21 @@ try {
     expect(await monitorExit).to.equal(1);
   });
 
+  it('readinessProbe: start-container-status set → returns 200 (probe passes)', async () => {
+    Underpost.env.set('start-container-status', RUNNING_STATUS);
+    const res = await fetch(`http://127.0.0.1:${INTERNAL_PORT}/_internal/ready`);
+    expect(res.status).to.equal(200);
+    const body = await res.json();
+    expect(body.status).to.equal('running-deployment');
+  });
+
+  it('readinessProbe: start-container-status unset → returns 503 (probe fails)', async () => {
+    // Unset from beforeEach re-stamp; clear it.
+    Underpost.env.set('start-container-status', '');
+    const res = await fetch(`http://127.0.0.1:${INTERNAL_PORT}/_internal/ready`);
+    expect(res.status).to.equal(503);
+  });
+
   // Custom instances (cyberia-*) gate on K8s Ready and read status via exec;
   // their runtime never stamps `running-deployment` (stays `initializing`).
   it('instance (kubernetes gate + exec): K8s Ready with initializing status → exits 0', async () => {