@underpostnet/cyberia 3.3.0 → 3.3.76

package/src/cli/run.js

@@ -4,10 +4,12 @@
  * @namespace UnderpostRun
  */
 
-import { daemonProcess, pbcopy, shellCd, shellExec } from '../server/process.js';
+import { daemonProcess, pbcopy, shellArgumentFactory, shellCd, shellExec } from '../server/runtime/process.js';
+import { cli, withExecutionProfile } from '../server/build/execution.js';
+import { syncDeployPackages } from '../server/build/package.js';
+import { RUNTIME_STATUS } from '../server/runtime/runtime-status.js';
 import {
   awaitDeployMonitor,
-  buildKindPorts,
   clusterContextFactory,
   clusterTypeFactory,
   dispatchBuildInstanceEnv,
@@ -22,41 +24,46 @@ import {
   generateSecurePassword,
   instanceHttpRouteRulesFactory,
   instanceInterceptStatusesFactory,
+  instanceEnvFilePath,
   instancePortFactory,
   instanceProxyRoutesFactory,
   instanceStatusPageEntriesFactory,
-  isDeployRunnerContext,
+  instanceProjectPathFactory,
   loadConfInstances,
   loadProjectInstanceEnvBuilder,
   loadConfServerJson,
-  loadReplicas,
-  resolveDeployList,
   resolveEnvScoped,
   selectConfInstances,
   waitForPort,
   clusterInstancesFactory,
   deployTrafficEntriesFactory,
-  curlStatusChainFactory,
+  publicIngressProbeFactory,
   hostIngressFactsFactory,
   hostRenderInstancesFactory,
   instanceTrafficPlanFactory,
   trafficTableRowsFactory,
   isTrafficServingFactory,
   nextTrafficFactory,
+  redeployPlanFactory,
   stopPlanFactory,
   trafficFromRoutingInfoFactory,
-} from '../server/conf.js';
-import { cronDeployIdResolve } from '../server/cron.js';
-import { getNpmRootPath, writeEnv } from '../server/environment.js';
-import { actionInitLog, loggerFactory } from '../server/logger.js';
+} from '../server/runtime/conf.js';
+import { buildKindPorts, deployRoutesExists, readDeployRoutes, resolveDeployList } from '../server/network/router.js';
+import { clientBundleHostFilter, pullClientBundle, pushClientBundle } from '../client-builder/client-bundle.js';
+import { cronDeployIdResolve } from '../server/ops/cron.js';
+import { deployEnvFactory, getNpmRootPath, writeEnv } from '../server/runtime/environment.js';
+import { actionInitLog, loggerFactory } from '../server/ops/logger.js';
 
 import fs from 'fs-extra';
 import { range, s4, setPad, timer } from '../client/components/core/CommonJs.js';
 
 import os from 'os';
+import nodePath from 'node:path';
+import { domainContextFactory } from './domains.js';
 import Underpost from '../index.js';
 import dotenv from 'dotenv';
 import { MongoBootstrap } from '../db/mongo/MongoBootstrap.js';
+import { MongoExpress } from '../db/mongo/MongoExpress.js';
 import {
   UNDERPOST_GATEWAY,
   assertStaticAssets,
@@ -69,7 +76,7 @@ import {
   readHostInstanceRegistry,
   writeHostInstanceRegistry,
   writeHostServerConf,
-} from '../server/underpost-gateway.js';
+} from '../server/network/underpost-gateway.js';
 const logger = loggerFactory(import.meta);
 
 /**
@@ -89,6 +96,9 @@ const logger = loggerFactory(import.meta);
  * @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.
+ * @property {string} runtimeImage - `src/runtime/<name>` image family the cluster runner brings up (`cluster`).
+ * @property {string} image - Container image the deployment pulls and runs (`sync`).
+ * @property {string} versions - Comma-separated blue/green deployment versions (`sync`).
  * @property {string} containerName - The name of the container to run.
  * @property {string} namespace - The namespace to run in.
  * @property {string} timeoutResponse - The response timeout duration.
@@ -132,11 +142,13 @@ const logger = loggerFactory(import.meta);
  * @property {boolean} kind - Whether to run in kind mode.
  * @property {boolean} k3s - Whether to run in k3s mode.
  * @property {string} hosts - The hosts to use.
+ * @property {string} split - Zip part size in MB for push-bundle, or 'none' to upload a single zip.
  * @property {string} deployId - The deployment ID.
  * @property {string} instanceId - The instance ID.
  * @property {string} user - The user to run as.
  * @property {string} group - The group to use.
  * @property {string} pid - The process ID.
+ * @property {string} repoEnginePrivate - Private configuration repository the pull runner checks out, overriding the pairing derived from the engine source.
  * @property {boolean} disablePrivateConfUpdate - Whether to disable private configuration updates.
  * @property {string} monitorStatus - The monitor status option.
  * @property {string} monitorStatusKindType - The monitor status kind type option.
@@ -183,6 +195,9 @@ const DEFAULT_OPTION = {
   volumeHostPath: '',
   volumeMountPath: '',
   imageName: '',
+  image: '',
+  runtimeImage: '',
+  versions: '',
   containerName: '',
   namespace: 'default',
   timeoutResponse: '',
@@ -226,11 +241,13 @@ const DEFAULT_OPTION = {
   kind: false,
   k3s: false,
   hosts: '',
+  split: '',
   deployId: '',
   instanceId: '',
   user: '',
   group: '',
   pid: '',
+  repoEnginePrivate: '',
   disablePrivateConfUpdate: false,
   monitorStatus: '',
   monitorStatusKindType: '',
@@ -271,33 +288,6 @@ const DEFAULT_OPTION = {
  * @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
@@ -326,13 +316,12 @@ class UnderpostRun {
         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)
+            : deployRoutesExists()
               ? resolveDeployList('dd')
               : fs.existsSync(confRoot)
                 ? fs
@@ -488,7 +477,7 @@ class UnderpostRun {
      * @memberof UnderpostRun
      */
     'dev-cluster': (path, options = DEFAULT_OPTION) => {
-      const baseCommand = options.dev ? 'node bin' : 'underpost';
+      const baseCommand = cli('underpost', { local: true });
       const mongoHosts = ['mongodb-0.mongodb-service'];
       let primaryMongoHost = 'mongodb-0.mongodb-service';
       const clusterType = clusterTypeFactory(options);
@@ -826,52 +815,21 @@ class UnderpostRun {
       return results;
     },
 
-    /**
-     * @method dev-hosts-expose
-     * @description Deploys a specified service in development mode with `/etc/hosts` modification for local access.
-     * @param {string} path - The input value, identifier, or path for the operation (used as the deployment ID to deploy).
-     * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
-     * @memberof UnderpostRun
-     */
-    '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 });
-    },
-
-    /**
-     * @method dev-hosts-restore
-     * @description Restores the `/etc/hosts` file to its original state after modifications made during development deployments.
-     * @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
-     */
-    'dev-hosts-restore': (path, options = DEFAULT_OPTION) => {
-      // 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);
-    },
-
     /**
      * @method cluster-build
-     * @description Build configuration for cluster deployment.
-     * @param {string} path - The input value, identifier, or path for the operation.
+     * @description Resets the workspace and regenerates every routed deploy's default
+     * configuration, optionally committing the result to both repositories.
+     *
+     * Single-replica materialization is not done here: `deploy --sync` builds those folders
+     * as part of the deploy itself (`getDataDeploy({ buildSingleReplica: true })`).
+     * @param {string} path - `cmt` to commit the regenerated configuration; otherwise unused.
      * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
      * @memberof UnderpostRun
      */
     'cluster-build': (path, options = DEFAULT_OPTION) => {
-      const nodeOptions =
-        (options.nodeName ? ` --node-name ${options.nodeName}` : '') +
-        (options.sshKeyPath ? ` --ssh-key-path ${options.sshKeyPath}` : '');
       shellExec(`node bin run clean`);
-      shellExec(`node bin run --dev sync-replica template-deploy${nodeOptions}`);
-      shellExec(`node bin run sync-replica template-deploy${nodeOptions}`);
-      shellExec(`node bin env clean`);
-      for (const deployId of fs.readFileSync('./engine-private/deploy/dd.router', 'utf8').split(','))
-        shellExec(`node bin new --default-conf --deploy-id ${deployId.trim()}`);
+      shellExec(`node bin app clean`);
+      for (const deployId of readDeployRoutes()) shellExec(`node bin new --default-conf --deploy-id ${deployId}`);
       if (path === 'cmt') {
         shellExec(`git add . && underpost cmt . build cluster-build`);
         shellExec(`cd engine-private && git add . && underpost cmt . build cluster-build`);
@@ -887,14 +845,14 @@ class UnderpostRun {
      * @memberof UnderpostRun
      */
     'template-deploy': (path = '', options = DEFAULT_OPTION) => {
-      const baseCommand = options.dev ? 'node bin' : 'underpost';
+      const baseCommand = cli('underpost', { local: true });
       shellExec(`npm run security:secrets`);
       const reportPath = './gitleaks-report.json';
       if (fs.existsSync(reportPath) && JSON.parse(fs.readFileSync(reportPath, 'utf8')).length > 0) {
         logger.error('Secrets detected in gitleaks-report.json, aborting template-deploy');
         return;
       }
-      shellExec(`${baseCommand} run pull`);
+      Underpost.repo.fastForwardEnginePair(baseCommand);
       shellExec(`${baseCommand} run shared-dir`);
 
       // Capture the sanitized message from the last N commits (--from-n-commit, default 1) for
@@ -964,14 +922,14 @@ class UnderpostRun {
      * @memberof UnderpostRun
      */
     'template-deploy-local': async (path, options = DEFAULT_OPTION) => {
-      const baseCommand = options.dev ? 'node bin' : 'underpost';
+      const baseCommand = cli('underpost', { local: true });
       shellExec(`npm run security:secrets`);
       const reportPath = './gitleaks-report.json';
       if (fs.existsSync(reportPath) && JSON.parse(fs.readFileSync(reportPath, 'utf8')).length > 0) {
         logger.error('Secrets detected in gitleaks-report.json, aborting template-deploy');
         return;
       }
-      shellExec(`${baseCommand} run pull`);
+      Underpost.repo.fastForwardEnginePair(baseCommand);
       shellExec(`${baseCommand} run shared-dir`);
 
       // Capture the sanitized message from the last N commits (--from-n-commit, default 1).
@@ -1015,47 +973,51 @@ class UnderpostRun {
     },
     /**
      * @method pull
-     * @description Clones or pulls updates for the `engine` and `engine-private` repositories into `/home/dd/engine` and `/home/dd/engine/engine-private`.
-     * @param {string} path - The input value, identifier, or path for the operation.
+     * @description Brings the node's engine checkout and its private configuration to the tip of
+     * their repositories, at `/home/dd/engine` and `/home/dd/engine/engine-private`.
+     *
+     * With no argument this is the monorepo pair, `engine` and `engine-private`. Naming a source
+     * repository deploys that source instead, and its private conf repository is derived from the
+     * conf id they share rather than passed separately — `underpostnet/engine-test-lampp` pairs
+     * with `underpostnet/engine-lampp-private`, as does `underpostnet/engine-lampp`.
+     * `--repo-engine-private` overrides that derivation for a conf repository the pairing cannot
+     * name, and is the flag `deploy/lib/host.sh` forwards `ENGINE_SRC_PRIVATE_REPO` through.
+     *
+     * Both checkouts are replaced rather than merged, by the same `--switch-repo` route the fleet
+     * sync takes — so a node moves onto a test source repo and back without being reprovisioned,
+     * and one that has drifted onto commits of its own is brought back instead of refused.
+     *
+     * The replacement checkout is installed before this returns: it is a different commit than
+     * the one the caller started from, and nothing that follows can run against uninstalled
+     * dependencies.
+     * @param {string} path - Engine source repository, as `owner/repo` or a clone URL. Defaults to
+     *   the `GITHUB_USERNAME` monorepo.
      * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
      * @memberof UnderpostRun
      */
-    pull: (path, options = DEFAULT_OPTION) => {
+    pull: (path = '', options = DEFAULT_OPTION) => {
       // shellExec is fail-fast by default — any non-zero exit throws and
       // propagates up to the workflow step. No per-call flag required.
-      if (!fs.existsSync(`/home/dd`) || !fs.existsSync(`/home/dd/engine`)) {
-        fs.mkdirSync(`/home/dd`, { recursive: true });
-        shellExec(`cd /home/dd && underpost clone ${process.env.GITHUB_USERNAME}/engine`, { silent: true });
-      } else {
-        shellExec(`underpost run clean`);
-        shellExec(`cd /home/dd/engine && underpost pull . ${process.env.GITHUB_USERNAME}/engine`, { silent: true });
-      }
-      if (!fs.existsSync(`/home/dd/engine/engine-private`))
-        shellExec(`cd /home/dd/engine && underpost clone ${process.env.GITHUB_USERNAME}/engine-private`, {
-          silent: true,
-        });
-      else
-        shellExec(
-          `cd /home/dd/engine/engine-private && underpost pull . ${process.env.GITHUB_USERNAME}/engine-private`,
-          { silent: true },
-        );
-    },
-    /**
-     * @method release-deploy
-     * @description Executes deployment (`underpost run deploy`) for all deployment IDs listed in `./engine-private/deploy/dd.router`.
-     * @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
-     */
-    'release-deploy': (path, options = DEFAULT_OPTION) => {
-      actionInitLog();
-      shellExec(`underpost --version`);
-      shellCd(`/home/dd/engine`);
-      for (const _deployId of fs.readFileSync(`./engine-private/deploy/dd.router`, 'utf8').split(',')) {
-        const deployId = _deployId.trim();
-        shellExec(`underpost run deploy ${deployId}`, { async: true });
-      }
+      const { engine: source, enginePrivate: privateRepo } = Underpost.repo.enginePairFactory({
+        engine: path,
+        enginePrivate: options.repoEnginePrivate,
+      });
+      logger.info('Pulling engine source', { source, privateRepo });
+
+      const engineRoot = `/home/dd/engine`;
+      // Cleaning is the in-process API rather than a shell round trip through the
+      // global `underpost`: that bin is linked at the very checkout being replaced,
+      // so a tree left without its dependencies made the pre-clean — and with it the
+      // whole pull — exit non-zero on exactly the node that needed replacing.
+      if (fs.existsSync(engineRoot)) Underpost.repo.clean({ paths: [engineRoot, `${engineRoot}/engine-private`] });
+      Underpost.repo.syncCheckout({ path: engineRoot, repo: source });
+      Underpost.repo.syncCheckout({ path: `${engineRoot}/engine-private`, repo: privateRepo });
+      // The checkout that lands here is a different commit than the one this process
+      // started from, and its package.json is only a description until it is installed.
+      // Everything after this — the linked global bin included — runs from this tree.
+      shellExec(`cd ${engineRoot} && npm install`);
     },
+
     /**
      * @method ssh-deploy
      * @description Dispatches the corresponding CD workflow for SSH-based deployment, replacing empty commits with workflow_dispatch.
@@ -1125,36 +1087,35 @@ echo -e "[code]\nname=Visual Studio Code\nbaseurl=https://packages.microsoft.com
     },
     /**
      * @method sync
-     * @description Cleans up, and then runs a deployment synchronization command (`underpost deploy --kubeadm --build-manifest --sync...`) using parameters parsed from `path` (deployId, replicas, versions, image, node).
+     * @description Cleans up, and then runs a deployment synchronization command (`underpost deploy --kubeadm --build-manifest --sync...`).
+     *
+     * Every input is a flag: `--deploy-id`, `--replicas`, `--versions`, `--image`, `--node-name`.
      *
      * Forwards `--image-pull-policy <policy>` to the underlying `deploy --build-manifest` invocation when `options.imagePullPolicy` is set,
      * which then plumbs through `buildManifest` and `deploymentYamlPartsFactory` to override the container `imagePullPolicy` in the generated
      * `deployment.yaml`. Useful when you want to force `Always` so the kubelet re-pulls a mutable tag on every rollout. Example:
-     *   `node bin run sync dd-core --kubeadm --image-pull-policy Always`
-     * @param {string} path - The input value, identifier, or path for the operation (used as a comma-separated string containing deploy parameters).
+     *   `node bin run sync --deploy-id dd-core --kubeadm --image-pull-policy Always`
+     *
+     * Runs in one of two modes. Given `--deploy-id`, it deploys. Passed `--build`, or no
+     * `--deploy-id` at all, it renders the manifests and the router table and stops before
+     * touching the cluster:
+     *   `node bin run --dev --build sync --deploy-id dd-default`
+     * @param {string} [path] - Unused; every input is a flag.
      * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
      * @memberof UnderpostRun
      */
     sync: async (path, options = DEFAULT_OPTION) => {
-      // Dev usage: node bin run --dev --build sync dd-default
-      const env = options.dev ? 'development' : 'production';
+      const env = deployEnvFactory(options);
       options = { ...options, gatewayApi: gatewayApiEnabledFactory(options) };
-      const baseCommand = 'node bin'; // options.dev ? 'node bin' : 'underpost';
+      const baseCommand = cli('underpost', { local: true });
       const baseClusterCommand = options.dev ? ' --dev' : '';
       const clusterFlag = options.k3s ? ' --k3s' : options.kind ? ' --kind' : ' --kubeadm';
-      const defaultPath = [
-        'dd-default',
-        options.replicas,
-        ``,
-        ``,
-        !options.kubeadm && !options.k3s ? 'kind-control-plane' : os.hostname(),
-      ];
-      let [deployId, replicas, versions, image, node] = path ? path.split(',') : defaultPath;
-      deployId = deployId ? deployId : defaultPath[0];
-      replicas = replicas ? replicas : defaultPath[1];
-      versions = versions ? versions.replaceAll('+', ',') : defaultPath[2];
-      image = image ? image : defaultPath[3];
-      node = node ? node : options.nodeName ? options.nodeName : defaultPath[4];
+      const deploying = !options.build && !!options.deployId;
+      const deployId = options.deployId || 'dd-default';
+      const replicas = options.replicas || 1;
+      const image = options.image || '';
+      const node = options.nodeName || (!options.kubeadm && !options.k3s ? 'kind-control-plane' : os.hostname());
+      let versions = options.versions || '';
       shellExec(`${baseCommand} cluster --ns-use ${options.namespace}`);
 
       if (image && !image.startsWith('localhost'))
@@ -1165,7 +1126,7 @@ echo -e "[code]\nname=Visual Studio Code\nbaseurl=https://packages.microsoft.com
           k3s: options.k3s,
         });
 
-      if (isDeployRunnerContext(path, options)) {
+      if (deploying) {
         if (!options.disablePrivateConfUpdate) {
           const { validVersion } = Underpost.repo.privateConfUpdate(deployId);
           if (!validVersion) throw new Error('Version mismatch');
@@ -1183,7 +1144,7 @@ echo -e "[code]\nname=Visual Studio Code\nbaseurl=https://packages.microsoft.com
         }
       }
 
-      const currentTraffic = isDeployRunnerContext(path, options)
+      const currentTraffic = deploying
         ? Underpost.deploy.getCurrentTraffic(deployId, {
             namespace: options.namespace,
             env,
@@ -1207,14 +1168,12 @@ echo -e "[code]\nname=Visual Studio Code\nbaseurl=https://packages.microsoft.com
       });
 
       const ignorePods =
-        isDeployRunnerContext(path, options) && targetTraffic
+        deploying && targetTraffic
           ? Underpost.kubectl.get(`${deployId}-${env}-${targetTraffic}`, 'pods', options.namespace).map((p) => p.NAME)
           : [];
 
       const timeoutFlags = Underpost.deploy.timeoutFlagsFactory(options);
-      const cmdString = options.cmd
-        ? ' --cmd ' + (options.cmd.find((c) => c.match('"')) ? '"' + options.cmd + '"' : "'" + options.cmd + "'")
-        : '';
+      const cmdString = options.cmd ? ` --cmd ${shellArgumentFactory(options.cmd)}` : '';
       const gitCleanFlag = options.gitClean ? ' --git-clean' : '';
 
       const skipFullBuildFlag = options.skipFullBuild ? ' --skip-full-build' : '';
@@ -1223,11 +1182,22 @@ echo -e "[code]\nname=Visual Studio Code\nbaseurl=https://packages.microsoft.com
       const sshKeyPathFlag = options.sshKeyPath ? ` --ssh-key-path ${options.sshKeyPath}` : '';
       const gatewayApiFlags = Underpost.deploy.gatewayApiFlagsFactory(options);
 
+      // Retarget `underpost-config` at this sync's environment before anything is
+      // deployed. `underpost host load` reads it back inside the
+      // pod, so a stale Secret makes the container resolve the wrong NODE_ENV.
+      if (deploying) {
+        Underpost.host.apply(domainContextFactory({ env, namespace: options.namespace }));
+        Underpost.app.apply(
+          domainContextFactory({ env, namespace: options.namespace, args: { 'deploy-id': deployId } }),
+        );
+      }
+
       // 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} --ssr`);
+      // the caller explicitly selected a pre-built bundle workflow. `--env` is
+      // explicit: the SSR pass must render for the target environment, never for
+      // whatever NODE_ENV the calling shell happens to carry.
+      if (deploying && !options.skipFullBuild) shellExec(`${baseCommand} client ${deployId} --env ${env} --ssr`);
 
       shellExec(
         `${baseCommand} deploy${clusterFlag} --build-manifest --sync --info-router --replicas ${replicas} --node ${node}${
@@ -1237,7 +1207,7 @@ echo -e "[code]\nname=Visual Studio Code\nbaseurl=https://packages.microsoft.com
         }${timeoutFlags}${cmdString}${gitCleanFlag}${skipFullBuildFlag}${pullBundleFlag}${imagePullPolicyFlag}${sshKeyPathFlag}${gatewayApiFlags} ${deployId} ${env}`,
       );
 
-      if (isDeployRunnerContext(path, options)) {
+      if (deploying) {
         if (options.gatewayApi) {
           const namespace = options.namespace || 'default';
           const gatewayRoot = Underpost.deploy.underpostGatewayRootFactory(options);
@@ -1308,6 +1278,48 @@ echo -e "[code]\nname=Visual Studio Code\nbaseurl=https://packages.microsoft.com
         );
     },
 
+    /**
+     * @method net-tables
+     * @description Prints the host's network tables: interfaces and links (`ip -br link show`) with state, MAC address, and flags, followed by IP addresses (`ip -br addr show`) with IPv4/IPv6, each aligned via `column -t`.
+     * @param {string} path - The input value, identifier, or path for the operation (unused).
+     * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow (unused).
+     * @memberof UnderpostRun
+     */
+    'net-tables': (path, options = DEFAULT_OPTION) => {
+      logger.info(`INTERFACES & LINKS`);
+      shellExec(`(echo "INTERFACE STATE MAC FLAGS"; ip -br link show) | column -t`);
+      logger.info(`IP ADDRESSES`);
+      shellExec(`(echo "INTERFACE STATE IPV4 IPV6"; ip -br addr show) | column -t`);
+      logger.info('KERNEL ROUTING TABLE');
+      shellExec(`(echo "DESTINATION GATEWAY INTERFACE PROTO SCOPE METRIC"; \
+ip route show | awk '{
+  dst = $1; gw = "on-link"; dev = "-"; proto = "-"; scope = "-"; metric = "-";
+  for (i=1; i<=NF; i++) {
+    if ($i == "via") gw = $(i+1);
+    if ($i == "dev") dev = $(i+1);
+    if ($i == "proto") proto = $(i+1);
+    if ($i == "scope") scope = $(i+1);
+    if ($i == "metric") metric = $(i+1);
+  }
+  print dst, gw, dev, proto, scope, metric;
+}') | column -t`);
+      logger.info(`ACTIVE NAT FLOWS`);
+      shellExec(`(echo "CHAIN TYPE TARGET_IP_PORT PACKETS BYTES"; \
+sudo nft list table ip nat | awk '
+/chain (PREROUTING|POSTROUTING)/ {chain=$2} 
+/dnat to|masquerade|snat to/ && !/packets 0/ {
+    type = ($0 ~ "dnat") ? "DNAT" : (($0 ~ "masquerade") ? "MASQUERADE" : "SNAT");
+    target = "N/A";
+    pkts = "0"; bytes = "0";
+    for(i=1; i<=NF; i++) {
+        if ($i == "packets") pkts = $(i+1);
+        if ($i == "bytes") bytes = $(i+1);
+        if ($i == "to") target = $(i+1);
+    }
+    print chain, type, target, pkts, bytes;
+}') | column -t`);
+    },
+
     /**
      * @method stop
      * @description Deletes colour-suffixed Deployments and their Services, leaving routing untouched.
@@ -1419,8 +1431,8 @@ echo -e "[code]\nname=Visual Studio Code\nbaseurl=https://packages.microsoft.com
           ? options.timezone
           : path
             ? path
-            : Underpost.env.get('TIME_ZONE', undefined, { disableLog: true })
-              ? Underpost.env.get('TIME_ZONE')
+            : Underpost.host.store.get('TIME_ZONE', undefined, { disableLog: true })
+              ? Underpost.host.store.get('TIME_ZONE')
               : process.env.TIME_ZONE
                 ? process.env.TIME_ZONE
                 : 'America/New_York';
@@ -1563,7 +1575,6 @@ echo -e "[code]\nname=Visual Studio Code\nbaseurl=https://packages.microsoft.com
       // 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}`;
@@ -1573,18 +1584,8 @@ echo -e "[code]\nname=Visual Studio Code\nbaseurl=https://packages.microsoft.com
         } 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));
-        }
+        // Cache by URL so rows that share one never repeat network work.
+        if (!probeCache.has(url)) probeCache.set(url, publicIngressProbeFactory(url));
         return { path: normalizedPath, url, statuses: probeCache.get(url) };
       };
 
@@ -1625,7 +1626,7 @@ echo -e "[code]\nname=Visual Studio Code\nbaseurl=https://packages.microsoft.com
 
       // 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 columns = ['#', 'HOST', 'PATH', 'KIND', 'ROUTE', 'TLS', 'HTTP3', 'CURRENT', 'OPPOSITE'];
       const deploymentStatus = (status, includeServing = false) => {
         if (!status) return `unrouted - missing${includeServing ? ' not-serving' : ''}`;
         return [
@@ -1635,10 +1636,11 @@ echo -e "[code]\nname=Visual Studio Code\nbaseurl=https://packages.microsoft.com
           ...(includeServing ? [status.serving ? 'serving' : 'not-serving'] : []),
         ].join(' ');
       };
-      const cellOf = (row) => {
+      const cellOf = (row, index) => {
         const facts = ingressFacts[row.host] || {};
         const pathStatus = row.probes.map((probe) => `${probe.path} [${probe.statuses.join('→')}]`).join(' ');
         return [
+          `${index + 1}(${row.probes.length})`,
           row.host,
           pathStatus,
           row.kind,
@@ -1693,7 +1695,8 @@ echo -e "[code]\nname=Visual Studio Code\nbaseurl=https://packages.microsoft.com
         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);
+        const envRows = reportRows.filter((row) => row.env === env);
+        const envCells = envRows.map((row, index) => cellOf(row, index));
         if (envCells.length > 0) printTable(envCells, `[${env.toUpperCase()}]`);
       }
       console.log('');
@@ -1978,22 +1981,33 @@ EOF
 
     /**
      * @method instance
-     * @param {string} path - The input value, identifier, or path for the operation (used as a comma-separated string containing workflow parameters).
+     * @description Deploys the custom instances a deploy declares in `conf.instances.json`.
+     *
+     * Every input is a flag: `--deploy-id`, `--instance-id`, `--replicas`, `--node-name`.
+     * `--instance-id` naming a template id selects its whole variant family.
+     * @param {string} path - Unused; every input is a flag.
      * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
      * @memberof UnderpostRun
      */
     instance: async (path = '', options = DEFAULT_OPTION) => {
-      const env = options.dev ? 'development' : 'production';
+      const env = deployEnvFactory(options);
       options = {
         ...options,
         gatewayApi: gatewayApiEnabledFactory(options),
         namespace: options.namespace || 'default',
       };
-      const baseCommand = options.dev ? 'node bin' : 'underpost';
+      const baseCommand = cli('underpost', { local: true });
       const baseClusterCommand = options.dev ? ' --dev' : '';
-      let [deployId, id, replicas] = path.split(',');
-      if (!replicas) replicas = options.replicas;
+      const deployId = options.deployId;
+      const id = options.instanceId;
+      const replicas = options.replicas || 1;
+      if (!deployId) throw new Error('The --deploy-id option is required by the instance runner');
+      if (!id) throw new Error('The --instance-id option is required by the instance runner');
       const confInstances = selectConfInstances(loadConfInstances(deployId), id);
+      // Retarget `underpost-config` at this run's environment before any instance
+      // Deployment is submitted: it is what `underpost host load` reads inside the pod,
+      // and a stale one makes the container resolve the wrong NODE_ENV.
+      if (!options.expose) Underpost.host.apply(domainContextFactory({ env, namespace: options.namespace }));
       const { liveTrafficById, targetTrafficById, serving } = instanceTrafficPlanFactory({
         instances: confInstances,
         requestedTraffic: options.traffic,
@@ -2089,7 +2103,6 @@ EOF
         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);
         shellExec(`kubectl delete service ${podId}-service --namespace ${options.namespace} --ignore-not-found`);
         shellExec(`kubectl delete deployment ${podId} --namespace ${options.namespace} --ignore-not-found`);
         for (const _volume of _volumes)
@@ -2219,11 +2232,10 @@ EOF
 
     /**
      * @method deploy-key
-     * @description Copies the deploy key for a specific user and deployId to a temporary location on the local machine.
+     * @description Copies the cluster scoped deploy key for a specific user to a temporary location on the local machine.
      * @param {string} path - The input value, identifier, or path for the operation (not used in this method).
      * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
      * @param {string} options.user - The user for which to copy the deploy key.
-     * @param {string} options.deployId - The deployment identifier associated with the deploy key.
      * @memberof UnderpostRun
      */
     'deploy-key': (path, options = DEFAULT_OPTION) => {
@@ -2232,13 +2244,18 @@ EOF
         shellExec(`rm -rf /home/dd/tmp/${prefix}_*`);
         return;
       }
-      if (!options.user || !options.deployId) {
-        logger.error('Both --user and --deploy-id options are required to copy the deploy key.');
+      if (!options.user) {
+        logger.error('The --user option is required to copy the deploy key.');
+        return;
+      }
+      const sourcePath = `${Underpost.ssh.userKeyDir(options.user)}/id_rsa`;
+      if (!fs.existsSync(sourcePath)) {
+        logger.error(`No deploy key found at ${sourcePath}; run: node bin ssh --user ${options.user} --user-add`);
         return;
       }
       const targetPath = `/home/dd/tmp/${prefix}_${s4()}${s4()}`;
       fs.mkdirSync('/home/dd/tmp', { recursive: true });
-      fs.copyFileSync(`./engine-private/conf/${options.deployId}/users/${options.user}/id_rsa`, targetPath);
+      fs.copyFileSync(sourcePath, targetPath);
       logger.info(`Copied deploy key to ${targetPath}`);
       if (options.copy) pbcopy(targetPath);
     },
@@ -2254,19 +2271,25 @@ EOF
      * If `--build` is supplied the image is built from the project Dockerfile and loaded into the
      * cluster before the manifest is written (kind by default; `--kubeadm` / `--k3s` override).
      *
-     * @param {string} path - Comma-separated: `deployId,instanceId[,projectPath]`.
-     *   `projectPath` is the root directory that contains the `Dockerfile` (e.g. `./cyberia-client`).
-     *   Artifacts are written to `<projectPath>/manifests/<env>/Dockerfile` and
-     *   `<projectPath>/manifests/<env>/deployment.yaml`.
-     *   In production, files are also copied to `<projectPath>/Dockerfile` and
-     *   `<projectPath>/deployment.yaml`.
+     * The target is named by `--deploy-id` and `--instance-id`, like every other instance runner.
+     * Where the artifacts land is not an argument: an instance's project directory is derived from
+     * the conf entry itself (see {@link instanceProjectPathFactory}), so the caller cannot pair an
+     * instance with someone else's checkout. Artifacts are written to
+     * `<project>/manifests/deployments/<instance>-<env>/`, and in production the pair is also
+     * copied to `<project>/Dockerfile` and `<project>/deployment.yaml`.
+     *
+     * @param {string} path - Unused; the target comes from `--deploy-id` and `--instance-id`.
      * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
      * @memberof UnderpostRun
      */
     '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 deployId = options.deployId;
+      const id = options.instanceId;
+      if (!deployId || !id) {
+        logger.error('[instance-build-manifest] --deploy-id and --instance-id are required');
+        return;
+      }
 
       const confInstances = loadConfInstances(deployId);
       // Targeting a template id builds every world in the family. The fan-out
@@ -2284,20 +2307,23 @@ EOF
       }
       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 },
-          );
+          await UnderpostRun.RUNNERS['instance-build-manifest']('', {
+            ...options,
+            instanceId: instance.id,
+            instanceOnly: true,
+          });
         return;
       }
 
+      const instance = selected[0];
+      // The conf names the project: its repository, else its runtime, else its id. A world and the
+      // checkout it publishes to cannot disagree, because only one of them is stated.
+      const rootPath = instanceProjectPathFactory(instance);
       const envManifestPath = `${rootPath}/manifests/deployments/${id}-${env}`;
       const outputPath = `${envManifestPath}/deployment.yaml`;
       const dockerfileManifestPath = `${envManifestPath}/Dockerfile`;
 
       fs.mkdirpSync(envManifestPath);
-
-      const instance = selected[0];
       const isDefaultInstance = instance.id === instance.templateId || !instance.templateId;
       const instanceEnvBuilder = await loadProjectInstanceEnvBuilder(deployId);
 
@@ -2344,14 +2370,15 @@ EOF
       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) {
+      // Build the image from the project's own Dockerfile and load it into the cluster when
+      // --build is set.
+      if (options.build) {
         const isKind = !options.kubeadm && !options.k3s;
         Underpost.image.build({
-          path: projectPath,
+          path: rootPath,
           imageName: _image,
           podmanSave: true,
-          imageOutPath: projectPath,
+          imageOutPath: rootPath,
           kind: isKind,
           kubeadm: !!options.kubeadm,
           k3s: !!options.k3s,
@@ -2471,12 +2498,11 @@ EOF
       // 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));
+      // No project override: this runner and the sync now derive the root from the same instance
+      // by the same rule, so passing one here could only make them disagree.
+      const statusPageEntries = instanceStatusPageEntriesFactory({ instances: [instance] }).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
@@ -2569,11 +2595,11 @@ EOF
       // 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`;
+        const instanceEnvDir = nodePath.dirname(instanceEnvFilePath(deployId, _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`;
+          const templateEnvPath = instanceEnvFilePath(deployId, instance.templateId, targetEnv);
           if (!fs.existsSync(templateEnvPath))
             throw new Error(`[instance-build-manifest] Missing canonical env file: ${templateEnvPath}`);
           const baseEnv = dotenv.parse(fs.readFileSync(templateEnvPath, 'utf8'));
@@ -2585,7 +2611,7 @@ EOF
             containerDeployId: `${_deployId}-${targetEnv}`,
             builders: instanceEnvBuilder ? { [deployId]: instanceEnvBuilder } : {},
           });
-          writeEnv(`${instanceEnvDir}/${targetEnv}.env`, builtEnv);
+          writeEnv(instanceEnvFilePath(deployId, _id, targetEnv), builtEnv);
         }
         logger.info('[instance-build-manifest] Instance env written', {
           dir: instanceEnvDir,
@@ -2667,7 +2693,6 @@ EOF
      * @memberof UnderpostRun
      */
     'host-update': async (path, options = DEFAULT_OPTION) => {
-      // const baseCommand = options.dev ? 'node bin' : 'underpost';
       shellExec(`chmod +x ${options.underpostRoot}/scripts/rocky-setup.sh`);
       shellExec(`${options.underpostRoot}/scripts/rocky-setup.sh${options.dev ? ' --install-dev' : ``}`);
     },
@@ -2734,7 +2759,7 @@ EOF`);
      * @memberof UnderpostRun
      */
     'dd-container': async (path = '', options = DEFAULT_OPTION) => {
-      const baseCommand = options.dev ? 'node bin' : 'underpost';
+      const baseCommand = cli('underpost', { local: true });
       const baseClusterCommand = options.dev ? ' --dev' : '';
       const currentImage = options.imageName
         ? options.imageName
@@ -2831,15 +2856,15 @@ EOF`);
      * @memberof UnderpostRun
      */
     'git-conf': (path = '', options = DEFAULT_OPTION) => {
-      const defaultUsername = Underpost.env.get('GITHUB_USERNAME');
-      const defaultEmail = Underpost.env.get('GITHUB_EMAIL');
+      const defaultUsername = Underpost.host.store.get('GITHUB_USERNAME');
+      const defaultEmail = Underpost.host.store.get('GITHUB_EMAIL');
       const validPath = path && path.split(',').length;
       const [username, email] = validPath ? path.split(',') : [defaultUsername, defaultEmail];
       if (validPath) {
-        Underpost.env.set('GITHUB_USERNAME', username);
-        Underpost.env.set('GITHUB_EMAIL', email);
-        Underpost.env.get('GITHUB_USERNAME');
-        Underpost.env.get('GITHUB_EMAIL');
+        Underpost.host.store.set('GITHUB_USERNAME', username);
+        Underpost.host.store.set('GITHUB_EMAIL', email);
+        Underpost.host.store.get('GITHUB_USERNAME');
+        Underpost.host.store.get('GITHUB_EMAIL');
       }
       shellExec(
         `git config --global credential.helper "" && ` +
@@ -2870,7 +2895,7 @@ EOF`);
 
     /**
      * @method promote
-     * @description Switches traffic between blue/green deployments for a specified deployment ID(s) (uses `dd.router` for 'dd', or a specific ID).
+     * @description Switches traffic between blue/green deployments for a specified deployment ID(s) (uses `dd.routes` for 'dd', or a specific ID).
      * When `--tls` is set, rebuilds the proxy manifest with `--cert` so the HTTPProxy includes
      * TLS config, deletes stale Certificate resources, then reapplies the proxy and secret.yaml
      * (cert-manager Certificate resources) for each affected deployment.
@@ -2906,7 +2931,7 @@ EOF`);
       };
 
       if (inputDeployId === 'dd') {
-        for (const deployId of fs.readFileSync(`./engine-private/deploy/dd.router`, 'utf8').split(',')) {
+        for (const deployId of readDeployRoutes()) {
           const currentTraffic = Underpost.deploy.getCurrentTraffic(deployId, {
             namespace: options.namespace,
             env: inputEnv,
@@ -2932,44 +2957,6 @@ EOF`);
         applyCerts(inputDeployId, targetTraffic);
       }
     },
-    /**
-     * @method metrics
-     * @description Deploys Prometheus and Grafana for metrics monitoring, targeting the hosts defined in the deployment configuration files.
-     * @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
-     */
-    metrics: async (path, options = DEFAULT_OPTION) => {
-      if (path === 'server') {
-        shellExec(
-          `kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/high-availability-1.21+.yaml`,
-        );
-        await timer(2000);
-
-        shellExec(`kubectl patch deployment metrics-server -n kube-system \
-  --type='json' \
-  -p='[
-    {
-      "op":"add",
-      "path":"/spec/template/spec/containers/0/args/-",
-      "value":"--kubelet-insecure-tls"
-    }
-  ]'`);
-        shellExec(`kubectl scale deployment metrics-server \
-  -n kube-system \
-  --replicas=1`);
-
-        return;
-      }
-      const deployList = fs.readFileSync(`./engine-private/deploy/dd.router`, 'utf8').split(',');
-      let hosts = [];
-      for (const deployId of deployList) {
-        const confServer = loadConfServerJson(`./engine-private/conf/${deployId}/conf.server.json`);
-        hosts = hosts.concat(Object.keys(confServer));
-      }
-      shellExec(`node bin cluster --prom ${hosts.join(',')}`);
-      shellExec(`node bin cluster --grafana`);
-    },
     /**
      * @method cluster
      * @description Deploys a full production/development ready Kubernetes cluster environment including MongoDB,
@@ -2982,21 +2969,24 @@ EOF`);
      * 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
+     * Custom instances come from `--instance-id`. 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.
+     *
+     * Every input is a flag: `--runtime-image` (default `express`), `--deploy-id` (comma-separated, or the `dd` meta
+     * id; unset reads the route table) and `--instance-id` (comma-separated; a template id such as `mmo-server`
+     * selects its whole variant family):
+     *   `node bin run cluster --runtime-image express --deploy-id dd-cyberia --instance-id mmo-server --dev`
+     * @param {string} path - Unused; every input is a flag.
      * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
      * @memberof UnderpostRun
      */
     cluster: async (path = '', options = DEFAULT_OPTION) => {
       const { underpostRoot } = options;
-      const env = options.dev ? 'development' : 'production';
-      const baseCommand = options.dev ? 'node bin' : 'underpost';
+      const env = deployEnvFactory(options);
+      const baseCommand = cli('underpost', { local: true });
       const baseClusterCommand = options.dev ? ' --dev' : '';
       const clusterType = clusterTypeFactory(options, 'kubeadm');
       shellCd(`/home/dd/engine`);
@@ -3004,23 +2994,15 @@ EOF`);
       await timer(5000);
       shellExec(`${baseCommand} cluster${baseClusterCommand} --${clusterType}`);
       await timer(5000);
-      let [runtimeImage, deployList, instanceListId] =
-        path && path.trim() && path.split(',')
-          ? path.split(',')
-          : [
-              'express',
-              fs.readFileSync(`${underpostRoot}/engine-private/deploy/dd.router`, 'utf8').replaceAll(',', '+'),
-              '',
-            ];
+      const runtimeImage = options.runtimeImage || 'express';
+      const instanceListId = options.instanceId || '';
       // 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('+');
+      const deployList = options.deployId ? resolveDeployList(options.deployId) : readDeployRoutes();
+      if (deployList.length === 0) logger.warn('No deploy list provided');
       await timer(5000);
       // --reset-mongodb wipes the retained hostPath volumes before the rollout.
       // This workflow already tore the node down and re-imports every database
@@ -3097,10 +3079,13 @@ EOF`);
         const hostListenResult = etcHostFactory(hosts);
         logger.info(hostListenResult.renderHosts);
       }
-      const version = 'v3.3.0';
+      const version = 'v3.3.76';
       const instanceOptionsFactory = (deployId, instanceId) => ({
         ...options,
         ...clusterContextFactory(clusterType),
+        deployId,
+        instanceId,
+        replicas: options.replicas || 1,
         gatewayApi,
         gatewayBootstrapComplete: true,
         tls: true,
@@ -3147,17 +3132,16 @@ EOF`);
                 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, \
+                node bin app load --env ${env} --args deploy-id=dd-cyberia, \
                 sudo chown -R dd:dd /home/dd/engine/src/client/public/cyberia, \
-                node bin env dd-cyberia ${env}, \
+                node bin app load --env ${env} --args deploy-id=dd-cyberia, \
                 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} client ${deployId} --env ${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
@@ -3260,10 +3244,7 @@ EOF`);
         // 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),
-          );
+          await UnderpostRun.RUNNERS.instance('', instanceOptionsFactory(deployId, instanceId));
         }
       }
       logger.info('[cluster] Ingress stack deployed', {
@@ -3655,6 +3636,10 @@ EOF`);
     /**
      * @method deploy
      * @description Deploys a specified service (identified by `path`) using blue/green strategy, monitors its status, and switches traffic upon readiness.
+     *
+     * The target colour is restarted when it is already deployed, and built and applied when it is not:
+     * between cycles only the routed colour has a Deployment, so its counterpart being absent is the
+     * normal state rather than a precondition.
      * @param {string} path - The input value, identifier, or path for the operation (used as the deployment ID to deploy).
      * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
      * @memberof UnderpostRun
@@ -3662,19 +3647,57 @@ EOF`);
     deploy: async (path, options = DEFAULT_OPTION) => {
       const deployId = path;
       const env = options.dev ? 'development' : 'production';
+      const namespace = options.namespace || 'default';
       const { validVersion } = Underpost.repo.privateConfUpdate(deployId);
       if (!validVersion) throw new Error('Version mismatch');
-      const currentTraffic = Underpost.deploy.getCurrentTraffic(deployId, { namespace: options.namespace, env });
-      const targetTraffic = currentTraffic === 'blue' ? 'green' : 'blue';
+      options = { ...options, gatewayApi: gatewayApiEnabledFactory(options) };
+      const currentTraffic = Underpost.deploy.getCurrentTraffic(deployId, {
+        namespace,
+        env,
+        gatewayApi: options.gatewayApi,
+      });
+      const { targetTraffic, create } = redeployPlanFactory({
+        liveTraffic: currentTraffic,
+        hasDeployment: (colour) =>
+          Underpost.deploy.deploymentExists({ deployment: `${deployId}-${env}-${colour}`, namespace }),
+      });
       const ignorePods = Underpost.kubectl
-        .get(`${deployId}-${env}-${targetTraffic}`, 'pods', options.namespace)
+        .get(`${deployId}-${env}-${targetTraffic}`, 'pods', namespace)
         .map((p) => p.NAME);
 
-      shellExec(`sudo kubectl rollout restart deployment/${deployId}-${env}-${targetTraffic} -n ${options.namespace}`);
+      if (create) {
+        // The target colour having no Deployment is the steady state of a
+        // blue/green cycle, not a missing prerequisite: build that colour's
+        // manifest and apply it, leaving the live colour routed until the
+        // promotion below.
+        const replicas = options.replicas || 1;
+        const node =
+          (currentTraffic
+            ? Underpost.deploy.deploymentNode({ deployment: `${deployId}-${env}-${currentTraffic}`, namespace })
+            : '') || options.nodeName;
+        logger.info('Target traffic colour is not deployed; creating it', {
+          deployId,
+          env,
+          targetTraffic,
+          node: node || '(unpinned)',
+        });
+        const deployFlags =
+          ` --versions ${targetTraffic} --replicas ${replicas} --namespace ${namespace}${node ? ` --node ${node}` : ''}` +
+          `${options.image ? ` --image ${options.image}` : ''}` +
+          `${Underpost.deploy.timeoutFlagsFactory(options)}${options.imagePullPolicy ? ` --image-pull-policy ${options.imagePullPolicy}` : ''}` +
+          `${Underpost.deploy.gatewayApiFlagsFactory(options)}`;
+        // `--build-manifest` returns before any cluster mutation, so the colour is
+        // rendered first and applied by the second call. `--traffic` keeps the
+        // generated traffic Service on the colour still serving.
+        shellExec(
+          `node bin deploy --build-manifest --info-router --traffic ${currentTraffic || targetTraffic}${deployFlags} ${deployId} ${env}`,
+        );
+        shellExec(`node bin deploy --disable-update-proxy${deployFlags} ${deployId} ${env}`);
+      } else shellExec(`sudo kubectl rollout restart deployment/${deployId}-${env}-${targetTraffic} -n ${namespace}`);
 
-      await Underpost.monitor.monitorReadyRunner(deployId, env, targetTraffic, ignorePods, options.namespace);
+      await Underpost.monitor.monitorReadyRunner(deployId, env, targetTraffic, ignorePods, namespace);
 
-      Underpost.deploy.switchTraffic(deployId, env, targetTraffic, options.replicas, options.namespace, options);
+      Underpost.deploy.switchTraffic(deployId, env, targetTraffic, options.replicas, namespace, options);
     },
 
     /**
@@ -3764,7 +3787,10 @@ EOF`);
         }`;
         shellExec(cmd, { async: true });
       }
-      if ((await awaitDeployMonitor()) !== true) return;
+      // A bare `return` here exited 0, so a runtime that latched `container-status=error` looked
+      // like a clean start to everything upstream — the shell, and any CI job wrapping it.
+      if ((await awaitDeployMonitor()) !== true)
+        throw new Error(`[run dev] ${deployId} api runtime reported ${RUNTIME_STATUS.ERROR}; see the logs above`);
       {
         const cmd = `npm run dev:client ${deployId} ${subConf} ${host} ${_path} proxy${options.tls ? ' tls' : ''}`;
 
@@ -3772,7 +3798,8 @@ EOF`);
           async: true,
         });
       }
-      if ((await awaitDeployMonitor()) !== true) return;
+      if ((await awaitDeployMonitor()) !== true)
+        throw new Error(`[run dev] ${deployId} client runtime reported ${RUNTIME_STATUS.ERROR}; see the logs above`);
       shellExec(
         `NODE_ENV=development node src/proxy proxy ${deployId} ${subConf} ${host} ${_path}${options.tls ? ' tls' : ''}`,
       );
@@ -3787,7 +3814,7 @@ EOF`);
      */
     service: async (path = '', options = DEFAULT_OPTION) => {
       const env = options.dev ? 'development' : 'production';
-      const baseCommand = options.dev ? 'node bin' : 'underpost';
+      const baseCommand = cli('underpost', { local: true });
       const baseClusterCommand = options.dev ? ' --dev' : '';
       shellCd(`/home/dd/engine`);
       let [deployId, serviceId, host, _path, replicas, image, node] = path.split(',');
@@ -3836,9 +3863,9 @@ EOF`);
       );
       switch (serviceId) {
         case 'mongo-express-service': {
-          shellExec(`kubectl delete svc mongo-express-service -n ${options.namespace} --ignore-not-found`);
-          shellExec(`kubectl delete deployment mongo-express -n ${options.namespace} --ignore-not-found`);
-          shellExec(`kubectl apply -f manifests/deployment/mongo-express/deployment.yaml -n ${options.namespace}`);
+          // One deploy path for the client, shared with `cluster --mongo-express`: the secret,
+          // the auth-mode overlay selection and the readiness wait live there.
+          await MongoExpress.deploy({ namespace: options.namespace, options });
           podToMonitor = 'mongo-express';
           break;
         }
@@ -3892,26 +3919,6 @@ EOF`);
       logger.info(hostListenResult.renderHosts);
     },
 
-    /**
-     * @method sh
-     * @description Enables remote control for the Kitty terminal emulator.
-     * @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
-     */
-    sh: async (path = '', options = DEFAULT_OPTION) => {
-      let [operator, arg0, arg1] = path.split(',');
-      if (operator == 'copy') {
-        shellExec(
-          `kitty @ get-text ${arg0 === 'all' ? '--match all' : '--self'} --extent all${
-            arg1 === 'ansi' ? ' --ansi yes' : ''
-          } | kitty +kitten clipboard`,
-        );
-        return;
-      }
-      shellExec(`kitty -o allow_remote_control=yes`);
-    },
-
     /**
      * @method log
      * @description Searches and highlights keywords in a specified log file, optionally showing surrounding lines.
@@ -3970,28 +3977,44 @@ EOF`);
 
       // Services
       logger.info('Process info');
-      shellExec(`sudo ps -p ${pid} -o pid,ppid,user,stime,etime,cmd`);
+      shellExec(`sudo ps -p ${pid} -o pid,ppid,user,stime,etime,cmd`, {
+        silentOnError: true,
+      });
       logger.info('Command line');
-      shellExec(`sudo cat /proc/${pid}/cmdline | tr '\\0' ' ' ; echo`);
+      shellExec(`sudo cat /proc/${pid}/cmdline | tr '\\0' ' ' ; echo`, {
+        silentOnError: true,
+      });
       logger.info('Executable path');
       shellExec(`sudo readlink -f /proc/${pid}/exe`);
       logger.info('Working directory');
-      shellExec(`sudo readlink -f /proc/${pid}/cwd`);
+      shellExec(`sudo readlink -f /proc/${pid}/cwd`, {
+        silentOnError: true,
+      });
       logger.info('Environment variables (first 200)');
-      shellExec(`sudo tr '\\0' '\\n' </proc/${pid}/environ | head -200`);
+      shellExec(`sudo tr '\\0' '\\n' </proc/${pid}/environ | head -200`, {
+        silentOnError: true,
+      });
 
       // Parent
       logger.info('Parent process');
-      const parentInfo = shellExec(`sudo ps -o pid,ppid,user,cmd -p ${pid}`, { stdout: true, silent: true });
+      const parentInfo = shellExec(`sudo ps -o pid,ppid,user,cmd -p ${pid}`, {
+        stdout: true,
+        silent: true,
+        silentOnError: true,
+      });
       console.log(parentInfo);
       const ppidMatch = parentInfo.split('\n').find((l) => l.trim().startsWith(pid));
       if (ppidMatch) {
         const ppid = ppidMatch.trim().split(/\s+/)[1];
         logger.info(`Parent PID: ${ppid}`);
-        shellExec(`ps -fp ${ppid}`);
+        shellExec(`ps -fp ${ppid}`, {
+          silentOnError: true,
+        });
       }
       logger.info('Process tree');
-      shellExec(`pstree -s ${pid}`);
+      shellExec(`pstree -s ${pid}`, {
+        silentOnError: true,
+      });
     },
 
     /**
@@ -4036,7 +4059,7 @@ EOF`);
     'deploy-test': async (path, options = DEFAULT_OPTION) => {
       // Note: use recomendation empty deploy cluster: node bin --dev cluster
       const env = options.dev ? 'development' : 'production';
-      const baseCommand = options.dev ? 'node bin' : 'underpost';
+      const baseCommand = cli('underpost', { local: true });
       const baseClusterCommand = options.dev ? ' --dev' : '';
       const inputs = path ? path.split(',') : [];
       const deployId = inputs[0] ? inputs[0] : 'dd-test';
@@ -4045,10 +4068,12 @@ EOF`);
         : [
             `npm install -g npm@11.2.0`,
             `npm install -g underpost`,
-            `${baseCommand} secret underpost --create-from-env`,
+            `${baseCommand} host load`,
             `${baseCommand} start --build --run ${deployId} ${env}`,
           ];
-      shellExec(`node bin run sync${baseClusterCommand} --deploy-id-cron-jobs none dd-test --cmd "${cmd}"`);
+      shellExec(
+        `node bin run sync${baseClusterCommand} --deploy-id-cron-jobs none --deploy-id dd-test --cmd ${shellArgumentFactory(cmd)}`,
+      );
     },
 
     /**
@@ -4179,26 +4204,7 @@ EOF`);
 
       shellCd('/home/dd/engine');
     },
-    /**
-     * @method pull-rocky-image
-     * @description Pulls the base `rockylinux:9` image from Docker Hub via Podman.
-     * @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
-     */
-    'pull-rocky-image': (path, options = DEFAULT_OPTION) => {
-      shellExec(`sudo podman pull docker.io/library/rockylinux:9`);
-    },
-    /**
-     * @method rmi
-     * @description Forces the removal of all local Podman images (`podman rmi $(podman images -qa) --force`).
-     * @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
-     */
-    rmi: (path, options = DEFAULT_OPTION) => {
-      shellExec(`podman rmi $(podman images -qa) --force`);
-    },
+
     /**
      * @method kill
      * @description Kills processes listening on the specified port(s). If the `path` contains a `+`, it treats it as a range of ports to kill.
@@ -4244,333 +4250,6 @@ EOF`);
       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.
-     * @param {string} path - The input value, identifier, or path for the operation (used as the optional path to the secret file).
-     * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
-     * @memberof UnderpostRun
-     */
-    secret: (path, options = DEFAULT_OPTION) => {
-      const cronDeployId = cronDeployIdResolve() || 'dd-cron';
-      Underpost.secret.underpost.createFromEnvFile(
-        `/home/dd/engine/engine-private/conf/${cronDeployId}/.env.${options.dev ? 'development' : 'production'}`,
-      );
-    },
-    /**
-     * @method underpost-config
-     * @description Calls `Underpost.deploy.configMap` to create a Kubernetes ConfigMap, defaulting to the 'production' environment.
-     * @param {string} path - The input value, identifier, or path for the operation (used as the optional configuration name/environment).
-     * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
-     * @memberof UnderpostRun
-     */
-    'underpost-config': (path = '', options = DEFAULT_OPTION) => {
-      Underpost.deploy.configMap(path ? path : 'production', options.namespace);
-    },
     /**
      * @method gpu-env
      * @description Sets up a dedicated GPU development environment cluster, resetting and then setting up the cluster with `--dedicated-gpu` and monitoring the pods.
@@ -4666,7 +4345,7 @@ UNDERPOST_SOPS_ENV_EOF`,
           ? 'Directory'
           : 'File';
 
-      const envs = Underpost.env.list();
+      const envs = Underpost.host.store.list();
 
       const cmd = `kubectl apply -f - <<'EOF'
 apiVersion: ${apiVersion}
@@ -4732,186 +4411,47 @@ EOF`;
 
     /**
      * @method push-bundle
-     * @description Builds the client zip for the specified deployment, splits it into parts, and uploads to file storage.
-     *   Steps: set env, build+split zip, upload only the zip parts belonging to the deploy-id's hosts (from conf.server.json).
-     *   Only files matching `<host>-<route>.zip.part*` or `<host>-<route>.zip` for each non-skipped route are uploaded.
-     * @param {string} path - Optional `fsPath.splitOption` string.
-     *   Examples: `build` (default split 8), `build.16` (split 16 MB), `build.none-split` (no split flag).
+     * @description Builds the deployment's client bundles and uploads them to file storage.
+     *   Steps: set env, build and split the zips, then upload each resolved route's artifacts
+     *   under the deployment's `storage.bundle.json`. Routes the client build skips — redirects,
+     *   rebuild-disabled routes, and `singleReplica` routes that carry their own deploy id —
+     *   produce no bundle and are not pushed.
+     * @param {string} path - Optional comma-separated host filter (e.g. 'a.com' or 'a.com,b.com').
+     *   Empty selects every host in `engine-private/conf/<deployId>/conf.server.json`.
      * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow.
-     * @param {string} [options.deployId] - Override deploy ID.
+     * @param {string} [options.deployId] - Deploy ID for storage lookup (defaults to 'dd-default').
+     * @param {string} [options.split] - Zip part size in MB, or 'none' to upload one zip. Defaults to 8.
      * @param {boolean} [options.dev] - Use development environment; defaults to production.
      * @memberof UnderpostRun
      */
-    'push-bundle': (path = '', options = DEFAULT_OPTION) => {
-      const baseCommand = 'node bin'; // options.dev ? 'node bin' : 'underpost';
-      const env = options.dev ? 'development' : 'production';
-      const deployId = options.deployId || 'dd-default';
-      const pathParts = (path || '').split('.');
-      const fsPath = (pathParts[0] || '').trim() || 'build';
-      const splitOption = (pathParts[1] || '').trim();
-
-      let splitFlag = '--split 8';
-      if (splitOption) {
-        if (splitOption === 'none-split') {
-          splitFlag = '';
-        } else {
-          const splitMb = Number(splitOption);
-          if (Number.isFinite(splitMb) && splitMb > 0) {
-            splitFlag = `--split ${splitMb}`;
-          } else {
-            logger.warn('push-bundle: invalid split option, using default split 8', {
-              path,
-              splitOption,
-            });
-          }
-        }
-      }
-
-      const confServerPath = `./engine-private/conf/${deployId}/conf.server.json`;
-      const confServer = fs.existsSync(confServerPath)
-        ? loadReplicas(deployId, loadConfServerJson(confServerPath))
-        : {};
-      const storageFilePath = `engine-private/conf/${deployId}/storage.bundle.json`;
-
-      shellExec(`${baseCommand} env ${deployId} ${env}`);
-      shellExec(`${baseCommand} client ${deployId} --build-zip${splitFlag ? ` ${splitFlag}` : ''}`);
-
-      const pushBundleFiles = (host, routePath) => {
-        const buildId = `${host}-${routePath.replaceAll('/', '')}`;
-        const buildDir = `./${fsPath}`;
-        if (!fs.existsSync(buildDir)) return;
-        const partFiles = fs
-          .readdirSync(buildDir)
-          .filter(
-            (name) =>
-              name.startsWith(`${buildId}.zip.part`) ||
-              name.startsWith(`${buildId}.zip-part`) ||
-              name === `${buildId}.zip`,
-          )
-          .map((name) => `${fsPath}/${name}`);
-        if (partFiles.length === 0) {
-          logger.warn(`push-bundle: no bundle files found for '${host}${routePath}'`, { buildId });
-          return;
-        }
-        for (const partFile of partFiles) {
-          shellExec(
-            `${baseCommand} fs ${partFile} --deploy-id ${deployId} --storage-file-path ${storageFilePath} --force`,
-          );
-        }
-      };
-
-      for (const host of Object.keys(confServer)) {
-        for (const routePath of Object.keys(confServer[host])) {
-          const routeConf = confServer[host][routePath] || {};
-          if (routeConf.redirect || routeConf.disabledRebuild) continue;
-          if (routeConf.singleReplica) {
-            if (routeConf.replicas) {
-              for (const replica of routeConf.replicas) {
-                pushBundleFiles(host, replica);
-              }
-            }
-            continue;
-          }
-          pushBundleFiles(host, routePath);
-        }
-      }
-    },
+    'push-bundle': (path = '', options = DEFAULT_OPTION) =>
+      pushClientBundle({
+        deployId: options.deployId || 'dd-default',
+        hosts: clientBundleHostFilter(path),
+        split: options.split,
+        dev: options.dev,
+      }),
 
     /**
      * @method pull-bundle
-     * @description Downloads split zip parts from file storage, merges and extracts them, and moves the result into the public directory.
-     *   Steps: set env, download parts (omit-unzip), merge zip, unzip, remove zip + parts, move to public/<host>[/path].
-     *   Iterates over every non-singleReplica, non-redirect, non-disabledRebuild route in conf.server.json
-     *   so that multi-path deployments are handled correctly.
-     * @param {string} path - Optional comma-separated host name(s) to restrict processing (e.g. 'underpost.net' or 'a.com,b.com').
-     *   If omitted, all hosts from `engine-private/conf/<deployId>/conf.server.json` are used.
+     * @description Downloads the deployment's client bundles from file storage and installs them
+     *   into the served public directory.
+     *   Steps: set env, download the parts, merge and extract each resolved route's zip, then
+     *   replace `public/<host>[<route>]` with the extracted tree. Route selection matches
+     *   push-bundle, so the two directions always address the same set of bundles.
+     * @param {string} path - Optional comma-separated host filter (e.g. 'a.com' or 'a.com,b.com').
+     *   Empty selects every host in `engine-private/conf/<deployId>/conf.server.json`.
      * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow.
      * @param {string} [options.deployId] - Deploy ID for storage lookup (defaults to 'dd-default').
      * @param {boolean} [options.dev] - Use development environment; defaults to production.
      * @memberof UnderpostRun
      */
-    'pull-bundle': (path = '', options = DEFAULT_OPTION) => {
-      const baseCommand = 'node bin'; // options.dev ? 'node bin' : 'underpost';
-      const env = options.dev ? 'development' : 'production';
-      const deployId = options.deployId || 'dd-default';
-      const confServerPath = `./engine-private/conf/${deployId}/conf.server.json`;
-      const confServer = fs.existsSync(confServerPath)
-        ? loadReplicas(deployId, loadConfServerJson(confServerPath))
-        : {};
-      const hostsArg = path
-        ? path
-            .split(',')
-            .map((h) => h.trim())
-            .filter(Boolean)
-        : Object.keys(confServer);
-
-      if (hostsArg.length === 0) {
-        logger.error('pull-bundle: no hosts resolved', { deployId, path, confServerPath });
-        return;
-      }
-
-      shellExec(`${baseCommand} env ${deployId} ${env}`);
-      if (!fs.existsSync('./build')) fs.mkdirSync('./build', { recursive: true });
-      shellExec(
-        `${baseCommand} fs build --recursive --deploy-id ${deployId} --storage-file-path engine-private/conf/${deployId}/storage.bundle.json --pull --omit-unzip`,
-      );
-
-      const pullBundleRoute = (host, routePath) => {
-        const buildId = `${host}-${routePath.replaceAll('/', '')}`;
-        const zipPath = `build/${buildId}.zip`;
-        const buildDir = './build';
-        const hasZip = fs.existsSync(zipPath);
-        const hasParts =
-          fs.existsSync(buildDir) &&
-          fs
-            .readdirSync(buildDir)
-            .some((name) => name.startsWith(`${buildId}.zip.part`) || name.startsWith(`${buildId}.zip-part`));
-
-        if (!hasZip && !hasParts) {
-          logger.warn(`Bundle not found for '${host}${routePath}'. Skipping.`, { zipPath, deployId });
-          return;
-        }
-
-        if (hasParts) shellExec(`${baseCommand} client --merge-zip ${zipPath}`);
-        shellExec(`${baseCommand} client --unzip ${zipPath}`);
-        shellExec(`sudo rm -rf ${zipPath}`);
-
-        if (fs.existsSync(buildDir)) {
-          fs.readdirSync(buildDir)
-            .filter((name) => name.startsWith(`${buildId}.zip.part`) || name.startsWith(`${buildId}.zip-part`))
-            .forEach((partFile) => shellExec(`sudo rm -rf ${buildDir}/${partFile}`));
-        }
-
-        const extractedDir = `build/${buildId.replace(/-$/, '')}`;
-        if (!fs.existsSync(extractedDir)) {
-          logger.warn(`Extracted build dir not found: ${extractedDir}. Skipping move for '${host}${routePath}'.`);
-          return;
-        }
-
-        const publicDestPath = routePath === '/' ? `public/${host}` : `public/${host}${routePath}`;
-        if (fs.existsSync(publicDestPath)) shellExec(`sudo rm -rf ${publicDestPath}`);
-        if (routePath !== '/') shellExec(`sudo mkdir -p public/${host}`);
-        fs.copySync(`${extractedDir}`, `${publicDestPath}`);
-      };
-
-      for (const host of hostsArg) {
-        const routePaths = confServer[host] ? Object.keys(confServer[host]) : ['/'];
-
-        for (const routePath of routePaths) {
-          const routeConf = confServer[host] ? confServer[host][routePath] || {} : {};
-          if (routeConf.redirect || routeConf.disabledRebuild) continue;
-          if (routeConf.singleReplica) {
-            if (routeConf.replicas) {
-              for (const replica of routeConf.replicas) {
-                pullBundleRoute(host, replica);
-              }
-            }
-            continue;
-          }
-          pullBundleRoute(host, routePath);
-        }
-      }
-    },
+    'pull-bundle': async (path = '', options = DEFAULT_OPTION) =>
+      await pullClientBundle({
+        deployId: options.deployId || 'dd-default',
+        hosts: clientBundleHostFilter(path),
+        dev: options.dev,
+      }),
 
     /**
      * @method kubeadm-wireguard
@@ -4935,15 +4475,30 @@ EOF`;
 
     /**
      * @method build-cluster-deployment-manifests
-     * @description Builds deployment manifests for both production and development environments using `node bin deploy --build-manifest`, syncing them, and setting replicas to 1 for the `dd` deployment.
+     * @description Builds deployment manifests for both production and development environments using `underpost deploy --build-manifest`, syncing them, and setting replicas to 1 for the `dd` deployment. Runs under `HERMETIC_BUILD`, so it needs no reachable cluster.
      * @param {string} path - Unused.
      * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow.
      * @memberof UnderpostRun
      */
-    'build-cluster-deployment-manifests': (path = '', options = DEFAULT_OPTION) => {
-      shellExec(`node bin deploy --build-manifest --sync --info-router --replicas 1 dd development`);
-      shellExec(`node bin deploy --build-manifest --sync --info-router --replicas 1 dd production --cert`);
-    },
+    'build-cluster-deployment-manifests': (path = '', options = DEFAULT_OPTION) =>
+      // Manifest generation writes files; it does not touch a cluster. Declaring that once
+      // here is what lets the whole tree below run on a build box with no apiserver — the
+      // profile rides into both child processes through the environment.
+      withExecutionProfile('HERMETIC_BUILD', async () => {
+        // Each deploy's package manifest is generated from the engine's before the cluster
+        // manifests that ship it: a deploy id declares only its identity and whatever its
+        // catalog adds, so a dependency the engine gained reaches every deploy from here.
+        await syncDeployPackages();
+        // `local` is load-bearing: this builds the manifests of the checkout it was
+        // launched from, and a globally installed underpost is a different package that
+        // reads different paths out of the same cwd.
+        const underpost = cli('underpost', { local: true });
+        const flags = '--build-manifest --sync --info-router --replicas 1';
+        shellExec(`${underpost} deploy ${flags} dd development`);
+        shellExec(`${underpost} deploy ${flags} dd production --cert`);
+        // What the build just produced is what the project repository carries.
+        if (deployRoutesExists()) Underpost.deploy.mirrorDefaultManifests();
+      }),
 
     /**
      * @method monitor-ui
@@ -5083,7 +4638,7 @@ EOF`;
         const result = await Underpost.run.CALL(runner, path, options);
         return result;
       } catch (error) {
-        console.log(error);
+        console.error(error);
         logger.error(error);
         process.exit(1);
       }