underpost 3.2.70 → 3.2.90

package/src/cli/run.js

@@ -5,48 +5,72 @@
  */
 
 import { daemonProcess, getTerminalPid, pbcopy, shellCd, shellExec } from '../server/process.js';
-import crypto from 'crypto';
 import {
   awaitDeployMonitor,
   buildKindPorts,
-  Config,
+  clusterContextFactory,
+  clusterTypeFactory,
   cronDeployIdResolve,
+  dispatchBuildInstanceEnv,
+  deployHostsFactory,
   etcHostFactory,
+  exposePartialMatchesFactory,
+  exposePathPartsFactory,
+  exposePortListFactory,
+  exposePortPlanFactory,
+  exposeTcpPortsFactory,
+  gatewayApiEnabledFactory,
+  generateSecurePassword,
   getNpmRootPath,
+  instanceHttpRouteRulesFactory,
+  instanceInterceptStatusesFactory,
+  instancePortFactory,
+  instanceProxyRoutesFactory,
+  instanceStatusPageEntriesFactory,
   isDeployRunnerContext,
+  loadConfInstances,
+  loadProjectInstanceEnvBuilder,
   loadConfServerJson,
   loadReplicas,
+  resolveDeployList,
+  resolveEnvScoped,
+  selectConfInstances,
+  waitForPort,
   writeEnv,
+  clusterInstancesFactory,
+  deployTrafficEntriesFactory,
+  curlStatusChainFactory,
+  hostIngressFactsFactory,
+  hostRenderInstancesFactory,
+  instanceTrafficPlanFactory,
+  trafficTableRowsFactory,
+  isTrafficServingFactory,
+  nextTrafficFactory,
+  stopPlanFactory,
+  trafficFromRoutingInfoFactory,
 } from '../server/conf.js';
 import { actionInitLog, loggerFactory } from '../server/logger.js';
 
 import fs from 'fs-extra';
-import net from 'net';
 import { range, s4, setPad, timer } from '../client/components/core/CommonJs.js';
 
 import os from 'os';
 import Underpost from '../index.js';
 import dotenv from 'dotenv';
 import { MongoBootstrap } from '../db/mongo/MongoBootstrap.js';
-
-const waitForPort = (port, host = '127.0.0.1', { maxAttempts = 30, interval = 2000 } = {}) =>
-  new Promise((resolve, reject) => {
-    let attempts = 0;
-    const tryConnect = () => {
-      attempts++;
-      const socket = net.createConnection({ port, host }, () => {
-        socket.destroy();
-        resolve();
-      });
-      socket.on('error', () => {
-        socket.destroy();
-        if (attempts >= maxAttempts) return reject(new Error(`Port ${port} not ready after ${maxAttempts} attempts`));
-        setTimeout(tryConnect, interval);
-      });
-    };
-    tryConnect();
-  });
-
+import {
+  UNDERPOST_GATEWAY,
+  assertStaticAssets,
+  gatewayFallbackProbeRunner,
+  hostServerConfFactory,
+  installGatewayConf,
+  instanceFallbackChecksFactory,
+  placeInstanceStaticAssets,
+  pwaFallbackChecksFactory,
+  readHostInstanceRegistry,
+  writeHostInstanceRegistry,
+  writeHostServerConf,
+} from '../server/underpost-gateway.js';
 const logger = loggerFactory(import.meta);
 
 /**
@@ -57,8 +81,12 @@ const logger = loggerFactory(import.meta);
  * @property {boolean} dev - Whether to run in development mode.
  * @property {string} podName - The name of the pod to run.
  * @property {string} nodeName - The name of the node to run.
+ * @property {string} ingressNode - Dedicated node for the host-network public ingress; never inherited from nodeName.
  * @property {string} sshKeyPath - Private key path for node SSH operations, forwarded to volume shipping over SSH.
  * @property {number} port - Custom port to use.
+ * @property {string} exposeContainerPorts - Comma-separated Service/container destination ports.
+ * @property {string} exposeHostPorts - Comma-separated host listening ports.
+ * @property {boolean} localProxy - Start the development path proxy after exposing matched resources.
  * @property {string} volumeHostPath - The host path for the volume.
  * @property {string} volumeMountPath - The mount path for the volume.
  * @property {string} imageName - The name of the image to run.
@@ -73,6 +101,11 @@ const logger = loggerFactory(import.meta);
  * @property {boolean} force - Whether to force the operation.
  * @property {boolean} reset - Whether to reset the operation.
  * @property {boolean} tls - Whether to use TLS.
+ * @property {boolean} gatewayApi - Apply the Gateway API stack (Gateway + HTTPRoute) instead of the Contour HTTPProxy. Both manifest sets are always generated.
+ * @property {boolean} disableGatewayApi - Fall back to the Contour HTTPProxy stack in runners where the Gateway API is the default (`cluster`).
+ * @property {string} gatewayClass - GatewayClass name baked into generated Gateway manifests.
+ * @property {boolean} disableHttp3 - Omit QUIC/HTTP3 listener config and the Alt-Svc advertisement.
+ * @property {number} quicPort - UDP port advertised for QUIC/HTTP3.
  * @property {string} cmd - The command to run in the container.
  * @property {string} tty - The TTY option for the container.
  * @property {string} stdin - The stdin option for the container.
@@ -123,14 +156,31 @@ const logger = loggerFactory(import.meta);
  * @property {boolean} pullBundle - Whether to pull the bundle before running. Use together with --skip-full-build to skip the local build entirely (supported by: sync, template-deploy).
  * @property {boolean} remove - Whether to remove/teardown resources instead of creating them (e.g. delete-expose for k3s proxy devices in dev-cluster).
  * @property {boolean} test - Whether to enable test/generic-purpose mode (e.g. use self-signed TLS instead of cert-manager).
+ * @property {string} hostAliases - Pod `/etc/hosts` entries, as semicolon-separated `ip=host1,host2` groups.
+ * @property {string} args - Comma-separated arguments forwarded to the runner's own command.
+ * @property {boolean} cert - Issue cert-manager certificates; set implicitly by `tls` in the promote workflow.
+ * @property {boolean} instanceOnly - Act on the one instance id given, without expanding its variant family.
+ * @property {string} labels - Comma-separated `key=value` pairs applied to the created resources.
+ * @property {string} npmRoot - Resolved npm global root, cached on the options once looked up.
+ * @property {object} on - Lifecycle hooks (`{ init }`) a programmatic caller supplies; unused from the CLI.
+ * @property {string} traffic - Blue/green colour to bake into generated manifests (default: `blue`).
+ * @property {boolean} gatewayBootstrapComplete - Internal marker: a parent orchestration already proved the static gateway fallback.
+ * @property {boolean} noBackendCheckpoint - Internal marker: this promote is the deliberate no-backend fallback checkpoint, so it must not wait for the target colour's endpoints.
+ * @property {Object<string,string>} targetTrafficById - Internal instance id → explicitly pre-routed traffic colour.
+ * @property {string} volumeType - hostPath volume type (`DirectoryOrCreate`, `FileOrCreate`, or `dev` for the latter).
+ * @property {string} branch - The Git branch to use for operations (e.g., for template-deploy, ssh-deploy).
  * @memberof UnderpostRun
  */
 const DEFAULT_OPTION = {
   dev: false,
   podName: '',
   nodeName: '',
+  ingressNode: '',
   sshKeyPath: '',
   port: 0,
+  exposeContainerPorts: '',
+  exposeHostPorts: '',
+  localProxy: false,
   volumeHostPath: '',
   volumeMountPath: '',
   imageName: '',
@@ -145,6 +195,11 @@ const DEFAULT_OPTION = {
   force: false,
   reset: false,
   tls: false,
+  gatewayApi: false,
+  disableGatewayApi: false,
+  gatewayClass: '',
+  disableHttp3: false,
+  quicPort: 0,
   cmd: '',
   tty: '',
   stdin: '',
@@ -193,6 +248,18 @@ const DEFAULT_OPTION = {
   pullBundle: false,
   remove: false,
   test: false,
+  branch: '',
+  args: '',
+  cert: false,
+  instanceOnly: false,
+  gatewayBootstrapComplete: false,
+  noBackendCheckpoint: false,
+  targetTrafficById: {},
+  labels: '',
+  npmRoot: '',
+  on: undefined,
+  traffic: '',
+  volumeType: '',
 };
 
 /**
@@ -204,6 +271,34 @@ const DEFAULT_OPTION = {
  * runners for executing specific commands.
  * @memberof UnderpostRun
  */
+
+// Secrets `sops-setup` onboards when no explicit list is passed: the full self-hosted data tier.
+// `mongodb-keyfile` is listed alongside `mongodb-secret` because the MongoDB StatefulSet mounts
+// it as a volume for intra-replica-set auth and will not start without it, so onboarding the
+// credentials alone would leave Mongo broken.
+const SOPS_SETUP_DEFAULT_SECRETS = ['postgres-secret', 'mariadb-secret', 'mongodb-secret', 'mongodb-keyfile'];
+
+/**
+ * Produces a value for a Secret data key that has no origin seed file and no `--args` override.
+ * Key-aware because the data tier does not want one shape of secret: a replica-set keyfile is a
+ * long base64 blob, a username is an identifier, and everything else is a password.
+ * @param {string} key - Secret data key (e.g. 'password', 'username', 'mongodb-keyfile').
+ * @returns {string} Generated value.
+ * @memberof UnderpostRun
+ */
+const generateSeedValue = (key) => {
+  if (key === 'username') return 'admin';
+  // MongoDB keyfile: 6-1024 base64 characters shared by every replica-set member. Newlines are
+  // stripped so the value round-trips identically through YAML and through
+  // MongoBootstrap.readCredential, which strips them too.
+  if (key === 'mongodb-keyfile')
+    return shellExec(`openssl rand -base64 756`, { stdout: true, silent: true, disableLog: true }).replace(
+      /\r?\n/g,
+      '',
+    );
+  return generateSecurePassword(24);
+};
+
 class UnderpostRun {
   /**
    * @static
@@ -212,6 +307,180 @@ class UnderpostRun {
    * @memberof UnderpostRun
    */
   static RUNNERS = {
+    /**
+     * @method status
+     * @description Reports deployment traffic, routing, Pods, expanded instances, and host capacity.
+     * @param {string} path - Deploy id, comma-separated ids, or `dd`; empty uses the router/configured projects.
+     * @param {UnderpostRunDefaultOptions} options - Namespace, environment (`--dev`), cluster, and node options.
+     * @returns {Promise<{deployments: object[], machine: object}>} Structured status report.
+     * @memberof UnderpostRun
+     */
+    status: async (path = '', options = DEFAULT_OPTION) => {
+      options = {
+        ...options,
+        gatewayApi: gatewayApiEnabledFactory(options),
+        namespace: options.namespace || 'default',
+      };
+      if (!/^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$/.test(options.namespace))
+        throw new Error(`Invalid Kubernetes namespace: ${options.namespace}`);
+      if (options.nodeName && !/^[a-zA-Z0-9._-]+$/.test(options.nodeName))
+        throw new Error(`Invalid Kubernetes node name: ${options.nodeName}`);
+      const env = options.dev ? 'development' : 'production';
+      const requestedDeploys = `${path || options.deployId || ''}`.trim();
+      const routerPath = './engine-private/deploy/dd.router';
+      const confRoot = './engine-private/conf';
+      const deployIds = [
+        ...new Set(
+          requestedDeploys
+            ? resolveDeployList(requestedDeploys)
+            : fs.existsSync(routerPath)
+              ? resolveDeployList('dd')
+              : fs.existsSync(confRoot)
+                ? fs
+                    .readdirSync(confRoot)
+                    .filter(
+                      (deployId) =>
+                        fs.existsSync(`${confRoot}/${deployId}/conf.server.json`) ||
+                        fs.existsSync(`${confRoot}/${deployId}/conf.instances.json`),
+                    )
+                    .sort()
+                : [],
+        ),
+      ];
+      if (deployIds.length === 0) throw new Error('No deployments found for status');
+      if (deployIds.some((deployId) => !/^[a-zA-Z0-9._-]+$/.test(deployId)))
+        throw new Error(`Invalid deployment status path: ${requestedDeploys}`);
+
+      const deployments = [];
+      for (const deployId of deployIds) {
+        const instances = [];
+        if (fs.existsSync(`${confRoot}/${deployId}/conf.instances.json`)) {
+          for (const instance of loadConfInstances(deployId)) {
+            const instanceDeployId = `${deployId}-${instance.id}`;
+            instances.push({
+              id: instance.id,
+              host: instance.host,
+              path: instance.path,
+              fromPort: instance.fromPort,
+              toPort: instance.toPort,
+              fromDebugPort: instance.fromDebugPort,
+              toDebugPort: instance.toDebugPort,
+              traffic: Underpost.deploy.getCurrentTraffic(instanceDeployId, {
+                namespace: options.namespace,
+                hostTest: instance.host,
+                env,
+                gatewayApi: options.gatewayApi,
+              }),
+            });
+          }
+        }
+        const deployment = {
+          deployId,
+          env,
+          traffic: Underpost.deploy.getCurrentTraffic(deployId, {
+            namespace: options.namespace,
+            env,
+            gatewayApi: options.gatewayApi,
+          }),
+          router: await Underpost.deploy.routerFactory(deployId, env),
+          pods: Underpost.kubectl.get(deployId, 'pods', options.namespace),
+          instances,
+        };
+        deployments.push(deployment);
+        logger.info('', deployment);
+      }
+
+      const interfaceName = Underpost.dns.getDefaultNetworkInterface();
+      const machine = {
+        hostname: os.hostname(),
+        arch: Underpost.baremetal.getHostArch(),
+        clusterType: clusterTypeFactory(options),
+        ipv4Public: await Underpost.dns.getPublicIp(),
+        ipv4Local: Underpost.dns.getLocalIPv4Address(),
+        resources: Underpost.cluster.getResourcesCapacity(options.nodeName),
+        defaultInterfaceName: interfaceName,
+        defaultInterfaceInfo: os.networkInterfaces()[interfaceName],
+      };
+      logger.info('Machine', machine);
+      return { deployments, machine };
+    },
+
+    /**
+     * @method expose
+     * @description Port-forwards every Service whose name partially matches path, falling back to matching Pods.
+     * Works through the active kubeconfig for Kind, k3s, and kubeadm clusters.
+     * Comma-separated path fragments determine resource index order; host and
+     * container port lists are paired against that same order.
+     * @param {string} path - One or more comma-separated literal Service/Pod name fragments.
+     * @param {UnderpostRunDefaultOptions} options - Namespace, cluster type, and optional port overrides.
+     * @returns {Array<{kindType: string, name: string, localPort: number, remotePort: number}>} Forward plan.
+     * @memberof UnderpostRun
+     */
+    expose: (path, options = DEFAULT_OPTION) => {
+      const namespace = options.namespace || 'default';
+      const clusterType = clusterTypeFactory(options);
+      const pathParts = exposePathPartsFactory(path || options.podName);
+      if (!/^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$/.test(namespace))
+        throw new Error(`Invalid Kubernetes namespace: ${namespace}`);
+      let kindType = 'svc';
+      let resources = exposePartialMatchesFactory(Underpost.kubectl.get('', kindType, namespace), pathParts);
+
+      if (resources.length === 0) {
+        kindType = 'pod';
+        resources = exposePartialMatchesFactory(Underpost.kubectl.get('', 'pods', namespace), pathParts);
+      }
+      if (resources.length === 0)
+        throw new Error(`No Service or Pod partially matching '${pathParts.join(',')}' in namespace '${namespace}'`);
+
+      const containerPorts = exposePortListFactory(options.exposeContainerPorts, '--expose-container-ports');
+      const hostPorts = exposePortListFactory(options.exposeHostPorts, '--expose-host-ports');
+      const portsOf = (resource) => {
+        let declaredPorts = exposeTcpPortsFactory(resource);
+        if (kindType === 'pod' && declaredPorts.length === 0) {
+          const podJson = shellExec(`sudo kubectl get pod ${resource.NAME} -n ${namespace} -o json`, {
+            stdout: true,
+            silent: true,
+          });
+          const pod = JSON.parse(podJson);
+          declaredPorts = (pod.spec?.containers || [])
+            .flatMap((container) => container.ports || [])
+            .map(({ containerPort }) => parseInt(containerPort))
+            .filter((port) => Number.isInteger(port) && port > 0);
+        }
+        return declaredPorts;
+      };
+      const plan = exposePortPlanFactory({ resources, kindType, containerPorts, hostPorts, portsOf });
+
+      logger.info('[expose] Kubernetes port-forward plan', {
+        clusterType,
+        namespace,
+        matches: pathParts,
+        plan,
+      });
+      for (const { kindType, name, localPort, remotePort } of plan)
+        shellExec(`sudo kubectl port-forward -n ${namespace} ${kindType}/${name} ${localPort}:${remotePort}`, {
+          async: true,
+        });
+
+      if (options.localProxy) {
+        const deployId = options.deployId || pathParts[0];
+        const env = options.dev ? 'development' : 'production';
+        const envFile = `./engine-private/conf/${deployId}/.env.${env}`;
+        let basePort = plan[0].localPort - 1;
+        if (fs.existsSync(envFile)) {
+          const portMatch = fs.readFileSync(envFile, 'utf8').match(/^PORT=(\d+)/m);
+          if (portMatch) basePort = parseInt(portMatch[1]);
+        }
+        const tlsFlag = options.tls ? ' tls' : '';
+        shellExec(
+          `NODE_ENV=${env} PORT=${basePort} DEV_PROXY_PORT_OFFSET=0 node src/proxy proxy ${deployId} ${env}${tlsFlag}`,
+          { async: true },
+        );
+      }
+
+      return plan;
+    },
+
     /**
      * @method dev-cluster
      * @description Resets and deploys a full development cluster including MongoDB, Valkey, exposes services, and updates `/etc/hosts` for local access.
@@ -223,26 +492,21 @@ class UnderpostRun {
       const baseCommand = options.dev ? 'node bin' : 'underpost';
       const mongoHosts = ['mongodb-0.mongodb-service'];
       let primaryMongoHost = 'mongodb-0.mongodb-service';
-      if (!options.expose) {
-        shellExec(`${baseCommand} cluster${options.dev ? ' --dev' : ''} --reset`);
-        shellExec(`${baseCommand} cluster${options.dev ? ' --dev' : ''}`);
+      const clusterType = clusterTypeFactory(options);
+      const clusterFlag = ` --${clusterType}`;
+      const clusterInitFlag = clusterType === 'kind' ? '' : clusterFlag;
+      const clusterOptions = `${options.dev ? ' --dev' : ''}${clusterInitFlag} --namespace ${options.namespace}`;
+      if (!options.expose && !options.remove) {
+        shellExec(`${baseCommand} cluster${clusterOptions} --reset`);
+        shellExec(`${baseCommand} cluster${clusterOptions}`);
 
         shellExec(
-          `${baseCommand} cluster${options.dev ? ' --dev' : ''} --mongodb --service-host ${mongoHosts.join(
-            ',',
-          )} --pull-image`,
+          `${baseCommand} cluster${clusterOptions} --mongodb --service-host ${mongoHosts.join(',')} --pull-image`,
         );
-        shellExec(`${baseCommand} cluster${options.dev ? ' --dev' : ''} --valkey --pull-image`);
+        shellExec(`${baseCommand} cluster${clusterOptions} --valkey --pull-image`);
       }
-      if (options.k3s) {
-        if (options.remove) {
-          shellExec(`${baseCommand} lxd --delete-expose k3s-control:27017`);
-          shellExec(`${baseCommand} lxd --delete-expose k3s-control:6379`);
-        } else {
-          shellExec(`${baseCommand} lxd --expose k3s-control:27017 --node-port 32017`);
-          shellExec(`${baseCommand} lxd --expose k3s-control:6379 --node-port 32079`);
-        }
-        shellExec(`lxc config device show k3s-control`);
+      if (options.remove) {
+        shellExec(`${baseCommand} run kill '6379,27017'`);
       } else {
         try {
           const primaryPodName =
@@ -251,49 +515,26 @@ class UnderpostRun {
               podName: 'mongodb-0',
               disableAuth: options.dev,
             }) || 'mongodb-0';
-          shellExec(
-            `${baseCommand} deploy --expose --namespace ${options.namespace} --disable-update-underpost-config mongo`,
-            { async: true },
-          );
-          shellExec(
-            `${baseCommand} deploy --expose --namespace ${options.namespace} --disable-update-underpost-config valkey`,
-            { async: true },
-          );
+          primaryMongoHost = `${primaryPodName}.mongodb-service`;
         } catch (error) {
           logger.warn('Failed to detect MongoDB primary pod, using default', {
             error: error.message,
             default: primaryMongoHost,
           });
         }
+        shellExec(
+          `${baseCommand} run expose mongodb-service --namespace ${options.namespace}${clusterFlag} --expose-container-ports 27017 --expose-host-ports 27017`,
+          { async: true },
+        );
+        shellExec(
+          `${baseCommand} run expose valkey-service --namespace ${options.namespace}${clusterFlag} --expose-container-ports 6379 --expose-host-ports 6379`,
+          { async: true },
+        );
       }
       const hostListenResult = etcHostFactory([primaryMongoHost]);
       logger.info(hostListenResult.renderHosts);
     },
 
-    /**
-     * @method etc-hosts
-     * @description Modifies the `/etc/hosts` file to add entries for local access to services,
-     * based on the provided path input.
-     * @param {string} path - The input value, identifier, or path for the operation (used to specify the entries to add to /etc/hosts).
-     */
-    'etc-hosts': (path = '', options = DEFAULT_OPTION) => {
-      etcHostFactory(path.split(','));
-    },
-
-    /**
-     * @method ipfs-expose
-     * @description Exposes IPFS Cluster services on specified ports for local access.
-     * @type {Function}
-     * @memberof UnderpostRun
-     */
-    'ipfs-expose': (path, options = DEFAULT_OPTION) => {
-      const ports = [5001, 9094, 8080];
-      for (const port of ports)
-        shellExec(`node bin deploy --expose ipfs-cluster --expose-port ${port} --disable-update-underpost-config`, {
-          async: true,
-        });
-    },
-
     /**
      * @method metadata
      * @description Generates metadata for the specified path after exposing the development cluster.
@@ -306,19 +547,30 @@ class UnderpostRun {
       shellExec(`node bin run kill '${ports}'`);
       shellExec(`node bin run dev-cluster --dev --expose --namespace ${options.namespace}`, { async: true });
       logger.info('Waiting for port-forward services to be ready...');
-      try {
-        await Promise.all([waitForPort(27017), waitForPort(6379)]);
-        logger.info('Port-forward services are ready');
-      } catch (err) {
-        logger.error('Port-forward services failed to become ready', { error: err.message });
+      const ready = await Promise.all([27017, 6379].map((port) => waitForPort({ port })));
+      if (ready.some((reachable) => !reachable)) {
         shellExec(`node bin run kill '${ports}'`);
-        throw err;
+        throw new Error('Port-forward services failed to become ready');
       }
+      logger.info('Port-forward services are ready');
       shellExec(`node bin metadata --generate ${path}`);
       shellExec(`node bin db --dev --clean-fs-collection dd`);
       shellExec(`node bin run kill '${ports}'`);
     },
 
+    /**
+     * @method ipfs-expose
+     * @description Exposes every declared TCP port on the matching IPFS Cluster Service.
+     * @type {Function}
+     * @memberof UnderpostRun
+     */
+    'ipfs-expose': (path, options = DEFAULT_OPTION) => {
+      // 5001 Kubo RPC API / WebUI: Kubo/IPFS HTTP API + IPFS WebUI (e.g., http://localhost:5001/webui).
+      // 9094 IPFS Cluster HTTP API: IPFS Cluster REST API consumed by ipfs-cluster-ctl and WebUI clients (e.g., http://localhost:9094/).
+      // 8080 (or 8081) IPFS Gateway: Public HTTP Gateway for accessing pinned content by CID (e.g., http://localhost:8080/ipfs/Qm...).
+      shellExec(`node bin run expose ipfs --expose-host-ports 5001,9094,8080`);
+    },
+
     /**
      * @method svc-ls
      * @description Lists systemd services and installed packages, optionally filtering by the provided path.
@@ -354,28 +606,6 @@ class UnderpostRun {
       shellExec(`sudo rm -f /etc/yum.repos.d/${path}*.repo`);
     },
 
-    /**
-     * @method ssh-deploy-info
-     * @description Retrieves deployment status and pod information from a remote server via SSH.
-     * @param {string} path - The input value, identifier, or path for the operation.
-     * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
-     * @memberof UnderpostRun
-     */
-    'ssh-deploy-info': async (path = '', options = DEFAULT_OPTION) => {
-      const env = options.dev ? 'development' : 'production';
-      await Underpost.ssh.sshRemoteRunner(
-        `node bin deploy ${path ? path : 'dd'} ${env} --status && kubectl get pods -A`,
-        {
-          deployId: options.deployId,
-          user: options.user,
-          dev: options.dev,
-          remote: true,
-          useSudo: true,
-          cd: '/home/dd/engine',
-        },
-      );
-    },
-
     /**
      * @method node-move
      * @description Abstract runner that relocates any schedulable Kubernetes workload
@@ -445,8 +675,8 @@ class UnderpostRun {
           services: 'service',
         })[k] || k;
 
-      // Kinds that own a pod template we can patch; rolloutKinds additionally
-      // support `kubectl rollout restart` to reschedule existing pods now.
+      // Kinds that own a pod template we can patch. Changing that template is
+      // itself the controller's rollout trigger.
       const templated = [
         'deployment',
         'statefulset',
@@ -456,7 +686,6 @@ class UnderpostRun {
         'cronjob',
         'replicationcontroller',
       ];
-      const rolloutKinds = ['deployment', 'statefulset', 'daemonset'];
       const templateSelectorPath = (kind) =>
         kind === 'cronjob'
           ? ['spec', 'jobTemplate', 'spec', 'template', 'spec', 'nodeSelector']
@@ -545,10 +774,9 @@ class UnderpostRun {
           continue;
         }
 
-        // Idempotency: skip the patch + rollout if the resource is already where
-        // we want it. Compares the live pod-template nodeSelector against the
-        // desired placement so a repeated run does not trigger an unnecessary
-        // rollout restart.
+        // Idempotency: skip the patch if the resource is already where we want
+        // it. Compares the live pod-template nodeSelector against the desired
+        // placement so a repeated run does not trigger an unnecessary rollout.
         const basePath = kind === 'cronjob' ? 'spec.jobTemplate.spec.template.spec' : 'spec.template.spec';
         const jsonpath = (expr) =>
           shellExec(`kubectl get ${kind} ${name} -n ${ns} -o jsonpath='${expr}'`, {
@@ -578,16 +806,17 @@ class UnderpostRun {
         }
 
         const patchCmd = `kubectl patch ${kind} ${name} -n ${ns} --type=merge -p '${buildPatch(kind)}'`;
-        const restartCmd = `kubectl rollout restart ${kind} ${name} -n ${ns}`;
         if (dryRun) {
           logger.info(`[dry-run] ${patchCmd}`);
-          if (rolloutKinds.includes(kind)) logger.info(`[dry-run] ${restartCmd}`);
           results.push({ ref, kind, status: 'dry-run', node: remove ? undefined : node });
           continue;
         }
 
         shellExec(patchCmd);
-        if (rolloutKinds.includes(kind)) shellExec(restartCmd);
+        // nodeSelector is part of the pod template, so this patch already
+        // creates a new controller revision. A rollout restart here creates a
+        // second, immediately superseding revision and can strand the previous
+        // Ready replica in "pending termination" while the newest pod starts.
         logger.info(remove ? `Cleared node placement: ${kind}/${name}` : `Moved ${kind}/${name} -> ${node}`, {
           namespace: ns,
         });
@@ -605,10 +834,12 @@ class UnderpostRun {
      * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
      * @memberof UnderpostRun
      */
-    'dev-hosts-expose': (path, options = DEFAULT_OPTION) => {
-      shellExec(
-        `node bin deploy ${path} development --disable-update-deployment --disable-update-proxy --kubeadm --etc-hosts`,
-      );
+    'dev-hosts-expose': async (path, options = DEFAULT_OPTION) => {
+      shellExec(`node bin deploy ${path} development --disable-update-deployment --disable-update-proxy --kubeadm`);
+      // /etc/hosts is written here, not by `deploy`: that command has no
+      // --etc-hosts option, and the `etc-hosts` runner already resolves a
+      // deploy's hosts from its conf.server.json.
+      await UnderpostRun.RUNNERS['etc-hosts']('', { ...options, deployId: path });
     },
 
     /**
@@ -619,7 +850,10 @@ class UnderpostRun {
      * @memberof UnderpostRun
      */
     'dev-hosts-restore': (path, options = DEFAULT_OPTION) => {
-      shellExec(`node bin deploy --restore-hosts`);
+      // Rewrite /etc/hosts with the loopback block alone, dropping the deploy
+      // host entries `dev-hosts-expose` (and the `cluster` runner) added.
+      const hostListenResult = etcHostFactory([]);
+      logger.info(hostListenResult.renderHosts);
     },
 
     /**
@@ -714,10 +948,11 @@ class UnderpostRun {
       if (deployConfId) inputs.deploy_conf_id = deployConfId;
       if (deployType) inputs.deploy_type = deployType;
 
+      // Omit `ref` so dispatchWorkflow auto-detects the repo's default branch
+      // (a fork may default to `main` rather than the monorepo's `master`).
       Underpost.repo.dispatchWorkflow({
         repo,
         workflowFile: 'npmpkg.ci.yml',
-        ref: 'master',
         inputs,
       });
     },
@@ -761,7 +996,7 @@ class UnderpostRun {
      * @memberof UnderpostRun
      */
     'docker-image': (path, options = DEFAULT_OPTION) => {
-      const repo = Underpost.repo.resolveInstanceRepo(path, options.dev);
+      const repo = Underpost.repo.resolveInstanceRepo(path, !options.test);
       Underpost.repo.dispatchWorkflow({
         repo,
         workflowFile: `docker-image${path ? `.${path}` : ''}${options.dev ? '.dev' : ''}.ci.yml`,
@@ -841,11 +1076,13 @@ class UnderpostRun {
         job = 'init';
         confId = path.replace(/^init-/, '');
       }
-      const repo = Underpost.repo.resolveInstanceRepo(confId, options.dev);
+      const repo = Underpost.repo.resolveInstanceRepo(confId, !options.test);
+      // Omit `ref` so dispatchWorkflow auto-detects the target repo's default
+      // branch (getDefaultBranch): the monorepo is `master` but instance repos
+      // like engine-cyberia default to `main` — hardcoding either 422s.
       Underpost.repo.dispatchWorkflow({
         repo,
         workflowFile: `${confId}.cd.yml`,
-        ref: 'master',
         inputs: { job },
       });
     },
@@ -902,6 +1139,7 @@ echo -e "[code]\nname=Visual Studio Code\nbaseurl=https://packages.microsoft.com
     sync: async (path, options = DEFAULT_OPTION) => {
       // Dev usage: node bin run --dev --build sync dd-default
       const env = options.dev ? 'development' : 'production';
+      options = { ...options, gatewayApi: gatewayApiEnabledFactory(options) };
       const baseCommand = 'node bin'; // options.dev ? 'node bin' : 'underpost';
       const baseClusterCommand = options.dev ? ' --dev' : '';
       const clusterFlag = options.k3s ? ' --k3s' : options.kind ? ' --kind' : ' --kubeadm';
@@ -939,11 +1177,28 @@ echo -e "[code]\nname=Visual Studio Code\nbaseurl=https://packages.microsoft.com
       }
 
       const currentTraffic = isDeployRunnerContext(path, options)
-        ? Underpost.deploy.getCurrentTraffic(deployId, { namespace: options.namespace })
+        ? Underpost.deploy.getCurrentTraffic(deployId, {
+            namespace: options.namespace,
+            env,
+            gatewayApi: options.gatewayApi,
+          })
         : '';
       let targetTraffic = currentTraffic ? (currentTraffic === 'blue' ? 'green' : 'blue') : 'green';
       if (targetTraffic) versions = versions ? versions : targetTraffic;
 
+      // The routed colour is only live traffic while it still has a ready
+      // endpoint. Everything downstream that would take the host offline to prove
+      // the maintenance fallback is conditional on this being false: a first
+      // bring-up has nothing to interrupt, a re-deploy does.
+      const serving = isTrafficServingFactory({
+        liveTraffic: currentTraffic,
+        hasReadyEndpoints: (colour) =>
+          Underpost.deploy.serviceHasReadyEndpoints({
+            service: `${deployId}-${env}-${colour}-service`,
+            namespace: options.namespace || 'default',
+          }),
+      });
+
       const ignorePods =
         isDeployRunnerContext(path, options) && targetTraffic
           ? Underpost.kubectl.get(`${deployId}-${env}-${targetTraffic}`, 'pods', options.namespace).map((p) => p.NAME)
@@ -959,16 +1214,69 @@ echo -e "[code]\nname=Visual Studio Code\nbaseurl=https://packages.microsoft.com
       const pullBundleFlag = options.pullBundle ? ' --pull-bundle' : '';
       const imagePullPolicyFlag = options.imagePullPolicy ? ` --image-pull-policy ${options.imagePullPolicy}` : '';
       const sshKeyPathFlag = options.sshKeyPath ? ` --ssh-key-path ${options.sshKeyPath}` : '';
+      const gatewayApiFlags = Underpost.deploy.gatewayApiFlagsFactory(options);
+
+      // A direct sync owns the same gateway-first contract as the full cluster
+      // runner. Build the host-side SSR documents before generating routes unless
+      // the caller explicitly selected a pre-built bundle workflow.
+      if (isDeployRunnerContext(path, options) && !options.skipFullBuild)
+        shellExec(`${baseCommand} client ${deployId} ${env}`);
 
       shellExec(
         `${baseCommand} deploy${clusterFlag} --build-manifest --sync --info-router --replicas ${replicas} --node ${node}${
           image ? ` --image ${image}` : ''
         }${versions ? ` --versions ${versions}` : ''}${
           options.namespace ? ` --namespace ${options.namespace}` : ''
-        }${timeoutFlags}${cmdString}${gitCleanFlag}${skipFullBuildFlag}${pullBundleFlag}${imagePullPolicyFlag}${sshKeyPathFlag} ${deployId} ${env}`,
+        }${timeoutFlags}${cmdString}${gitCleanFlag}${skipFullBuildFlag}${pullBundleFlag}${imagePullPolicyFlag}${sshKeyPathFlag}${gatewayApiFlags} ${deployId} ${env}`,
       );
 
       if (isDeployRunnerContext(path, options)) {
+        if (options.gatewayApi) {
+          const namespace = options.namespace || 'default';
+          const gatewayRoot = Underpost.deploy.underpostGatewayRootFactory(options);
+          shellExec(`kubectl rollout status deployment/${UNDERPOST_GATEWAY.name} -n ${namespace} --timeout=5m`);
+          const staticAssets = Underpost.deploy.syncStaticAssets(deployId, env, {
+            ...options,
+            namespace,
+            // Prefer the currently serving workload as the document source. On
+            // an initial deploy there is none, so sync falls back to the checkout.
+            versions: currentTraffic || versions || targetTraffic,
+          });
+          assertStaticAssets({ records: staticAssets, hostRoot: gatewayRoot, label: 'sync' });
+
+          if (serving)
+            logger.info('[sync] Live colour serving; holding traffic until the target colour is Ready', {
+              deployId,
+              live: currentTraffic,
+              target: targetTraffic,
+            });
+          else {
+            // Remove any inactive-colour workload left by an earlier cycle. Without
+            // this cleanup the probe could hit a stale Ready pod and never exercise
+            // the configured unavailable-backend fallback.
+            shellExec(
+              `kubectl delete service ${deployId}-${env}-${targetTraffic}-service -n ${namespace} --ignore-not-found`,
+            );
+            shellExec(
+              `kubectl delete deployment ${deployId}-${env}-${targetTraffic} -n ${namespace} --ignore-not-found`,
+            );
+            // Publish the target-colour route while its Service is deliberately
+            // absent. Site paths reach underpost-gateway and must return the
+            // configured maintenance body before deployment.yaml is submitted.
+            shellExec(
+              `${baseCommand} deploy${clusterFlag}${cmdString} --replicas ${replicas} --node ${node} --disable-update-deployment ${deployId} ${env} --versions ${versions}${
+                options.namespace ? ` --namespace ${options.namespace}` : ''
+              }${timeoutFlags}${gitCleanFlag}${imagePullPolicyFlag}${sshKeyPathFlag}${gatewayApiFlags}`,
+            );
+            await gatewayFallbackProbeRunner({
+              gatewayStatusRunner: UnderpostRun.RUNNERS['gateway-status'],
+              checks: pwaFallbackChecksFactory(deployId),
+              options,
+              label: 'sync',
+            });
+          }
+        }
+
         // Backup app/services repositories with repo-backup configured
         shellExec(
           `${baseCommand} db ${deployId} ${clusterFlag}${baseClusterCommand} --repo-backup --primary-pod --git --force-clone --preserveUUID ${options.namespace ? ` --ns ${options.namespace}` : ''}`,
@@ -976,163 +1284,119 @@ echo -e "[code]\nname=Visual Studio Code\nbaseurl=https://packages.microsoft.com
         shellExec(
           `${baseCommand} deploy${clusterFlag}${cmdString} --replicas ${replicas} --node ${node} --disable-update-proxy ${deployId} ${env} --versions ${versions}${
             options.namespace ? ` --namespace ${options.namespace}` : ''
-          }${timeoutFlags}${gitCleanFlag}${imagePullPolicyFlag}${sshKeyPathFlag}`,
+          }${timeoutFlags}${gitCleanFlag}${imagePullPolicyFlag}${sshKeyPathFlag}${gatewayApiFlags}`,
         );
         if (!targetTraffic)
-          targetTraffic = Underpost.deploy.getCurrentTraffic(deployId, { namespace: options.namespace });
+          targetTraffic = Underpost.deploy.getCurrentTraffic(deployId, {
+            namespace: options.namespace,
+            env,
+            gatewayApi: options.gatewayApi,
+          });
         await Underpost.monitor.monitorReadyRunner(deployId, env, targetTraffic, ignorePods, options.namespace);
         Underpost.deploy.switchTraffic(deployId, env, targetTraffic, replicas, options.namespace, options);
       } else
-        logger.info('current traffic', Underpost.deploy.getCurrentTraffic(deployId, { namespace: options.namespace }));
+        logger.info(
+          'current traffic',
+          Underpost.deploy.getCurrentTraffic(deployId, { namespace: options.namespace, env }),
+        );
     },
 
     /**
      * @method stop
-     * @description Stops a deployment by deleting the corresponding Kubernetes deployment and service resources.
-     * @param {string} path - The input value, identifier, or path for the operation (used to determine which traffic to stop).
+     * @description Deletes colour-suffixed Deployments and their Services, leaving routing untouched.
+     *
+     * Four ways to say what to stop, resolved by {@link ServerConfBuilder.stopPlanFactory}:
+     *
+     * ```bash
+     * # Literal: exactly this Deployment, flags ignored
+     * node bin run stop dd-cyberia-mmo-server-forest-development-blue
+     *
+     * # The deploy's PWA workload, inactive colour
+     * node bin run stop --deploy-id dd-cyberia
+     *
+     * # ...plus every variant of each instance family, inactive colour
+     * node bin run stop --deploy-id dd-cyberia --instance-id mmo-client,mmo-server
+     *
+     * # Explicit colours; both, where they exist
+     * node bin run stop --deploy-id dd-cyberia --traffic blue,green
+     * ```
+     *
+     * The default colour is the blue/green partner of whatever each target is
+     * serving, so a stop is safe against a live host unless `--traffic` names the
+     * serving colour outright — which is warned about, not refused.
+     *
+     * That colour is read through the same routing stack that published it: the
+     * Gateway API HTTPRoute by default, the Contour HTTPProxy under
+     * `--disable-gateway-api`. Reading the wrong kind finds no colour, degrades to
+     * "blue", and stops whichever Deployment happens to carry that name. It is
+     * resolved per target too — an instance's colour lives under its own
+     * `<deployId>-<instanceId>` prefix, and on a shared host the parent's answer
+     * belongs to a different variant.
+     * @param {string} [path] - Literal comma-separated Deployment names; when set, every flag is ignored.
      * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
      * @memberof UnderpostRun
      */
     stop: async (path = '', options = DEFAULT_OPTION) => {
-      let currentTraffic = Underpost.deploy.getCurrentTraffic(options.deployId, {
-        namespace: options.namespace,
-        hostTest: options.hosts,
-      });
       const env = options.dev ? 'development' : 'production';
+      const namespace = options.namespace || 'default';
+      const gatewayApi = gatewayApiEnabledFactory(options);
+
+      // Memoized because the plan and the serving check ask the same question,
+      // and `--traffic` skips the plan's lookup entirely — which is exactly when
+      // the check has to make its own.
+      const liveTraffic = {};
+      const liveTrafficOf = (target) => {
+        if (liveTraffic[target.id] === undefined)
+          liveTraffic[target.id] =
+            Underpost.deploy.getCurrentTraffic(target.id, {
+              hostTest: target.host || options.hosts,
+              namespace,
+              env,
+              gatewayApi,
+            }) || '';
+        return liveTraffic[target.id];
+      };
 
-      if (!path.match('current')) currentTraffic === 'blue' ? (currentTraffic = 'green') : (currentTraffic = 'blue');
-      const [_deployId] = path.split(',');
-      const deploymentId = `${_deployId ? _deployId : options.deployId}${
-        options.instanceId ? `-${options.instanceId}` : ''
-      }-${env}-${currentTraffic}`;
-
-      shellExec(`kubectl delete deployment ${deploymentId} -n ${options.namespace}`);
-      shellExec(`kubectl delete svc ${deploymentId}-service -n ${options.namespace}`);
-    },
-
-    /**
-     * @method ssh-deploy-stop
-     * @description Stops a remote deployment via SSH by executing the appropriate Underpost command on the remote server.
-     * @param {string} path - The input value, identifier, or path for the operation (used to determine which traffic to stop).
-     * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
-     * @memberof UnderpostRun
-     */
-    'ssh-deploy-stop': async (path, options = DEFAULT_OPTION) => {
-      const baseCommand = options.dev ? 'node bin' : 'underpost';
-      const baseClusterCommand = options.dev ? ' --dev' : '';
-
-      const remoteCommand = [
-        `${baseCommand} run${baseClusterCommand} stop${path ? ` ${path}` : ''}`,
-        ` --deploy-id ${options.deployId}${options.instanceId ? ` --instance-id ${options.instanceId}` : ''}`,
-        ` --namespace ${options.namespace}${options.hosts ? ` --hosts ${options.hosts}` : ''}`,
-      ].join('');
-
-      await Underpost.ssh.sshRemoteRunner(remoteCommand, {
-        deployId: options.deployId,
-        user: options.user,
-        dev: options.dev,
-        remote: true,
-        useSudo: true,
-        cd: '/home/dd/engine',
-      });
-    },
-
-    /**
-     * @method ssh-deploy-db-rollback
-     * @description Performs a database rollback on remote deployment via SSH.
-     * @param {string} path - Comma-separated deployId and optional number of commits to reset (format: "deployId,nCommits")
-     * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
-     * @param {string} options.deployId - The deployment identifier
-     * @param {string} options.user - The SSH user for credential lookup
-     * @param {boolean} options.dev - Development mode flag
-     * @memberof UnderpostRun
-     */
-    'ssh-deploy-db-rollback': async (path = '', options = DEFAULT_OPTION) => {
-      const baseCommand = options.dev ? 'node bin' : 'underpost';
-      let [deployId, nCommitsReset] = path.split(',');
-      if (!nCommitsReset) nCommitsReset = 1;
-
-      const remoteCommand = `${baseCommand} db ${deployId} --git --kubeadm --primary-pod --force-clone --macro-rollback-export ${nCommitsReset}${options.namespace ? ` --ns ${options.namespace}` : ''}`;
-
-      await Underpost.ssh.sshRemoteRunner(remoteCommand, {
-        deployId: options.deployId,
-        user: options.user,
-        dev: options.dev,
-        remote: true,
-        useSudo: true,
-        cd: '/home/dd/engine',
-      });
-    },
-
-    /**
-     * @method ssh-deploy-db
-     * @description Imports/restores a database on remote deployment via SSH.
-     * @param {string} path - The deployment ID for database import
-     * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
-     * @param {string} options.deployId - The deployment identifier
-     * @param {string} options.user - The SSH user for credential lookup
-     * @param {boolean} options.dev - Development mode flag
-     * @memberof UnderpostRun
-     */
-    'ssh-deploy-db': async (path, options = DEFAULT_OPTION) => {
-      const baseCommand = options.dev ? 'node bin' : 'underpost';
-
-      const remoteCommand = `${baseCommand} db ${path} --import --drop --preserveUUID --git --kubeadm --primary-pod --force-clone${options.namespace ? ` --ns ${options.namespace}` : ''}`;
-
-      await Underpost.ssh.sshRemoteRunner(remoteCommand, {
+      const { deployments, error } = stopPlanFactory({
+        path,
         deployId: options.deployId,
-        user: options.user,
-        dev: options.dev,
-        remote: true,
-        useSudo: true,
-        cd: '/home/dd/engine',
+        instanceId: options.instanceId,
+        traffic: options.traffic,
+        env,
+        instancesFor: (instanceId) => selectConfInstances(loadConfInstances(options.deployId), instanceId),
+        liveTrafficOf,
       });
-    },
-
-    /**
-     * @method ssh-deploy-db-status
-     * @description Retrieves database status/stats for a deployment (or all deployments from dd.router) via SSH.
-     * @param {string} path - Comma-separated deployId(s) or 'dd' to use the dd.router list.
-     * @param {UnderpostRunDefaultOptions} options - Runner options (uses options.deployId for SSH host lookup).
-     * @param {string} options.deployId - Deployment identifier used for SSH config lookup.
-     * @param {string} options.user - SSH user for credential lookup.
-     * @param {boolean} options.dev - Development mode flag.
-     * @param {string} [options.namespace] - Kubernetes namespace to pass to the db check.
-     * @memberof UnderpostRun
-     */
-    'ssh-deploy-db-status': async (path = '', options = DEFAULT_OPTION) => {
-      const baseCommand = options.dev ? 'node bin' : 'underpost';
-
-      let deployList = [];
-      if (!path || path === 'dd') {
-        if (!fs.existsSync('./engine-private/deploy/dd.router')) {
-          logger.warn('dd.router not found; nothing to run');
-          return;
-        }
-        deployList = fs
-          .readFileSync('./engine-private/deploy/dd.router', 'utf8')
-          .split(',')
-          .map((d) => d.trim())
-          .filter(Boolean);
-      } else {
-        deployList = path
-          .split(',')
-          .map((d) => d.trim())
-          .filter(Boolean);
+      if (error) {
+        logger.error(error);
+        return [];
       }
 
-      for (const deployId of deployList) {
-        const remoteCommand = `${baseCommand} db ${deployId} --stats --kubeadm --primary-pod${options.namespace ? ` --ns ${options.namespace}` : ''}`;
+      // Read once: it decides what is reported as actually stopped, and a target
+      // that is already gone is a no-op worth naming rather than a silent delete.
+      const deployedNames = Underpost.kubectl.get('', 'deployment', namespace).map((entry) => entry.NAME);
+      const stopped = [];
+      for (const target of deployments) {
+        const existed = deployedNames.includes(target.deployment);
+        if (existed) stopped.push(target.deployment);
+        // The Service is deleted either way: an orphan left by a half-finished
+        // cycle outlives its Deployment and would keep resolving to no endpoints.
+        shellExec(`kubectl delete deployment ${target.deployment} -n ${namespace} --ignore-not-found`);
+        shellExec(`kubectl delete svc ${target.deployment}-service -n ${namespace} --ignore-not-found`);
+      }
 
-        await Underpost.ssh.sshRemoteRunner(remoteCommand, {
-          deployId: options.deployId,
-          user: options.user,
-          dev: options.dev,
-          remote: true,
-          useSudo: true,
-          cd: '/home/dd/engine',
+      const serving = deployments.filter(
+        (target) => target.kind !== 'literal' && target.colour === liveTrafficOf(target),
+      );
+      if (serving.length > 0)
+        logger.warn('Stopped the serving colour; those routes stay published and now have no backend', {
+          deployments: serving.map((target) => target.deployment),
         });
-      }
+      logger.info('Stop complete', {
+        namespace,
+        stopped,
+        absent: deployments.filter((target) => !stopped.includes(target.deployment)).map((t) => t.deployment),
+      });
+      return stopped;
     },
 
     /**
@@ -1157,102 +1421,543 @@ echo -e "[code]\nname=Visual Studio Code\nbaseurl=https://packages.microsoft.com
     },
 
     /**
-     * @method get-proxy
-     * @description Retrieves and logs the HTTPProxy resources in the specified namespace using `kubectl get HTTPProxy`.
-     * @param {string} path - The input value, identifier, or path for the operation (used as an optional filter for the HTTPProxy resources).
+     * @method get-traffic
+     * @description Prints the live blue/green colour of every routable
+     * deployment, of both kinds, as a table.
+     * @param {string} [path] - Comma-separated hosts to report on; empty reports every host.
      * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
      * @memberof UnderpostRun
      */
-    'get-proxy': async (path = '', options = DEFAULT_OPTION) => {
-      console.log(
-        shellExec(`kubectl get HTTPProxy -n ${options.namespace} ${path} -o yaml`, {
-          silent: true,
+    'get-traffic': async (path = '', options = DEFAULT_OPTION) => {
+      options = {
+        ...options,
+        gatewayApi: gatewayApiEnabledFactory(options),
+        namespace: options.namespace || 'default',
+      };
+      // A report answers "what is live", so it cannot pick one environment from a
+      // flag and call the other absent: a cluster running `development` would be
+      // reported as entirely unrouted. Both are scanned and the environment is a
+      // column; `--dev` narrows to development when only that is wanted.
+      const envs = options.dev ? ['development'] : options.test ? ['development', 'production'] : ['production'];
+      const hosts = `${path || ''}`
+        .split(',')
+        .map((host) => host.trim())
+        .filter(Boolean);
+
+      const confRoot = './engine-private/conf';
+      const deployList = options.deployId
+        ? resolveDeployList(options.deployId)
+        : fs.existsSync(confRoot)
+          ? fs
+              .readdirSync(confRoot)
+              .filter((deployId) => fs.existsSync(`${confRoot}/${deployId}/conf.server.json`))
+              .sort()
+          : [];
+
+      const deployments = Underpost.kubectl.get('', 'deployment', options.namespace);
+      const deployedNames = deployments.map((entry) => entry.NAME);
+
+      // Four cluster-wide reads, correlated once: which kind describes a host,
+      // whether its listener terminates TLS, and whether QUIC is enabled on it.
+      // A missing CRD is an empty list, so a single-stack cluster reads the same
+      // way as one running both.
+      const listResources = (kind) => {
+        const raw = shellExec(`kubectl get ${kind} -A -o json`, {
           stdout: true,
-        })
-          .replaceAll(`blue`, `blue`.bgBlue.bold.black)
-          .replaceAll('green', 'green'.bgGreen.bold.black)
-          .replaceAll('Error', 'Error'.bold.red)
-          .replaceAll('error', 'error'.bold.red)
-          .replaceAll('ERROR', 'ERROR'.bold.red)
-          .replaceAll('Invalid', 'Invalid'.bold.red)
-          .replaceAll('invalid', 'invalid'.bold.red)
-          .replaceAll('INVALID', 'INVALID'.bold.red),
+          silent: true,
+          silentOnError: true,
+        });
+        try {
+          const parsed = JSON.parse(`${raw || ''}`);
+          return Array.isArray(parsed?.items) ? parsed.items : [];
+        } catch {
+          return [];
+        }
+      };
+      const ingressFacts = hostIngressFactsFactory({
+        httpRoutes: listResources('httproute'),
+        httpProxies: listResources('httpproxy'),
+        gateways: listResources('gateway'),
+        clientTrafficPolicies: listResources('clienttrafficpolicy'),
+      });
+      const trafficServiceSelectors = Object.fromEntries(
+        listResources('service')
+          .filter((service) => service?.metadata?.labels?.['underpost.net/traffic-service'] === 'true')
+          .map((service) => [
+            `${service?.metadata?.namespace || 'default'}/${service?.metadata?.name}`,
+            service?.spec?.selector?.app || '',
+          ]),
       );
+
+      // One read per host, reused across every deployment and environment that
+      // shares it — the colour match is pure, only the fetch is expensive.
+      const routingInfo = {};
+      const hostRoutingInfo = (host) => {
+        if (routingInfo[host] === undefined)
+          routingInfo[host] = Underpost.deploy.readHostRoutingInfo({ host, options });
+        return routingInfo[host];
+      };
+      const trafficState = {};
+      const liveTrafficStateOf = (entry, env) => {
+        const key = `${entry.id}/${env}`;
+        if (trafficState[key]) return trafficState[key];
+        const stableService = Underpost.deploy.trafficServiceNameFactory({ deployId: entry.id, env });
+        const selector = trafficServiceSelectors[`${options.namespace}/${stableService}`] || '';
+        const stableTraffic = trafficFromRoutingInfoFactory({ info: selector, deployId: entry.id, env });
+        if (stableTraffic)
+          return (trafficState[key] = {
+            colour: stableTraffic,
+            service: stableService,
+          });
+        const legacyTraffic = trafficFromRoutingInfoFactory({
+          info: hostRoutingInfo(entry.host),
+          deployId: entry.id,
+          env,
+        });
+        return (trafficState[key] = {
+          colour: legacyTraffic,
+          service: legacyTraffic ? `${entry.deployment}-${legacyTraffic}-service` : '',
+        });
+      };
+      const servingState = {};
+      const servesTraffic = (entry, env) => {
+        const service = liveTrafficStateOf(entry, env).service;
+        if (!service) return false;
+        const key = `${options.namespace}/${service}`;
+        if (servingState[key] === undefined)
+          servingState[key] = Underpost.deploy.serviceHasReadyEndpoints({
+            service,
+            namespace: options.namespace,
+          });
+        return servingState[key];
+      };
+
+      const rows = envs.flatMap((env) =>
+        trafficTableRowsFactory({
+          entries: deployList
+            .flatMap((deployId) => deployTrafficEntriesFactory({ deployId, env }))
+            .map((entry) => ({ ...entry, env })),
+          hosts,
+          liveTrafficOf: (entry) => liveTrafficStateOf(entry, env).colour,
+          servesTraffic: (entry) => servesTraffic(entry, env),
+        }),
+      );
+
+      if (rows.length === 0) {
+        logger.warn('No configured hosts matched the requested traffic report', {
+          hosts,
+          envs,
+          deployList,
+          namespace: options.namespace,
+        });
+        return rows;
+      }
+
+      // Probe the exact public URL represented by each host/path row. PWA rows
+      // can carry several configured paths in one cell, while instance rows
+      // carry one; cache by URL so shared rows never repeat network work.
+      const shellArg = (value) => `'${`${value}`.replaceAll("'", "'\\''")}'`;
+      const probeCache = new Map();
+      const probePath = (host, routePath, tls) => {
+        const normalizedPath = `${routePath || '/'}`.startsWith('/') ? `${routePath || '/'}` : `/${routePath}`;
+        let url;
+        try {
+          url = new URL(normalizedPath, `${tls ? 'https' : 'http'}://${host}`).href;
+        } catch {
+          return { path: normalizedPath, url: '', statuses: ['000'] };
+        }
+        if (!probeCache.has(url)) {
+          // -L follows the real redirect chain, -v supplies one response line
+          // per hop, -i keeps full response headers available, and -s removes
+          // only the progress meter. The body is discarded to keep a status
+          // report bounded even when a host returns a large application page.
+          const raw = shellExec(
+            `curl -L -v -i -s --connect-timeout 3 --max-time 12 --max-redirs 10 ` +
+              `-o /dev/null -w '\nUNDERPOST_CURL_FINAL=%{http_code}\n' ${shellArg(url)} 2>&1 || true`,
+            { stdout: true, silent: true, silentOnError: true, disableLog: true },
+          );
+          probeCache.set(url, curlStatusChainFactory(raw));
+        }
+        return { path: normalizedPath, url, statuses: probeCache.get(url) };
+      };
+
+      const deploymentByName = new Map(deployments.map((deployment) => [deployment.NAME, deployment]));
+      const readinessOf = (deployment) => {
+        const replicas = deployment?.READY || '-';
+        const [ready, desired] = `${replicas}`.split('/').map(Number);
+        return {
+          replicas,
+          exists: Boolean(deployment),
+          ready: Number.isFinite(ready) && Number.isFinite(desired) && desired > 0 && ready === desired,
+        };
+      };
+      const deploymentStatusOf = (row, traffic) => {
+        if (!traffic) return null;
+        const deployment = `${row.deployment}-${traffic}`;
+        return {
+          deployment,
+          traffic,
+          ...readinessOf(deploymentByName.get(deployment)),
+        };
+      };
+      const reportRows = rows.map((row) => {
+        const facts = ingressFacts[row.host] || {};
+        const probes = [...new Set(`${row.path || '/'}`.split(/\s+/).filter(Boolean))].map((routePath) =>
+          probePath(row.host, routePath, facts.tls),
+        );
+        const oppositeTraffic = row.traffic ? nextTrafficFactory(row.traffic) : '';
+        const current = deploymentStatusOf(row, row.traffic);
+        const opposite = deploymentStatusOf(row, oppositeTraffic);
+        return {
+          ...row,
+          probes,
+          current: current ? { ...current, serving: row.serving } : null,
+          opposite,
+        };
+      });
+
+      // Padded on the raw values, coloured afterwards: an ANSI escape counts
+      // toward String.length and would skew every column right of it.
+      const columns = ['HOST', 'PATH', 'KIND', 'ROUTE', 'TLS', 'HTTP3', 'CURRENT', 'OPPOSITE'];
+      const deploymentStatus = (status, includeServing = false) => {
+        if (!status) return `unrouted - missing${includeServing ? ' not-serving' : ''}`;
+        return [
+          status.deployment,
+          status.replicas,
+          status.exists ? (status.ready ? 'ready' : 'not-ready') : 'missing',
+          ...(includeServing ? [status.serving ? 'serving' : 'not-serving'] : []),
+        ].join(' ');
+      };
+      const cellOf = (row) => {
+        const facts = ingressFacts[row.host] || {};
+        const pathStatus = row.probes.map((probe) => `${probe.path} [${probe.statuses.join('→')}]`).join(' ');
+        return [
+          row.host,
+          pathStatus,
+          row.kind,
+          facts.route || 'none',
+          facts.tls ? 'yes' : 'no',
+          facts.http3 ? 'yes' : 'no',
+          deploymentStatus(row.current, true),
+          deploymentStatus(row.opposite),
+        ];
+      };
+      const paint = (value, i) => {
+        if (columns[i] === 'PATH')
+          return value.replace(/\b(?:000|[1-5][0-9]{2})\b/g, (status) => {
+            if (/^1/.test(status)) return status.cyan;
+            if (/^2/.test(status)) return status.green;
+            if (/^3/.test(status)) return status.cyan;
+            if (/^4/.test(status)) return status.yellow;
+            return status.red;
+          });
+        if (columns[i] === 'CURRENT' || columns[i] === 'OPPOSITE') {
+          if (value === '-') return value;
+          const [deployment, replicas, status, serving] = value.split(' ');
+          const deploymentDisplay = deployment.replace(
+            /-(blue|green)$/,
+            (_, traffic) => `-${traffic === 'blue' ? traffic.bgBlue.bold.black : traffic.bgGreen.bold.black}`,
+          );
+          const replicasDisplay = readinessOf({ READY: replicas }).ready ? replicas.green : replicas.red;
+          const statusDisplay = status === 'ready' ? status.green : status.red;
+          const servingDisplay = serving ? (serving === 'serving' ? serving.green : serving.red) : '';
+          return [deploymentDisplay, replicasDisplay, statusDisplay, servingDisplay].filter(Boolean).join(' ');
+        }
+        // TLS and HTTP/3 being off is a normal development state, not a fault, so
+        // only the affirmative is highlighted.
+        if (columns[i] === 'TLS' || columns[i] === 'HTTP3') return value === 'yes' ? value.green : value;
+        if (columns[i] === 'ROUTE') return value === 'none' ? value.red : value;
+        return value;
+      };
+      // A shared table renderer, called once per environment when both are
+      // scanned: mixing development and production rows into one table is what
+      // made an unrouted production host look like a duplicate of the same,
+      // live development host.
+      const printTable = (cells, heading) => {
+        const widths = columns.map((column, i) => Math.max(column.length, ...cells.map((cell) => `${cell[i]}`.length)));
+        const line = (values, painted) =>
+          values
+            .map(
+              (value, i) => (painted ? paint(`${value}`, i) : `${value}`) + ' '.repeat(widths[i] - `${value}`.length),
+            )
+            .join('  ');
+        console.log(heading ? `\n${heading.bold}\n${line(columns, false).bold}` : `\n${line(columns, false).bold}`);
+        console.log(widths.map((width) => '-'.repeat(width)).join('  '));
+        for (const cell of cells) console.log(line(cell, true));
+      };
+      for (const env of envs) {
+        const envCells = reportRows.filter((row) => row.env === env).map(cellOf);
+        if (envCells.length > 0) printTable(envCells, `[${env.toUpperCase()}]`);
+      }
+      console.log('');
+      return reportRows;
+    },
+
+    /**
+     * @method restore-mongo
+     * @description Initializes a MongoDB replica set in the cluster without resetting existing data.
+     * @param {string} path - The input value, identifier, or path for the operation.
+     * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
+    'restore-mongo': async (path, options = DEFAULT_OPTION) => {
+      await MongoBootstrap.initReplicaSet({
+        namespace: options.namespace || 'default',
+        reset: options.reset || false,
+        clusterType: options.kubeadm ? 'kubeadm' : options.k3s ? 'k3s' : 'kind', // o 'k3s' / 'kubeadm' según corresponda
+        underpostRoot: '.',
+      });
+    },
+
+    /**
+     * @method ingress-refresh
+     * @description Rebuilds the shared HTTPProxy/HTTPRoute host map without
+     * inheriting application workload placement. Supplying a path or
+     * `--ingress-node` is the explicit recovery mechanism for relocating the
+     * public 80/443 listener.
+     * @param {string} [path] - Optional ingress node name.
+     * @param {UnderpostRunDefaultOptions} options - Runner options.
+     * @returns {boolean} True after the ingress is Ready with the refreshed map.
+     * @memberof UnderpostRun
+     */
+    'ingress-refresh': (path = '', options = DEFAULT_OPTION) => {
+      const namespace = options.namespace || 'default';
+      const ingressNode = options.ingressNode || `${path || ''}`.trim();
+      const updated = Underpost.cluster.refreshUnderpostIngress({
+        namespace,
+        options: { ...options, ingressNode },
+      });
+      if (!updated)
+        throw new Error(
+          `[ingress-refresh] ${UNDERPOST_INGRESS.name} is not installed; install both ingress stacks first`,
+        );
+      logger.info('[ingress-refresh] Shared ingress is operational', {
+        namespace,
+        node: ingressNode || '(preserved)',
+      });
+      return true;
     },
 
     'instance-promote': async (path, options = DEFAULT_OPTION) => {
       const env = options.dev ? 'development' : 'production';
-      const baseCommand = options.dev ? 'node bin' : 'underpost';
-      const baseClusterCommand = options.dev ? ' --dev' : '';
+      options = { ...options, gatewayApi: gatewayApiEnabledFactory(options) };
       let [deployId, id] = path.split(',');
-      const confInstances = JSON.parse(
-        fs.readFileSync(`./engine-private/conf/${deployId}/conf.instances.json`, 'utf8'),
-      );
+      const confInstances = loadConfInstances(deployId);
+      const promoted = selectConfInstances(confInstances, id);
       let promotedTraffic = '';
-      for (const instance of confInstances) {
-        let {
-          id: _id,
-          host: _host,
-          path: _path,
-          image: _image,
-          fromPort: _fromPort,
-          toPort: _toPort,
-          fromDebugPort: _fromDebugPort,
-          toDebugPort: _toDebugPort,
-          cmd: _cmd,
-          volumes: _volumes,
-          metadata: _metadata,
-        } = instance;
-        if (id !== _id) continue;
-        const _deployId = `${deployId}-${_id}`;
-        // Use debug ports in development when defined, fall back to production ports.
-        if (env === 'development' && _fromDebugPort) _fromPort = _fromDebugPort;
-        if (env === 'development' && _toDebugPort) _toPort = _toDebugPort;
-        const currentTraffic = Underpost.deploy.getCurrentTraffic(_deployId, {
-          hostTest: _host,
+
+      // A Contour HTTPProxy is named after its host, so every instance sharing a
+      // host shares one object. Rebuilding it from the promoted instance alone
+      // would drop its siblings' routes, so each host is rendered from the full
+      // set: promoted instances flip colour, the rest keep their live colour.
+      //
+      // "Full set" is not what the conf currently declares. Each variant sub-path
+      // is its own deployment, and one that was dropped from the conf while its
+      // workload is still up must keep its route — otherwise editing the variant
+      // list to scope a deploy takes the untouched variants offline. The
+      // descriptors last published for the host cover exactly that gap, and a
+      // variant leaves the render only once its Deployment is gone.
+      const promotedIds = new Set(promoted.map((instance) => instance.id));
+      const hosts = [...new Set(promoted.map((instance) => instance.host))];
+      const namespace = options.namespace || 'default';
+      const gatewayConfDir = Underpost.deploy.gatewayConfDirFactory({ deployId, env });
+      const deployedNames = Underpost.kubectl.get('', 'deployment', namespace).map((entry) => entry.NAME);
+      const instancesByHost = Object.fromEntries(
+        hosts.map((host) => [
+          host,
+          hostRenderInstancesFactory({
+            declared: confInstances.filter((instance) => instance.host === host),
+            preserved: readHostInstanceRegistry({ confDir: gatewayConfDir, host }),
+            isDeployed: (instance) =>
+              deployedNames.some((name) => name.startsWith(`${deployId}-${instance.id}-${env}-`)),
+          }),
+        ]),
+      );
+      const affected = hosts.flatMap((host) => instancesByHost[host]);
+      const trafficById = {};
+      const currentTrafficById = {};
+      const bootstrapTrafficById = {};
+      for (const instance of affected) {
+        const currentTraffic = Underpost.deploy.getCurrentTraffic(`${deployId}-${instance.id}`, {
+          hostTest: instance.host,
           namespace: options.namespace,
+          env,
+          gatewayApi: options.gatewayApi,
         });
-        const targetTraffic = currentTraffic ? (currentTraffic === 'blue' ? 'green' : 'blue') : 'blue';
-        promotedTraffic = targetTraffic;
-        let proxyYaml =
-          Underpost.deploy.baseProxyYamlFactory({ host: _host, env: options.tls ? 'production' : env, options }) +
-          Underpost.deploy.deploymentYamlServiceFactory({
-            path: _path,
-            port: _fromPort,
-            // serviceId: deployId,
-            deployId: _deployId,
-            env,
-            deploymentVersions: [targetTraffic],
-            // pathRewritePolicy,
+        currentTrafficById[instance.id] = currentTraffic;
+        if (!promotedIds.has(instance.id)) {
+          trafficById[instance.id] = currentTraffic || 'blue';
+          continue;
+        }
+        trafficById[instance.id] = nextTrafficFactory(currentTraffic, options.targetTrafficById?.[instance.id]);
+        promotedTraffic = trafficById[instance.id];
+      }
+
+      // Readiness is mandatory for an actual promotion. The only exception is
+      // the explicit no-backend checkpoint, whose purpose is to prove that an
+      // endpointless selector returns the configured fallback before a workload
+      // exists.
+      if (!options.noBackendCheckpoint)
+        for (const instance of affected.filter((entry) => promotedIds.has(entry.id))) {
+          const podId = `${deployId}-${instance.id}-${env}-${trafficById[instance.id]}`;
+          if (
+            !Underpost.deploy.awaitDeploymentReady({ deployment: podId, namespace }) ||
+            !Underpost.deploy.awaitServiceEndpoints({ service: `${podId}-service`, namespace })
+          )
+            throw new Error(`Refusing to promote ${instance.id} to unready colour ${trafficById[instance.id]}`);
+        }
+
+      // Bootstrap one stable Service per instance on its current ready colour.
+      // Routes and fallback blocks can now migrate without changing traffic;
+      // promoted selectors move to their targets only after the whole host has
+      // converged below.
+      for (const instance of affected) {
+        const instanceDeployId = `${deployId}-${instance.id}`;
+        const currentTraffic = currentTrafficById[instance.id];
+        const currentReady =
+          !!currentTraffic &&
+          Underpost.deploy.serviceHasReadyEndpoints({
+            service: `${instanceDeployId}-${env}-${currentTraffic}-service`,
+            namespace,
+          });
+        const bootstrapTraffic = currentReady ? currentTraffic : trafficById[instance.id];
+        bootstrapTrafficById[instance.id] = bootstrapTraffic;
+        Underpost.deploy.applyTrafficService({
+          deployId: instanceDeployId,
+          env,
+          traffic: bootstrapTraffic,
+          namespace,
+          fromPort: instancePortFactory({ instance, env }),
+          toPort: instancePortFactory({ instance, env, container: true }),
+        });
+      }
+
+      // Instance routes attach to the Gateway the parent deploy owns. A Gateway
+      // per instance host cannot work beside it: `mergeGateways` collapses every
+      // Gateway of the class onto one listener per (port, protocol), so a
+      // hostname-scoped listener and the deploy's hostname-less one contend for
+      // the same port — on 80 the hostname-scoped one is dropped outright, and
+      // on 443 it keeps an SNI filter chain whose route table is left empty.
+      // Either way every path on the instance host answers 404 while the
+      // Gateway reports Programmed and the route reports Accepted.
+      const gatewayName = Underpost.deploy.gatewayNameFactory({ deployId, env });
+      for (const host of hosts) {
+        const hostInstances = instancesByHost[host];
+        const routingEnv = options.tls ? 'production' : env;
+        // Every variant of this host contributes one proxied sub-path to the
+        // shared gateway, whose interception turns each workload's own error
+        // into that variant's declared document.
+        if (options.gatewayApi)
+          writeHostServerConf({
+            confDir: gatewayConfDir,
+            host,
+            conf: hostServerConfFactory({
+              host,
+              namespace: options.namespace || 'default',
+              routes: hostInstances.map((instance) => ({
+                path: instance.path,
+                upstream: `${Underpost.deploy.trafficServiceNameFactory({
+                  deployId: `${deployId}-${instance.id}`,
+                  env,
+                })}:${instancePortFactory({ instance, env })}`,
+                statuses: instanceInterceptStatusesFactory(instance),
+                stripPrefix: Array.isArray(instance.pathRewritePolicy) && instance.pathRewritePolicy.length > 0,
+              })),
+            }),
+          });
+        // Recorded before the route is published, so a variant dropped from the
+        // conf keeps its descriptor from the render that still carried it.
+        writeHostInstanceRegistry({ confDir: gatewayConfDir, host, instances: hostInstances });
+        // The route below sends every intercepted path to this shared Nginx
+        // service. Load the host block first so an Accepted route can never race
+        // a gateway that still has only its default server configuration.
+        if (options.gatewayApi)
+          installGatewayConf({
+            hostRoot: Underpost.deploy.underpostGatewayRootFactory(options),
+            confSourceDir: gatewayConfDir,
+            namespace: options.namespace,
           });
+        let proxyYaml = options.gatewayApi
+          ? Underpost.deploy.httpRouteYamlFactory({
+              host,
+              options,
+              parentName: gatewayName,
+              rules: instanceHttpRouteRulesFactory({ deployId, instances: hostInstances, env, trafficById, options }),
+            })
+          : Underpost.deploy.baseProxyYamlFactory({ host, env: routingEnv, options }) +
+            instanceProxyRoutesFactory({ deployId, instances: hostInstances, env, trafficById });
         if (options.tls) {
           if (options.test) {
-            const sslDir = `./engine-private/ssl/${_host}`;
-            const nameSafe = _host.replace(/[^a-zA-Z0-9_.-]/g, '_');
-            fs.mkdirpSync(sslDir);
-            shellExec(`bash ./scripts/ssl.sh "${sslDir}" "${_host}"`);
-            shellExec(`kubectl delete secret ${_host} -n ${options.namespace} --ignore-not-found`);
-            shellExec(
-              `kubectl create secret tls ${_host} --cert="${sslDir}/${nameSafe}.pem" --key="${sslDir}/${nameSafe}-key.pem" -n ${options.namespace}`,
-            );
+            Underpost.deploy.selfSignedTlsSecretFactory({
+              host,
+              namespace: options.namespace,
+              underpostRoot: options.underpostRoot || '.',
+            });
           } else {
-            shellExec(`sudo kubectl delete Certificate ${_host} -n ${options.namespace} --ignore-not-found`);
-            proxyYaml += Underpost.deploy.buildCertManagerCertificate({ ...options, host: _host });
+            shellExec(`sudo kubectl delete Certificate ${host} -n ${options.namespace} --ignore-not-found`);
+            proxyYaml += Underpost.deploy.buildCertManagerCertificate({ ...options, host });
           }
         }
-        // console.log(proxyYaml);
-        shellExec(`kubectl delete HTTPProxy ${_host} --namespace ${options.namespace} --ignore-not-found`);
+        if (options.gatewayApi) {
+          // Left by the per-host model this replaces. Both outlive the route
+          // that referenced them and keep contending for the merged listener.
+          for (const name of [`Gateway ${host}`, `ClientTrafficPolicy ${host}-http3`])
+            shellExec(`kubectl delete ${name} --namespace ${options.namespace} --ignore-not-found`, { silent: true });
+        }
+        // The host's route object is replaced in place, never deleted first:
+        // `apply` moves the whole spec in one transition, so the hostname always
+        // has a route. Delete-then-apply left a window with none, and Envoy
+        // answered every request that landed in it 404 — an outage on each
+        // promote, independent of which colour was healthy.
         shellExec(
-          `kubectl apply -f - -n ${options.namespace} <<EOF
+          `kubectl apply -f - -n ${options.namespace} <<'EOF'
 ${proxyYaml}
 EOF
 `,
           { disableLog: true },
         );
       }
+      // These hostnames may have just moved between stacks, or appeared for the
+      // first time. A shared edge that has not been told answers them from the
+      // other data plane, which has no route for them — a 404 in front of a
+      // healthy workload. No-op when no shared edge is installed.
+      const sharedIngressUpdated = Underpost.cluster.refreshUnderpostIngress({ namespace, options });
+      if (sharedIngressUpdated) {
+        Underpost.deploy.removeInactiveHostRoutes({ hosts, gatewayApi: options.gatewayApi, namespace });
+        Underpost.cluster.refreshUnderpostIngress({ namespace, options });
+      }
+      if (!options.noBackendCheckpoint)
+        for (const instance of affected.filter((entry) => promotedIds.has(entry.id))) {
+          const instanceDeployId = `${deployId}-${instance.id}`;
+          const targetTraffic = trafficById[instance.id];
+          const bootstrapTraffic = bootstrapTrafficById[instance.id];
+          if (targetTraffic !== bootstrapTraffic)
+            Underpost.deploy.applyTrafficService({
+              deployId: instanceDeployId,
+              env,
+              traffic: targetTraffic,
+              namespace,
+              fromPort: instancePortFactory({ instance, env }),
+              toPort: instancePortFactory({ instance, env, container: true }),
+            });
+          const trafficService = Underpost.deploy.trafficServiceNameFactory({ deployId: instanceDeployId, env });
+          if (!Underpost.deploy.awaitServiceEndpoints({ service: trafficService, namespace })) {
+            if (targetTraffic !== bootstrapTraffic)
+              Underpost.deploy.applyTrafficService({
+                deployId: instanceDeployId,
+                env,
+                traffic: bootstrapTraffic,
+                namespace,
+                fromPort: instancePortFactory({ instance, env }),
+                toPort: instancePortFactory({ instance, env, container: true }),
+              });
+            throw new Error(`Traffic Service ${trafficService} never became ready on ${targetTraffic}`);
+          }
+        }
       // Refresh the gRPC service to ensure it points to the parent deploy's current traffic.
       if (promotedTraffic) {
-        const parentTraffic = Underpost.deploy.getCurrentTraffic(deployId, { namespace: options.namespace }) || 'blue';
+        const parentTraffic =
+          Underpost.deploy.getCurrentTraffic(deployId, { namespace: options.namespace, env }) || 'blue';
         const grpcServicePath = Underpost.deploy.buildGrpcServiceManifest({
           deployId,
           env,
@@ -1272,13 +1977,75 @@ EOF
      */
     instance: async (path = '', options = DEFAULT_OPTION) => {
       const env = options.dev ? 'development' : 'production';
+      options = {
+        ...options,
+        gatewayApi: gatewayApiEnabledFactory(options),
+        namespace: options.namespace || 'default',
+      };
       const baseCommand = options.dev ? 'node bin' : 'underpost';
       const baseClusterCommand = options.dev ? ' --dev' : '';
       let [deployId, id, replicas] = path.split(',');
       if (!replicas) replicas = options.replicas;
-      const confInstances = JSON.parse(
-        fs.readFileSync(`./engine-private/conf/${deployId}/conf.instances.json`, 'utf8'),
-      );
+      const confInstances = selectConfInstances(loadConfInstances(deployId), id);
+      const { liveTrafficById, targetTrafficById, serving } = instanceTrafficPlanFactory({
+        instances: confInstances,
+        requestedTraffic: options.traffic,
+        liveTrafficOf: (instance) =>
+          Underpost.deploy.getCurrentTraffic(`${deployId}-${instance.id}`, {
+            hostTest: instance.host,
+            namespace: options.namespace,
+            env,
+            gatewayApi: options.gatewayApi,
+          }),
+        servesTraffic: (instance, colour) =>
+          Underpost.deploy.serviceHasReadyEndpoints({
+            service: `${deployId}-${instance.id}-${env}-${colour}-service`,
+            namespace: options.namespace,
+          }),
+      });
+
+      let prePromoted = false;
+      const fallbackChecks = instanceFallbackChecksFactory(confInstances);
+      // The promote points intercepted statuses at these documents on either
+      // path, so they are placed regardless of which one runs.
+      if (options.gatewayApi && fallbackChecks.length > 0 && !options.expose)
+        placeInstanceStaticAssets({ instances: confInstances, options, label: 'instance' });
+      if (
+        options.gatewayApi &&
+        !options.gatewayBootstrapComplete &&
+        fallbackChecks.length > 0 &&
+        !options.expose &&
+        serving.length === 0
+      ) {
+        // Clear the target colour before routing to it. A previous blue/green
+        // cycle may have left that inactive Deployment Ready, which would turn
+        // this into a stale-app probe instead of a no-backend fallback probe.
+        for (const instance of confInstances) {
+          const podId = `${deployId}-${instance.id}-${env}-${targetTrafficById[instance.id]}`;
+          shellExec(`kubectl delete service ${podId}-service --namespace ${options.namespace} --ignore-not-found`);
+          shellExec(`kubectl delete deployment ${podId} --namespace ${options.namespace} --ignore-not-found`);
+        }
+        // A direct `run instance` must publish and prove its configured static
+        // fallback before it submits the first instance Deployment document.
+        await UnderpostRun.RUNNERS['instance-promote'](`${deployId},${id}`, {
+          ...options,
+          targetTrafficById,
+          noBackendCheckpoint: true,
+        });
+        await gatewayFallbackProbeRunner({
+          gatewayStatusRunner: UnderpostRun.RUNNERS['gateway-status'],
+          checks: fallbackChecks,
+          options,
+          label: 'instance',
+        });
+        prePromoted = true;
+      } else if (serving.length > 0)
+        logger.info('[instance] Live colour serving; holding traffic until the target colour is Ready', {
+          hosts: [...new Set(serving.map((instance) => instance.host))],
+          live: serving.map((instance) => `${instance.id}:${liveTrafficById[instance.id]}`),
+          target: serving.map((instance) => `${instance.id}:${targetTrafficById[instance.id]}`),
+        });
+
       const etcHosts = [];
       for (const instance of confInstances) {
         let {
@@ -1286,10 +2053,6 @@ EOF
           host: _host,
           path: _path,
           image: _image,
-          fromPort: _fromPort,
-          toPort: _toPort,
-          fromDebugPort: _fromDebugPort,
-          toDebugPort: _toDebugPort,
           cmd: _cmd,
           volumes: _volumes,
           metadata: _metadata,
@@ -1297,11 +2060,9 @@ EOF
           readinessProbe: _readinessProbe,
           livenessProbe: _livenessProbe,
         } = instance;
-        if (id !== _id) continue;
         const _deployId = `${deployId}-${_id}`;
-        // Use debug ports in development when defined, fall back to production ports.
-        if (env === 'development' && _fromDebugPort) _fromPort = _fromDebugPort;
-        if (env === 'development' && _toDebugPort) _toPort = _toDebugPort;
+        const _fromPort = instancePortFactory({ instance, env });
+        const _toPort = instancePortFactory({ instance, env, container: true });
         etcHosts.push(_host);
         if (options.expose) continue;
         // Examples images:
@@ -1318,12 +2079,7 @@ EOF
             k3s: options.k3s,
           });
 
-        const currentTraffic = Underpost.deploy.getCurrentTraffic(_deployId, {
-          hostTest: _host,
-          namespace: options.namespace,
-        });
-
-        const targetTraffic = currentTraffic ? (currentTraffic === 'blue' ? 'green' : 'blue') : 'blue';
+        const targetTraffic = targetTrafficById[instance.id];
         const podId = `${_deployId}-${env}-${targetTraffic}`;
         const ignorePods = Underpost.kubectl.get(podId, 'pods', options.namespace).map((p) => p.NAME);
         Underpost.deploy.configMap(env, options.namespace);
@@ -1343,20 +2099,21 @@ EOF
                 k3s: options.k3s,
                 env,
               }),
-              clusterContext: options.k3s ? 'k3s' : options.kubeadm ? 'kubeadm' : 'kind',
+              clusterContext: clusterTypeFactory(options),
               gitClean: options.gitClean || false,
               sshKeyPath: options.sshKeyPath || '',
             });
         // Regenerate the parent deploy's gRPC ClusterIP service pointing to the
         // parent's current traffic colour and apply it before the instance pod starts so
         // DNS is resolvable the moment the pod boots.
-        const parentTraffic = Underpost.deploy.getCurrentTraffic(deployId, { namespace: options.namespace }) || 'blue';
+        const parentTraffic =
+          Underpost.deploy.getCurrentTraffic(deployId, { namespace: options.namespace, env }) || 'blue';
         const grpcServicePath = Underpost.deploy.buildGrpcServiceManifest({
           deployId,
           env,
           confServer: loadConfServerJson(`./engine-private/conf/${deployId}/conf.server.json`),
           namespace: options.namespace,
-          traffic: [targetTraffic],
+          traffic: [parentTraffic],
           host: _host,
         });
         if (grpcServicePath) shellExec(`kubectl apply -f ${grpcServicePath} -n ${options.namespace}`);
@@ -1371,7 +2128,6 @@ EOF
         // Resolve env-scoped lifecycle/probe blocks: each can be either
         //   { ...envObj }                        // shared shape
         //   { development: {...}, production: {...} }   // env-specific
-        const pickEnv = (v) => (v && (v.development || v.production) ? v[env] : v);
 
         // Convention: an instance config may place `imagePullPolicy` inside
         // the env-scoped lifecycle block (alongside postStart/preStop).
@@ -1379,7 +2135,7 @@ EOF
         // strip it from the lifecycle hash so the rendered YAML stays valid.
         // CLI override (`--image-pull-policy`) wins over the conf value.
         const { lifecycle: lifecycleForManifest, imagePullPolicy: lifecycleImagePullPolicy } =
-          Underpost.deploy.extractInstanceImagePullPolicy(pickEnv(_lifecycle));
+          Underpost.deploy.extractInstanceImagePullPolicy(resolveEnvScoped(_lifecycle, env));
         const instanceImagePullPolicy = options.imagePullPolicy || lifecycleImagePullPolicy;
 
         let deploymentYaml = `---
@@ -1395,16 +2151,31 @@ ${Underpost.deploy
     volumes: _volumes,
     cmd: resolvedCmd,
     lifecycle: lifecycleForManifest,
-    readinessProbe: pickEnv(_readinessProbe),
-    livenessProbe: pickEnv(_livenessProbe),
+    readinessProbe: Underpost.deploy.requiredReadinessProbeFactory({
+      probe: resolveEnvScoped(_readinessProbe, env),
+      port: _toPort,
+    }),
+    livenessProbe: resolveEnvScoped(_livenessProbe, env),
     containerPort: _toPort,
     imagePullPolicy: instanceImagePullPolicy,
+    // Pin the pod in the manifest submitted for its only rollout. Volumes were
+    // already resolved against this node; leaving the pod unconstrained could
+    // schedule it away from its data and require a second, post-ready move.
+    nodeName: options.nodeName
+      ? Underpost.deploy.resolveDeployNode({
+          node: options.nodeName,
+          kind: options.kind,
+          kubeadm: options.kubeadm,
+          k3s: options.k3s,
+          env,
+        })
+      : '',
   })
   .replace('{{ports}}', buildKindPorts(_fromPort, _toPort))}
 `;
         // console.log(deploymentYaml);
         shellExec(
-          `kubectl apply -f - -n ${options.namespace} <<EOF
+          `kubectl apply -f - -n ${options.namespace} <<'EOF'
 ${deploymentYaml}
 EOF
 `,
@@ -1426,13 +2197,13 @@ EOF
           logger.error(`Deployment ${deployId} did not become ready in time.`);
           return;
         }
-        shellExec(
-          `${baseCommand} run${baseClusterCommand} --namespace ${options.namespace}` +
-            `${options.nodeName ? ` --node-name ${options.nodeName}` : ''}` +
-            `${options.tls ? ` --tls ${options.test ? '--test' : ''}` : ''}` +
-            ` instance-promote '${path}'`,
-        );
       }
+      // Cluster-invoked instances inherit a fallback route for the old
+      // colour, so they still promote the family atomically after every variant
+      // is Ready. A direct run already routed the exact target colour before the
+      // Deployment and proved its fallback; that route simply starts proxying the
+      // new endpoints and must not be toggled a second time.
+      if (!options.expose && !prePromoted) await UnderpostRun.RUNNERS['instance-promote'](`${deployId},${id}`, options);
       if (options.etcHosts) {
         const hostListenResult = etcHostFactory(etcHosts);
         logger.info(hostListenResult.renderHosts);
@@ -1485,35 +2256,48 @@ EOF
      * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
      * @memberof UnderpostRun
      */
-    'instance-build-manifest': (path, options = DEFAULT_OPTION) => {
+    'instance-build-manifest': async (path, options = DEFAULT_OPTION) => {
       const env = options.dev ? 'development' : 'production';
       let [deployId, id, projectPath] = path.split(',');
       const rootPath = projectPath ? projectPath : '.';
+
+      const confInstances = loadConfInstances(deployId);
+      // Targeting a template id builds every world in the family. The fan-out
+      // re-enters this runner with `instanceOnly` because the default world
+      // keeps the template id verbatim — without it, selecting `mmo-server`
+      // would match the family again and recurse forever. Only that default
+      // world publishes to the project root, so the repo keeps exactly one
+      // canonical Dockerfile/deployment.yaml pair.
+      const selected = options.instanceOnly
+        ? confInstances.filter((instance) => instance.id === id)
+        : selectConfInstances(confInstances, id);
+      if (selected.length === 0) {
+        logger.error(`Instance with id '${id}' not found in conf.instances.json for deployId '${deployId}'`);
+        return;
+      }
+      if (!options.instanceOnly && (selected.length > 1 || selected[0].id !== id)) {
+        for (const instance of selected)
+          await UnderpostRun.RUNNERS['instance-build-manifest'](
+            [deployId, instance.id, projectPath].filter((v) => v !== undefined).join(','),
+            { ...options, instanceOnly: true },
+          );
+        return;
+      }
+
       const envManifestPath = `${rootPath}/manifests/deployments/${id}-${env}`;
       const outputPath = `${envManifestPath}/deployment.yaml`;
       const dockerfileManifestPath = `${envManifestPath}/Dockerfile`;
 
       fs.mkdirpSync(envManifestPath);
 
-      const confInstances = JSON.parse(
-        fs.readFileSync(`./engine-private/conf/${deployId}/conf.instances.json`, 'utf8'),
-      );
-
-      const instance = confInstances.find((i) => i.id === id);
-      if (!instance) {
-        logger.error(`Instance with id '${id}' not found in conf.instances.json for deployId '${deployId}'`);
-        return;
-      }
+      const instance = selected[0];
+      const isDefaultInstance = instance.id === instance.templateId || !instance.templateId;
+      const instanceEnvBuilder = await loadProjectInstanceEnvBuilder(deployId);
 
       let {
         id: _id,
         host: _host,
-        path: _path,
         image: _image,
-        fromPort: _fromPort,
-        toPort: _toPort,
-        fromDebugPort: _fromDebugPort,
-        toDebugPort: _toDebugPort,
         cmd: _cmd,
         volumes: _volumes,
         metadata: _metadata,
@@ -1550,9 +2334,8 @@ EOF
 
       const _deployId = `${deployId}-${_id}`;
       if (!_image) _image = `underpost/underpost-engine:${Underpost.version}`;
-      // Use debug ports in development when defined, fall back to production ports.
-      if (env === 'development' && _fromDebugPort) _fromPort = _fromDebugPort;
-      if (env === 'development' && _toDebugPort) _toPort = _toDebugPort;
+      const _fromPort = instancePortFactory({ instance, env });
+      const _toPort = instancePortFactory({ instance, env, container: true });
 
       // Build image from projectPath Dockerfile and load into cluster when --build is set.
       if (options.build && projectPath) {
@@ -1585,13 +2368,12 @@ EOF
 
       // Env-aware lifecycle / probe selection. Each block may either be
       // a single object (shared across envs) or `{ development, production }`.
-      const pickEnv = (v) => (v && (v.development || v.production) ? v[env] : v);
 
       // Convention: an instance config may place `imagePullPolicy` inside
       // the env-scoped lifecycle block (alongside postStart/preStop).
       // Extract it onto the container spec and strip it from the lifecycle hash.
       const { lifecycle: lifecycleForManifest, imagePullPolicy: lifecycleImagePullPolicy } =
-        Underpost.deploy.extractInstanceImagePullPolicy(pickEnv(_lifecycle));
+        Underpost.deploy.extractInstanceImagePullPolicy(resolveEnvScoped(_lifecycle, env));
       const instanceImagePullPolicy = options.imagePullPolicy || lifecycleImagePullPolicy;
 
       const deploymentYaml =
@@ -1608,10 +2390,22 @@ EOF
             volumes: _volumes,
             cmd: resolvedCmd,
             lifecycle: lifecycleForManifest,
-            readinessProbe: pickEnv(_readinessProbe),
-            livenessProbe: pickEnv(_livenessProbe),
+            readinessProbe: Underpost.deploy.requiredReadinessProbeFactory({
+              probe: resolveEnvScoped(_readinessProbe, env),
+              port: _toPort,
+            }),
+            livenessProbe: resolveEnvScoped(_livenessProbe, env),
             containerPort: _toPort,
             imagePullPolicy: instanceImagePullPolicy,
+            nodeName: options.nodeName
+              ? Underpost.deploy.resolveDeployNode({
+                  node: options.nodeName,
+                  kind: options.kind,
+                  kubeadm: options.kubeadm,
+                  k3s: options.k3s,
+                  env,
+                })
+              : '',
           })
           .replace('{{ports}}', buildKindPorts(_fromPort, _toPort));
 
@@ -1651,17 +2445,51 @@ EOF
         })}\n`;
       }
 
-      // proxy.yaml — HTTPProxy for the instance host (mirrors instance-promote).
+      // proxy.yaml — this instance's OWN route only (its sub-path → its own
+      // service), so each variant's build dir carries a distinct, instance-scoped
+      // fragment rather than an identical copy of the whole host proxy. The
+      // complete host HTTPProxy — every variant's route aggregated onto the one
+      // fqdn, each pointing at its live colour — is assembled and applied by
+      // `instance-promote` at deploy time, and only once EVERY variant is ready.
       const proxyYaml =
         Underpost.deploy.baseProxyYamlFactory({ host: _host, env, options }) +
-        Underpost.deploy.deploymentYamlServiceFactory({
-          path: _path,
-          port: _fromPort,
-          deployId: _deployId,
+        instanceProxyRoutesFactory({
+          deployId,
+          instances: [instance],
           env,
-          deploymentVersions: [targetTraffic],
+          trafficById: { [instance.id]: targetTraffic },
         });
 
+      // A status route is only emitted for a page this project actually ships, so
+      // a rewrite never points at a document that cannot exist. The check is a
+      // read: placing the document into the gateway volume is `deploy
+      // --sync-static`'s job at apply time, and a build must not mutate the host.
+      // `projectPath` is passed through because this runner is given one
+      // explicitly; the sync derives the same root from the instance itself.
+      const statusPageEntries = instanceStatusPageEntriesFactory({
+        instances: [instance],
+        projectPath: rootPath,
+      }).filter((entry) => fs.existsSync(entry.sourcePath));
+
+      // httproute.yaml — this instance's own routes, including the status routes
+      // that reach the static utility instead of this workload. No Gateway is
+      // emitted beside it: the parent deploy owns the one Gateway that
+      // terminates every hostname it serves, and a second, hostname-scoped one
+      // would contend with it for the merged listener rather than add to it.
+      const httpRouteYaml = Underpost.deploy.httpRouteYamlFactory({
+        host: _host,
+        options,
+        parentName: Underpost.deploy.gatewayNameFactory({ deployId, env }),
+        rules: instanceHttpRouteRulesFactory({
+          deployId,
+          instances: [instance],
+          env,
+          trafficById: { [instance.id]: targetTraffic },
+          options,
+          servedStatuses: statusPageEntries.map((page) => `${page.status}`),
+        }),
+      });
+
       // grpc-service.yaml — the parent deploy's gRPC ClusterIP (shared; the
       // instance cmd resolves {{grpc-service-dns}} to it). Reuse the parent's
       // generated manifest when present rather than regenerating it here.
@@ -1677,31 +2505,108 @@ EOF
       fs.writeFileSync(`${instanceBuildDir}/deployment.yaml`, deploymentYaml, 'utf8');
       const siblingManifests = {
         'pv-pvc.yaml': pvPvcYaml,
+        'traffic-service.yaml': Underpost.deploy.trafficServiceYamlFactory({
+          deployId: _deployId,
+          env,
+          traffic: targetTraffic,
+          namespace: options.namespace,
+          fromPort: _fromPort,
+          toPort: _toPort,
+        }),
         'proxy.yaml': proxyYaml,
+        // No gateway.yaml: the parent deploy owns the Gateway. `writeManifest`
+        // removes the file a previous per-host build left behind.
+        'gateway.yaml': '',
+        'httproute.yaml': httpRouteYaml,
         'grpc-service.yaml': grpcServiceYaml,
       };
-      for (const [name, content] of Object.entries(siblingManifests)) {
-        if (!content) continue;
-        fs.writeFileSync(`${envManifestPath}/${name}`, content, 'utf8');
-        fs.writeFileSync(`${instanceBuildDir}/${name}`, content, 'utf8');
-      }
+      // Written only when they carry objects, and removed otherwise: an empty
+      // manifest makes `kubectl apply` fail with "no objects passed to apply",
+      // so a build that produces none must leave none behind either.
+      for (const [name, content] of Object.entries(siblingManifests))
+        for (const dir of [envManifestPath, instanceBuildDir])
+          Underpost.deploy.writeManifest({ filePath: `${dir}/${name}`, content });
       logger.info('[instance-build-manifest] Sibling manifests written', {
         project: envManifestPath,
         enginePrivate: instanceBuildDir,
         pvPvc: !!pvPvcYaml,
         proxy: !!proxyYaml,
+        httpRoute: !!httpRouteYaml,
+        statusPages: statusPageEntries.length,
         grpcService: !!grpcServiceYaml,
       });
+      const { gatewayClassName, http3, quicPort, altSvc } = Underpost.deploy.gatewayApiConfigFactory(options);
+      logger.info('[instance-build-manifest] Gateway API manifests written', {
+        host: _host,
+        gatewayClass: gatewayClassName,
+        http3,
+        quicPort,
+        altSvc: http3 ? altSvc : null,
+        statusPages: (instance.customStatusPages || []).map((page) => ({
+          status: page.status,
+          route: `${instance.path === '/' ? '' : instance.path}/${page.status}`,
+          hostPath: page.hostPath,
+        })),
+        statusPageResources: statusPageEntries,
+      });
 
-      if (env === 'production') {
+      // --- Per-instance env files -----------------------------------------
+      // Each env file starts from the template instance's canonical file for the
+      // same mode. Operator-owned keys remain private and are copied verbatim;
+      // deploy-specific builders may then derive application env from the
+      // normalized instance path/code.
+      //
+      // A derived instance's env dir is generated in full: both development.env
+      // and production.env are written on every build, so a deploy in either
+      // environment always finds the env file its `cmd` sources, no matter which
+      // mode this build ran. The default/template instance owns the committed
+      // source files, so only its current-mode file is idempotently refreshed.
+      if (instance.templateId) {
+        const instanceEnvDir = `./engine-private/conf/${deployId}/instances/${_id}/env`;
+        fs.mkdirpSync(instanceEnvDir);
+        const envsToWrite = isDefaultInstance ? [env] : ['development', 'production'];
+        for (const targetEnv of envsToWrite) {
+          const templateEnvPath = `./engine-private/conf/${deployId}/instances/${instance.templateId}/env/${targetEnv}.env`;
+          if (!fs.existsSync(templateEnvPath))
+            throw new Error(`[instance-build-manifest] Missing canonical env file: ${templateEnvPath}`);
+          const baseEnv = dotenv.parse(fs.readFileSync(templateEnvPath, 'utf8'));
+          const builtEnv = dispatchBuildInstanceEnv({
+            deployId,
+            instance,
+            environment: targetEnv,
+            baseEnv,
+            containerDeployId: `${_deployId}-${targetEnv}`,
+            builders: instanceEnvBuilder ? { [deployId]: instanceEnvBuilder } : {},
+          });
+          writeEnv(`${instanceEnvDir}/${targetEnv}.env`, builtEnv);
+        }
+        logger.info('[instance-build-manifest] Instance env written', {
+          dir: instanceEnvDir,
+          instanceCode: instance.instanceCode,
+          envs: envsToWrite,
+          builder: instanceEnvBuilder?.name || 'canonical-copy',
+        });
+      }
+
+      if (env === 'production' && isDefaultInstance) {
         if (fs.existsSync(dockerfileManifestPath)) {
           fs.copyFileSync(dockerfileManifestPath, `${rootPath}/Dockerfile`);
         }
         fs.copyFileSync(outputPath, `${rootPath}/deployment.yaml`);
         // Sibling manifests alongside deployment.yaml at the project root.
-        for (const name of ['pv-pvc.yaml', 'proxy.yaml', 'grpc-service.yaml']) {
+        for (const name of [
+          'pv-pvc.yaml',
+          'traffic-service.yaml',
+          'proxy.yaml',
+          'gateway.yaml',
+          'httproute.yaml',
+          'grpc-service.yaml',
+        ]) {
           const src = `${envManifestPath}/${name}`;
+          // Absence is mirrored too, so the repo never ships a manifest this
+          // build stopped producing.
           if (fs.existsSync(src)) fs.copyFileSync(src, `${rootPath}/${name}`);
+          else fs.removeSync(`${rootPath}/${name}`);
         }
         logger.info('[instance-build-manifest] Production artifacts copied to project root', {
           rootPath,
@@ -1908,9 +2813,7 @@ EOF`);
       shellExec(`kubectl apply -k ${underpostRoot}/manifests/deployment/adminer/. -n ${options.namespace}`);
       const successInstance = await Underpost.test.statusMonitor('adminer', 'Running', 'pods', 1000, 60 * 10);
 
-      if (successInstance) {
-        shellExec(`underpost deploy --expose adminer --namespace ${options.namespace}`);
-      }
+      if (successInstance) return UnderpostRun.RUNNERS.expose(path || 'adminer', options);
     },
 
     /**
@@ -1969,6 +2872,7 @@ EOF`);
      * @memberof UnderpostRun
      */
     promote: async (path, options = DEFAULT_OPTION) => {
+      options = { ...options, gatewayApi: gatewayApiEnabledFactory(options) };
       let [inputDeployId, inputEnv, inputReplicas] = path.split(',');
       if (!inputEnv) inputEnv = 'production';
       if (!inputReplicas) inputReplicas = 1;
@@ -1996,13 +2900,19 @@ EOF`);
 
       if (inputDeployId === 'dd') {
         for (const deployId of fs.readFileSync(`./engine-private/deploy/dd.router`, 'utf8').split(',')) {
-          const currentTraffic = Underpost.deploy.getCurrentTraffic(deployId, { namespace: options.namespace });
+          const currentTraffic = Underpost.deploy.getCurrentTraffic(deployId, {
+            namespace: options.namespace,
+            env: inputEnv,
+          });
           const targetTraffic = currentTraffic === 'blue' ? 'green' : 'blue';
           Underpost.deploy.switchTraffic(deployId, inputEnv, targetTraffic, inputReplicas, options.namespace, options);
           applyCerts(deployId, targetTraffic);
         }
       } else {
-        const currentTraffic = Underpost.deploy.getCurrentTraffic(inputDeployId, { namespace: options.namespace });
+        const currentTraffic = Underpost.deploy.getCurrentTraffic(inputDeployId, {
+          namespace: options.namespace,
+          env: inputEnv,
+        });
         const targetTraffic = currentTraffic === 'blue' ? 'green' : 'blue';
         Underpost.deploy.switchTraffic(
           inputDeployId,
@@ -2055,8 +2965,24 @@ EOF`);
     },
     /**
      * @method cluster
-     * @description Deploys a full production/development ready Kubernetes cluster environment including MongoDB, MariaDB, Valkey, Contour (Ingress), and Cert-Manager, and deploys all services.
-     * @param {string} path - The input value, identifier, or path for the operation.
+     * @description Deploys a full production/development ready Kubernetes cluster environment including MongoDB,
+     * MariaDB, Valkey, the Gateway API data plane (Envoy Gateway), Contour, and Cert-Manager, and deploys all services.
+     *
+     * Ingress is served by the Gateway API stack (Gateway + HTTPRoute) with QUIC/HTTP3 in **both** environments;
+     * `--disable-gateway-api` falls back to the Contour HTTPProxy stack. Because HTTP/3 has no cleartext transport,
+     * development terminates TLS too: a self-signed certificate per host (mkcert via `scripts/ssl.sh`, whose root CA
+     * the script installs into the system + NSS trust stores) is issued into the secret the Gateway listener
+     * references, and every host is written to `/etc/hosts` so the operator's browser reaches the PWA at
+     * `https://<host>` on the local machine.
+     *
+     * Custom instances are the optional third segment of `path`. They are resolved per deploy against that deploy's
+     * own `conf.instances.json`, so an id only runs where its deploy declares it, and each one is deployed after its
+     * deploy's default workload is serving — an instance reads the parent's world configuration over the parent's
+     * gRPC ClusterIP at boot. Instance hosts share the deploy's environment: the same self-signed certificates and
+     * `/etc/hosts` pass in development, the same cert-manager issuance in production.
+     * @param {string} path - `<runtime-image>,<deploy-list>[,<instance-list>]` — `+`-separated lists, e.g.
+     *   `express,dd-cyberia,mmo-server` or `express,dd-cyberia+dd-core,mmo-server+mmo-client`. An instance list entry
+     *   may be a template id (`mmo-server`), which selects its whole variant family.
      * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
      * @memberof UnderpostRun
      */
@@ -2065,30 +2991,39 @@ EOF`);
       const env = options.dev ? 'development' : 'production';
       const baseCommand = options.dev ? 'node bin' : 'underpost';
       const baseClusterCommand = options.dev ? ' --dev' : '';
-      const clusterType = options.k3s ? 'k3s' : 'kubeadm';
+      const clusterType = clusterTypeFactory(options, 'kubeadm');
       shellCd(`/home/dd/engine`);
       shellExec(`${baseCommand} cluster${baseClusterCommand} --reset --${clusterType}`);
       await timer(5000);
       shellExec(`${baseCommand} cluster${baseClusterCommand} --${clusterType}`);
       await timer(5000);
-      let [runtimeImage, deployList] =
+      let [runtimeImage, deployList, instanceListId] =
         path && path.trim() && path.split(',')
           ? path.split(',')
           : [
               'express',
               fs.readFileSync(`${underpostRoot}/engine-private/deploy/dd.router`, 'utf8').replaceAll(',', '+'),
+              '',
             ];
-      shellExec(
-        `${baseCommand} image${baseClusterCommand} --build ${
-          runtimeImage ? ` --pull-base --path ${underpostRoot}/src/runtime/${runtimeImage}` : ''
-        } --${clusterType}`,
-      );
+      // shellExec(
+      //   `${baseCommand} image${baseClusterCommand} --build ${
+      //     runtimeImage ? ` --pull-base --path ${underpostRoot}/src/runtime/${runtimeImage}` : ''
+      //   } --${clusterType}`,
+      // );
       if (!deployList) {
         deployList = [];
         logger.warn('No deploy list provided');
       } else deployList = deployList.split('+');
       await timer(5000);
-      shellExec(`${baseCommand} cluster${baseClusterCommand} --${clusterType} --pull-image --mongodb`);
+      // --reset-mongodb wipes the retained hostPath volumes before the rollout.
+      // This workflow already tore the node down and re-imports every database
+      // from its git backup a few lines below, so inheriting the previous
+      // cluster's replica set config is never wanted — that state leaves mongod
+      // parked outside its own config and the bootstrap fighting to recover it.
+      shellExec(`${baseCommand} cluster${baseClusterCommand} --${clusterType} --pull-image --mongodb --reset-mongodb`);
+      if (deployList.includes('dd-cyberia'))
+        shellExec(`${baseCommand} cluster${baseClusterCommand} --${clusterType} --pull-image --ipfs --replicas 1`);
+
       if (runtimeImage === 'lampp') {
         await timer(5000);
         shellExec(`${baseCommand} cluster${baseClusterCommand} --${clusterType} --pull-image --mariadb`);
@@ -2101,19 +3036,614 @@ EOF`);
       }
       await timer(5000);
       shellExec(`${baseCommand} cluster${baseClusterCommand} --${clusterType} --pull-image --valkey`);
+      // Exactly one ingress stack is installed, because the two cannot coexist
+      // on this node: Contour's Envoy DaemonSet declares hostPort 80/443, so the
+      // CNI hostport plugin DNATs everything arriving on those ports straight to
+      // it — before the Gateway API data plane's own listener can see them. With
+      // no HTTPProxy objects to program (this workflow applies HTTPRoutes),
+      // Contour's Envoy has no listeners and refuses the redirected connection,
+      // which looks exactly like a gateway that is not listening at all.
+      const gatewayApi = gatewayApiEnabledFactory(options);
+      const gatewayApiFlags = Underpost.deploy.gatewayApiFlagsFactory({ ...options, gatewayApi });
       await timer(5000);
-      shellExec(`${baseCommand} cluster${baseClusterCommand} --${clusterType} --contour`);
+      if (gatewayApi) {
+        shellExec(
+          `${baseCommand} cluster${baseClusterCommand} --${clusterType} --gateway-api${
+            options.gatewayClass ? ` --gateway-class ${options.gatewayClass}` : ''
+          }`,
+        );
+      } else shellExec(`${baseCommand} cluster${baseClusterCommand} --${clusterType} --contour`);
+      if (gatewayApi)
+        shellExec(
+          `kubectl rollout status deployment/${UNDERPOST_GATEWAY.name} -n ${options.namespace || 'default'} --timeout=5m`,
+        );
       if (env === 'production') {
         await timer(5000);
         shellExec(`${baseCommand} cluster${baseClusterCommand} --${clusterType} --cert-manager`);
       }
+
+      const { byDeployId: instancesByDeployId, unmatched: unmatchedInstanceIds } = clusterInstancesFactory(
+        deployList,
+        instanceListId,
+      );
+      if (unmatchedInstanceIds.length > 0)
+        logger.warn('[cluster] No deploy declares these instances; they will not be deployed', {
+          instances: unmatchedInstanceIds,
+          deployList,
+        });
+
+      // Development terminates TLS with a locally trusted certificate instead of
+      // cert-manager: QUIC/HTTP3 has no cleartext transport, so without it the
+      // dev gateway would fall back to an HTTP-only listener. The hosts are
+      // written to /etc/hosts in a single pass — etcHostFactory rewrites the
+      // file, so one call per deploy would drop the previous deploy's entries.
+      // Instance hosts come through the same resolver the Gateway's certificate
+      // list uses, so the two can never disagree about what the deploy serves.
+      const hosts = [...new Set(deployList.flatMap((deployId) => deployHostsFactory(deployId)))];
+      if (env === 'development') {
+        for (const host of hosts)
+          Underpost.deploy.selfSignedTlsSecretFactory({
+            host,
+            namespace: options.namespace || 'default',
+            underpostRoot,
+          });
+        const hostListenResult = etcHostFactory(hosts);
+        logger.info(hostListenResult.renderHosts);
+      }
+      const version = 'v3.2.90';
+      const instanceOptionsFactory = (deployId, instanceId) => ({
+        ...options,
+        ...clusterContextFactory(clusterType),
+        gatewayApi,
+        gatewayBootstrapComplete: true,
+        tls: true,
+        test: env === 'development',
+        etcHosts: false,
+        namespace: options.namespace || 'default',
+        imageName:
+          deployId === 'dd-cyberia' && env === 'development' && instanceId === 'mmo-server'
+            ? `underpost/cyberia-server-dev:${version}`
+            : deployId === 'dd-cyberia' && env === 'development' && instanceId === 'mmo-client'
+              ? `underpost/cyberia-client-dev:${version}`
+              : undefined,
+      });
+      const deployFlagsById = {};
+      const fallbackChecks = new Map();
+
+      // Regenerating the manifests is required, not incidental: the TLS listener
+      // — and with it the QUIC policy and the HTTPRoute set — is only emitted
+      // when the TLS and gateway flags are known at generation time. It takes two
+      // passes because `--build-manifest` returns after writing the manifests, so
+      // the same flags have to be repeated on the apply call.
       for (const deployId of deployList) {
-        shellExec(
-          `${baseCommand} deploy ${deployId} ${env} --${clusterType}${env === 'production' ? ' --cert' : ''}${
-            env === 'development' ? ' --etc-hosts' : ''
-          }${options.namespace ? ` --namespace ${options.namespace}` : ''}`,
+        const deployFlags =
+          `--${clusterType}${env === 'production' ? ' --cert' : ' --self-signed'}${gatewayApiFlags}` +
+          `${options.namespace ? ` --namespace ${options.namespace}` : ''}` +
+          (deployId === 'dd-cyberia'
+            ? ` --image 'underpost/engine-cyberia:${version}'  \
+                --versions blue \
+                --image-pull-policy Always \
+                --cmd 'cd /home/dd/engine, \
+                underpost clone underpostnet/engine-cyberia, \
+                mkdir -p /home/dd/engine/src/client/public/itemledger \
+                  /home/dd/engine/src/client/public/cryptokoyn \
+                  /home/dd/engine/src/client/components/cryptokoyn \
+                  /home/dd/engine/src/client/components/itemledger \
+                  /home/dd/engine/hardhat, \
+                cp -a ./engine-cyberia/src/client/public/itemledger/. /home/dd/engine/src/client/public/itemledger/, \
+                cp -a ./engine-cyberia/src/client/public/cryptokoyn/. /home/dd/engine/src/client/public/cryptokoyn/, \
+                cp -a ./engine-cyberia/src/client/components/cryptokoyn/. /home/dd/engine/src/client/components/cryptokoyn/, \
+                cp -a ./engine-cyberia/src/client/components/itemledger/. /home/dd/engine/src/client/components/itemledger/, \
+                cp -a ./engine-cyberia/src/client/Itemledger.index.js /home/dd/engine/src/client/Itemledger.index.js, \
+                cp -a ./engine-cyberia/src/client/Cryptokoyn.index.js /home/dd/engine/src/client/Cryptokoyn.index.js, \
+                rm -rf ./engine-cyberia, \
+                sudo rm -rf ./engine-private/, \
+                node bin clone underpostnet/engine-cyberia-private, \
+                sudo mv ./engine-cyberia-private ./engine-private, \
+                node bin env dd-cyberia ${env}, \
+                node ./engine-private/itc-scripts/dd-cyberia-0.js, \
+                sudo chown -R dd:dd /home/dd/engine/src/client/public/cyberia, \
+                node bin env dd-cyberia ${env}, \
+                node bin client dd-cyberia ${env}, \
+                node bin start dd-cyberia ${env} --run'`
+            : '');
+        deployFlagsById[deployId] = deployFlags;
+        // SSR status and context documents belong to the ingress bootstrap, so
+        // build them on the host before any workload Deployment is submitted.
+        shellExec(`${baseCommand} client ${deployId} ${env}`);
+        shellExec(`${baseCommand} deploy ${deployId} ${env} --build-manifest ${deployFlags}`);
+        // Seed the static tree before the routes exist, so every status page and
+        // intercepted context the manifests just pointed at resolves from the
+        // first request. This pass places what this checkout built; the pass
+        // after the rollout replaces each document with the container's own,
+        // which is the only place clients built from private sources exist.
+        if (gatewayApi) {
+          const staticAssets = Underpost.deploy.syncStaticAssets(deployId, env, {
+            ...options,
+            ...clusterContextFactory(clusterType),
+            gatewayApi,
+            namespace: options.namespace || 'default',
+            versions: /--versions\s+([^\s]+)/.exec(deployFlags)?.[1] || options.versions || 'blue',
+          });
+          const missingAssets = staticAssets.filter((entry) => !entry.source);
+          if (missingAssets.length > 0)
+            throw new Error(
+              `[cluster] Static gateway bootstrap is missing configured assets for ${deployId}: ` +
+                missingAssets.map((entry) => entry.assetPath).join(', '),
+            );
+
+          // Record the exact documents the no-backend checkpoint must return.
+          // PWA paths use the SSR maintenance view; custom instances have no
+          // maintenance view and reuse their first declared status document.
+          const confServer = loadConfServerJson(`./engine-private/conf/${deployId}/conf.server.json`);
+          const confSSRPath = `./engine-private/conf/${deployId}/conf.ssr.json`;
+          const confSSR = fs.existsSync(confSSRPath) ? JSON.parse(fs.readFileSync(confSSRPath, 'utf8')) : {};
+          for (const host of Object.keys(confServer))
+            for (const path of Object.keys(confServer[host])) {
+              const maintenance = Underpost.deploy
+                .edgeRouteEntriesFactory({ confServer, confSSR, host, path })
+                .find((entry) => entry.context === 'maintenance');
+              if (maintenance)
+                fallbackChecks.set(`${host}${path}`, {
+                  host,
+                  path,
+                  assetPath: maintenance.assetPath,
+                  kind: maintenance.kind,
+                });
+            }
+          const selectedInstances = instancesByDeployId[deployId].ids.flatMap((instanceId) =>
+            selectConfInstances(loadConfInstances(deployId), instanceId),
+          );
+          for (const entry of instanceStatusPageEntriesFactory({ instances: selectedInstances }))
+            if (!fallbackChecks.has(`${entry.host}${entry.path}`))
+              fallbackChecks.set(`${entry.host}${entry.path}`, {
+                host: entry.host,
+                path: entry.path,
+                assetPath: entry.assetPath,
+                kind: `status:${entry.status}`,
+              });
+        }
+        // Apply only the gateway tier. Application Services and Deployments are
+        // deliberately absent so the status fallback can be observed first.
+        shellExec(`${baseCommand} deploy ${deployId} ${env} --disable-update-deployment ${deployFlags}`);
+        // Instance host routes and their custom status pages are part of
+        // the same ingress bootstrap. `instance-promote` is safe here: it only
+        // writes the Nginx host block and routing objects; no instance Deployment
+        // is created until the second phase below.
+        for (const instanceId of instancesByDeployId[deployId].ids) {
+          logger.info('[cluster] Bootstrapping custom instance gateway', { deployId, instanceId, env });
+          await UnderpostRun.RUNNERS['instance-promote'](`${deployId},${instanceId}`, {
+            ...instanceOptionsFactory(deployId, instanceId),
+            noBackendCheckpoint: true,
+          });
+        }
+      }
+
+      // This is the deliberate no-backend checkpoint. The static Nginx pod, all
+      // Gateway listeners, parent HTTPRoutes and selected instance HTTPRoutes
+      // must be live before the first application Deployment YAML is submitted.
+      if (gatewayApi && fallbackChecks.size > 0) {
+        const fallbackResults = await gatewayFallbackProbeRunner({
+          gatewayStatusRunner: UnderpostRun.RUNNERS['gateway-status'],
+          checks: [...fallbackChecks.values()],
+          options: { ...options, gatewayApi, namespace: options.namespace || 'default' },
+          label: 'cluster',
+        });
+        logger.info('[cluster] Gateway fallback checkpoint passed; starting application deployments', {
+          hosts,
+          fallbacks: fallbackResults,
+        });
+      }
+
+      for (const deployId of deployList) {
+        const deployFlags = deployFlagsById[deployId];
+        // Preserve the already-operational ingress objects and apply only the
+        // workload manifests. EndpointSlices will update as pods become Ready;
+        // the site route continues to reach underpost-gateway throughout.
+        shellExec(`${baseCommand} deploy ${deployId} ${env} --disable-update-proxy ${deployFlags}`);
+        if (gatewayApi) {
+          const namespace = options.namespace || 'default';
+          const version = /--versions\s+([^\s,]+)/.exec(deployFlags)?.[1] || 'blue';
+          shellExec(`kubectl rollout status deployment/${deployId}-${env}-${version} -n ${namespace} --timeout=15m`);
+          shellExec(`${baseCommand} deploy ${deployId} ${env} --sync-static ${deployFlags}`);
+        }
+
+        // Custom instance pods depend on the parent's gRPC service, so they are
+        // still started after the parent is Ready. Their routes already exist and
+        // keep serving the custom fallback until the atomic promotion completes.
+        for (const instanceId of instancesByDeployId[deployId].ids) {
+          logger.info('[cluster] Deploying custom instance', { deployId, instanceId, env, clusterType });
+          await UnderpostRun.RUNNERS.instance(
+            `${deployId},${instanceId},${options.replicas || 1}`,
+            instanceOptionsFactory(deployId, instanceId),
+          );
+        }
+      }
+      logger.info('[cluster] Ingress stack deployed', {
+        env,
+        stack: gatewayApi ? 'gateway-api' : 'httpproxy',
+        gatewayClass: gatewayApi ? Underpost.deploy.gatewayApiConfigFactory(options).gatewayClassName : null,
+        http3: gatewayApi && options.disableHttp3 !== true,
+        tls: env === 'production' ? 'cert-manager' : 'self-signed',
+        hosts,
+        instances: Object.fromEntries(
+          deployList
+            .filter((deployId) => instancesByDeployId[deployId].ids.length > 0)
+            .map((deployId) => [deployId, instancesByDeployId[deployId].ids]),
+        ),
+      });
+      if (gatewayApi) await UnderpostRun.RUNNERS['gateway-status']('', options);
+    },
+
+    /**
+     * @method gateway-status
+     * @description Reports whether the Gateway API data plane is actually
+     * serving. Applying a Gateway only records intent: the controller
+     * provisions Envoy asynchronously, so a deploy can finish cleanly while
+     * nothing listens on the node — the failure then surfaces much later as a
+     * bare "connection refused" from the browser. This waits for the Gateways to
+     * be Programmed and prints the data plane's pods and services.
+     * @param {string} path - Unused.
+     * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
+    'gateway-status': async (path = '', options = DEFAULT_OPTION) => {
+      const namespace = options.namespace || 'default';
+      const dataPlaneNamespace = 'envoy-gateway-system';
+      const capture = (cmd) => shellExec(cmd, { stdout: true, silent: true, silentOnError: true })?.trim?.() || '';
+
+      const programmed = shellExec(
+        `kubectl wait --for=condition=Programmed --timeout=180s gateway --all -n ${namespace}`,
+        { silentOnError: true },
+      );
+      if (programmed?.code !== 0)
+        logger.warn(
+          '[gateway-status] Gateways are not Programmed. The listeners are not being served; ' +
+            `check 'kubectl describe gateway -n ${namespace}' and the controller logs in ${dataPlaneNamespace}.`,
+        );
+      shellExec(`kubectl get gateway -n ${namespace} -o wide`, { silentOnError: true });
+
+      // Per-listener truth. A Gateway reports Programmed while individual
+      // listeners are rejected, so the aggregate condition hides exactly the
+      // case where some hostnames serve and others do not. Prints each
+      // listener's attached route count and any failing condition with its
+      // reason — an unresolved TLS secret or a rejected listener names itself.
+      const listenerStatus = capture(
+        `kubectl get gateway -n ${namespace} -o jsonpath=` +
+          `'{range .items[*]}{.metadata.name}{"  "}` +
+          `{range .status.listeners[*]}{.name}=routes:{.attachedRoutes}` +
+          `{range .conditions[?(@.status=="False")]}{" "}{.type}/{.reason}{end}{"  "}{end}{"\\n"}{end}'`,
+      );
+      logger.info('[gateway-status] Listeners (name=routes + failing conditions)\n' + (listenerStatus || '(none)'));
+
+      // Envoy Gateway policies attach to a Gateway but configure the merged
+      // listener, so two of them competing for the same listener is resolved by
+      // rejecting one — and the rejection is recorded here, not on the Gateway.
+      const policyStatus = capture(
+        `kubectl get clienttrafficpolicy -n ${namespace} -o jsonpath=` +
+          `'{range .items[*]}{.metadata.name}{range .status.ancestors[*]}` +
+          `{range .conditions[?(@.status=="False")]}{"  "}{.type}/{.reason}: {.message}{end}{end}{"\\n"}{end}'`,
+      );
+      logger.info(
+        '[gateway-status] ClientTrafficPolicies (failing conditions)\n' +
+          (policyStatus
+            .split('\n')
+            .filter((line) => line.includes('  '))
+            .join('\n') || '(none — all policies accepted)'),
+      );
+
+      // Envoy Gateway policies that fail to translate are not visible on the
+      // Gateway or the route: the resource is admitted, its status carries the
+      // rejection, and the xDS snapshot it belonged to can go with it — which
+      // reads downstream as every hostname answering route_not_found.
+      const backendPolicyStatus = capture(
+        `kubectl get backendtrafficpolicy -n ${namespace} -o jsonpath=` +
+          `'{range .items[*]}{.metadata.name}{range .status.ancestors[*]}` +
+          `{range .conditions[?(@.status=="False")]}{"  "}{.type}/{.reason}: {.message}{end}{end}{"\n"}{end}' ` +
+          `2>/dev/null`,
+      );
+      logger.info(
+        '[gateway-status] BackendTrafficPolicies (failing conditions)\n' +
+          (backendPolicyStatus
+            .split('\n')
+            .filter((line) => line.includes('  '))
+            .join('\n') || '(none — all policies accepted)'),
+      );
+
+      // Route-level conditions. A rule that references something unresolvable
+      // can cost the whole route, and then every path on that hostname answers
+      // with a bare gateway 404 while the Gateway and its listeners stay green.
+      const routeStatus = capture(
+        `kubectl get httproute -n ${namespace} -o jsonpath=` +
+          `'{range .items[*]}{.metadata.name}{range .status.parents[*]}` +
+          `{range .conditions[?(@.status=="False")]}{"  "}{.type}/{.reason}: {.message}{end}{end}{"\\n"}{end}'`,
+      )
+        .split('\n')
+        .filter((line) => line.includes('  '));
+      logger.info(
+        '[gateway-status] HTTPRoutes (failing conditions)\n' +
+          (routeStatus.join('\n') || '(none — all routes accepted)'),
+      );
+
+      // The workloads the routes point at. A status code that moves between runs
+      // (500 here, 404 there) is the application's, not the gateway's, and the
+      // gateway config cannot explain it — restarts and unready containers can.
+      const backends = capture(
+        `kubectl get pods -n ${namespace} -o custom-columns=` +
+          `'NAME:.metadata.name,READY:.status.containerStatuses[*].ready,RESTARTS:.status.containerStatuses[*].restartCount,STATUS:.status.phase'`,
+      );
+      logger.info('[gateway-status] Workloads behind the routes\n' + (backends || '(none)'));
+
+      // A Programmed Gateway only means Envoy was provisioned — not that it is
+      // reachable from this machine. Which of the two is false decides the fix,
+      // so report the pod's network mode and container ports, the service type
+      // and node ports, and what the host is actually listening on.
+      const dataPlane = capture(
+        `kubectl get pods -n ${dataPlaneNamespace} -o custom-columns=` +
+          `'NAME:.metadata.name,HOST_NETWORK:.spec.hostNetwork,PORTS:.spec.containers[*].ports[*].containerPort'`,
+      );
+      const services = capture(
+        `kubectl get svc -n ${dataPlaneNamespace} -o custom-columns=` +
+          `'NAME:.metadata.name,TYPE:.spec.type,PORTS:.spec.ports[*].port,NODEPORTS:.spec.ports[*].nodePort,TARGETS:.spec.ports[*].targetPort'`,
+      );
+      logger.info('[gateway-status] Data plane\n' + dataPlane + '\n\n' + services);
+
+      // Envoy creates its listener sockets only once the control plane has
+      // pushed a config with routes attached, which lands a little after the
+      // pod reports Ready. Polling that window is the difference between
+      // "connection refused" and a working gateway, so wait for the socket
+      // rather than sampling it once.
+      const listenerFilter = `grep -E ':(80|443|10080|10443) '`;
+      let hostListeners = '';
+      for (let attempt = 0; attempt < 30; attempt++) {
+        hostListeners = capture(`sudo ss -lntupH 2>/dev/null | ${listenerFilter}`);
+        if (/:443\s/.test(hostListeners)) break;
+        await timer(2000);
+      }
+      const servesHttps = /:443\s/.test(hostListeners);
+      logger.info('[gateway-status] Host listeners on 80/443/10080/10443\n' + (hostListeners || '(none)'));
+
+      if (!servesHttps) {
+        logger.warn(
+          '[gateway-status] Nothing is listening on this host port 443, so a browser reaching the ' +
+            'hostnames through /etc/hosts gets "connection refused". Compare the two tables above: ' +
+            'HOST_NETWORK=false means the pod is on the pod network (only the ClusterIP/NodePort is ' +
+            'reachable); HOST_NETWORK=true with PORTS 10080/10443 means the privileged-port remap is ' +
+            'still active. Until it is resolved, forward the merged service to expose it locally:\n' +
+            `  kubectl port-forward -n ${dataPlaneNamespace} svc/<envoy-service> 443:443 80:80 --address 127.0.0.1`,
+        );
+        return { programmed: programmed?.code === 0, servesHttps, dataPlane, services, hostListeners, probes: [] };
+      }
+
+      // An open socket still is not proof the hostname routes anywhere. Probe
+      // each Gateway hostname exactly as the browser would — through /etc/hosts,
+      // validating the certificate against the trust store `scripts/ssl.sh`
+      // populated — so the workflow ends on an observed response, not an
+      // inference. Each host is probed twice: over loopback, and pinned to the
+      // node IP. The two answers separate a loopback-specific block from a data
+      // plane that is not reachable at all.
+      const nodeIp = capture(
+        `kubectl get node -o jsonpath='{.items[0].status.addresses[?(@.type=="InternalIP")].address}'`,
+      );
+      // The `server` header is reported alongside the status because the code
+      // alone cannot say who produced it: `500 (envoy)` is a gateway or upstream
+      // failure, while `500` from the workload's own server is an application
+      // error, and the two lead to completely different fixes.
+      const probeUrl = (url, resolveArgs = '') => {
+        const raw = capture(
+          `curl -sS -o /dev/null -D - -w 'HTTP_CODE=%{http_code}' --max-time 10 ${resolveArgs}${url} 2>&1 | tr -d '\\r'`,
+        );
+        const status = /HTTP_CODE=([0-9]{3})/.exec(raw)?.[1];
+        if (!status) return raw.split('\n').find((line) => line.startsWith('curl:')) || 'no-response';
+        const server = /^server:\s*(.+)$/im.exec(raw)?.[1]?.trim();
+        return server ? `${status} (${server})` : status;
+      };
+      const probe = (host, resolveTo) =>
+        probeUrl(`https://${host}`, resolveTo ? `--resolve ${host}:443:${resolveTo} ` : '');
+      // Port 80 is the same Envoy process, same host, same listener set — only
+      // the port differs. It separates "this gateway is unreachable" from
+      // "something specifically rejects 443".
+      const probeHttp = (host) => probeUrl(`http://${host}`);
+      // curl writes `000` when it never got a response, so a bare three-digit
+      // match would read a failed connection as success.
+      const answered = (status) => /^[1-5][0-9]{2}\b/.test(status);
+      // The routes, not the listeners, are where the hostnames live: a
+      // consolidated Gateway serves every hostname from one hostname-less
+      // listener and picks the certificate by SNI, so reading the listeners
+      // would leave nothing to probe.
+      const hosts = [
+        ...new Set(
+          (path
+            ? path.split(',')
+            : capture(`kubectl get httproute -n ${namespace} -o jsonpath='{.items[*].spec.hostnames[*]}'`).split(/\s+/)
+          )
+            .map((host) => host.trim())
+            .filter(Boolean),
+        ),
+      ];
+      const probes = hosts.map((host) => ({
+        host,
+        http: probeHttp(host),
+        loopback: probe(host),
+        ...(nodeIp ? { nodeIp: probe(host, nodeIp) } : {}),
+      }));
+      logger.info('[gateway-status] HTTPS probe', { nodeIp: nodeIp || '(unknown)', probes });
+
+      // A gateway answer alone cannot say whether the gateway or the workload
+      // produced the code: Envoy relays an upstream response unchanged. So when
+      // a hostname fails, ask its backend the *same* question from inside the
+      // cluster, bypassing Envoy.
+      //
+      // Same question is the whole point: these workloads route by virtual host,
+      // so a probe carrying `Host: <service-name>` exercises a different branch
+      // than the browser did and its answer means nothing. Each probe therefore
+      // replays the route it came from — the Gateway hostname, the rule path,
+      // and the rewrite the rule would have applied — against the rule's own
+      // backend. Only then do the two columns compare.
+      const failing = probes.filter((entry) => /^[45]/.test(entry.loopback) || /^[45]/.test(entry.http));
+      if (failing.length > 0) {
+        const routes = JSON.parse(
+          capture(`kubectl get httproute -n ${namespace} -o json`) || '{"items":[]}',
+        ).items.filter((route) => failing.some((entry) => route.spec?.hostnames?.includes(entry.host)));
+        // Exec into the static utility rather than spawning a probe pod: it is
+        // installed with the gateway stack, sits in this namespace, and its
+        // BusyBox shell already carries wget — no image pull, no pod churn.
+        const probePod = capture(
+          `kubectl get pods -n ${namespace} -l app=${UNDERPOST_GATEWAY.name} -o jsonpath='{.items[0].metadata.name}'`,
+        );
+        if (!probePod || routes.length === 0) {
+          logger.warn(
+            '[gateway-status] Cannot probe backends directly: ' +
+              (probePod
+                ? 'no HTTPRoute matched a failing hostname'
+                : `no ${UNDERPOST_GATEWAY.name} pod in ${namespace}`),
+          );
+        } else {
+          const backendProbes = [];
+          for (const route of routes) {
+            const host = route.spec.hostnames[0];
+            for (const rule of route.spec.rules || []) {
+              const backend = (rule.backendRefs || [])[0];
+              if (!backend) continue;
+              const match = rule.matches?.[0]?.path?.value || '/';
+              const rewrite = (rule.filters || []).find((filter) => filter.type === 'URLRewrite')?.urlRewrite?.path;
+              const target =
+                rewrite?.type === 'ReplaceFullPath'
+                  ? rewrite.replaceFullPath
+                  : rewrite?.type === 'ReplacePrefixMatch'
+                    ? rewrite.replacePrefixMatch
+                    : match;
+              const raw = capture(
+                `kubectl exec -n ${namespace} ${probePod} -- wget -S -O /dev/null -T 5 ` +
+                  `--header 'Host: ${host}' http://${backend.name}:${backend.port}${target} 2>&1 || true`,
+              );
+              const code = /HTTP\/[0-9.]+\s+([0-9]{3})/.exec(raw)?.[1];
+              const failure = raw.split('\n').find((line) => line.includes('wget:'));
+              backendProbes.push({
+                request: `${host}${match}`,
+                backend: `${backend.name}:${backend.port}${target}`,
+                direct: code || failure?.trim() || 'no-response',
+                gateway: failing.find((entry) => entry.host === host)?.http,
+              });
+            }
+          }
+          logger.info('[gateway-status] Backend probe (same Host and path, bypassing Envoy)', { backendProbes });
+          // Only the rule the browser actually hit is comparable, so judge on
+          // the root rule rather than on every rule of the route.
+          const rootProbes = backendProbes.filter((entry) => entry.request.endsWith('/'));
+          const appFault = rootProbes.filter((entry) => `${entry.direct}` === `${entry.gateway}`);
+          const gatewayFault = rootProbes.filter(
+            (entry) => /^[0-9]{3}$/.test(entry.direct) && `${entry.direct}` !== `${entry.gateway}`,
+          );
+          if (gatewayFault.length > 0) {
+            logger.warn(
+              '[gateway-status] These backends answer differently without Envoy in the path, so the gateway is ' +
+                'not relaying the workload response — the routing layer is the fault:\n  ' +
+                gatewayFault
+                  .map((entry) => `${entry.request} -> backend ${entry.direct}, gateway ${entry.gateway}`)
+                  .join('\n  '),
+            );
+            // The access log is the only artifact that says *why*. Its
+            // response_flags column separates an Envoy local reply (NR no route,
+            // UF upstream connect failure, UH no healthy upstream, DPE protocol
+            // error) from a relayed upstream status, which no amount of probing
+            // from outside can distinguish.
+            // Selector, not owning-gateway labels: under `mergeGateways` the data
+            // plane belongs to the GatewayClass, so per-Gateway labels are absent
+            // and a selector built from them silently matches nothing.
+            const dataPlaneLog = capture(
+              `kubectl logs -n ${dataPlaneNamespace} ` +
+                `-l app.kubernetes.io/name=envoy,app.kubernetes.io/component=proxy ` +
+                `-c envoy --tail=60 --prefix 2>/dev/null | tail -60`,
+            );
+            logger.info(
+              '[gateway-status] Data plane access log (response_flags names the reason)\n' +
+                (dataPlaneLog || `(none — check: kubectl get pods -n ${dataPlaneNamespace} --show-labels)`),
+            );
+            // A translation the control plane rejected after admitting the
+            // resource surfaces only here, never on the object's own status.
+            const controlPlaneLog = capture(
+              `kubectl logs -n ${dataPlaneNamespace} deployment/envoy-gateway --tail=40 2>/dev/null ` +
+                `| grep -Ei 'error|warn|reject|invalid' | tail -20`,
+            );
+            logger.info('[gateway-status] Control plane errors\n' + (controlPlaneLog || '(none in the last 40 lines)'));
+          }
+          if (appFault.length > 0)
+            logger.warn(
+              '[gateway-status] These backends return the same code without Envoy in the path, so the gateway is ' +
+                'relaying an application response — the routing layer is not the fault:\n  ' +
+                appFault.map((entry) => `${entry.request} -> ${entry.direct}`).join('\n  ') +
+                `\n  Read the workload log: kubectl logs -n ${namespace} <pod>`,
+            );
+        }
+      }
+
+      const unreachable = probes.filter((entry) => !answered(entry.loopback));
+      if (unreachable.length > 0) {
+        // Narrow it here rather than leaving the operator with a bare refusal.
+        // A socket bound on 0.0.0.0 that resets a loopback connection is either
+        // not in this network namespace, or something is rejecting the packet.
+        const listenerPid = /pid=(\d+)/.exec(hostListeners)?.[1];
+        const hostNetns = capture(`sudo readlink /proc/1/ns/net`);
+        const listenerNetns = listenerPid ? capture(`sudo readlink /proc/${listenerPid}/ns/net`) : '';
+        // Anything that can answer a SYN with ICMP port-unreachable, from either
+        // rule engine. firewalld on RHEL 9 keeps its rules in its own `inet
+        // firewalld` nftables table, which `iptables-save` cannot see at all —
+        // grepping only iptables hides half the packet path.
+        const rejectRules = capture(
+          `sudo iptables-save 2>/dev/null | grep -E '(REJECT|DROP)' | grep -E '(dport|dpt:) ?(443|https)\\b' | head -20`,
+        );
+        const nftRules = capture(
+          `sudo nft list ruleset 2>/dev/null | grep -nE '(dport|ports) .*(443|https)|reject' | head -20`,
+        );
+        // A hostPort claim outranks any process listening on the node: the CNI
+        // plugin DNATs the port to the claiming pod first, so the packet never
+        // reaches the gateway. This is the one failure that leaves every other
+        // signal green.
+        const hostPortHijack = capture(
+          `sudo nft list ruleset 2>/dev/null | grep -E 'dport (80|443)\\b.*dnat to' | head -5`,
+        );
+        const hostPortClaims = capture(
+          `kubectl get daemonset,deployment -A ` +
+            `-o jsonpath='{range .items[*]}{.metadata.namespace}/{.metadata.name}={.spec.template.spec.containers[*].ports[*].hostPort}{"\\n"}{end}'`,
+        )
+          .split('\n')
+          .filter((line) => /=.*\b(80|443)\b/.test(line));
+        logger.warn(`[gateway-status] ${unreachable.length}/${probes.length} hostnames did not answer over HTTPS`, {
+          listenerPid: listenerPid || '(unknown)',
+          hostNetns: hostNetns || '(unknown)',
+          listenerNetns: listenerNetns || '(unknown)',
+          sameNetworkNamespace: !!hostNetns && hostNetns === listenerNetns,
+          nodeIpReachable: probes.some((entry) => answered(entry.nodeIp)),
+          endpointlessServices: capture(
+            `kubectl get svc -A -o jsonpath=` + `'{range .items[*]}{.metadata.namespace}/{.metadata.name} {end}'`,
+          )
+            .split(/\s+/)
+            .filter(Boolean)
+            .filter((ref) => {
+              const [ns, name] = ref.split('/');
+              return !capture(
+                `kubectl get endpointslice -n ${ns} -l kubernetes.io/service-name=${name} ` +
+                  `-o jsonpath='{.items[*].endpoints[*].addresses[*]}'`,
+              ).trim();
+            }),
+          httpReachable: probes.some((entry) => answered(entry.http)),
+          hostPortHijack: hostPortHijack || '(none)',
+          hostPortClaims: hostPortClaims.length > 0 ? hostPortClaims : '(none)',
+          rejectRules: rejectRules || '(none matching 443 in iptables)',
+          nftRules: nftRules || '(none matching 443 in nftables)',
+        });
+        logger.warn(
+          '[gateway-status] Read it as: hostPortHijack non-empty → another workload reserved host port ' +
+            '80/443 and the CNI DNATs those ports to it before the gateway can see them; hostPortClaims ' +
+            'names the owner, and only one ingress stack can hold them. httpReachable=true → the same Envoy ' +
+            'answers on 80, so only 443 is rejected. sameNetworkNamespace=false → the listener is not on ' +
+            'this host despite hostNetwork. endpointlessServices naming a Service that publishes 80/443 → ' +
+            'kube-proxy REJECTs those ports on its behalf; delete it.',
         );
       }
+
+      return { programmed: programmed?.code === 0, servesHttps, dataPlane, services, hostListeners, probes };
     },
     /**
      * @method deploy
@@ -2124,11 +3654,11 @@ EOF`);
      */
     deploy: async (path, options = DEFAULT_OPTION) => {
       const deployId = path;
+      const env = options.dev ? 'development' : 'production';
       const { validVersion } = Underpost.repo.privateConfUpdate(deployId);
       if (!validVersion) throw new Error('Version mismatch');
-      const currentTraffic = Underpost.deploy.getCurrentTraffic(deployId, { namespace: options.namespace });
+      const currentTraffic = Underpost.deploy.getCurrentTraffic(deployId, { namespace: options.namespace, env });
       const targetTraffic = currentTraffic === 'blue' ? 'green' : 'blue';
-      const env = options.dev ? 'development' : 'production';
       const ignorePods = Underpost.kubectl
         .get(`${deployId}-${env}-${targetTraffic}`, 'pods', options.namespace)
         .map((p) => p.NAME);
@@ -2315,7 +3845,11 @@ EOF`);
       }
       const success = await Underpost.test.statusMonitor(podToMonitor);
       if (success) {
-        const versions = Underpost.deploy.getCurrentTraffic(deployId, { namespace: options.namespace }) || 'blue';
+        const versions =
+          Underpost.deploy.getCurrentTraffic(deployId, {
+            namespace: options.namespace,
+            env: options.dev ? 'development' : 'production',
+          }) || 'blue';
         if (!node) node = os.hostname();
         const timeoutFlags = Underpost.deploy.timeoutFlagsFactory(options);
         shellExec(
@@ -2346,10 +3880,7 @@ EOF`);
      */
     'etc-hosts': async (path = '', options = DEFAULT_OPTION) => {
       const hosts = path ? path.split(',') : [];
-      if (options.deployId) {
-        const confServer = loadConfServerJson(`./engine-private/conf/${options.deployId}/conf.server.json`);
-        hosts.push(...Object.keys(confServer));
-      }
+      if (options.deployId) hosts.push(...deployHostsFactory(options.deployId));
       const hostListenResult = etcHostFactory(hosts);
       logger.info(hostListenResult.renderHosts);
     },
@@ -2702,31 +4233,314 @@ EOF`);
      * @memberof UnderpostRun
      */
     'generate-pass': (path, options = DEFAULT_OPTION) => {
-      const length = path && parseInt(path) > 0 ? parseInt(path) : 16;
-      const lower = 'abcdefghijklmnopqrstuvwxyz';
-      const upper = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';
-      const digits = '0123456789';
-      const special = '@#$%^&*()_+';
-      const all = lower + upper + digits + special;
-      const buf = crypto.randomBytes(length + 4);
-      // Guarantee at least one character from each required class
-      const chars = [
-        lower[buf[0] % lower.length],
-        upper[buf[1] % upper.length],
-        digits[buf[2] % digits.length],
-        special[buf[3] % special.length],
-      ];
-      for (let i = 4; i < length; i++) chars.push(all[buf[i] % all.length]);
-      // Fisher-Yates shuffle using an independent random buffer
-      const shuf = crypto.randomBytes(length);
-      for (let i = chars.length - 1; i > 0; i--) {
-        const j = shuf[i % shuf.length] % (i + 1);
-        [chars[i], chars[j]] = [chars[j], chars[i]];
-      }
-      const password = chars.join('');
+      const password = generateSecurePassword(path && parseInt(path) > 0 ? parseInt(path) : 16);
       if (options.copy) pbcopy(password);
       else console.log(password);
     },
+    /**
+     * @method sops-setup
+     * @description End-to-end SOPS/Age onboarding for a host: installs tooling, generates the Age
+     * keypair and creation rules, pins the key path for non-interactive runs, encrypts the
+     * requested Secrets into the Git-tracked store, then validates and applies them.
+     *
+     * Every step is idempotent and re-runnable. Notably it delegates key generation to
+     * `secret sops --init` rather than calling `age-keygen` directly: a bare `age-keygen -o`
+     * overwrites an existing key, which would orphan every manifest already encrypted to the
+     * previous recipient with no way to recover them.
+     *
+     * On a host that pulled a store created elsewhere, the freshly generated key is not a recipient
+     * of the inherited manifests. `init()` registers this host in the creation rules so what it
+     * encrypts from here on stays readable, but existing manifests can only be re-keyed from a host
+     * that still holds a decrypting key. That case is reported per secret and then raised by the
+     * apply pre-flight with the available remedies, rather than surfacing as a sops decrypt error.
+     *
+     * Onboards the whole self-hosted data tier by default — PostgreSQL, MariaDB, and MongoDB
+     * (`postgres-secret`, `mariadb-secret`, `mongodb-secret`, `mongodb-keyfile`). The MongoDB
+     * keyfile is included because the StatefulSet mounts it for intra-replica-set auth and will
+     * not start without it. Pass an explicit comma-separated list to narrow the set.
+     *
+     * Secret values are resolved per data key, in order:
+     *   1. the origin seed file, when one exists (`engine-private/postgresql-password`) — this is
+     *      the real onboarding path, carrying the credential the cluster already runs on;
+     *   2. `--args` as `key=value` pairs, for a value supplied by the operator;
+     *   3. a freshly generated value: a base64 keyfile for `mongodb-keyfile`, `admin` for a
+     *      `username`, otherwise a 24-character secure password.
+     *
+     * Plaintext manifests are written by Node under `/dev/shm` at mode 600 and shredded by
+     * `encrypt()`. They are never emitted through a shell heredoc, which would place the
+     * credential in the command string and therefore in the process table and the command log.
+     *
+     * Usage:
+     *   underpost run sops-setup                                   # postgres + mariadb + mongo
+     *   underpost run sops-setup mongodb-secret,mongodb-keyfile --namespace prod
+     *   underpost run sops-setup postgres-secret --args "password=s3cr3t"
+     *   underpost run sops-setup --dry-run                         # stop before mutating cluster
+     *   underpost run sops-setup --force                           # replace stored manifests
+     * @param {string} path - Comma-separated Secret names to onboard. Defaults to the full data
+     *   tier: postgres-secret, mariadb-secret, mongodb-secret, mongodb-keyfile.
+     * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
+     * @param {string} options.namespace - Target namespace for the store and the apply (default: 'default').
+     * @param {string} options.args - Comma-separated `key=value` overrides for Secret data keys.
+     * @param {boolean} options.dryRun - Validate and server-dry-run only; never apply.
+     * @param {boolean} options.force - Replace encrypted manifests that already exist.
+     * @memberof UnderpostRun
+     */
+    'sops-setup': (path = '', options = DEFAULT_OPTION) => {
+      const namespace = options.namespace || 'default';
+      const secretNames = (path || SOPS_SETUP_DEFAULT_SECRETS.join(','))
+        .split(',')
+        .map((name) => name.trim())
+        .filter(Boolean);
+
+      // `--args key=value,key2=value2` overrides, applied to any secret that declares that key.
+      const overrides = `${options.args || ''}`.split(',').reduce((acc, pair) => {
+        const separator = pair.indexOf('=');
+        if (separator > 0) acc[pair.slice(0, separator).trim()] = pair.slice(separator + 1).trim();
+        return acc;
+      }, {});
+
+      logger.info('sops-setup', { secretNames, namespace, dryRun: !!options.dryRun, force: !!options.force });
+
+      // 1. Host tooling, then keypair + creation rules. Both no-op when already present.
+      Underpost.secret.sops.installTooling();
+      Underpost.secret.sops.init();
+
+      // 2. Pin the resolved key path for non-interactive runs (systemd units, CronJobs, sudo).
+      //    Written with the concrete path rather than a guessed default, because `sudo` resets
+      //    HOME and a wrong guess surfaces later as an opaque decrypt failure.
+      const keyFile = Underpost.secret.sops.keyFile();
+      shellExec(
+        `sudo tee /etc/profile.d/underpost-sops.sh >/dev/null <<'UNDERPOST_SOPS_ENV_EOF'
+export SOPS_AGE_KEY_FILE="\${SOPS_AGE_KEY_FILE:-${keyFile}}"
+UNDERPOST_SOPS_ENV_EOF`,
+      );
+      shellExec(`sudo chmod 644 /etc/profile.d/underpost-sops.sh`);
+
+      // 3. Build and encrypt each requested Secret.
+      const stageDir = '/dev/shm/underpost-secrets';
+      const held = Underpost.secret.sops.localRecipients();
+      fs.ensureDirSync(stageDir);
+      fs.chmodSync(stageDir, 0o700);
+      try {
+        for (const name of secretNames) {
+          const stored = Underpost.secret.sops.has(name, namespace);
+          if (stored && !options.force) {
+            // A stored manifest this host cannot open is present but unusable here, so reporting it
+            // as onboarded would send the operator on to an apply that is guaranteed to fail.
+            if (Underpost.secret.sops.decryptable(Underpost.secret.sops.manifestPath(name, namespace), held))
+              logger.info(`${name} is already onboarded in ns/${namespace}; skipping (use --force to replace)`);
+            else
+              logger.warn(
+                `${name} is stored in ns/${namespace} but is sealed to an Age recipient this host does not hold; ` +
+                  `skipping. Adopt the store's key, re-key it from a host that holds one, or re-onboard from the ` +
+                  `origin seed files with --force.`,
+              );
+            continue;
+          }
+
+          // Data keys come from the secret's origin seed contract, so an onboarded manifest
+          // carries exactly the keys the workload's secretKeyRef already expects.
+          const seedSources = Underpost.secret.sops.seedSources(name);
+          const dataKeys = Object.keys(seedSources).length > 0 ? Object.keys(seedSources) : ['password'];
+          const stringData = {};
+          for (const key of dataKeys) {
+            const seedPath = seedSources[key];
+            if (seedPath && fs.existsSync(seedPath)) {
+              stringData[key] = fs.readFileSync(seedPath, 'utf8').trim();
+              logger.info(`${name}.${key} seeded from ${seedPath}`);
+            } else if (overrides[key] !== undefined) {
+              stringData[key] = overrides[key];
+              logger.info(`${name}.${key} taken from --args`);
+            } else {
+              stringData[key] = generateSeedValue(key);
+              // Replacing a stored manifest with a value nothing seeded means the credential the
+              // running datastore still authenticates against is being thrown away.
+              if (stored)
+                logger.warn(
+                  `${name}.${key} generated while replacing the stored manifest — no seed file at ` +
+                    `${seedPath || '(unmapped)'} and no --args override. The running datastore keeps its old ` +
+                    `credential until this value is applied to it; pass --args "${key}=<value>" to keep the ` +
+                    `existing one.`,
+                );
+              else logger.info(`${name}.${key} generated`);
+            }
+          }
+
+          const stagePath = `${stageDir}/${name}.yaml`;
+          fs.outputFileSync(
+            stagePath,
+            [
+              'apiVersion: v1',
+              'kind: Secret',
+              'metadata:',
+              `  name: ${name}`,
+              `  namespace: ${namespace}`,
+              '  labels:',
+              '    app.kubernetes.io/managed-by: underpost',
+              'type: Opaque',
+              'stringData:',
+              // Single-quoted YAML scalars with doubled internal quotes: values are generated or
+              // operator-supplied and may contain characters YAML would otherwise interpret.
+              ...Object.entries(stringData).map(([key, value]) => `  ${key}: '${`${value}`.replace(/'/g, "''")}'`),
+              '',
+            ].join('\n'),
+            'utf8',
+          );
+          fs.chmodSync(stagePath, 0o600);
+          // encrypt() stages, validates, moves into place, and shreds the plaintext source.
+          Underpost.secret.sops.encrypt(stagePath, namespace, options);
+        }
+      } finally {
+        // Defense in depth: encrypt() shreds each source, but a throw mid-loop must not leave a
+        // plaintext manifest sitting in shared memory.
+        fs.removeSync(stageDir);
+      }
+
+      Underpost.secret.sops.list();
+
+      // 4. Validate every manifest in the namespace, then apply unless this is a dry run.
+      Underpost.secret.sops.apply(namespace, { dryRun: true });
+      if (options.dryRun) return logger.info('--dry-run: validated only, cluster left unchanged');
+      Underpost.secret.sops.apply(namespace);
+    },
+    /**
+     * @method sops-status
+     * @description Reports the live state of the SOPS/Age secret system: host tooling, the Age
+     * key and its recipient, the committed creation rules, every stored manifest with whether the
+     * local key can open it and whether the cluster still matches, and which managed Secrets are
+     * onboarded versus still seeding from their origin path.
+     *
+     * Read-only and safe to run anywhere. Decryption happens only for the drift check, only for
+     * manifests the local key is a recipient of, and only into `kubectl diff` with its output
+     * discarded — no secret value is ever printed or written to disk.
+     *
+     * Usage:
+     *   underpost run sops-status                                   # every managed key, ns default
+     *   underpost run sops-status mongo                             # partial match: both mongo keys
+     *   underpost run sops-status --namespace prod                  # every managed key in ns prod
+     * @param {string} path - Comma-separated managed Secret keys to report on; empty reports all.
+     *   Matched as case-insensitive substrings (`mongo` selects mongodb-secret and mongodb-keyfile).
+     *   Filters both the stored-manifest listing and the coverage table.
+     * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
+     * @param {string} options.namespace - Namespace to inspect (DEFAULT_OPTION scheme, default 'default').
+     * @memberof UnderpostRun
+     */
+    'sops-status': (path = '', options = DEFAULT_OPTION) => {
+      const sops = Underpost.secret.sops;
+      // `--namespace` selects the namespace (DEFAULT_OPTION scheme); `path` narrows which managed
+      // Secret keys to report on, so the two axes stay independent.
+      const namespace = options.namespace || 'default';
+      const manageSecretKeyFilter = path
+        .split(',')
+        .map((key) => key.trim().toLowerCase())
+        .filter(Boolean);
+      // Partial, case-insensitive substring match, so `mongo` reaches both `mongodb-secret` and
+      // `mongodb-keyfile` without having to spell either out.
+      const matchesKeyFilter = (name) =>
+        manageSecretKeyFilter.length === 0 || manageSecretKeyFilter.some((key) => name.toLowerCase().includes(key));
+      const mark = (ok) => (ok ? 'yes' : 'no');
+
+      // ── Tooling ────────────────────────────────────────────────────────────
+      const version = (bin, flag) =>
+        sops.hasBinary(bin)
+          ? shellExec(`${bin} ${flag} 2>/dev/null | head -1`, { stdout: true, silent: true, disableLog: true }).trim()
+          : '(not installed)';
+      logger.info(
+        '[sops-status] Tooling\n' +
+          `  sops        ${version('sops', '--version')}\n` +
+          `  age         ${version('age', '--version')}\n` +
+          `  age-keygen  ${sops.hasBinary('age-keygen') ? 'installed' : '(not installed)'}`,
+      );
+
+      // ── Age key ────────────────────────────────────────────────────────────
+      const keyFile = sops.keyFile();
+      const keyExists = fs.existsSync(keyFile);
+      // A key file may hold several identities — that is how a host joins a store it did not
+      // create — so every check below works against the whole held set, not one recipient.
+      const held = sops.localRecipients();
+      const keyMode = keyExists ? (fs.statSync(keyFile).mode & 0o777).toString(8) : '';
+      logger.info(
+        '[sops-status] Age key\n' +
+          `  path        ${keyFile}\n` +
+          `  present     ${mark(keyExists)}${keyExists ? `  (mode ${keyMode}${keyMode === '600' || keyMode === '400' ? '' : ' — INSECURE, run chmod 600'})` : ''}\n` +
+          `  recipients  ${held.join(', ') || (keyExists ? '(none — unreadable key file)' : '(none)')}` +
+          (keyExists ? '' : `\n  searched    ${sops.keyFileCandidates().join(', ')}`),
+      );
+
+      // ── Creation rules ─────────────────────────────────────────────────────
+      const confPath = './engine-private/secrets/.sops.yaml';
+      const ruleRecipients = sops.creationRecipients();
+      logger.info(
+        '[sops-status] Creation rules\n' +
+          `  config      ${confPath} ${fs.existsSync(confPath) ? '' : '(missing — run: underpost secret sops --init)'}\n` +
+          `  recipients  ${ruleRecipients.length > 0 ? ruleRecipients.join(', ') : '(none)'}\n` +
+          `  local key listed  ${mark(held.some((recipient) => ruleRecipients.includes(recipient)))}`,
+      );
+
+      // ── Stored manifests ───────────────────────────────────────────────────
+      const manifests = sops.manifests(namespace).filter((manifest) => matchesKeyFilter(manifest.name));
+      const onboarded = new Set();
+      if (manifests.length === 0)
+        logger.warn(
+          `[sops-status] Store\n  no encrypted manifests in ns/${namespace}` +
+            (manageSecretKeyFilter.length > 0 ? ` matching ${manageSecretKeyFilter.join(', ')}` : ''),
+        );
+      else {
+        const rows = manifests.map((manifest) => {
+          onboarded.add(manifest.name);
+          const recipients = sops.manifestRecipients(manifest.path);
+          const decryptable = sops.decryptable(manifest.path, held);
+          const live = shellExec(
+            `kubectl get secret ${manifest.name} -n ${manifest.namespace} --ignore-not-found -o name 2>/dev/null || true`,
+            { stdout: true, silent: true, silentOnError: true, disableLog: true },
+          ).trim();
+          // Drift is decided by kubectl's exit code; its stdout would contain the decrypted
+          // values, so it is discarded rather than captured.
+          let sync = 'n/a';
+          if (live && decryptable) {
+            const result = shellExec(
+              `bash -c 'set -o pipefail; SOPS_AGE_KEY_FILE="${keyFile}" sops --decrypt "${manifest.path}" ` +
+                `| kubectl diff -f - -n "${manifest.namespace}" >/dev/null 2>&1'`,
+              { silentOnError: true, disableLog: true, stdout: false },
+            );
+            sync = result.code === 0 ? 'in-sync' : result.code === 1 ? 'DRIFT' : 'error';
+          } else if (!live) sync = 'not applied';
+          else if (!decryptable) sync = 'no local key';
+          return (
+            `  ${`${manifest.namespace}/${manifest.name}`.padEnd(34)} ` +
+            `recipients=${String(recipients.length).padEnd(3)} ` +
+            `decryptable=${mark(decryptable).padEnd(4)} ` +
+            `live=${mark(!!live).padEnd(4)} ` +
+            `${sync}`
+          );
+        });
+        logger.info(`[sops-status] Store — ns/${namespace} (${manifests.length} manifest(s))\n` + rows.join('\n'));
+      }
+
+      // ── Coverage ───────────────────────────────────────────────────────────
+      const coverage = sops
+        .managedSecrets()
+        .filter(matchesKeyFilter)
+        .map((name) => {
+          const seeds = Object.values(sops.seedSources(name));
+          const seedPresent = seeds.length > 0 && seeds.every((seed) => fs.existsSync(seed));
+          const source = onboarded.has(name)
+            ? 'sops'
+            : seedPresent
+              ? 'origin seed'
+              : seeds.length
+                ? 'MISSING'
+                : 'unmapped';
+          return `  ${name.padEnd(24)} ${source.padEnd(12)} ${seeds.length ? `seed=${mark(seedPresent)}` : ''}`;
+        });
+      if (coverage.length === 0)
+        logger.warn(
+          `[sops-status] Coverage\n  no managed Secret matches ${manageSecretKeyFilter.join(', ')}\n` +
+            `  known keys: ${sops.managedSecrets().join(', ')}`,
+        );
+      else
+        logger.info('[sops-status] Coverage (which source each managed Secret deploys from)\n' + coverage.join('\n'));
+    },
     /**
      * @method secret
      * @description Creates an Underpost secret named 'underpost' from a file, defaulting to `/home/dd/engine/engine-private/conf/dd-cron/.env.production` if no path is provided.
@@ -2847,7 +4661,7 @@ EOF`);
 
       const envs = Underpost.env.list();
 
-      const cmd = `kubectl apply -f - <<EOF
+      const cmd = `kubectl apply -f - <<'EOF'
 apiVersion: ${apiVersion}
 kind: ${kindType}
 metadata: