fix(supervisor): reject padded org override keys and sharpen placement wording

The override lookup is exact, so a padded or blank org key would parse
at startup and then never match a run. The release note now describes
the user-visible result and the docs row states the selector-override
vs toleration-append semantics separately.

Author: myftija

.server-changes/supervisor-org-placement-overrides.md

@@ -3,4 +3,4 @@ area: supervisor
 type: feature
 ---
 
-Operators can now pin an organization's runs to specific nodes, with per-organization node selectors and tolerations for run pods.
+Operators can now route an organization's runs to specific Kubernetes node pools.

apps/supervisor/src/envUtil.test.ts

@@ -288,6 +288,14 @@ describe("OrgPlacementOverrides", () => {
     ).toEqual({ org_123: { nodeSelector: { pool: "a" } } });
   });
 
+  it("should reject blank or padded org keys, since the lookup is exact", () => {
+    for (const key of [" ", " org_123", "org_123 "]) {
+      expect(
+        OrgPlacementOverrides.safeParse(JSON.stringify({ [key]: {} })).success
+      ).toBe(false);
+    }
+  });
+
   it("should reject an empty node selector value instead of pinning the org to nothing", () => {
     for (const value of ["", "   "]) {
       expect(

apps/supervisor/src/envUtil.ts

@@ -221,7 +221,13 @@ export const OrgPlacementOverrides = z
   .pipe(
     z
       .record(
-        z.string().min(1),
+        z
+          .string()
+          .min(1)
+          .refine((key) => key === key.trim() && key.trim().length > 0, {
+            message:
+              "Org override keys must not be blank or padded with whitespace; the lookup is exact",
+          }),
         z
           .object({
             nodeSelector: NodeSelector.optional(),

docs/self-hosting/env/supervisor.mdx

@@ -48,7 +48,7 @@ mode: "wide"
 | `KUBERNETES_NAMESPACE`                      | No       | default     | The namespace that runs should be in.                       |
 | `KUBERNETES_WORKER_NODETYPE_LABEL`          | No       | v4-worker   | Nodes for runs need `nodetype=<this>`. Empty: any node.     |
 | `KUBERNETES_RUNNER_TOLERATIONS`             | No       | —           | Run pod tolerations. CSV: `key=value:effect`/`key:effect`.  |
-| `KUBERNETES_ORG_PLACEMENT_OVERRIDES`        | No       | —           | Per-org node selector and tolerations for run pods, merged over the defaults. JSON keyed by the org's internal ID (the `org` label on run pods). |
+| `KUBERNETES_ORG_PLACEMENT_OVERRIDES`        | No       | —           | Per-org node selectors override matching defaults, and tolerations append to existing run-pod tolerations. JSON keyed by the org's internal ID (the `org` label on run pods). |
 | `KUBERNETES_IMAGE_PULL_SECRETS`             | No       | —           | Image pull secrets (CSV).                                   |
 | `KUBERNETES_EPHEMERAL_STORAGE_SIZE_LIMIT`   | No       | 10Gi        | Ephemeral storage size limit. Applies to all runs.          |
 | `KUBERNETES_EPHEMERAL_STORAGE_SIZE_REQUEST` | No       | 2Gi         | Ephemeral storage size request. Applies to all runs.        |