@telorun/k8s-runner 0.14.0 → 0.15.1

package/src/config.ts

@@ -45,12 +45,58 @@ export interface LimitCeilings {
   ephemeralStorage: string;
 }
 
+/**
+ * Which routing layer the runner publishes per-session routes on.
+ *
+ *  - `auto`    — resolve from what is CONFIGURED, then from what the cluster
+ *                serves; refuse at boot when the answer is genuinely ambiguous.
+ *  - `ingress` — `networking.k8s.io/v1` Ingress.
+ *  - `gateway` — `gateway.networking.k8s.io/v1` HTTPRoute.
+ *  - `none`    — publish nothing; the session is logs-only even with a base
+ *                domain set.
+ */
+export type SessionRoutingMode = "auto" | "ingress" | "gateway" | "none";
+
+const ROUTING_MODES: readonly SessionRoutingMode[] = ["auto", "ingress", "gateway", "none"];
+
+/** The Gateway a session's HTTPRoute attaches to. Never detected: picking one of
+ *  several Gateways is the same guess as picking one of two routing APIs, and a
+ *  route attached to the wrong Gateway fails exactly as silently as no route. */
+export interface GatewayParentConfig {
+  name: string;
+  /** Defaults to the session namespace — mirroring Gateway API's own
+   *  `parentRefs[].namespace` default, which is the route's own namespace. */
+  namespace: string;
+  /** Optional listener name, when the Gateway has several and only one should
+   *  carry session traffic. */
+  sectionName?: string;
+}
+
+export interface SessionRoutingConfig {
+  mode: SessionRoutingMode;
+  /** Wildcard base domain for per-session hosts; unset → logs-only whatever the
+   *  mode, since without it no host can be constructed at all. */
+  baseDomain?: string;
+  /** IngressClass for created session Ingresses (ingress mode). */
+  ingressClassName?: string;
+  /** `kubernetes.io/tls` Secret (in the session namespace) the per-session
+   *  Ingress presents so an upstream (e.g. Cloudflare Full (Strict)) can validate
+   *  the origin. Must cover `*.<baseDomain>`. INGRESS MODE ONLY — under Gateway
+   *  API the certificate belongs to the Gateway's listener, so setting this in
+   *  gateway mode is refused at boot rather than silently ignored. */
+  tlsSecretName?: string;
+  gateway?: GatewayParentConfig;
+  /** How long a published route may go unclaimed by any controller before it is
+   *  reported `unprogrammed`. */
+  routeReadyTimeoutMs: number;
+}
+
 export interface K8sRunnerConfig extends RunnerCoreConfig {
   /** Identity advertised on `/v1/capabilities` — studio labels the runner
    *  with these. */
   displayName: string;
   description: string;
-  /** Namespace where session Pods/Services/Ingresses are created. */
+  /** Namespace where session Pods/Services and routing objects are created. */
   sessionNamespace: string;
   /** Default image for spawned session Pods (telorun/node). Baked into the runner
    *  image as `RUNNER_IMAGE` at build time (the kernel version the runner was
@@ -64,14 +110,8 @@ export interface K8sRunnerConfig extends RunnerCoreConfig {
   imagePullSecret?: string;
   /** Optional sandbox RuntimeClass (gvisor/kata). Unset → cluster default (runc). */
   runtimeClass?: string;
-  /** Wildcard base domain for per-session ingress; unset → logs-only. */
-  sessionIngressBaseDomain?: string;
-  /** Optional IngressClass name for created session Ingresses. */
-  sessionIngressClassName?: string;
-  /** Optional `kubernetes.io/tls` Secret (in the session namespace) the per-session
-   *  Ingress presents so an upstream (e.g. Cloudflare Full (Strict)) can validate
-   *  the origin. Must cover the wildcard `*.<sessionIngressBaseDomain>`. Unset → no TLS block. */
-  sessionIngressTlsSecretName?: string;
+  /** How per-session routes are published. */
+  sessionRouting: SessionRoutingConfig;
   /** Runner's own in-cluster base URL, used to build the bundle fetch URL the
    *  initContainer curls (e.g. http://k8s-runner.telo-runner:8062). */
   selfUrl: string;
@@ -102,6 +142,69 @@ function parseTagRegex(raw: string | undefined, field: string): RegExp[] | undef
   }
 }
 
+/** Parse the routing mode, THROWING on an unrecognized one rather than degrading
+ *  to a default — a typo'd mode that silently fell back to `auto` is the same
+ *  class of failure this whole mechanism exists to remove. */
+function parseRoutingMode(raw: string | undefined): SessionRoutingMode {
+  const v = raw?.trim();
+  if (!v) return "auto";
+  if ((ROUTING_MODES as readonly string[]).includes(v)) return v as SessionRoutingMode;
+  throw new RunnerConfigError(
+    `SESSION_ROUTING_MODE must be one of ${ROUTING_MODES.join(" | ")} (got '${v}').`,
+  );
+}
+
+function loadSessionRoutingConfig(
+  env: NodeJS.ProcessEnv,
+  sessionNamespace: string,
+): SessionRoutingConfig {
+  const mode = parseRoutingMode(env.SESSION_ROUTING_MODE);
+  const gatewayName = env.SESSION_GATEWAY_NAME?.trim() || undefined;
+  const tlsSecretName = env.SESSION_INGRESS_TLS_SECRET?.trim() || undefined;
+
+  // A certificate configured for a layer that will never present it is a silent
+  // downgrade to plaintext origin traffic, so it is refused rather than ignored.
+  // This is only the FAST PATH, for the mode that states the layer outright: the
+  // authoritative refusal is at routing resolution, because under `auto` a named
+  // Gateway decides the layer and nothing here can see that yet.
+  if (mode === "gateway" && tlsSecretName) {
+    throw new RunnerConfigError(
+      "SESSION_INGRESS_TLS_SECRET is set but SESSION_ROUTING_MODE=gateway. Under Gateway API the " +
+        "origin certificate belongs to the Gateway listener's own `tls.certificateRefs`, not to the " +
+        "per-session route. Move the Secret reference to the Gateway and unset this.",
+    );
+  }
+  if (mode === "gateway" && !gatewayName) {
+    throw new RunnerConfigError(
+      "SESSION_ROUTING_MODE=gateway requires SESSION_GATEWAY_NAME — the Gateway each session's " +
+        "HTTPRoute attaches to. Set it (and SESSION_GATEWAY_NAMESPACE when the Gateway is not in " +
+        `'${sessionNamespace}').`,
+    );
+  }
+
+  return {
+    mode,
+    baseDomain: env.SESSION_ROUTING_BASE_DOMAIN?.trim() || undefined,
+    ingressClassName: env.SESSION_INGRESS_CLASS?.trim() || undefined,
+    tlsSecretName,
+    ...(gatewayName
+      ? {
+          gateway: {
+            name: gatewayName,
+            namespace: env.SESSION_GATEWAY_NAMESPACE?.trim() || sessionNamespace,
+            sectionName: env.SESSION_GATEWAY_SECTION_NAME?.trim() || undefined,
+          },
+        }
+      : {}),
+    routeReadyTimeoutMs:
+      parsePositiveInt(
+        env.SESSION_ROUTE_READY_TIMEOUT_SECONDS,
+        60,
+        "SESSION_ROUTE_READY_TIMEOUT_SECONDS",
+      ) * 1000,
+  };
+}
+
 function loadBaseImageCatalogConfig(env: NodeJS.ProcessEnv): BaseImageCatalogConfig {
   return {
     enabled: parseBool(env.RUNNER_BASE_IMAGE_CATALOG_ENABLED, true, "RUNNER_BASE_IMAGE_CATALOG_ENABLED"),
@@ -136,19 +239,19 @@ export function loadK8sRunnerConfig(env: NodeJS.ProcessEnv): K8sRunnerConfig {
     );
   }
 
+  const sessionNamespace = env.RUNNER_SESSION_NAMESPACE?.trim() || "telo-sessions";
+
   return {
     ...loadCoreConfig(env, { port: DEFAULT_PORT }),
     displayName: env.RUNNER_DISPLAY_NAME?.trim() || "Telo Runner",
     description:
       env.RUNNER_DESCRIPTION?.trim() || "Runs the Telo application in a cloud environment",
-    sessionNamespace: env.RUNNER_SESSION_NAMESPACE?.trim() || "telo-sessions",
+    sessionNamespace,
     defaultImage: env.RUNNER_IMAGE?.trim() || "telorun/node:latest-slim",
     initImage: env.RUNNER_INIT_IMAGE?.trim() || "busybox:stable",
     imagePullSecret: env.RUNNER_IMAGE_PULL_SECRET?.trim() || undefined,
     runtimeClass: env.RUNNER_RUNTIME_CLASS?.trim() || undefined,
-    sessionIngressBaseDomain: env.SESSION_INGRESS_BASE_DOMAIN?.trim() || undefined,
-    sessionIngressClassName: env.SESSION_INGRESS_CLASS?.trim() || undefined,
-    sessionIngressTlsSecretName: env.SESSION_INGRESS_TLS_SECRET?.trim() || undefined,
+    sessionRouting: loadSessionRoutingConfig(env, sessionNamespace),
     selfUrl: selfUrl.replace(/\/+$/, ""),
     managedByLabel: env.RUNNER_MANAGED_BY?.trim() || "telo-k8s-runner",
     // Sized for a pod that RESOLVES ITS OWN module closure. They used to be

package/src/k8s/backend.ts

@@ -17,7 +17,14 @@ import type { K8sRunnerConfig } from "../config.js";
 import { clampLimits } from "../limits.js";
 import { apiFailure, apiReason, withCause } from "./api-error.js";
 import type { KubeClient } from "./client.js";
-import { buildSessionIngress, buildSessionService, endpointsFor } from "./ingress.js";
+import {
+  buildSessionService,
+  endpointsFor,
+  hostForPort,
+  watchRouteHealth,
+  type PublishedRoute,
+  type SessionRouter,
+} from "./routing/index.js";
 import { buildAppPod, buildSessionPod, INSPECT_PORT } from "./pod-spec.js";
 import {
   deletePod,
@@ -50,10 +57,13 @@ export interface K8sBackendDeps {
   kube: KubeClient;
   config: K8sRunnerConfig;
   bundleStore: BundleStore;
+  /** How this cluster publishes session routes, resolved once at boot. Absent →
+   *  logs-only: no base domain, or `SESSION_ROUTING_MODE=none`. */
+  router?: SessionRouter;
 }
 
 export function createKubernetesBackend(deps: K8sBackendDeps): RunnerBackend {
-  const { kube, config, bundleStore } = deps;
+  const { kube, config, bundleStore, router } = deps;
   const ns = config.sessionNamespace;
 
   async function probe(probeConfig: ProbeConfig): Promise<AvailabilityReport> {
@@ -82,7 +92,7 @@ export function createKubernetesBackend(deps: K8sBackendDeps): RunnerBackend {
     // outlives its runs — so it takes its own path rather than accreting
     // branches through this one.
     if (spec.mode === "watch") {
-      return startWatchSession({ kube, config }, spec);
+      return startWatchSession({ kube, config, router }, spec);
     }
     return startRunSession(spec);
   }
@@ -155,7 +165,9 @@ export function createKubernetesBackend(deps: K8sBackendDeps): RunnerBackend {
     let startDeadline: NodeJS.Timeout | undefined;
     let podIP: string | undefined;
     const debugAbort = new AbortController();
-    const reachAbort = new AbortController();
+    // Aborts every background watcher this session started: the per-port
+    // reachability probes and the route-health watch.
+    const watchersAbort = new AbortController();
 
     const stdin = new PassThrough();
     const stdout = new Writable({
@@ -178,7 +190,7 @@ export function createKubernetesBackend(deps: K8sBackendDeps): RunnerBackend {
       clearStartDeadline();
       abortWatch();
       debugAbort.abort();
-      reachAbort.abort();
+      watchersAbort.abort();
       bundleStore.drop(spec.sessionId);
       spec.onStatus(status);
       try {
@@ -197,7 +209,7 @@ export function createKubernetesBackend(deps: K8sBackendDeps): RunnerBackend {
     const flipRunning = (): void => {
       if (readyFlipped || finished) return;
       readyFlipped = true;
-      spec.onStatus({ kind: "running", endpoints: endpointsFor(config, spec.sessionId, app.ports) });
+      spec.onStatus({ kind: "running", endpoints: endpointsFor(config, spec.sessionId, app.ports, Boolean(router)) });
     };
 
     let resolveRunning!: () => void;
@@ -327,13 +339,52 @@ export function createKubernetesBackend(deps: K8sBackendDeps): RunnerBackend {
       );
     }
 
-    if (config.sessionIngressBaseDomain && app.ports.length > 0) {
-      await createIngress(deps, spec.sessionId, podName, podUid, app.ports).catch((err) => {
-        spec.onOutput(
-          appName,
-          Buffer.from(`\r\n[runner] failed to create ingress: ${apiReason(err)}\r\n`),
-          "tty",
+    if (router && app.ports.length > 0) {
+      let published: PublishedRoute[] = [];
+      try {
+        published = await publishRoutes(
+          deps,
+          router,
+          spec.sessionId,
+          podName,
+          podUid,
+          app.ports,
         );
+      } catch (err) {
+        // A publish failure is reported on the ROUTE channel, not only as a
+        // terminal line: the endpoints were already advertised on the `running`
+        // status, so leaving this to a log line is the silence this whole change
+        // exists to remove.
+        const reason = `could not publish the session route: ${apiReason(err)}`;
+        for (const p of app.ports) {
+          if (p.protocol !== "tcp") continue;
+          spec.onRoute(appName, {
+            host: hostForPort(config, spec.sessionId, p.port),
+            port: p.port,
+            state: "unprogrammed",
+            reason,
+          });
+        }
+        spec.onOutput(appName, Buffer.from(`\r\n[runner] ${reason}\r\n`), "tty");
+      }
+      // Verify the routing layer actually PROGRAMMED what we published. Without
+      // this a cluster whose routing objects nothing reconciles is indistinguishable
+      // from a healthy one: reachability below dials the pod directly and stays
+      // green while every public URL 404s.
+      void watchRouteHealth({
+        router,
+        sessionId: spec.sessionId,
+        routes: published,
+        onState: (route, state, reason) =>
+          spec.onRoute(appName, { host: route.host, port: route.port, state, reason }),
+        onReadError: (err) =>
+          spec.onOutput(
+            appName,
+            Buffer.from(`\r\n[runner] could not read route status: ${apiReason(err)}\r\n`),
+            "tty",
+          ),
+        signal: watchersAbort.signal,
+        timeoutMs: config.sessionRouting.routeReadyTimeoutMs,
       });
     }
 
@@ -372,7 +423,7 @@ export function createKubernetesBackend(deps: K8sBackendDeps): RunnerBackend {
     if (tcpPorts.length > 0) {
       void (async () => {
         const ip = await resolvePodIP();
-        if (reachAbort.signal.aborted) return;
+        if (watchersAbort.signal.aborted) return;
         if (!ip) {
           // Couldn't resolve the pod IP to probe — report unverified rather than
           // leaving the badge spinning forever.
@@ -383,7 +434,7 @@ export function createKubernetesBackend(deps: K8sBackendDeps): RunnerBackend {
           host: ip,
           ports: tcpPorts,
           onState: (port, state) => spec.onReachability(appName, port, state),
-          signal: reachAbort.signal,
+          signal: watchersAbort.signal,
         });
       })();
     }
@@ -443,28 +494,27 @@ export function createKubernetesBackend(deps: K8sBackendDeps): RunnerBackend {
   return { probe, start, reapOrphans };
 }
 
-async function createIngress(
+/** Create the session Service and publish its routes on whichever layer the
+ *  cluster resolved to. Returns the hosts published, for the route watch. */
+async function publishRoutes(
   deps: K8sBackendDeps,
+  router: SessionRouter,
   sessionId: string,
   podName: string,
   podUid: string,
   ports: PortMapping[],
-): Promise<void> {
+): Promise<PublishedRoute[]> {
   const { kube, config } = deps;
   const ns = config.sessionNamespace;
   const service = buildSessionService(config, sessionId, podName, podUid, ports);
   await kube.core.createNamespacedService({ namespace: ns, body: service });
-  const { ingress } = buildSessionIngress(
-    config,
+  return router.publish({
     sessionId,
-    service.metadata!.name!,
+    serviceName: service.metadata!.name!,
     podName,
     podUid,
     ports,
-  );
-  // No tcp ports → no HTTP-routable rules; the Service still exists for any udp.
-  if (!ingress.spec?.rules?.length) return;
-  await kube.networking.createNamespacedIngress({ namespace: ns, body: ingress });
+  });
 }
 
 async function clusterReachable(kube: KubeClient): Promise<boolean> {

package/src/k8s/client.ts

@@ -1,9 +1,23 @@
-import { Attach, CoreV1Api, KubeConfig, NetworkingV1Api, Watch } from "@kubernetes/client-node";
+import {
+  ApisApi,
+  Attach,
+  CoreV1Api,
+  CustomObjectsApi,
+  KubeConfig,
+  NetworkingV1Api,
+  Watch,
+} from "@kubernetes/client-node";
 
 export interface KubeClient {
   kc: KubeConfig;
   core: CoreV1Api;
   networking: NetworkingV1Api;
+  /** Gateway API has no typed client in `@kubernetes/client-node`, so HTTPRoutes
+   *  are read and written as unstructured custom objects. */
+  custom: CustomObjectsApi;
+  /** API-group discovery, used to decide whether Gateway API is served at all
+   *  when the routing mode is `auto`. */
+  apis: ApisApi;
   attach: Attach;
   watch: Watch;
 }
@@ -24,6 +38,8 @@ export function createKubeClient(): KubeClient {
     kc,
     core: kc.makeApiClient(CoreV1Api),
     networking: kc.makeApiClient(NetworkingV1Api),
+    custom: kc.makeApiClient(CustomObjectsApi),
+    apis: kc.makeApiClient(ApisApi),
     attach: new Attach(kc),
     watch: new Watch(kc),
   };

package/src/k8s/pod-status.ts

@@ -132,6 +132,14 @@ export function is404(err: unknown): boolean {
   return statusCode(err) === 404;
 }
 
+/** A name-already-taken rejection — what makes a create idempotent by falling
+ *  through to a replace. Reads the status through `statusCode` like every other
+ *  classification here, so an `ECONNREFUSED` or a `DOMException`'s legacy number
+ *  in `code` cannot be mistaken for one. */
+export function isConflict(err: unknown): boolean {
+  return statusCode(err) === 409;
+}
+
 export function msg(err: unknown): string {
   if (err instanceof Error) return err.message;
   if (typeof err === "string") return err;

package/src/k8s/routing/create-or-replace.ts

@@ -0,0 +1,16 @@
+import { isConflict } from "../pod-status.js";
+
+/** A create that yields to an existing object of the same name. Every routing
+ *  object is republished on reload (an app's declared port set changes), so the
+ *  write has to be idempotent rather than create-once. */
+export async function createOrReplace(
+  create: () => Promise<unknown>,
+  replace: () => Promise<unknown>,
+): Promise<void> {
+  try {
+    await create();
+  } catch (err) {
+    if (!isConflict(err)) throw err;
+    await replace();
+  }
+}

package/src/k8s/routing/gateway-router.test.ts

@@ -0,0 +1,236 @@
+import { describe, expect, it } from "vitest";
+
+import type { PortMapping } from "@telorun/runner-core";
+
+import type { K8sRunnerConfig } from "../../config.js";
+import type { KubeClient } from "../client.js";
+import { createGatewayRouter } from "./gateway-router.js";
+
+const sessionId = "hzyayvabgyvz";
+
+const config = {
+  sessionNamespace: "telo-sessions",
+  managedByLabel: "telo-k8s-runner",
+  sessionRouting: {
+    mode: "gateway",
+    baseDomain: "telo.run",
+    routeReadyTimeoutMs: 60_000,
+    gateway: { name: "public", namespace: "gateway-system" },
+  },
+} as K8sRunnerConfig;
+
+interface Recorded {
+  created: Record<string, unknown>[];
+  deleted: string[];
+}
+
+/** A KubeClient stub carrying only what the gateway router touches. */
+function fakeKube(opts: {
+  existing?: { metadata?: { name?: string } }[];
+  getResult?: (name: string) => unknown;
+} = {}): { kube: KubeClient; rec: Recorded } {
+  const rec: Recorded = { created: [], deleted: [] };
+  const kube = {
+    custom: {
+      createNamespacedCustomObject: async ({ body }: { body: Record<string, unknown> }) => {
+        rec.created.push(body);
+        return body;
+      },
+      listNamespacedCustomObject: async () => ({ items: opts.existing ?? [] }),
+      deleteNamespacedCustomObject: async ({ name }: { name: string }) => {
+        rec.deleted.push(name);
+        return {};
+      },
+      getNamespacedCustomObject: async ({ name }: { name: string }) => {
+        if (opts.getResult) return opts.getResult(name);
+        throw Object.assign(new Error("not found"), { code: 404 });
+      },
+      replaceNamespacedCustomObject: async ({ body }: { body: Record<string, unknown> }) => body,
+    },
+  } as unknown as KubeClient;
+  return { kube, rec };
+}
+
+const ports: PortMapping[] = [
+  { port: 8080, protocol: "tcp" },
+  { port: 9090, protocol: "tcp" },
+  { port: 5000, protocol: "udp" },
+];
+
+const publishArgs = {
+  sessionId,
+  serviceName: `telo-run-${sessionId}`,
+  podName: "pod",
+  podUid: "uid",
+  ports,
+};
+
+describe("createGatewayRouter.publish", () => {
+  it("creates ONE HTTPRoute PER PORT — hostnames are route-scoped, so a shared route would collapse every host onto one backend", async () => {
+    const { kube, rec } = fakeKube();
+    const routes = await createGatewayRouter(kube, config, "v1").publish(publishArgs);
+
+    expect(rec.created).toHaveLength(2);
+    for (const body of rec.created) {
+      const spec = body.spec as { hostnames: string[]; rules: { backendRefs: unknown[] }[] };
+      expect(spec.hostnames).toHaveLength(1);
+      expect(spec.rules).toHaveLength(1);
+      expect(spec.rules[0].backendRefs).toHaveLength(1);
+    }
+    // Each host is bound to its own port's backend, never a sibling's.
+    const pairs = rec.created.map((b) => {
+      const spec = b.spec as {
+        hostnames: string[];
+        rules: { backendRefs: { name: string; port: number }[] }[];
+      };
+      return [spec.hostnames[0], spec.rules[0].backendRefs[0].port];
+    });
+    expect(pairs).toEqual([
+      [`8080-${sessionId}.telo.run`, 8080],
+      [`9090-${sessionId}.telo.run`, 9090],
+    ]);
+    expect(routes).toEqual([
+      { host: `8080-${sessionId}.telo.run`, port: 8080 },
+      { host: `9090-${sessionId}.telo.run`, port: 9090 },
+    ]);
+  });
+
+  it("skips udp ports — they are not HTTP-routable", async () => {
+    const { kube, rec } = fakeKube();
+    await createGatewayRouter(kube, config, "v1").publish({
+      ...publishArgs,
+      ports: [{ port: 5000, protocol: "udp" }],
+    });
+    expect(rec.created).toEqual([]);
+  });
+
+  it("attaches to the configured Gateway, carrying the listener when one is named", async () => {
+    const { kube, rec } = fakeKube();
+    const sectioned = {
+      ...config,
+      sessionRouting: {
+        ...config.sessionRouting,
+        gateway: { name: "public", namespace: "gateway-system", sectionName: "https" },
+      },
+    } as K8sRunnerConfig;
+    await createGatewayRouter(kube, sectioned, "v1").publish({ ...publishArgs, ports: [ports[0]] });
+    expect((rec.created[0].spec as { parentRefs: unknown[] }).parentRefs).toEqual([
+      {
+        group: "gateway.networking.k8s.io",
+        kind: "Gateway",
+        name: "public",
+        namespace: "gateway-system",
+        sectionName: "https",
+      },
+    ]);
+  });
+
+  it("deletes the route of a port a reload dropped — one object per port means a stale one keeps routing", async () => {
+    const { kube, rec } = fakeKube({
+      existing: [
+        { metadata: { name: `telo-run-${sessionId}-8080` } },
+        { metadata: { name: `telo-run-${sessionId}-9090` } },
+      ],
+    });
+    await createGatewayRouter(kube, config, "v1").publish({
+      ...publishArgs,
+      ports: [{ port: 8080, protocol: "tcp" }],
+    });
+    expect(rec.deleted).toEqual([`telo-run-${sessionId}-9090`]);
+  });
+
+  it("posts at the served API version", async () => {
+    const { kube, rec } = fakeKube();
+    await createGatewayRouter(kube, config, "v1beta1").publish({ ...publishArgs, ports: [ports[0]] });
+    expect(rec.created[0].apiVersion).toBe("gateway.networking.k8s.io/v1beta1");
+  });
+});
+
+describe("createGatewayRouter.verdictFor", () => {
+  const route = { host: `8080-${sessionId}.telo.run`, port: 8080 };
+
+  function verdict(status: unknown) {
+    const { kube } = fakeKube({ getResult: () => ({ status }) });
+    return createGatewayRouter(kube, config, "v1").verdictFor(sessionId, route);
+  }
+
+  it("is pending while no controller has written status", async () => {
+    await expect(verdict(undefined)).resolves.toEqual({ kind: "pending" });
+    await expect(verdict({ parents: [] })).resolves.toEqual({ kind: "pending" });
+  });
+
+  it("is programmed once a parent accepted and resolved it", async () => {
+    await expect(
+      verdict({
+        parents: [
+          {
+            conditions: [
+              { type: "Accepted", status: "True" },
+              { type: "ResolvedRefs", status: "True" },
+            ],
+          },
+        ],
+      }),
+    ).resolves.toEqual({ kind: "programmed" });
+  });
+
+  it("reports the controller's own reason for a refusal — the actionable half", async () => {
+    await expect(
+      verdict({
+        parents: [
+          {
+            conditions: [
+              {
+                type: "Accepted",
+                status: "False",
+                reason: "NotAllowedByListeners",
+                message: "no listener admits routes from this namespace",
+              },
+            ],
+          },
+        ],
+      }),
+    ).resolves.toEqual({
+      kind: "rejected",
+      reason: "NotAllowedByListeners: no listener admits routes from this namespace",
+    });
+  });
+
+  it("reports an unresolvable backend rather than calling the route programmed", async () => {
+    await expect(
+      verdict({
+        parents: [
+          {
+            conditions: [
+              { type: "Accepted", status: "True" },
+              { type: "ResolvedRefs", status: "False", reason: "BackendNotFound" },
+            ],
+          },
+        ],
+      }),
+    ).resolves.toEqual({ kind: "rejected", reason: "BackendNotFound" });
+  });
+
+  it("lets one accepting parent win over a sibling's refusal — traffic arrives either way", async () => {
+    await expect(
+      verdict({
+        parents: [
+          { conditions: [{ type: "Accepted", status: "False", reason: "NoMatchingParent" }] },
+          {
+            conditions: [
+              { type: "Accepted", status: "True" },
+              { type: "ResolvedRefs", status: "True" },
+            ],
+          },
+        ],
+      }),
+    ).resolves.toEqual({ kind: "programmed" });
+  });
+
+  it("is pending when the object is not visible yet", async () => {
+    const { kube } = fakeKube();
+    await expect(
+      createGatewayRouter(kube, config, "v1").verdictFor(sessionId, route),
+    ).resolves.toEqual({ kind: "pending" });
+  });
+});