underpost 3.2.28 → 3.2.30

package/CHANGELOG.md

@@ -1,6 +1,46 @@
 # Changelog
 
-## 2026-06-23
+## 2026-06-25
+
+### server
+
+- Add only build client in development mode in normal server run start up ([a332ae458](https://github.com/underpostnet/engine/commit/a332ae458f79458c7911a4a158037ada250d3af6))
+
+### cli-start
+
+- Add start-container-status in start pipeline to insulate readinessProbe monitor server status, prevent external overwritten status ([75f67cf3f](https://github.com/underpostnet/engine/commit/75f67cf3fcbc07716415caac4e67ab91abb05985))
+
+### cyberia-cli
+
+- Enhance cyberia-saga variety theme separate custom prompt of random subject theme ([1945a2553](https://github.com/underpostnet/engine/commit/1945a2553780d1d3b5fa20e40eedcc7d0b1ecd9c))
+- Enhance cyberia-saga variety theme handle and prompt seed customization ([a335d3e20](https://github.com/underpostnet/engine/commit/a335d3e20025f8e714ff98fdc27d7895970187b5))
+
+### db
+
+- Improve wait status ready mongo pods in bootstrap methods ([6805e35c2](https://github.com/underpostnet/engine/commit/6805e35c22e43315c14dc9e7457ca3d599877ea8))
+
+### cli-env
+
+- Add keepKeys array options in clean env method ([5b3be0bca](https://github.com/underpostnet/engine/commit/5b3be0bca14a0ccfa64740aff12d2af17a7c29ce))
+
+### repository
+
+- Add getRemoteUrl and switchRemote repository methods in repository cli ([0412b9986](https://github.com/underpostnet/engine/commit/0412b998683a8369833eb363f8c9953744ae1a3a))
+
+### deploy
+
+- Enhance node customization in default deployment and custom instance workloads ([31c6b6d3b](https://github.com/underpostnet/engine/commit/31c6b6d3b397229b0216f82b8aef29b6941e474e))
+- Fix node affinity assignment in volume mount factory ([9ec1ef931](https://github.com/underpostnet/engine/commit/9ec1ef9313ac0dbb5993cd3f158d2d01eae7dec5))
+
+### cli-run
+
+- Add flag ssh key path to customize key usage for ssh operations in deployments pipelines ([861cd7373](https://github.com/underpostnet/engine/commit/861cd73734d3442783419af4403bbb8e88711f19))
+
+### start-cli
+
+- Improve underpost container status persistence ([bff2e8f8d](https://github.com/underpostnet/engine/commit/bff2e8f8d65c6a2fe8572fe0bc9c42b9566db918))
+
+## New release v:3.2.28 (2026-06-23)
 
 ### hardhat
 

package/CLI-HELP.md

@@ -1,6 +1,6 @@
 ## Underpost CLI
 
-> underpost ci/cd cli v3.2.28
+> underpost ci/cd cli v3.2.30
 
 **Usage:** `underpost [options] [command]`
 
@@ -222,6 +222,9 @@ Manages commits to a GitHub repository, supporting various commit types and opti
 | `--bc <commit-hash>` | Shows branches that contain the specified commit. |
 | `--is-remote-repo <url-repo>` | Checks whether a remote Git repository URL is reachable. Prints true or false. |
 | `--has-changes` | Prints "1" if there are staged or unstaged git changes in the repository, empty string otherwise. |
+| `--remote-url` | Prints the current git remote URL (origin) in plain text. |
+| `--switch-repo <url>` | Switches the git remote (origin) to <url> and force-pulls the target branch, overwriting the current working tree (discards local commits and tracked changes). Accepts a full URL or "owner/repo". |
+| `--target-branch <branch>` | Target branch for --switch-repo (default: master). |
 | `-h, --help` | display help for command |
 
 ---
@@ -467,6 +470,7 @@ Manages application deployments, defaulting to deploying development pods.
 | `--cert-hosts <hosts>` | Resets TLS/SSL certificate secrets for specified hosts. |
 | `--self-signed` | Use a pre-created self-signed TLS secret (kubernetes.io/tls) instead of cert-manager. The secret must already exist in the namespace with the same name as the host. Enables TLS in the Contour HTTPProxy virtualhost without requiring a production ClusterIssuer. |
 | `--node <node>` | Sets optional node for deployment operations. |
+| `--ssh-key-path <path>` | Private key path for node SSH operations. Currently used when shipping a hostPath volume to a remote target node over SSH. Defaults to engine-private/deploy/id_rsa. |
 | `--build-manifest` | Builds Kubernetes YAML manifests, including deployments, services, proxies, and secrets. |
 | `--replicas <replicas>` | Sets a custom number of replicas for deployments. |
 | `--image <image>` | Sets a custom image for deployments. |
@@ -830,6 +834,7 @@ Runs specified scripts using various runners.
 | `--replicas <replicas>` | Sets a custom number of replicas for deployment. |
 | `--pod-name <pod-name>` | Optional: Specifies the pod name for execution. |
 | `--node-name <node-name>` | Optional: Specifies the node name for execution. |
+| `--ssh-key-path <path>` | Optional: Private key path for node SSH operations, forwarded to volume shipping over SSH. Defaults to engine-private/deploy/id_rsa. |
 | `--port <port>` | Optional: Specifies the port for execution. |
 | `--etc-hosts` | Enables etc-hosts context for the runner execution. |
 | `--volume-host-path <volume-host-path>` | Optional: Specifies the volume host path for test execution. |

package/README.md

@@ -16,7 +16,7 @@
 
 <div align="center">
 
-[![Node.js CI](https://github.com/underpostnet/engine/actions/workflows/docker-image.ci.yml/badge.svg?branch=master)](https://github.com/underpostnet/engine/actions/workflows/docker-image.ci.yml) [![Test](https://github.com/underpostnet/engine/actions/workflows/coverall.ci.yml/badge.svg?branch=master)](https://github.com/underpostnet/engine/actions/workflows/coverall.ci.yml) [![Downloads](https://img.shields.io/npm/dm/underpost.svg)](https://www.npmjs.com/package/underpost) [![](https://data.jsdelivr.com/v1/package/npm/underpost/badge)](https://www.jsdelivr.com/package/npm/underpost) [![Socket Badge](https://socket.dev/api/badge/npm/package/underpost/3.2.28)](https://socket.dev/npm/package/underpost/overview/3.2.28) [![Coverage Status](https://coveralls.io/repos/github/underpostnet/engine/badge.svg?branch=master)](https://coveralls.io/github/underpostnet/engine?branch=master) [![Version](https://img.shields.io/npm/v/underpost.svg)](https://www.npmjs.org/package/underpost) [![License](https://img.shields.io/npm/l/underpost.svg)](https://www.npmjs.com/package/underpost)
+[![Node.js CI](https://github.com/underpostnet/engine/actions/workflows/docker-image.ci.yml/badge.svg?branch=master)](https://github.com/underpostnet/engine/actions/workflows/docker-image.ci.yml) [![Test](https://github.com/underpostnet/engine/actions/workflows/coverall.ci.yml/badge.svg?branch=master)](https://github.com/underpostnet/engine/actions/workflows/coverall.ci.yml) [![Downloads](https://img.shields.io/npm/dm/underpost.svg)](https://www.npmjs.com/package/underpost) [![](https://data.jsdelivr.com/v1/package/npm/underpost/badge)](https://www.jsdelivr.com/package/npm/underpost) [![Socket Badge](https://socket.dev/api/badge/npm/package/underpost/3.2.30)](https://socket.dev/npm/package/underpost/overview/3.2.30) [![Coverage Status](https://coveralls.io/repos/github/underpostnet/engine/badge.svg?branch=master)](https://coveralls.io/github/underpostnet/engine?branch=master) [![Version](https://img.shields.io/npm/v/underpost.svg)](https://www.npmjs.org/package/underpost) [![License](https://img.shields.io/npm/l/underpost.svg)](https://www.npmjs.com/package/underpost)
 
 </div>
 
@@ -88,7 +88,7 @@ npm run dev
 <!-- cli-index-start -->
 ## Underpost CLI
 
-> underpost ci/cd cli v3.2.28
+> underpost ci/cd cli v3.2.30
 
 **Usage:** `underpost [options] [command]`
 

package/manifests/cronjobs/dd-cron/dd-cron-backup.yaml

@@ -23,7 +23,7 @@ spec:
         spec:
           containers:
             - name: dd-cron-backup
-              image: underpost/underpost-engine:v3.2.28
+              image: underpost/underpost-engine:v3.2.30
               command:
                 - /bin/sh
                 - -c

package/manifests/cronjobs/dd-cron/dd-cron-dns.yaml

@@ -23,7 +23,7 @@ spec:
         spec:
           containers:
             - name: dd-cron-dns
-              image: underpost/underpost-engine:v3.2.28
+              image: underpost/underpost-engine:v3.2.30
               command:
                 - /bin/sh
                 - -c

package/manifests/deployment/dd-default-development/deployment.yaml

@@ -17,7 +17,7 @@ spec:
     spec:
       containers:
         - name: dd-default-development-blue
-          image: underpost/underpost-engine:v3.2.28
+          image: underpost/underpost-engine:v3.2.30
           #          resources:
           #            requests:
           #              memory: "124Ki"
@@ -98,7 +98,7 @@ spec:
     spec:
       containers:
         - name: dd-default-development-green
-          image: underpost/underpost-engine:v3.2.28
+          image: underpost/underpost-engine:v3.2.30
           #          resources:
           #            requests:
           #              memory: "124Ki"

package/package.json

@@ -2,7 +2,7 @@
     "type": "module",
     "main": "src/index.js",
     "name": "underpost",
-    "version": "3.2.28",
+    "version": "3.2.30",
     "description": "Underpost Platform — end-to-end CI/CD and application-delivery toolchain CLI. Covers bare metal, Kubernetes, K3s, kubeadm, LXD, container/image orchestration, secrets, databases, cron jobs, monitoring, SSH, runners, PWA + Workbox delivery, and release orchestration. Extensible via downstream CLIs.",
     "scripts": {
         "start": "node --max-old-space-size=8192 src/server",

package/scripts/test-monitor.sh

@@ -2,9 +2,7 @@
 #
 # test-monitor.sh — end-to-end deploy + two-phase monitor smoke test.
 #
-# Two deployment shapes are supported (see
-# src/client/public/nexodev/docs/references/Deploy-Monitor-PRD.md and
-# 'Deploy custom instance to K8S.md'):
+# Two deployment shapes are supported:
 #
 #   --mode runtime   `underpost start` deploy (e.g. dd-test). Monitored with the
 #                    HTTP gate: /_internal/ready probes + port-forward status.
@@ -26,11 +24,11 @@ MODE=runtime                                  # runtime | instance
 ENV=development                               # development | production
 DEPLOY_ID=dd-test                             # deploy id (instance mode: parent of conf.instances.json)
 INSTANCE_IDS=                                 # instance mode: csv of ids (default: all in conf.instances.json)
-IMAGE=underpost/wp:v3.2.14                    # runtime mode image (instance mode reads image from conf)
+IMAGE=underpost/wp:v3.2.30                    # runtime mode image (instance mode reads image from conf)
 VERSIONS=green                                # csv of blue/green versions
 REPLICAS=1                                    # replicas per deployment
 NAMESPACE=default                             # k8s namespace
-CLUSTER=                                      # kind | kubeadm | k3s | "" (auto/none)
+CLUSTER=kind                                  # kind | kubeadm | k3s | "" (auto/none)
 TIMEOUT_RESPONSE=300000ms                     # HTTPProxy per-route response timeout
 TEMPLATE_REPO=underpostnet/pwa-microservices-template-private  # runtime mode link repo
 ENVOY_NAMESPACE=projectcontour                # ingress namespace (instance TLS exposure)

package/src/cli/deploy.js

@@ -383,6 +383,10 @@ spec:
      * @param {string} [options.imagePullPolicy] - Container imagePullPolicy override (`Always`, `IfNotPresent`, `Never`); forwarded to deploymentYamlPartsFactory. Defaults to `Never` for `localhost/` images and `IfNotPresent` otherwise.
      * @param {boolean} [options.disableRuntimeProbes] - Omit internal-status HTTP probes from generated manifests. When true no readiness/liveness/startup probes are emitted.
      * @param {boolean} [options.tcpProbes] - Emit legacy TCP socket probes instead of HTTP internal-status probes (migration path).
+     * @param {string} [options.node] - Explicit target node for hostPath PV nodeAffinity pinning; resolved through {@link UnderpostDeploy.resolveDeployNode} together with the cluster flags.
+     * @param {boolean} [options.kind] - Kind cluster context; affects the cluster-type node default when no explicit node is set.
+     * @param {boolean} [options.kubeadm] - Kubeadm cluster context; affects the cluster-type node default when no explicit node is set.
+     * @param {boolean} [options.k3s] - K3s cluster context; affects the cluster-type node default when no explicit node is set.
      * @returns {Promise<void>} - Promise that resolves when the manifest is built.
      * @memberof UnderpostDeploy
      */
@@ -455,6 +459,15 @@ ${Underpost.deploy
           ? JSON.parse(fs.readFileSync(`./engine-private/conf/${deployId}/conf.volume.json`, 'utf8'))
           : [];
         if (confVolume.length > 0) {
+          // Mirror deployVolume's data-node resolution so the generated manifest
+          // pins the PV to the same node that physically receives the volume data.
+          const pvDataNode = Underpost.deploy.resolveDeployNode({
+            node: options.node,
+            kind: options.kind,
+            kubeadm: options.kubeadm,
+            k3s: options.k3s,
+            env,
+          });
           let volumeYaml = '';
           for (const deploymentVersion of deploymentVersions) {
             for (const volume of confVolume) {
@@ -466,6 +479,7 @@ ${Underpost.deploy
                 pvcId,
                 namespace: options.namespace,
                 hostPath,
+                nodeName: pvDataNode,
               })}\n`;
             }
           }
@@ -720,7 +734,8 @@ spec:
      * @param {string} options.image - Docker image for the deployment.
      * @param {string} options.traffic - Traffic status for the deployment.
      * @param {string} options.replicas - Number of replicas for the deployment.
-     * @param {string} options.node - Node name for resource allocation.
+     * @param {string} options.node - Explicit target node (highest precedence in the node chain). When empty, {@link UnderpostDeploy.resolveDeployNode} falls back to the cluster-type default (`kind-worker` for kind, host for kubeadm/k3s). Used for both volume placement and hostPath PV nodeAffinity.
+     * @param {string} [options.sshKeyPath] - Private key path for node SSH operations, forwarded to deployVolume when shipping a hostPath volume to a remote target node over SSH. Defaults to engine-private/deploy/id_rsa.
      * @param {boolean} options.disableUpdateDeployment - Whether to disable deployment updates.
      * @param {boolean} options.disableUpdateProxy - Whether to disable proxy updates.
      * @param {boolean} options.disableDeploymentProxy - Whether to disable deployment proxy.
@@ -938,9 +953,16 @@ EOF`);
                   env,
                   version,
                   namespace,
-                  nodeName: options.node ? options.node : env === 'development' ? 'kind-worker' : os.hostname(),
+                  nodeName: Underpost.deploy.resolveDeployNode({
+                    node: options.node,
+                    kind: options.kind,
+                    kubeadm: options.kubeadm,
+                    k3s: options.k3s,
+                    env,
+                  }),
                   clusterContext: options.k3s ? 'k3s' : options.kubeadm ? 'kubeadm' : 'kind',
                   gitClean: options.gitClean || false,
+                  sshKeyPath: options.sshKeyPath || '',
                 });
           }
 
@@ -1036,6 +1058,37 @@ EOF`);
       Underpost.env.set(`${deployId}-${env}-traffic`, targetTraffic);
     },
 
+    /**
+     * Resolves the effective target node for a deployment, applying a single
+     * precedence chain shared by every deploy workflow — the default `deploy`
+     * callback, `run sync`, and custom `run instance` — so node customization
+     * behaves identically everywhere:
+     *
+     *   1. **Explicit node** — `node` (the resolved `--node` value). Upstream
+     *      runners derive it from the comma-path field or `--node-name`
+     *      (`run sync`: `path.split(',')[4]` > `--node-name` > default) and from
+     *      `--node-name` directly (`run instance`).
+     *   2. **Cluster-type default** — when no explicit node is given: `kind-worker`
+     *      for a kind cluster (the node that hosts kind hostPath volumes),
+     *      otherwise the control-plane / current host (`os.hostname()`) for
+     *      kubeadm / k3s. With no explicit cluster flag, `development` is treated
+     *      as kind and `production` as the host, preserving legacy behaviour.
+     *
+     * @param {object} params
+     * @param {string} [params.node=''] - Explicit node (`--node`); highest precedence.
+     * @param {boolean} [params.kind=false] - Kind cluster context.
+     * @param {boolean} [params.kubeadm=false] - Kubeadm cluster context.
+     * @param {boolean} [params.k3s=false] - K3s cluster context.
+     * @param {string} [params.env=''] - Deployment environment; tie-breaker when no cluster flag is set.
+     * @returns {string} The effective node name.
+     * @memberof UnderpostDeploy
+     */
+    resolveDeployNode({ node = '', kind = false, kubeadm = false, k3s = false, env = '' } = {}) {
+      if (node) return node;
+      const isKind = kind || (!kubeadm && !k3s && env !== 'production');
+      return isKind ? 'kind-worker' : os.hostname();
+    },
+
     /**
      * Deploys a volume for a deployment.
      * @param {object} volume - Volume configuration.
@@ -1047,9 +1100,10 @@ EOF`);
      * @param {string} options.env - Environment for the deployment.
      * @param {string} options.version - Version of the deployment.
      * @param {string} options.namespace - Kubernetes namespace for the deployment.
-     * @param {string} options.nodeName - Node name for the deployment.
+     * @param {string} options.nodeName - Effective target node (already resolved via {@link UnderpostDeploy.resolveDeployNode}). The volume data is written/shipped here and the PV is pinned to it; an empty value falls back to the cluster-type default inside this method.
      * @param {string} [options.clusterContext='kind'] - Cluster context type ('kind', 'kubeadm', or 'k3s').
      * @param {boolean} [options.gitClean=false] - Whether to run git clean on volumeMountPath before copying.
+     * @param {string} [options.sshKeyPath=''] - Private key path used when the target node is remote and the volume is shipped over SSH. Empty falls back to copyDirToNode's default (engine-private/deploy/id_rsa).
      * @memberof UnderpostDeploy
      */
     deployVolume(
@@ -1062,6 +1116,7 @@ EOF`);
         nodeName: '',
         clusterContext: 'kind',
         gitClean: false,
+        sshKeyPath: '',
       },
     ) {
       if (!volume.claimName) {
@@ -1076,16 +1131,48 @@ EOF`);
       if (options.gitClean && volume.volumeMountPath) {
         Underpost.repo.clean({ paths: [volume.volumeMountPath] });
       }
+      // The node that physically receives the volume data. hostPath volumes are
+      // node-local, so the data must land on the node where the pod will run, and
+      // the PV is pinned there (nodeAffinity) so the scheduler co-locates the pod
+      // with its volume — never mounting an empty DirectoryOrCreate on another node.
+      let dataNode;
       if (clusterContext === 'kind') {
         const kindNode = options.nodeName || 'kind-worker';
+        dataNode = kindNode;
         shellExec(`docker exec -i ${kindNode} bash -c "mkdir -p ${rootVolumeHostPath}"`);
         shellExec(`tar -C ${volume.volumeMountPath} -c . | docker cp - ${kindNode}:${rootVolumeHostPath}`);
         shellExec(
           `docker exec -i ${kindNode} bash -c "chown -R 1000:1000 ${rootVolumeHostPath}; chmod -R 755 ${rootVolumeHostPath}"`,
         );
       } else {
-        if (!fs.existsSync(rootVolumeHostPath)) fs.mkdirSync(rootVolumeHostPath, { recursive: true });
-        fs.copySync(volume.volumeMountPath, rootVolumeHostPath);
+        const localHost = os.hostname();
+        dataNode = options.nodeName || localHost;
+        if (dataNode === localHost) {
+          // Target node is the control plane / current host: write directly.
+          if (!fs.existsSync(rootVolumeHostPath)) fs.mkdirSync(rootVolumeHostPath, { recursive: true });
+          fs.copySync(volume.volumeMountPath, rootVolumeHostPath);
+        } else {
+          // Target node is remote: fs.copySync would only write the control-plane
+          // filesystem, leaving the real node's hostPath empty. Ship the folder to
+          // the node over SSH so the data exists where the pod is pinned.
+          const nodeHost =
+            shellExec(
+              `kubectl get node ${dataNode} -o jsonpath='{.status.addresses[?(@.type=="InternalIP")].address}'`,
+              { stdout: true, silent: true, silentOnError: true },
+            ).trim() || dataNode;
+          logger.info('Shipping volume to remote node over SSH', {
+            node: dataNode,
+            host: nodeHost,
+            src: volume.volumeMountPath,
+            dest: rootVolumeHostPath,
+          });
+          Underpost.ssh.copyDirToNode({
+            host: nodeHost,
+            localDir: volume.volumeMountPath,
+            remoteDir: rootVolumeHostPath,
+            ...(options.sshKeyPath ? { keyPath: options.sshKeyPath } : {}),
+          });
+        }
       }
       shellExec(`kubectl delete pvc ${pvcId} -n ${namespace} --ignore-not-found`);
       shellExec(`kubectl delete pv ${pvId} --ignore-not-found`);
@@ -1094,6 +1181,7 @@ ${Underpost.deploy.persistentVolumeFactory({
   hostPath: rootVolumeHostPath,
   pvcId,
   namespace,
+  nodeName: dataNode,
 })}
 EOF
 `);
@@ -1182,11 +1270,28 @@ ${secret ? `          readOnly: true\n` : ''}`;
      * @param {string} options.hostPath - Host path for the persistent volume.
      * @param {string} options.pvcId - Persistent volume claim ID.
      * @param {string} [options.namespace='default'] - Kubernetes namespace for the PVC claimRef.
+     * @param {string} [options.nodeName=''] - Node name to which the persistent volume is pinned (optional).
      * @returns {string} - YAML configuration for the persistent volume and claim.
      * @memberof UnderpostDeploy
      */
-    persistentVolumeFactory({ hostPath, pvcId, namespace = 'default' }) {
+    persistentVolumeFactory({ hostPath, pvcId, namespace = 'default', nodeName = '' }) {
       const pvId = pvcId.replace(/^pvc-/, 'pv-');
+      // hostPath volumes are node-local: deployVolume writes the content to the
+      // filesystem of a single node. Without nodeAffinity the scheduler can place
+      // the pod on a different node and mount an empty DirectoryOrCreate hostPath
+      // (missing the materialized assets). Pin the PV to the node that holds the
+      // data so the pod is always co-located with its volume.
+      const nodeAffinity = nodeName
+        ? `
+  nodeAffinity:
+    required:
+      nodeSelectorTerms:
+        - matchExpressions:
+            - key: kubernetes.io/hostname
+              operator: In
+              values:
+                - ${nodeName}`
+        : '';
       return `apiVersion: v1
 kind: PersistentVolume
 metadata:
@@ -1197,7 +1302,7 @@ spec:
   accessModes:
     - ReadWriteOnce
   persistentVolumeReclaimPolicy: Retain
-  storageClassName: manual
+  storageClassName: manual${nodeAffinity}
   claimRef:
     apiVersion: v1
     kind: PersistentVolumeClaim

package/src/cli/env.js

@@ -143,12 +143,21 @@ class UnderpostRootEnv {
     /**
      * @method clean
      * @description Cleans the underpost root environment by removing the environment file.
+     * @param {object} options - Options for cleaning the environment.
+     * @param {Array<string>} [options.keepKeys=[]] - List of keys to keep in the environment file. If provided, only these keys will be retained.
      * @memberof UnderpostEnv
      */
-    clean() {
+    clean(options = { keepKeys: [] }) {
+      const { keepKeys } = options;
       const exeRootPath = `${getNpmRootPath()}/underpost`;
       const envPath = `${exeRootPath}/.env`;
-      fs.removeSync(envPath);
+      if (keepKeys && keepKeys.length > 0 && fs.existsSync(envPath)) {
+        const env = dotenv.parse(fs.readFileSync(envPath, 'utf8'));
+        const filteredEnv = Object.fromEntries(Object.entries(env).filter(([key]) => keepKeys.includes(key)));
+        writeEnv(envPath, filteredEnv);
+      } else {
+        fs.removeSync(envPath);
+      }
     },
     /**
      * @method isInsideContainer

package/src/cli/index.js

@@ -132,6 +132,12 @@ program
     '--has-changes',
     'Prints "1" if there are staged or unstaged git changes in the repository, empty string otherwise.',
   )
+  .option('--remote-url', 'Prints the current git remote URL (origin) in plain text.')
+  .option(
+    '--switch-repo <url>',
+    'Switches the git remote (origin) to <url> and force-pulls the target branch, overwriting the current working tree (discards local commits and tracked changes). Accepts a full URL or "owner/repo".',
+  )
+  .option('--target-branch <branch>', 'Target branch for --switch-repo (default: master).')
   .description('Manages commits to a GitHub repository, supporting various commit types and options.')
   .action(Underpost.repo.commit);
 
@@ -330,6 +336,10 @@ program
       'Enables TLS in the Contour HTTPProxy virtualhost without requiring a production ClusterIssuer.',
   )
   .option('--node <node>', 'Sets optional node for deployment operations.')
+  .option(
+    '--ssh-key-path <path>',
+    'Private key path for node SSH operations. Currently used when shipping a hostPath volume to a remote target node over SSH. Defaults to engine-private/deploy/id_rsa.',
+  )
   .option(
     '--build-manifest',
     'Builds Kubernetes YAML manifests, including deployments, services, proxies, and secrets.',
@@ -630,6 +640,10 @@ program
   .option('--replicas <replicas>', 'Sets a custom number of replicas for deployment.')
   .option('--pod-name <pod-name>', 'Optional: Specifies the pod name for execution.')
   .option('--node-name <node-name>', 'Optional: Specifies the node name for execution.')
+  .option(
+    '--ssh-key-path <path>',
+    'Optional: Private key path for node SSH operations, forwarded to volume shipping over SSH. Defaults to engine-private/deploy/id_rsa.',
+  )
   .option('--port <port>', 'Optional: Specifies the port for execution.')
   .option('--etc-hosts', 'Enables etc-hosts context for the runner execution.')
   .option('--volume-host-path <volume-host-path>', 'Optional: Specifies the volume host path for test execution.')

package/src/cli/repository.js

@@ -106,6 +106,9 @@ class UnderpostRepository {
      * @param {boolean} [options.changelogBuild=false] - If true, scrapes all git history and builds a full CHANGELOG.md. Commits containing 'New release v:' are used as version section titles. Only commits starting with '[<tag>]' are included as entries.
      * @param {string} [options.changelogMinVersion=''] - If set, overrides the default minimum version limit (2.85.0) for --changelog-build.
      * @param {boolean} [options.changelogNoHash=false] - If true, omits commit hashes from the changelog entries.
+     * @param {boolean} [options.remoteUrl=false] - If true, prints the current git remote URL (origin) in plain text and returns.
+     * @param {string} [options.switchRepo=''] - If set, switches the remote `origin` to this URL and force-pulls the target branch, overwriting the current working tree.
+     * @param {string} [options.targetBranch=''] - Target branch for `switchRepo` (defaults to `master`).
      * @memberof UnderpostRepository
      */
     commit(
@@ -135,6 +138,9 @@ class UnderpostRepository {
         bc: '',
         isRemoteRepo: '',
         hasChanges: false,
+        remoteUrl: false,
+        switchRepo: '',
+        targetBranch: '',
       },
     ) {
       if (!repoPath) repoPath = '.';
@@ -155,6 +161,22 @@ class UnderpostRepository {
         return;
       }
 
+      if (options.remoteUrl) {
+        const url = Underpost.repo.getRemoteUrl({ path: repoPath });
+        if (options.copy) pbcopy(url);
+        else console.log(url);
+        return;
+      }
+
+      if (options.switchRepo) {
+        Underpost.repo.switchRemote({
+          path: repoPath,
+          url: options.switchRepo,
+          branch: options.targetBranch || 'master',
+        });
+        return;
+      }
+
       if (options.bc) {
         console.log(
           shellExec(`cd ${repoPath} && git for-each-ref --contains ${options.bc} --format='%(refname:short)'`, {
@@ -1332,6 +1354,65 @@ Prevent build private config repo.`,
       return typeof raw === 'string' && /^[0-9a-f]{40}\t/m.test(raw);
     },
 
+    /**
+     * Returns the current URL of a git remote in plain text.
+     * @param {object} [opts]
+     * @param {string} [opts.path='.'] - Path to the git repository.
+     * @param {string} [opts.remote='origin'] - Remote name to query.
+     * @returns {string} The remote URL, or '' when the remote is not configured.
+     * @memberof UnderpostRepository
+     */
+    getRemoteUrl({ path: repoPath = '.', remote = 'origin' } = {}) {
+      return shellExec(`cd "${repoPath}" && git remote get-url ${remote}`, {
+        stdout: true,
+        silent: true,
+        disableLog: true,
+        silentOnError: true,
+      }).trim();
+    },
+
+    /**
+     * Switches a local repository onto a different remote and force-syncs its
+     * working tree to a target branch, discarding local commits and tracked
+     * changes — effectively "switch repo to <url>#<branch>".
+     *
+     * Sequence (idempotent, re-runnable):
+     *   1. Normalize the URL (`owner/repo` → full GitHub HTTPS) and set/add the
+     *      remote, storing the token-free URL so no secret leaks into `.git/config`.
+     *   2. Force-fetch the target branch (auth injected inline for private repos).
+     *   3. Reset the working tree to the fetched tip and check out the target
+     *      branch, overwriting any current tracked content.
+     *
+     * Untracked files are intentionally left in place (no `git clean`).
+     *
+     * @param {object} opts
+     * @param {string} opts.url - New remote URL (full URL or "owner/repo" short form).
+     * @param {string} [opts.path='.'] - Path to the git repository.
+     * @param {string} [opts.branch='master'] - Target branch to overwrite the current tree with.
+     * @param {string} [opts.remote='origin'] - Remote name to set and fetch from.
+     * @returns {void}
+     * @memberof UnderpostRepository
+     */
+    switchRemote({ url, path: repoPath = '.', branch = 'master', remote = 'origin' }) {
+      if (!url) throw new Error('switchRemote requires a target remote url');
+      if (!fs.existsSync(`${repoPath}/.git`)) throw new Error(`switchRemote: not a git repository: ${repoPath}`);
+      // Token-free URL for the stored remote; auth-injected URL only for the fetch.
+      let normalized = url;
+      if (!url.startsWith('http://') && !url.startsWith('https://') && !url.startsWith('git@')) {
+        normalized = `https://github.com/${url}`;
+      }
+      const authUrl = Underpost.repo.resolveAuthUrl(url);
+      const current = Underpost.repo.getRemoteUrl({ path: repoPath, remote });
+      if (!current) shellExec(`cd "${repoPath}" && git remote add ${remote} "${normalized}"`);
+      else shellExec(`cd "${repoPath}" && git remote set-url ${remote} "${normalized}"`);
+      logger.info('switchRemote', { path: repoPath, remote, branch, url: normalized });
+      shellExec(`cd "${repoPath}" && GIT_TERMINAL_PROMPT=0 git fetch --force "${authUrl}" ${branch}`);
+      // reset --hard first clears the worktree so the checkout cannot be blocked
+      // by conflicting local changes; -B points the target branch at the fetched tip.
+      shellExec(`cd "${repoPath}" && git reset --hard FETCH_HEAD`);
+      shellExec(`cd "${repoPath}" && git checkout -B ${branch} FETCH_HEAD`);
+    },
+
     /**
      * Returns metadata about unpushed commits in a git repository.
      * Fetches from origin, then counts commits ahead of the remote branch.

package/src/cli/run.js

@@ -56,6 +56,7 @@ const logger = loggerFactory(import.meta);
  * @property {boolean} dev - Whether to run in development mode.
  * @property {string} podName - The name of the pod to run.
  * @property {string} nodeName - The name of the node to run.
+ * @property {string} sshKeyPath - Private key path for node SSH operations, forwarded to volume shipping over SSH.
  * @property {number} port - Custom port to use.
  * @property {string} volumeHostPath - The host path for the volume.
  * @property {string} volumeMountPath - The mount path for the volume.
@@ -127,6 +128,7 @@ const DEFAULT_OPTION = {
   dev: false,
   podName: '',
   nodeName: '',
+  sshKeyPath: '',
   port: 0,
   volumeHostPath: '',
   volumeMountPath: '',
@@ -444,7 +446,15 @@ class UnderpostRun {
 
       // Kinds that own a pod template we can patch; rolloutKinds additionally
       // support `kubectl rollout restart` to reschedule existing pods now.
-      const templated = ['deployment', 'statefulset', 'daemonset', 'replicaset', 'job', 'cronjob', 'replicationcontroller'];
+      const templated = [
+        'deployment',
+        'statefulset',
+        'daemonset',
+        'replicaset',
+        'job',
+        'cronjob',
+        'replicationcontroller',
+      ];
       const rolloutKinds = ['deployment', 'statefulset', 'daemonset'];
       const templateSelectorPath = (kind) =>
         kind === 'cronjob'
@@ -456,7 +466,10 @@ class UnderpostRun {
       let selector = { 'kubernetes.io/hostname': node };
       if (!remove && options.labels) {
         selector = {};
-        for (const pair of `${options.labels}`.split(',').map((s) => s.trim()).filter(Boolean)) {
+        for (const pair of `${options.labels}`
+          .split(',')
+          .map((s) => s.trim())
+          .filter(Boolean)) {
           const eq = pair.indexOf('=');
           if (eq < 0) continue;
           selector[pair.slice(0, eq).trim()] = pair.slice(eq + 1).trim();
@@ -483,8 +496,11 @@ class UnderpostRun {
 
       const kubectlNames = (kind) =>
         (
-          shellExec(`kubectl get ${kind} -n ${ns} -o name`, { silent: true, stdout: true, silentOnError: true }).trim() ||
-          ''
+          shellExec(`kubectl get ${kind} -n ${ns} -o name`, {
+            silent: true,
+            stdout: true,
+            silentOnError: true,
+          }).trim() || ''
         )
           .split('\n')
           .map((s) => s.trim())
@@ -613,7 +629,9 @@ class UnderpostRun {
      * @memberof UnderpostRun
      */
     'cluster-build': (path, options = DEFAULT_OPTION) => {
-      const nodeOptions = options.nodeName ? ` --node-name ${options.nodeName}` : '';
+      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}`);
@@ -909,7 +927,7 @@ echo -e "[code]\nname=Visual Studio Code\nbaseurl=https://packages.microsoft.com
       replicas = replicas ? replicas : defaultPath[1];
       versions = versions ? versions.replaceAll('+', ',') : defaultPath[2];
       image = image ? image : defaultPath[3];
-      node = node ? node : defaultPath[4];
+      node = node ? node : options.nodeName ? options.nodeName : defaultPath[4];
       shellExec(`${baseCommand} cluster --ns-use ${options.namespace}`);
 
       if (image && !image.startsWith('localhost'))
@@ -950,13 +968,14 @@ echo -e "[code]\nname=Visual Studio Code\nbaseurl=https://packages.microsoft.com
       const skipFullBuildFlag = options.skipFullBuild ? ' --skip-full-build' : '';
       const pullBundleFlag = options.pullBundle ? ' --pull-bundle' : '';
       const imagePullPolicyFlag = options.imagePullPolicy ? ` --image-pull-policy ${options.imagePullPolicy}` : '';
+      const sshKeyPathFlag = options.sshKeyPath ? ` --ssh-key-path ${options.sshKeyPath}` : '';
 
       shellExec(
         `${baseCommand} deploy${clusterFlag} --build-manifest --sync --info-router --replicas ${replicas} --node ${node}${
           image ? ` --image ${image}` : ''
         }${versions ? ` --versions ${versions}` : ''}${
           options.namespace ? ` --namespace ${options.namespace}` : ''
-        }${timeoutFlags}${cmdString}${gitCleanFlag}${skipFullBuildFlag}${pullBundleFlag}${imagePullPolicyFlag} ${deployId} ${env}`,
+        }${timeoutFlags}${cmdString}${gitCleanFlag}${skipFullBuildFlag}${pullBundleFlag}${imagePullPolicyFlag}${sshKeyPathFlag} ${deployId} ${env}`,
       );
 
       if (isDeployRunnerContext(path, options)) {
@@ -965,9 +984,9 @@ echo -e "[code]\nname=Visual Studio Code\nbaseurl=https://packages.microsoft.com
           `${baseCommand} db ${deployId} ${clusterFlag}${baseClusterCommand} --repo-backup --primary-pod --git --force-clone --preserveUUID ${options.namespace ? ` --ns ${options.namespace}` : ''}`,
         );
         shellExec(
-          `${baseCommand} deploy${clusterFlag}${cmdString} --replicas ${replicas} --disable-update-proxy ${deployId} ${env} --versions ${versions}${
+          `${baseCommand} deploy${clusterFlag}${cmdString} --replicas ${replicas} --node ${node} --disable-update-proxy ${deployId} ${env} --versions ${versions}${
             options.namespace ? ` --namespace ${options.namespace}` : ''
-          }${timeoutFlags}${gitCleanFlag}${imagePullPolicyFlag}`,
+          }${timeoutFlags}${gitCleanFlag}${imagePullPolicyFlag}${sshKeyPathFlag}`,
         );
         if (!targetTraffic)
           targetTraffic = Underpost.deploy.getCurrentTraffic(deployId, { namespace: options.namespace });
@@ -1327,9 +1346,16 @@ EOF
               deployId: _deployId,
               env,
               version: targetTraffic,
-              nodeName: options.nodeName,
+              nodeName: Underpost.deploy.resolveDeployNode({
+                node: options.nodeName,
+                kind: options.kind,
+                kubeadm: options.kubeadm,
+                k3s: options.k3s,
+                env,
+              }),
               clusterContext: options.k3s ? 'k3s' : options.kubeadm ? 'kubeadm' : 'kind',
               gitClean: options.gitClean || false,
+              sshKeyPath: options.sshKeyPath || '',
             });
         // Regenerate the parent deploy's gRPC ClusterIP service pointing to the
         // parent's current traffic colour and apply it before the instance pod starts so

package/src/cli/secrets.js

@@ -104,12 +104,17 @@ class UnderpostSecret {
     /**
      * Removes all filesystem traces of secrets after deployment startup.
      * Centralizes the defense-in-depth cleanup performed
+     * @param {object} options - Options for cleaning the environment.
+     * @param {Array<string>} [options.keepKeys=[]] - List of keys to keep in the environment file. If provided, only these keys will be retained.
      * @memberof UnderpostSecret
      */
-    globalSecretClean() {
+    globalSecretClean(options = { keepKeys: [] }) {
+      const { keepKeys } = options;
       loadConf('clean');
       Underpost.repo.cleanupPrivateEngineRepo();
-      Underpost.env.clean();
+      Underpost.env.clean({
+        keepKeys: keepKeys.length > 0 ? keepKeys : ['container-status', 'start-container-status'],
+      });
     },
   };
 }

package/src/cli/ssh.js

@@ -496,6 +496,50 @@ EOF`);
       if (options.status) shellExec('service sshd status');
     },
 
+    /**
+     * Synchronously copies a local directory to a remote host over key-only SSH,
+     * streaming it as a tar archive (no intermediate file) and fixing ownership.
+     * Mirrors the kind-node `tar | docker cp` provisioning pattern but targets a
+     * real node via SSH, so node-local hostPath volumes can be materialized on the
+     * node where the pod will actually run.
+     *
+     * Idempotent and re-runnable: `mkdir -p` + `tar -x` overwrite in place. Throws
+     * on any SSH/tar failure so an empty-volume deploy is never produced silently.
+     *
+     * @function copyDirToNode
+     * @memberof UnderpostSSH
+     * @param {object} params
+     * @param {string} params.host - Target host/IP (key-only SSH reachable).
+     * @param {string} params.localDir - Local source directory.
+     * @param {string} params.remoteDir - Destination directory on the node.
+     * @param {number} [params.port=22] - SSH port.
+     * @param {string} [params.user='root'] - SSH user (key-only).
+     * @param {string} [params.keyPath='./engine-private/deploy/id_rsa'] - Private key path.
+     * @param {string} [params.owner='1000:1000'] - chown target on the node (empty to skip).
+     * @param {string} [params.mode='755'] - chmod mode on the node (empty to skip).
+     * @returns {void}
+     */
+    copyDirToNode: ({
+      host,
+      localDir,
+      remoteDir,
+      port = 22,
+      user = 'root',
+      keyPath = './engine-private/deploy/id_rsa',
+      owner = '1000:1000',
+      mode = '755',
+    }) => {
+      if (!host) throw new Error('copyDirToNode requires a host');
+      if (!localDir || !fs.existsSync(localDir)) throw new Error(`copyDirToNode: local dir not found: ${localDir}`);
+      if (!remoteDir) throw new Error('copyDirToNode requires a remoteDir');
+      shellExec(`chmod 600 ${keyPath}`, { silent: true, silentOnError: true, disableLog: true });
+      const sshOpts = `-i ${keyPath} -o BatchMode=yes -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null -p ${port}`;
+      shellExec(`ssh ${sshOpts} ${user}@${host} 'mkdir -p ${remoteDir}'`);
+      shellExec(`tar -C ${localDir} -c . | ssh ${sshOpts} ${user}@${host} 'tar -C ${remoteDir} -x'`);
+      const fixups = `${owner ? `chown -R ${owner} ${remoteDir}; ` : ''}${mode ? `chmod -R ${mode} ${remoteDir}` : ''}`.trim();
+      if (fixups) shellExec(`ssh ${sshOpts} ${user}@${host} '${fixups}'`);
+    },
+
     /**
      * Generic SSH remote command runner that SSH execution logic.
      * Executes arbitrary shell commands on a remote server via SSH with proper credential handling.

package/src/client.build.js

@@ -15,5 +15,3 @@ const logger = loggerFactory(import.meta);
 await logger.setUpInfo();
 
 await clientLiveBuild();
-
-// ProcessController.init(logger);

package/src/db/mongo/MongoBootstrap.js

@@ -290,19 +290,16 @@ class MongoBootstrap {
    * @returns {Promise<number>} Number of pods that failed to become ready (0 = all good).
    */
   static async waitForPods(namespace, replicaCount) {
-    const { default: Underpost } = await import('../../index.js');
-    const results = await Promise.all(
-      Array.from({ length: replicaCount }, async (_, i) => {
-        const podName = `${MONGODB_STATEFULSET_NAME}-${i}`;
-        const ready = await Underpost.test.statusMonitor(podName, 'Running', 'pods', 1000, 60 * 10);
-        return { index: i, ready };
-      }),
-    );
-    const failed = results.filter((r) => !r.ready).map((r) => `${MONGODB_STATEFULSET_NAME}-${r.index}`);
-    if (failed.length > 0) {
-      logger.error('MongoDB pods did not become ready', { failed });
+    let failedCount = 0;
+    for (let i = 0; i < replicaCount; i++) {
+      const podName = `${MONGODB_STATEFULSET_NAME}-${i}`;
+      const result = shellExec(`kubectl wait --for=condition=Ready pod/${podName} -n ${namespace} --timeout=60s`);
+      if (result.code !== 0) {
+        logger.error(`Pod ${podName} did not become ready`);
+        failedCount++;
+      }
     }
-    return failed.length;
+    return failedCount;
   }
 
   /**
@@ -620,6 +617,9 @@ class MongoBootstrap {
       process.env.DB_PASSWORD ||
       readTrimmedFile('./engine-private/mongodb-password');
 
+    // Ensure the pod is ready before querying
+    shellExec(`kubectl wait --for=condition=Ready pod/${podName} -n ${namespace} --timeout=60s`);
+
     const evalExpr = 'rs.status().members.filter(m=>m.stateStr=="PRIMARY").map(m=>m.name)';
 
     const cli = disableAuth ? 'mongo' : 'mongosh';

package/src/index.js

@@ -45,7 +45,7 @@ class Underpost {
    * @type {String}
    * @memberof Underpost
    */
-  static version = 'v3.2.28';
+  static version = 'v3.2.30';
 
   /**
    * Required Node.js major version

package/src/server/runtime-status.js

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

package/src/server/start.js

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

package/src/server.js

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

package/test/deploy-monitor.test.js

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