@telorun/k8s-runner 0.13.0 → 0.15.0

package/README.md

@@ -27,44 +27,45 @@ serving an anonymous tier, the ceiling *is* the policy.
 
 Per session the runner resolves the image, creates a Pod (`telo run`), watches it
 for status, attaches a PTY over the Pod `attach` subresource for the interactive
-`/io` channel, and — when an ingress base domain is configured — creates a
-per-session Service + Ingress (`<sessionId>.<base-domain>`) garbage-collected via
-an ownerReference to the Pod.
-
-**Every session runs a prebuilt per-app image** — there is no in-pod install
-path. On a session-create the runner stages the bundle plus a generated
-`Dockerfile` (`FROM <base>`, `ENV TELO_CACHE_DIR=/telo-cache`, `RUN telo install`),
-runs a trusted **Kaniko** Job in the `telo-builds` namespace that bakes every
-controller and module manifest into `/telo-cache/{manifests,npm}` and pushes the
-result, then runs the session pod from that image — so the session never installs
-anything on the start path and a slow/unreachable package registry can't stall it.
-
-**The image is keyed on the dependency closure, not the whole bundle** — the
-`imports:` set plus any controllers declared by inline `Telo.Definition` docs
-(see `extractDependencyKey`). A body-only edit (resource config, CEL) reuses the
-existing image; only an import or controller change rebuilds. The per-session
-**body is delivered at boot**, not baked: a body-fetch initContainer untars the
-staged bundle into a writable `/app` emptyDir, and the session runs `telo run
-/app/<entry> --no-cache-write` — reading the baked deps from the read-only
-`/telo-cache` and validating in-memory, so `readOnlyRootFilesystem` stays on with
-nothing written to the cache. Builds are existence-checked before building and
-single-flighted; a build failure surfaces as an actionable error carrying the
-build pod's log tail. `RUNNER_IMAGE_REPOSITORY` is therefore **required** — the
-runner refuses to start without a registry to build into.
+`/io` channel, and — when a routing base domain is configured — creates a
+per-session Service plus routing objects (an Ingress, or one HTTPRoute per port)
+at `<port>-<sessionId>.<base-domain>`, garbage-collected via an ownerReference to
+the Pod.
+
+**Every session runs the plain kernel image.** A body-fetch initContainer untars
+the staged bundle into a writable `/app` emptyDir and the session container runs
+`telo run /app/<entry>`, resolving its own module closure into a `/telo-cache`
+emptyDir on the way up. `readOnlyRootFilesystem` stays on — every write lands on
+a mounted emptyDir. The runner needs **no image registry of its own**: it builds
+nothing, pushes nothing, and creates no Jobs.
+
+The runner used to prebuild a self-contained per-app image with an on-cluster
+Kaniko Job, so that a slow package registry could not stall the start path. That
+is gone, and the cost is where it now shows: **a run session downloads its
+closure on every start**, since the cache lives and dies with the pod. A watch
+session pays it once and keeps the cache for the pod's life, which is the shape
+to reach for when start latency matters.
 
 **Coming-up progress** is reported over the `/v1` SSE stream as `progress` events
-(`build` → `provision`) while the session is still `starting`. The session is
-created with a fast `201` carrying the `streamUrl` **before** the build runs, so
-the client connects immediately and sees build + provision progress live; the
-backend then runs in the background and a start failure surfaces as a terminal
-`failed` status on the stream. The session flips to `running` when the Pod reaches
-`Running`.
+(`provision` → `boot`) while the session is still `starting`. The session is
+created with a fast `201` carrying the `streamUrl` **before** the pod is created,
+so the client connects immediately and sees provisioning live; the backend then
+runs in the background and a start failure surfaces as a terminal `failed` status
+on the stream. The session flips to `running` when the Pod reaches `Running`.
 
 Sandbox hardening is always on (non-root, read-only rootfs, drop-all caps, no
 service-account token, seccomp `RuntimeDefault`); a sandbox RuntimeClass
-(gVisor/Kata) is layered on when configured. In the prebuilt path the per-app
-image is single-tenant, so install scripts run normally inside the trusted build
-(native/postinstall controllers work) with no cross-tenant cache to poison.
+(gVisor/Kata) is layered on when configured. A controller whose install needs to
+run scripts or build native code runs them **inside the session pod** under that
+hardening — there is no trusted build step to run them in.
+
+**A Kubernetes API rejection reaches the client as its status and `reason`, never
+as the exception.** The API's error carries the full HTTP dump — the raw `Status`
+body naming the runner's ServiceAccount, the audit id, every response header —
+and a start failure's message travels verbatim to the client as the session's
+terminal status. So the client is told the operation, the HTTP code and the
+one-word reason (`Forbidden`, `NotFound`), plus who can fix a `403`; the raw
+exception rides along as the error's `cause` and lands in the runner's log.
 
 ## Watch sessions
 
@@ -74,7 +75,7 @@ different — a **workspace that runs continuously**. One pod holds a shared
 `/workspace` volume, a `workspace` container serving the editor's file routes, one
 `app-<name>` container per application running `telo run --watch`, and optionally
 a co-resident `agent` drawn from the `RUNNER_APPS` catalog. An edit then costs a
-kernel reload instead of a pod: no schedule, no pull, no build.
+kernel reload instead of a pod: no schedule, no pull, no module re-resolve.
 
 Off unless `RUNNER_WATCH_SESSIONS` is set. Run sessions are entirely unaffected.
 
@@ -105,7 +106,7 @@ agent's port the **manifest wins**: the session starts without the agent and say
 so on its stream, rather than refusing to run the user's app over a container
 they never asked for and cannot decline. Nothing else is arranged: the pod's containers
 share one network namespace, so the port simply joins the session's own Service
-and Ingress and answers at `<agentPort>-<sessionId>.<base-domain>`. The `running`
+and routing objects and answers at `<agentPort>-<sessionId>.<base-domain>`. The `running`
 status carries it as an `agent` endpoint beside `endpoints` — separate, because
 `endpoints` are the ports the user's applications declared, and an
 operator-launched container is not one of them. It is reachable without auth for
@@ -128,10 +129,10 @@ runner reconciles into a content-addressed ConfigMap — there is no third image
 build, and a runner upgrade that changes the manifest leaves running sessions
 mounting the one they booted with.
 
-**Watch sessions never build an image.** The build path exists to put a dependency
-closure on disk before boot; a watch session resolves its own into the workspace
-volume, which lives as long as the pod, so the download happens once per session
-and every later reload resolves from local disk.
+**A watch session resolves its closure once.** It lands in the workspace volume,
+which lives as long as the pod, so the download happens once per session and
+every later reload resolves from local disk — where a run session, whose cache
+dies with its pod, pays for it on every start.
 
 **One cache for the whole session.** The runner seeds `telo-workspace.yaml` at
 the workspace root when the session starts, and the kernel anchors its `.telo`
@@ -144,13 +145,11 @@ manifest lives outside the workspace and the walk-up would never reach the
 marker. A workspace that brings its own marker keeps it — overwriting one with a
 real `modules:` list would change what `telo release` discovers.
 
-**Egress moves into the session namespace.** Module fetches used to be scoped to
-the build namespace; a watch session resolves them itself, so the session
-namespace's NetworkPolicy has to reach module registries as well as the model
-provider. Core NetworkPolicy is CIDR-only and registries sit behind rotating-IP
-CDNs, so a locked-down operator needs a CNI with FQDN policy or an egress proxy
-here — the same stated dependency the build namespace already carries, one
-namespace over.
+**Egress lives in the session namespace.** Every session resolves its own module
+closure, so the session namespace's NetworkPolicy has to reach the module
+registries as well as the model provider. Core NetworkPolicy is CIDR-only and
+registries sit behind rotating-IP CDNs, so a locked-down operator needs a CNI
+with FQDN policy or an egress proxy here.
 
 ### Two nouns on one stream
 
@@ -214,10 +213,10 @@ transport whose kind does not emit one would silently get no routing.
 one-shot app completed is not a change. It touches the named app's entry manifest
 through the same path everything else uses, so it needs no signalling into the
 container, no shared PID namespace and no `exec` — **RBAC gains only `configmaps:
-get, create` and `update` on services/ingresses**, the latter so a reload that
-changes an app's declared port set can re-patch its routing. Without that, adding a
-`ports:` entry leaves the app bound to a port with no ingress, no error and no
-event.
+get, create` and `update` on services and routing objects**, the latter so a reload
+that changes an app's declared port set can re-patch its routing. Without that,
+adding a `ports:` entry leaves the app bound to a port with no route, no error and
+no event.
 
 Changing the app set costs a pod recreate because a pod's container list is fixed
 at creation. That is the only editing action in the design that costs a pod, and
@@ -288,17 +287,24 @@ outcome than a URL that silently reaches the wrong app.
 | `PORT` | `8062` | HTTP listen port |
 | `RUNNER_DISPLAY_NAME` | `Telo Runner` | Display name advertised on `/v1/capabilities` (the editor's runner label) |
 | `RUNNER_DESCRIPTION` | `Runs the Telo application in a cloud environment` | Description advertised on `/v1/capabilities` |
-| `RUNNER_APPS` | _(unset → no apps)_ | JSON map of operator-predefined apps launchable by name (chart: inline `apps.catalog`, or `apps.catalogSecret` referencing a Secret holding the JSON — use the Secret whenever entries embed secrets in `env`); see the docker-runner README for the entry shape, including the `port` an entry must declare to be usable as a session's co-resident `agent`. App sessions run the catalog image directly as a pod — no on-cluster build |
+| `RUNNER_APPS` | _(unset → no apps)_ | JSON map of operator-predefined apps launchable by name (chart: inline `apps.catalog`, or `apps.catalogSecret` referencing a Secret holding the JSON — use the Secret whenever entries embed secrets in `env`); see the docker-runner README for the entry shape, including the `port` an entry must declare to be usable as a session's co-resident `agent`. App sessions run the catalog image directly as a pod |
 | `RUNNER_APP_MAX_CPU` | `500m` | CPU ceiling for predefined-app pods (separate from the anonymous-session ceiling) |
 | `RUNNER_APP_MAX_MEMORY` | `512Mi` | Memory ceiling for predefined-app pods |
 | `RUNNER_APP_MAX_TTL_SECONDS` | `21600` | Wall-clock TTL for predefined-app pods (agent sessions are long-lived) |
 | `RUNNER_APP_MAX_EPHEMERAL_STORAGE` | `1Gi` | Ephemeral-storage ceiling for predefined-app pods |
 | `RUNNER_SESSION_NAMESPACE` | `telo-sessions` | Namespace for session objects |
 | `RUNNER_IMAGE` | _(baked at build: the CLI version for a released runner, `telorun/node:latest-slim` for a dev build)_ | Default base image; always offered in the picker and the fallback when the catalog is unreachable. Leave the chart's `session.image` empty to keep the session kernel in lockstep with the runner |
-| `RUNNER_INIT_IMAGE` | `busybox:stable` | Build-context fetch initContainer image (wget + tar) |
+| `RUNNER_INIT_IMAGE` | `busybox:stable` | Bundle-fetch initContainer image (wget + tar) |
+| `RUNNER_IMAGE_PULL_SECRET` | _(unset)_ | dockerconfig Secret (in `telo-sessions`) the kubelet pulls session images with — needed only for a kernel or catalog image in a private registry |
 | `RUNNER_RUNTIME_CLASS` | _(unset → runc)_ | Sandbox RuntimeClass (gvisor/kata) |
-| `SESSION_INGRESS_BASE_DOMAIN` | _(unset → logs-only)_ | Wildcard base for per-session ingress |
-| `SESSION_INGRESS_TLS_SECRET` | _(unset → no TLS block)_ | `kubernetes.io/tls` Secret (in `telo-sessions`) the session Ingress presents; must cover `*.<base-domain>`. Set for Cloudflare Full (Strict) / any origin-cert upstream |
+| `SESSION_ROUTING_MODE` | `auto` | `auto` \| `ingress` \| `gateway` \| `none`. See [Routing layer](#routing-layer) |
+| `SESSION_ROUTING_BASE_DOMAIN` | _(unset → logs-only)_ | Wildcard base for per-session hosts |
+| `SESSION_ROUTE_READY_TIMEOUT_SECONDS` | `60` | How long a published route may go unclaimed before the session reports it `unprogrammed` |
+| `SESSION_INGRESS_CLASS` | _(unset → cluster default)_ | IngressClass for session Ingresses (ingress mode) |
+| `SESSION_INGRESS_TLS_SECRET` | _(unset → no TLS block)_ | `kubernetes.io/tls` Secret (in `telo-sessions`) the session Ingress presents; must cover `*.<base-domain>`. Set for Cloudflare Full (Strict) / any origin-cert upstream. **Ingress mode only** — refused at boot in gateway mode, where the cert belongs to the Gateway listener |
+| `SESSION_GATEWAY_NAME` | _(unset)_ | Gateway each session's HTTPRoute attaches to. Required in gateway mode |
+| `SESSION_GATEWAY_NAMESPACE` | _(= session namespace)_ | Namespace of that Gateway |
+| `SESSION_GATEWAY_SECTION_NAME` | _(unset → any listener)_ | Listener name, when only one should carry session traffic |
 | `RUNNER_MAX_CPU` | `50m` | CPU ceiling |
 | `RUNNER_MAX_MEMORY` | `100Mi` | Memory ceiling |
 | `RUNNER_MAX_TTL_SECONDS` | `3600` | Wall-clock TTL (Pod `activeDeadlineSeconds`) |
@@ -327,12 +333,9 @@ against the same list, so a client that skips the editor can't widen the set.
 unreachable. Disable the catalog to lock `image` to `RUNNER_IMAGE`.
 
 Pinned tags (e.g. `0.30.1-slim`) are immutable. A picked **moving** tag like
-`latest-slim` only refreshes when the session's `pullPolicy` is `always`: the
-build then pins the per-app image to the base's current digest, so a moved tag
-yields a new image and rebuilds (otherwise the cached build — keyed on the tag
-string — is reused). Movement detection reads the digest from Docker Hub, so a
-base hosted elsewhere (GHCR, a private registry) can't be tracked — `always`
-degrades to reusing the cached build for it, same as `missing` / `never`.
+`latest-slim` only refreshes when the session's `pullPolicy` is `always`, which
+is the Pod's own `imagePullPolicy`: the kubelet re-pulls the tag on every
+session. `missing` and `never` reuse whatever that node already cached.
 
 | Env | Default | Purpose |
 | --- | --- | --- |
@@ -346,88 +349,144 @@ degrades to reusing the cached build for it, same as `missing` / `never`.
 | `RUNNER_BASE_IMAGE_LIMIT` | `20` | Cap on advertised tags (newest first) |
 | `RUNNER_BASE_IMAGE_REFRESH_SECONDS` | `3600` | Catalog re-fetch cadence |
 
-### Image build (required)
-
-| Env | Default | Purpose |
-| --- | --- | --- |
-| `RUNNER_IMAGE_REPOSITORY` | _(required)_ | Registry repo for per-app images; tag = bundle hash |
-| `RUNNER_BUILD_NAMESPACE` | `telo-builds` | Namespace the trusted Kaniko build Jobs run in |
-| `RUNNER_BUILDER_IMAGE` | `gcr.io/kaniko-project/executor:latest` | Image builder |
-| `RUNNER_BUILD_TIMEOUT_SECONDS` | `600` | Build Job deadline / wait budget |
-| `RUNNER_REGISTRY_INSECURE` | `false` | Push/pull over HTTP / self-signed |
-| `RUNNER_REGISTRY_API_URL` | _(unset → always build)_ | HTTP(S) base for the manifest existence check (authenticated via the push Secret) |
-| `RUNNER_REGISTRY_PUSH_SECRET` | _(unset)_ | dockerconfig Secret (in `telo-builds`) Kaniko pushes with; also authenticates the existence check |
-| `RUNNER_IMAGE_PULL_SECRET` | _(unset)_ | dockerconfig Secret (in `telo-sessions`) the kubelet pulls per-app images with |
-
 ## Deploy (Helm)
 
-The runner **requires a registry to build into** (there is no in-pod install
-fallback), so point it at one your cluster's kubelet can pull from:
+The chart is published as an OCI artifact at
+`oci://ghcr.io/telorun/charts/k8s-runner`:
 
 ```bash
-helm install telo-runner ./chart \
-  --set build.repository=registry.example.com/telo-sessions \
-  --set-file registry.dockerconfigjson=./dockerconfig.json \  # private-registry auth
+helm install telo-runner oci://ghcr.io/telorun/charts/k8s-runner \
+  --set watch.enabled=true \
   --set session.runtimeClass=gvisor
 ```
 
-For a private registry, `registry.dockerconfigjson` creates the dockerconfig
-Secret in **both** namespaces (push in `telo-builds`, pull in `telo-sessions`) and
-wires `RUNNER_REGISTRY_PUSH_SECRET` + `RUNNER_IMAGE_PULL_SECRET` — the kubelet
-needs the pull copy because the per-app image is private. (Or manage the Secrets
-yourself and reference them via `build.pushSecretName` / `build.pullSecretName`.)
-The push Secret doubles as the credential for the manifest existence check, so
-the runner can see an already-built image in a private registry and skip the
-rebuild — without it a private registry answers `401` and every run rebuilds.
-A no-auth registry needs none of this.
+Helm resolves the newest release when no `--version` is given; pass one to pin.
+From a checkout, `./chart` works the same way and is what you want when changing
+the chart itself.
+
+**The chart's version IS the runner's.** `version` and `appVersion` both carry
+`@telorun/k8s-runner`'s package version, stamped in the release PR and checked on
+every PR — so chart `0.13.0` installs runner image `0.13.0`, with no lookup
+table. That is also why `image.tag` defaults to empty and resolves to the chart's
+own `appVersion` rather than to `latest`: `--version 0.13.0` has to mean one
+thing, where a floating tag meant whatever it had moved to overnight.
 
 The chart provisions the static scaffolding: the runner Deployment (single
 replica — the registry is in-memory and the runner reaps orphaned pods on boot),
-Service, scoped RBAC, the `telo-runner` / restricted-PSS `telo-sessions` /
-baseline-PSS `telo-builds` namespaces, a `ResourceQuota`, and NetworkPolicies
-(session pod-to-pod isolation + the build namespace's registry egress). The
-runner creates per-session and per-build objects at runtime.
+Service, scoped RBAC, the `telo-runner` and restricted-PSS `telo-sessions`
+namespaces, a `ResourceQuota`, and the session pod-to-pod NetworkPolicy. The
+runner creates per-session objects at runtime. Nothing else is required — no
+image registry, no build namespace, no push credentials.
+
+For a kernel image or an operator catalog image held in a **private registry**,
+create the dockerconfigjson Secret in `telo-sessions` yourself and point
+`session.imagePullSecret` at it; the kubelet pulls with it.
+
+### Routing layer
+
+Session hosts are `<port>-<sessionId>.<base-domain>` — a single label, so one
+wildcard DNS record and one wildcard cert cover every session. **Both current
+routing APIs are supported**, because clusters ship Ingress, Gateway API, or
+both, and hardcoding either leaves the runner unroutable on the rest.
+
+`sessionRouting.mode` picks the layer:
+
+| mode | behaviour |
+| --- | --- |
+| `auto` (default) | Resolve from what is **configured**, then from what the cluster serves |
+| `ingress` | `networking.k8s.io/v1` Ingress |
+| `gateway` | `gateway.networking.k8s.io` HTTPRoute (`v1`, falling back to `v1beta1`) |
+| `none` | Publish nothing — logs-only even with a base domain set |
+
+`auto` reads configuration before installation, and that order is the point: a
+named Gateway wins, then a configured IngressClass, then a **default-marked**
+IngressClass (`ingressclass.kubernetes.io/is-default-class` — the cluster has
+nominated where an unqualified Ingress goes, and unqualified is what this runner
+creates), and only then does it look at what merely exists. **Gateway API CRDs are frequently present without being the intended
+path**, so "the API exists" is not evidence of intent. Where two usable layers
+exist and nothing was configured, the runner **refuses to start** rather than
+guessing — a wrong guess publishes routing objects nothing reconciles, which
+produces a healthy pod and a 404 on every URL, with nothing reported anywhere.
+
+```bash
+# Gateway API
+helm install telo-runner ./chart \
+  --set sessionRouting.mode=gateway \
+  --set sessionRouting.baseDomain=telo.run \
+  --set sessionRouting.gateway.name=public \
+  --set sessionRouting.gateway.namespace=gateway-system \
+  --set sessionRouting.dataPlaneNamespace=gateway-system
+```
+
+The Gateway needs a listener whose hostname covers `*.<base-domain>` and whose
+`allowedRoutes.namespaces` admits `telo-sessions`. A route it does not admit is
+reported per session with the controller's own reason (`NotAllowedByListeners`).
 
-The optional in-cluster registry (`--set registry.enabled=true --set
-build.insecureRegistry=true`) derives `build.repository` for you, but works only
-on clusters whose **nodes are configured to trust it** — otherwise an external/
-cloud registry is simpler. Installing with neither a `build.repository` nor
-`registry.enabled` is rejected at template time.
+**Upgrading from `sessionIngress.*`** is a breaking values change and the chart
+refuses the old keys rather than ignoring them — Helm drops unknown values
+silently, so an un-migrated file would otherwise boot a runner that logs
+`session routing disabled (logs-only)` and drops every session URL.
+
+> **One HTTPRoute per port.** Gateway API scopes `hostnames` to the whole route
+> while a rule matches on path, never host — so a single route carrying every
+> session hostname would send them all to whichever rule matched `/` first. An
+> Ingress rule owns its host, which is why that layer needs only one object.
+
+**`sessionRouting.dataPlaneNamespace` is not optional when routing is on.** The
+session NetworkPolicy admits traffic from that namespace only; without it the
+route programs correctly and the workload is still unreachable.
+
+### Route verification
+
+The runner already dials each declared port from its own network — that proves
+the app is **listening** and says nothing about whether traffic can **reach** it.
+So it separately verifies that what it published was actually programmed, and
+reports each host as `pending` → `programmed` / `unprogrammed` on the session
+event stream (`type: "route"`). Reported, never fatal: a slow controller and an
+absent one look alike for the first few seconds.
+
+Gateway API answers this precisely, from the `Accepted` / `ResolvedRefs`
+conditions a controller writes. Ingress has no rejection signal — a controller
+that refuses a rule simply never writes status — so there an unclaimed route is
+caught by the timeout rather than by a reason the cluster gave.
 
 ### Origin TLS (Cloudflare et al.)
 
+**Ingress mode only.** Under Gateway API the origin certificate belongs to the
+Gateway listener's own `certificateRefs`; setting `SESSION_INGRESS_TLS_SECRET`
+alongside `mode: gateway` is refused at boot rather than silently ignored.
+
 To have the per-session Ingress present an origin cert (so an upstream like
 Cloudflare in **Full (Strict)** mode validates the origin), give the chart a
 `kubernetes.io/tls` Secret in `telo-sessions`. The cert must cover the wildcard
-`*.<sessionIngress.baseDomain>` — session hosts are a single label
+`*.<sessionRouting.baseDomain>` — session hosts are a single label
 (`<port>-<sessionId>.<base-domain>`). Two ways:
 
 ```bash
 # A — reference a Secret you manage in telo-sessions (cert-manager, your own sync)
-helm install telo-runner ./chart --set sessionIngress.tls.secretName=telo-origin-tls
+helm install telo-runner ./chart --set sessionRouting.ingress.tls.secretName=telo-origin-tls
 
 # B — let the chart create the Secret from your cert + key
 helm install telo-runner ./chart \
-  --set-file sessionIngress.tls.cert=origin.pem \
-  --set-file sessionIngress.tls.key=origin.key
+  --set-file sessionRouting.ingress.tls.cert=origin.pem \
+  --set-file sessionRouting.ingress.tls.key=origin.key
 ```
 
 Either wires `SESSION_INGRESS_TLS_SECRET`, and the runner stamps a `spec.tls`
 block on every session Ingress. Leave all three empty to skip TLS at the origin
 (terminated entirely upstream).
 
-> **Egress notes.** (1) The kubelet pulls session images directly and does **not**
-> use cluster DNS, so the in-cluster registry only works where nodes trust it
-> (e.g. containerd `registries.conf`). (2) Core NetworkPolicy is CIDR-only and
-> cannot express the package-registry FQDN allowlist the build namespace needs —
-> use a CNI with FQDN policy (Cilium) or an egress proxy to tighten it.
+> **Egress note.** Core NetworkPolicy is CIDR-only and cannot express the
+> package-registry FQDN allowlist the session namespace needs — use a CNI with
+> FQDN policy (Cilium) or an egress proxy to tighten it.
 
 ## Development
 
 ```bash
 pnpm --filter @telorun/k8s-runner build   # tsc
-pnpm --filter @telorun/k8s-runner test    # vitest (limits clamp, tar, bundle token)
+pnpm --filter @telorun/k8s-runner test    # vitest (pod specs, limits clamp, tar, API errors)
 ```
 
 The Kubernetes backend can't be exercised without a cluster; unit tests cover the
-backend-independent logic (limit clamping, the tar writer, bundle tokens).
+backend-independent logic (the pod specs, limit clamping, the tar writer, and
+what an API rejection is allowed to tell a client).

package/dist/bundle-store.d.ts

@@ -1,9 +1,9 @@
 import type { FastifyInstance } from "fastify";
 import type { RunBundle } from "@telorun/runner-core";
 /**
- * Holds image-build contexts in memory and serves them over a tokenized,
- * cluster-internal URL the build Job's initContainer fetches once. The
- * per-build unguessable token prevents cross-build disclosure; the entry is
+ * Holds session bundles in memory and serves them over a tokenized,
+ * cluster-internal URL the session pod's initContainer fetches once. The
+ * per-session unguessable token prevents cross-session disclosure; the entry is
  * dropped after first fetch (or explicitly on cleanup).
  */
 export declare class BundleStore {
@@ -11,16 +11,9 @@ export declare class BundleStore {
     private readonly bundles;
     constructor(selfUrl: string);
     /**
-     * Stages an image-build context — the bundle plus a generated `Dockerfile` at
-     * the context root — and returns the tokenized, single-use URL the build Job's
-     * initContainer fetches. Keyed by `id` (a build id).
-     */
-    stageBuildContext(id: string, bundle: RunBundle, dockerfile: string): Promise<string>;
-    /**
-     * Stages the raw session bundle (no Dockerfile) and returns the tokenized,
-     * single-use URL the session Pod's body-delivery initContainer fetches into
-     * `/app`. Keyed by `sessionId`. The image is keyed only on the dependency
-     * closure, so the per-session body is delivered here at boot rather than baked.
+     * Stages the session bundle and returns the tokenized, single-use URL the
+     * session Pod's body-delivery initContainer fetches into `/app`. Keyed by
+     * `sessionId`.
      */
     stageSessionBundle(sessionId: string, bundle: RunBundle): Promise<string>;
     private stage;

package/dist/bundle-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bundle-store.d.ts","sourceRoot":"","sources":["../src/bundle-store.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AActD;;;;;GAKG;AACH,qBAAa,WAAW;IAGV,OAAO,CAAC,QAAQ,CAAC,OAAO;IAFpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmC;gBAE9B,OAAO,EAAE,MAAM;IAE5C;;;;OAIG;IACG,iBAAiB,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAO3F;;;;;OAKG;IACG,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC;YAIjE,KAAK;IAUnB,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAM7B,OAAO,CAAC,IAAI;IASZ,yEAAyE;IACzE,aAAa,CAAC,GAAG,EAAE,eAAe,GAAG,IAAI;CAiB1C"}
+{"version":3,"file":"bundle-store.d.ts","sourceRoot":"","sources":["../src/bundle-store.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AActD;;;;;GAKG;AACH,qBAAa,WAAW;IAGV,OAAO,CAAC,QAAQ,CAAC,OAAO;IAFpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmC;gBAE9B,OAAO,EAAE,MAAM;IAE5C;;;;OAIG;IACG,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC;YAIjE,KAAK;IAUnB,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAM7B,OAAO,CAAC,IAAI;IASZ,yEAAyE;IACzE,aAAa,CAAC,GAAG,EAAE,eAAe,GAAG,IAAI;CAiB1C"}

package/dist/bundle-store.js

@@ -4,9 +4,9 @@ import { makeBundleTarGz } from "./tar.js";
  *  stuck/never-started Pod can't grow the store unbounded. */
 const STAGING_TTL_MS = 5 * 60 * 1000;
 /**
- * Holds image-build contexts in memory and serves them over a tokenized,
- * cluster-internal URL the build Job's initContainer fetches once. The
- * per-build unguessable token prevents cross-build disclosure; the entry is
+ * Holds session bundles in memory and serves them over a tokenized,
+ * cluster-internal URL the session pod's initContainer fetches once. The
+ * per-session unguessable token prevents cross-session disclosure; the entry is
  * dropped after first fetch (or explicitly on cleanup).
  */
 export class BundleStore {
@@ -16,21 +16,9 @@ export class BundleStore {
         this.selfUrl = selfUrl;
     }
     /**
-     * Stages an image-build context — the bundle plus a generated `Dockerfile` at
-     * the context root — and returns the tokenized, single-use URL the build Job's
-     * initContainer fetches. Keyed by `id` (a build id).
-     */
-    async stageBuildContext(id, bundle, dockerfile) {
-        return this.stage(id, {
-            entryRelativePath: bundle.entryRelativePath,
-            files: [...bundle.files, { relativePath: "Dockerfile", contents: dockerfile }],
-        });
-    }
-    /**
-     * Stages the raw session bundle (no Dockerfile) and returns the tokenized,
-     * single-use URL the session Pod's body-delivery initContainer fetches into
-     * `/app`. Keyed by `sessionId`. The image is keyed only on the dependency
-     * closure, so the per-session body is delivered here at boot rather than baked.
+     * Stages the session bundle and returns the tokenized, single-use URL the
+     * session Pod's body-delivery initContainer fetches into `/app`. Keyed by
+     * `sessionId`.
      */
     async stageSessionBundle(sessionId, bundle) {
         return this.stage(sessionId, bundle);

package/dist/bundle-store.js.map

@@ -1 +1 @@
-{"version":3,"file":"bundle-store.js","sourceRoot":"","sources":["../src/bundle-store.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"bundle-store.js","sourceRoot":"","sources":["../src/bundle-store.ts"],"names":[],"mappings":"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"}

package/dist/capabilities.d.ts

@@ -19,9 +19,9 @@ export interface KubernetesRunnerCapabilitiesOptions {
  *  studio renders an editable dropdown constrained to that allowlist — which the
  *  session route re-validates server-side. Without a catalog (disabled /
  *  first-fetch failure) the list collapses to the single `defaultImage` (locked
- *  via `enforced`). `pullPolicy` is client-editable: `always` re-pulls the base
- *  image when its tag has moved upstream (rebuilding the per-app image), which
- *  is how a picked moving tag like `latest-slim` stays current.
+ *  via `enforced`). `pullPolicy` is client-editable and is the pod's own
+ *  `imagePullPolicy`: `always` re-pulls the kernel image, which is how a picked
+ *  moving tag like `latest-slim` stays current.
  *
  *  `terms`, when set (operator-provided via RUNNER_TERMS_*), are enforced: a
  *  session won't start until the client acknowledges the current version. */

package/dist/capabilities.js

@@ -5,9 +5,9 @@ import { sessionConfigSchema, } from "@telorun/runner-core";
  *  studio renders an editable dropdown constrained to that allowlist — which the
  *  session route re-validates server-side. Without a catalog (disabled /
  *  first-fetch failure) the list collapses to the single `defaultImage` (locked
- *  via `enforced`). `pullPolicy` is client-editable: `always` re-pulls the base
- *  image when its tag has moved upstream (rebuilding the per-app image), which
- *  is how a picked moving tag like `latest-slim` stays current.
+ *  via `enforced`). `pullPolicy` is client-editable and is the pod's own
+ *  `imagePullPolicy`: `always` re-pulls the kernel image, which is how a picked
+ *  moving tag like `latest-slim` stays current.
  *
  *  `terms`, when set (operator-provided via RUNNER_TERMS_*), are enforced: a
  *  session won't start until the client acknowledges the current version. */
@@ -30,7 +30,7 @@ export function kubernetesRunnerCapabilities(opts) {
                 imageDefault: defaultImage,
                 enforced: true,
                 imageEnum,
-                pullPolicyDescription: "Base-image freshness. `always` rebuilds the session image when the base tag has moved upstream (Docker Hub only); `missing` and `never` reuse the cached build.",
+                pullPolicyDescription: "Kernel-image freshness, applied as the Pod's imagePullPolicy. `always` re-pulls on every session, so a moving tag like `latest-slim` picks up a new release. `missing` pulls only when the node has no copy. `never` never pulls at all — on a node that has not already cached the image the session fails to start (ErrImageNeverPull), so it suits a cluster that pre-loads its images and nothing else.",
             }),
         },
         terms,

package/dist/capabilities.js.map

@@ -1 +1 @@
-{"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,GAGpB,MAAM,sBAAsB,CAAC;AAiB9B;;;;;;;;;;;6EAW6E;AAC7E,MAAM,UAAU,4BAA4B,CAC1C,IAAyC;IAEzC,MAAM,EAAE,WAAW,EAAE,WAAW,EAAE,YAAY,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,IAAI,CAAC;IAC1E,OAAO;QACL,WAAW;QACX,WAAW;QACX,QAAQ,EAAE;YACR,qEAAqE;YACrE,0EAA0E;YAC1E,kCAAkC;YAClC,EAAE,EAAE,CAAC,KAAK,EAAE,SAAS,CAAC;YACtB,KAAK,EAAE,IAAI;YACX,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,GAAG,CAAC,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC1E;QACD,MAAM,EAAE;YACN,MAAM,EAAE,mBAAmB,CAAC;gBAC1B,YAAY,EAAE,YAAY;gBAC1B,QAAQ,EAAE,IAAI;gBACd,SAAS;gBACT,qBAAqB,EACnB,iKAAiK;aACpK,CAAC;SACH;QACD,KAAK;KACN,CAAC;AACJ,CAAC"}
+{"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,GAGpB,MAAM,sBAAsB,CAAC;AAiB9B;;;;;;;;;;;6EAW6E;AAC7E,MAAM,UAAU,4BAA4B,CAC1C,IAAyC;IAEzC,MAAM,EAAE,WAAW,EAAE,WAAW,EAAE,YAAY,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,IAAI,CAAC;IAC1E,OAAO;QACL,WAAW;QACX,WAAW;QACX,QAAQ,EAAE;YACR,qEAAqE;YACrE,0EAA0E;YAC1E,kCAAkC;YAClC,EAAE,EAAE,CAAC,KAAK,EAAE,SAAS,CAAC;YACtB,KAAK,EAAE,IAAI;YACX,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,GAAG,CAAC,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC1E;QACD,MAAM,EAAE;YACN,MAAM,EAAE,mBAAmB,CAAC;gBAC1B,YAAY,EAAE,YAAY;gBAC1B,QAAQ,EAAE,IAAI;gBACd,SAAS;gBACT,qBAAqB,EACnB,6YAA6Y;aAChZ,CAAC;SACH;QACD,KAAK;KACN,CAAC;AACJ,CAAC"}