urun-cli 0.7.1__tar.gz → 0.7.3__tar.gz

{urun_cli-0.7.1 → urun_cli-0.7.3}/CHANGELOG.md

@@ -1,3 +1,21 @@
+## 0.7.3
+
+- `urun serve --urun-wheel <version>` — pin a deploy to a specific urun wheel
+  version (e.g. `2.0.0+1497.g8439ef6b3b77`). The pin renders
+  `URUN_WHEEL_VERSION` into the generated serve shim beside the `--warm` pin,
+  BEFORE the bundled-app import, and is content-bearing: it changes the
+  manifest hash, so a wheel roll is a NEW RELEASE (the shared reconciler's
+  wheel-roll path) — never a re-register of an immutable release, which the
+  control plane's deploy-register refuses with a 409. Omitted = byte-identical
+  shim (no pin line).
+
+## 0.7.2
+
+- Fix the generated serve shim: the `--warm N` pin assigns `URUN_SERVE_WARM`
+  as a STRING. The 0.7.1 shim assigned an int literal, which raises
+  `TypeError: str expected, not int` at `os.encode` inside any build/import —
+  the exact first-build failure the agents-a1-fp8 shared deploy hit.
+
 ## 0.7.1
 
 - `urun serve --warm N` — an idle replica floor on a serve deploy (the

{urun_cli-0.7.1 → urun_cli-0.7.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: urun-cli
-Version: 0.7.1
+Version: 0.7.3
 Summary: End-user CLI for deploying apps to urun
 Project-URL: Homepage, https://urun.sh
 Project-URL: Repository, https://github.com/urun-sh/urun-cli

{urun_cli-0.7.1 → urun_cli-0.7.3}/pyproject.toml

@@ -20,7 +20,7 @@ name = "urun-cli"
 # so every merge remains on the already-published version until this value is
 # advanced. Wiring semantic-release into CI remains separate work; this patch
 # bump is the minimal release unblock (post-v0.6.3 fixes + the Rust feature minor).
-version = "0.7.1"
+version = "0.7.3"
 description = "End-user CLI for deploying apps to urun"
 readme = "README.md"
 requires-python = ">=3.11"

{urun_cli-0.7.1 → urun_cli-0.7.3}/src/urun/catalog.py

@@ -384,7 +384,7 @@ ENGINE_DEPS: dict[str, list[str]] = {
         "pillow>=10.0.0",
         "openimageio",
         "cloudpickle>=3.1",
-        "huggingface_hub[hf_transfer]>=0.30.0,<1.0.0",
+        "huggingface_hub>=1.5.0,<2.0",
         "sentencepiece",
     ],
     "t2av": [
@@ -435,7 +435,7 @@ ENGINE_DEPS: dict[str, list[str]] = {
         "pillow>=10.0.0",
         "openimageio",
         "cloudpickle>=3.1",
-        "huggingface_hub[hf_transfer]>=0.30.0,<1.0.0",
+        "huggingface_hub>=1.5.0,<2.0",
         "sentencepiece",
         "nvidia-cuda-nvcc==13.0.88",
         "nvidia-cuda-crt==13.0.88",

{urun_cli-0.7.1 → urun_cli-0.7.3}/src/urun/cli.py

@@ -2965,6 +2965,17 @@ def _run_demo_frontend(
     )
     if launch.token_expires_at:
         print(f"Browser token expires: {launch.token_expires_at}")
+    if launch.principal_actor_id:
+        print(
+            f"Browser token identity: bound to your API key's principal "
+            f"(actor {launch.principal_actor_id}) — this session can re-attach "
+            "across `urun dev --attach` runs for this app"
+        )
+    else:
+        print(
+            "Browser token identity: a fresh per-invocation identity (this API "
+            "key has no resolvable principal)"
+        )
     print(
         f"Token endpoint: {launch.token_url} (re-mints silently; a re-mint gates NEW "
         "session starts only — live sessions keep running)"

{urun_cli-0.7.1 → urun_cli-0.7.3}/src/urun/client_tokens.py

@@ -158,7 +158,8 @@ def build_client_token_request(
     allowed_functions: list[str],
     allowed_origins: list[str] | None,
     max_session_s: int | None,
-    subject: str,
+    subject: str | None = None,
+    bind_principal: bool = False,
     dev: bool = False,
     metadata: dict[str, Any] | None = None,
 ) -> dict[str, Any]:
@@ -175,6 +176,15 @@ def build_client_token_request(
     the browser can never ask to be resolved. Omitted entirely when false,
     like every other optional field here: every non-dev mint
     send a body that does not mention dev mode at all.
+
+    ``bind_principal`` (ENG-297) asks the server to derive the subject
+    itself from the API key's creator (``client-user:<principalActorId>``)
+    instead of accepting one from the caller — mutually exclusive with
+    ``subject`` (the server 400s if both are sent; this mirrors that
+    locally, same convention as every other bound here). Omit both to keep
+    minting an unscoped ad-hoc subject the old way (nothing in this CLI
+    does that anymore, but the parameter combination stays legal for direct
+    callers/tests).
     """
     if not isinstance(expires_in, int) or isinstance(expires_in, bool):
         raise UrunError("client token expires_in must be an integer")
@@ -214,7 +224,14 @@ def build_client_token_request(
         not isinstance(max_session_s, int) or isinstance(max_session_s, bool) or max_session_s < 1
     ):
         raise UrunError("client token max_session_s must be a positive integer")
-    if not subject or len(subject) > CLIENT_TOKEN_MAX_SUBJECT_LENGTH:
+    if not isinstance(bind_principal, bool):
+        raise UrunError("client token bind_principal must be a boolean")
+    if bind_principal and subject is not None:
+        raise UrunError(
+            "client token bind_principal and subject are mutually exclusive — "
+            "bind_principal derives the subject server-side"
+        )
+    if not bind_principal and (not subject or len(subject) > CLIENT_TOKEN_MAX_SUBJECT_LENGTH):
         raise UrunError(
             f"client token subject must be 1..{CLIENT_TOKEN_MAX_SUBJECT_LENGTH} characters"
         )
@@ -227,8 +244,11 @@ def build_client_token_request(
     body: dict[str, Any] = {
         "expires_in": expires_in,
         "allowed_functions": list(allowed_functions),
-        "subject": subject,
     }
+    if subject is not None:
+        body["subject"] = subject
+    if bind_principal:
+        body["bind_principal"] = True
     if allowed_origins is not None:
         body["allowed_origins"] = list(allowed_origins)
     if max_session_s is not None:
@@ -245,6 +265,10 @@ class MintedToken:
     token: str
     expires_at: str
     org_id: str
+    # ENG-297: the claim-verified principal actor id, present only when the
+    # mint asked for bind_principal and it was resolved server-side. Absence
+    # is the normal unbound case, never an error.
+    principal_actor_id: str | None = None
 
 
 class ClientTokenMinter:
@@ -294,14 +318,55 @@ class ClientTokenMinter:
                         "client-token response did not include a positive integer expires_in"
                     )
                 expires_at = payload.get("expires_at")
+                principal_actor_id = payload.get("principal_actor_id")
+                # A bind_principal request answered with a PRESENT but
+                # malformed principal_actor_id (empty string, wrong type) is a
+                # server contract violation, not "unbound" — silently
+                # coercing it to None would make the CLI print "no resolvable
+                # principal" for a session the server actually DID bind,
+                # masking a bug instead of failing loud like every other
+                # contract check above. An ABSENT key is different: it is the
+                # expected shape from a pre-ENG-297 server that doesn't know
+                # the field at all (ignores bind_principal, mints with its own
+                # random subject) — the accepted deploy-lag scenario, not a
+                # bug — so it degrades to the unbound case exactly as before.
+                if (
+                    self._body.get("bind_principal") is True
+                    and "principal_actor_id" in payload
+                    and (not isinstance(principal_actor_id, str) or not principal_actor_id)
+                ):
+                    raise UrunError(
+                        "client-token response requested bind_principal but included a "
+                        "malformed principal_actor_id"
+                    )
                 self._minted = MintedToken(
                     token=token,
                     expires_at=expires_at if isinstance(expires_at, str) else "",
                     org_id=org_id,
+                    principal_actor_id=(
+                        principal_actor_id if isinstance(principal_actor_id, str) else None
+                    ),
                 )
                 self._remint_at = now + max(expires_in - self._skew, 1)
             return self._minted
 
+    def replace_body(self, body: dict[str, Any]) -> None:
+        """Swap the mint body for THIS minter's remaining life — every future
+        (re-)mint uses it, not just the next one.
+
+        The ONLY caller is launch_auth.py's bind_principal fallback: the
+        first mint discovers this API key has no resolvable principal, so
+        every mint for the rest of this process must use the legacy nonce
+        subject instead — never retry bind_principal again for this launch.
+        Forces an immediate re-mint (clears the cached token) so the swap
+        takes effect on the very next :meth:`current`, not after some stale
+        remint-skew window.
+        """
+        with self._lock:
+            self._body = body
+            self._minted = None
+            self._remint_at = 0.0
+
 
 class _TokenRequestHandler(BaseHTTPRequestHandler):
     """Serve scoped tokens and browser diagnostics for a local demo.

{urun_cli-0.7.1 → urun_cli-0.7.3}/src/urun/dev.py

@@ -1442,6 +1442,20 @@ def _maybe_launch_frontend(
         "origins: unrestricted (dev only); "
         f"max session: {f'{launch.max_session_s}s' if launch.max_session_s else 'uncapped (ends with the CLI)'})",
     )
+    mux.line(
+        "frontend | ",
+        (
+            f"browser token identity: bound to this API key's principal "
+            f"(actor {launch.principal_actor_id}) — this session can re-attach "
+            "across `urun dev` runs for this app"
+        )
+        if launch.principal_actor_id
+        else (
+            "browser token identity: a fresh per-invocation identity (this API "
+            "key has no resolvable principal — sessions will not re-attach "
+            "across runs; see the warning above)"
+        ),
+    )
     # Say the quiet part out loud: the scope above names the BASE app while the
     # dev loop deploys to `<app>--dev`, which reads like a mismatch to anyone
     # watching. It is the contract — the page asks for the base name and the

{urun_cli-0.7.1 → urun_cli-0.7.3}/src/urun/launch_auth.py

@@ -18,6 +18,7 @@ from __future__ import annotations
 
 import re
 import secrets
+import sys
 import urllib.parse
 from collections.abc import Callable, Sequence
 from dataclasses import dataclass, field
@@ -46,12 +47,16 @@ EVENTS_URL_ENV = "NEXT_PUBLIC_URUN_EVENTS_URL"
 # identity as a pure hash of (v3, orgId, token subject, app, function,
 # concurrency key) — services/session-api-ts/src/logical-id.ts:86 — and the
 # SDK sends no explicit id when the app names no sessionKey
-# (urun-ts packages/core/src/app.ts:162). The mint subject below is fixed for
-# the whole invocation, so the CLI's session and the page it launches derive
-# the SAME id and the platform's attach-or-create binds them together. There
-# is deliberately NO session-key env var: the launcher has nothing to publish.
-# Limitation, stated not hidden: an app passing its OWN sessionKey derives a
-# different id and lands on the platform's coalesce path, not a clean attach.
+# (urun-ts packages/core/src/app.ts:162). The mint subject is fixed for the
+# whole invocation — and, for a principal-bound mint (the default, ENG-297),
+# fixed ACROSS invocations too — so the CLI's session and the page it
+# launches derive the SAME id and the platform's attach-or-create binds them
+# together; a principal-bound launch additionally reattaches a PRIOR run's
+# still-live session for the same actor and app, not just the one page in
+# this process. There is deliberately NO session-key env var: the launcher
+# has nothing to publish. Limitation, stated not hidden: an app passing its
+# OWN sessionKey derives a different id and lands on the platform's coalesce
+# path, not a clean attach.
 # Next.js's built-in dev port, used when a frontend's dev script names none.
 DEFAULT_FRONTEND_PORT = 3000
 # The loopback host `urun dev` binds its token endpoint and pins the browser
@@ -62,6 +67,14 @@ DEFAULT_LAUNCH_HOST = "127.0.0.1"
 # and fails loud — another launch path must be added HERE deliberately.
 _LAUNCH_COMMANDS = frozenset({"dev"})
 
+# ENG-297: the session API's structured error code for "bind_principal was
+# requested but this API key's creator has no resolvable principal" (a
+# legacy key minted before member API keys existed, or an admin-minted key
+# with no creator) — urun-infra services/session-api-ts's
+# handleClientTokenMint. A NAMED constant, not a literal, so the catch below
+# and its test pin ONE string — never message matching.
+PRINCIPAL_UNRESOLVABLE_CODE = "principal_not_available"
+
 
 def launch_auth_label(command: str) -> str:
     """Inert SDK-side auth-provider label (the session API ignores
@@ -160,7 +173,13 @@ def _display_session_url(url: str) -> str:
     return urllib.parse.urlunsplit((parts.scheme, netloc, parts.path, "", ""))
 
 
-def mint_launch_client_token(minter: Any, session_url: str, *, command: str | None = None) -> Any:
+def mint_launch_client_token(
+    minter: Any,
+    session_url: str,
+    *,
+    command: str | None = None,
+    legacy_body_factory: Callable[[], dict[str, Any]] | None = None,
+) -> Any:
     """Mint the launch's first scoped client token, failing with a clear story.
 
     The mint is the first request the launch sends to the SESSION API, and
@@ -172,6 +191,20 @@ def mint_launch_client_token(minter: Any, session_url: str, *, command: str | No
     (Owner ruling 2026-08-03: remedy first, keep it short, and never name
     internal deployment topology — a customer reading this has a support
     issue, and a urun developer knows which host to point the flag at.)
+
+    When ``legacy_body_factory`` is given (only
+    :func:`prepare_frontend_launch_auth` passes one, when the primary mint
+    requested ``bind_principal``), a mint that fails with the server's
+    structured "no resolvable principal" 400
+    (:data:`PRINCIPAL_UNRESOLVABLE_CODE`) is retried EXACTLY ONCE against a
+    freshly-built legacy body (the old per-invocation nonce subject) — this
+    API key has no resolvable principal (a legacy or admin-minted key), so
+    the launch falls back rather than hard-failing a command that used to
+    work. The minter's body is swapped IN PLACE
+    (:meth:`ClientTokenMinter.replace_body`), so every LATER silent re-mint
+    (the TokenEndpoint's) also uses the legacy subject — bind_principal is
+    never retried again for this process. A failure on the retry itself
+    propagates raw, exactly like any other mint failure.
     """
     try:
         return minter.current()
@@ -186,6 +219,20 @@ def mint_launch_client_token(minter: Any, session_url: str, *, command: str | No
                 f"The URL tried ({_display_session_url(session_url)}) does not "
                 "serve POST /api/client-tokens."
             ) from exc
+        if (
+            legacy_body_factory is not None
+            and exc.status == 400
+            and exc.code == PRINCIPAL_UNRESOLVABLE_CODE
+        ):
+            print(
+                "warning: this API key has no resolvable principal — the browser "
+                "session falls back to a fresh per-invocation identity (it will not "
+                "re-attach to a prior `urun dev` run for this app). Re-create the key "
+                "as a member API key to fix this.",
+                file=sys.stderr,
+            )
+            minter.replace_body(legacy_body_factory())
+            return minter.current()
         raise
 
 
@@ -279,6 +326,10 @@ class FrontendLaunchAuth:
     allowed_functions: list[str]
     allowed_origins: list[str]
     max_session_s: int | None
+    # ENG-297: the claim-verified principal this launch's token is bound to,
+    # or None when this API key had no resolvable principal (the legacy
+    # fallback fired — see mint_launch_client_token).
+    principal_actor_id: str | None
     endpoint: TokenEndpoint
     # The launch's token minter — the SessionHolder authenticates its HTTP
     # calls with the same silently-re-minting token the page refreshes from.
@@ -349,20 +400,48 @@ def prepare_frontend_launch_auth(
     # Dev frontends may be opened through any loopback hostname or port. The
     # session API treats an absent claim as unrestricted; demo remains pinned.
     token_allowed_origins = None if dev else endpoint_allowed_origins
+
+    # The DEFAULT (bind_principal=True) asks the platform to derive the
+    # subject itself from the API key's creator (`client-user:<principalActorId>`)
+    # — stable across BOTH re-mints AND invocations, so the same actor
+    # launching the same app twice reattaches the SAME session (ENG-297)
+    # instead of minting a fresh identity every process run. `_legacy_nonce_body`
+    # below is the ONLY fallback: an API key with no resolvable principal
+    # (legacy or admin-minted) still gets a working launch, just back to the
+    # old per-invocation nonce — stable across re-mints for THIS launch,
+    # unique per invocation, so two such launches never coalesce their
+    # sessions.
     mint_body = build_client_token_request(
         expires_in=DEMO_TOKEN_EXPIRES_IN_S,
         allowed_functions=allowed_functions,
         allowed_origins=token_allowed_origins,
         max_session_s=max_session_s,
-        # Stable across re-mints (same actor keeps gating new starts for THIS
-        # launch), unique per invocation (two launches never coalesce their
-        # sessions).
-        subject=f"{command}:{app_slug}:{secrets.token_hex(4)}",
+        bind_principal=True,
         dev=dev,
         metadata={"source": "urun-cli", "command": command, "app": app_slug},
     )
+
+    def _legacy_nonce_body() -> dict[str, Any]:
+        # Rebuilt lazily — only if bind_principal actually fails — from the
+        # SAME scope/dev/metadata as the bound attempt; only the subject
+        # strategy differs. A fresh secrets.token_hex(4) each call: this is
+        # only ever invoked once per process (the fallback retries exactly
+        # once), so "fresh" here still means "one nonce for the whole
+        # invocation" exactly as before.
+        return build_client_token_request(
+            expires_in=DEMO_TOKEN_EXPIRES_IN_S,
+            allowed_functions=allowed_functions,
+            allowed_origins=token_allowed_origins,
+            max_session_s=max_session_s,
+            subject=f"{command}:{app_slug}:{secrets.token_hex(4)}",
+            dev=dev,
+            metadata={"source": "urun-cli", "command": command, "app": app_slug},
+        )
+
     minter = ClientTokenMinter(create_client_token, mint_body)
-    minted = mint_launch_client_token(minter, session_url, command=command)
+    minted = mint_launch_client_token(
+        minter, session_url, command=command, legacy_body_factory=_legacy_nonce_body
+    )
     endpoint = TokenEndpoint(
         minter,
         endpoint_allowed_origins,
@@ -385,6 +464,7 @@ def prepare_frontend_launch_auth(
         allowed_functions=allowed_functions,
         allowed_origins=token_allowed_origins or [],
         max_session_s=max_session_s,
+        principal_actor_id=minted.principal_actor_id,
         endpoint=endpoint,
         minter=minter,
     )

{urun_cli-0.7.1 → urun_cli-0.7.3}/src/urun/scratch.py

@@ -326,14 +326,33 @@ def capacity_verdict(
 # ---------------------------------------------------------------------------
 
 
-def _scratch_labels(name: str, source_name: str) -> dict[str, str]:
-    return {
+#: THE WEIGHTS-TIER IDENTITY a clone MUST keep. The vineyard fleet controller
+#: (control-plane ``vineyard_fleet.py``) spawns the per-(node, org) vineyardd
+#: for pods matching ``urun.sh/gpu-type,urun.sh/org-id`` and reads the org
+#: from ``urun.sh/org-id-verbatim``; the runtime's armed boot contract then
+#: waits 120 s for that daemon's socket and fails LOUD without it. A clone
+#: that dropped these booted only by luck - when it landed on a node where
+#: its org's daemon was already up for a real pod (dev-usw2 2026-09-10: the
+#: scratch scheduled onto the node hosting another org's daemon and died 7x
+#: on "vineyard daemon socket did not appear"). These label the weights
+#: tier the pod needs, not the materializer / capacity / routing attachment
+#: the clone is detached from - those stay stripped.
+WEIGHTS_TIER_LABELS = ("urun.sh/gpu-type", "urun.sh/org-id", "urun.sh/org-id-verbatim")
+
+
+def _scratch_labels(name: str, source_name: str, source_labels: dict[str, str]) -> dict[str, str]:
+    labels = {
         "app.kubernetes.io/component": SCRATCH_COMPONENT,
         "app.kubernetes.io/managed-by": SCRATCH_MANAGED_BY,
         "app.kubernetes.io/name": name,
         SCRATCH_LABEL: "true",
         SCRATCH_SOURCE_LABEL: source_name,
     }
+    for key in WEIGHTS_TIER_LABELS:
+        value = source_labels.get(key)
+        if value:
+            labels[key] = value
+    return labels
 
 
 def _clean_annotations(annotations: dict[str, str]) -> dict[str, str]:
@@ -529,6 +548,25 @@ def _invalidate_wheel_metadata() -> None:
                 )
 
 
+def _pip_accepts_break_system_packages() -> bool:
+    """Does the copied venv's OWN pip understand ``--break-system-packages``?
+
+    The option (and PEP 668 enforcement itself) landed in pip 23.0: on pip
+    22.x the flag is an unknown option and ``python -m pip install`` exits
+    BEFORE resolving ("no such option"), breaking previously-working
+    overlays. ``derive_scratch_sts`` neither constrains nor upgrades the
+    source venv's pip, so the flag is passed ONLY when this interpreter's
+    pip supports it — where it is needed, it is pip's own PEP 668 opt-out.
+    """
+    try:
+        import pip
+
+        major, minor = (int(part) for part in str(pip.__version__).split(".")[:2])
+    except (ImportError, ValueError, TypeError):
+        return False
+    return (major, minor) >= (23, 0)
+
+
 def _install_and_resolve() -> dict:
     """Install the candidate ONCE and read the EXACT artifact from pip's report.
 
@@ -553,6 +591,12 @@ def _install_and_resolve() -> dict:
             "install",
             "--no-deps",
             "--force-reinstall",
+            # The copied deps venv is a uv-managed interpreter carrying the
+            # PEP 668 EXTERNALLY-MANAGED marker; the overlay is a private
+            # per-pod copy, so pip's own opt-out applies (without it: rc=1,
+            # no readiness). Only offered to pips that HAVE the option —
+            # pip 22.x rejects it before resolving ("no such option").
+            *(("--break-system-packages",) if _pip_accepts_break_system_packages() else ()),
             "--disable-pip-version-check",
             "--report",
             str(REPORT),
@@ -825,7 +869,26 @@ def derive_scratch_sts(
             )
 
     expires_at = (now.astimezone(UTC) + timedelta(hours=ttl_hours)).isoformat(timespec="seconds")
-    labels = _scratch_labels(name, source_name)
+    source_pod_labels = dict(
+        (sts.get("spec", {}).get("template", {}).get("metadata", {}) or {}).get("labels") or {}
+    )
+    # Fail-closed BEFORE any create: the org identity is what the vineyard
+    # fleet controller routes the per-(node, org) daemon by (it reads the
+    # org from ``urun.sh/org-id-verbatim``) and the runtime's armed boot
+    # contract fails loud 120 s in without its socket. ``gpu-type`` stays
+    # optional (a CPU source carries none and needs no vineyard daemon);
+    # a template missing the org pair is NOT a cloneable source — a clone
+    # that silently omits it boots only by luck, then dies.
+    missing_identity = [
+        key for key in (ORG_ID_LABEL, "urun.sh/org-id-verbatim") if not source_pod_labels.get(key)
+    ]
+    if missing_identity:
+        raise UrunError(
+            "the source pod template is missing required org identity "
+            "label(s) — the clone would not be routed to its org's "
+            "vineyard daemon: " + ", ".join(missing_identity)
+        )
+    labels = _scratch_labels(name, source_name, source_pod_labels)
 
     meta = sts["metadata"]
     for key in _SERVER_METADATA_KEYS:

{urun_cli-0.7.1 → urun_cli-0.7.3}/src/urun/serve.py

@@ -63,6 +63,22 @@ CATALOG_URL_ENV = "URUN_CATALOG_URL"
 ANON_KEY_ENVS = ("URUN_CATALOG_ANON_KEY", "URUN_SUPABASE_ANON_KEY")
 
 
+def _urun_wheel_version_type(value: str) -> str:
+    """argparse type for ``--urun-wheel``: a non-empty string, no whitespace.
+
+    The wheel version is embedded verbatim in the generated shim (and compared
+    by the control plane against the recorded release pin), so anything blank
+    or whitespace-carrying is a typo, not a version. Raises argparse's
+    ArgumentTypeError so `urun serve --urun-wheel ""` fails at parse time with
+    a usable message.
+    """
+    if not value or value.split() != [value]:
+        raise argparse.ArgumentTypeError(
+            f"--urun-wheel must be a non-empty version string with no whitespace, got {value!r}"
+        )
+    return value
+
+
 def add_serve_parser(sub: argparse._SubParsersAction) -> None:
     serve_parser = sub.add_parser(
         "serve",
@@ -133,6 +149,20 @@ def _add_serve_model_args(parser: argparse.ArgumentParser) -> None:
             "deploys pass the catalog row's warm (default 0)."
         ),
     )
+    parser.add_argument(
+        "--urun-wheel",
+        dest="urun_wheel",
+        type=_urun_wheel_version_type,
+        default=None,
+        metavar="VERSION",
+        help=(
+            "Pin THIS deploy to a specific urun wheel version (e.g. "
+            "2.0.0+1497.g8439ef6b3b77). Content-bearing: it changes the deploy's "
+            "manifest hash, so a wheel roll is a NEW RELEASE, not a rebuild. "
+            "Shared-endpoint deploys pass the platform's current wheel version. "
+            "Omit = the platform's default wheel resolution."
+        ),
+    )
     parser.add_argument(
         "--entrypoint",
         help=(
@@ -316,6 +346,23 @@ def _validated_exo_pin(args: argparse.Namespace) -> tuple[str | None, str | None
     return exo_class, exo_image
 
 
+def _validated_urun_wheel(value: str | None) -> str | None:
+    """Re-validate the ``--urun-wheel`` pin for Namespace-built call paths.
+
+    argparse already refuses empty/whitespace values (``_urun_wheel_version_type``);
+    a Namespace built in code (tests, future callers) skips argparse, so the pin
+    is checked again here with the SAME rule. The wheel version is CONTENT in
+    the generated shim — a blank value is a config error the deployer must see,
+    never a silently unpinned manifest that fails to change the release hash.
+    """
+    if value is None:
+        return None
+    try:
+        return _urun_wheel_version_type(value)
+    except argparse.ArgumentTypeError as exc:
+        raise UrunError(str(exc)) from None
+
+
 def _build_deploy_args(args: argparse.Namespace, row: CatalogRow) -> argparse.Namespace:
     """Prepare the deploy() Namespace + project root for the resolved row.
 
@@ -330,9 +377,13 @@ def _build_deploy_args(args: argparse.Namespace, row: CatalogRow) -> argparse.Na
     ``urun.serve.app:app``. When ``--warm`` is given, the idle replica floor rides
     the same channel (``URUN_SERVE_WARM``, JSON int) so the bundled app's
     ``@app.function(warm=...)`` declares it at import; an omitted ``--warm``
-    renders nothing (byte-identical shim, legacy always-on NULL). Those land
-    scoped to THIS deploy artifact (NOT a shared ``URUN_SERVE_CONFIG``
-    materializer env, the retired coupling bug). The bundled app resolves engine
+    renders nothing (byte-identical shim, legacy always-on NULL). When
+    ``--urun-wheel`` is given, the wheel version rides ``URUN_WHEEL_VERSION`` the
+    same way — content-bearing, so a wheel roll produces a new manifest hash (a
+    NEW release, never a re-register of an immutable one); an omitted
+    ``--urun-wheel`` renders nothing. Those land scoped to THIS deploy artifact
+    (NOT a shared ``URUN_SERVE_CONFIG`` materializer env, the retired coupling
+    bug). The bundled app resolves engine
     ARGS by-string at boot; the engine NAME is pinned here only to select the
     build-time dependency group (vllm / llama-cpp-python / ...) so the deps venv
     carries the engine the adapter imports at load.
@@ -351,6 +402,16 @@ def _build_deploy_args(args: argparse.Namespace, row: CatalogRow) -> argparse.Na
             "--warm only applies to the bundled serve app (it is pinned in the "
             "generated shim); it cannot be combined with --entrypoint."
         )
+    # --urun-wheel re-validation (argparse already refuses empty/whitespace):
+    # a Namespace built in code skips argparse, so the pin is checked again
+    # here. The wheel version rides the shim env, so --entrypoint (the user's
+    # own app) + --urun-wheel cannot combine either.
+    urun_wheel = _validated_urun_wheel(getattr(args, "urun_wheel", None))
+    if urun_wheel is not None and getattr(args, "entrypoint", None):
+        raise UrunError(
+            "--urun-wheel only applies to the bundled serve app (it is pinned in "
+            "the generated shim); it cannot be combined with --entrypoint."
+        )
 
     entrypoint = getattr(args, "entrypoint", None)
     if entrypoint:
@@ -363,7 +424,7 @@ def _build_deploy_args(args: argparse.Namespace, row: CatalogRow) -> argparse.Na
         shim_root = None
     else:
         project_root, rel_entrypoint = _write_serve_shim(
-            row, exo_class=exo_class, exo_image=exo_image, warm=warm
+            row, exo_class=exo_class, exo_image=exo_image, warm=warm, urun_wheel=urun_wheel
         )
         # PLATFORM RELEASE SCOPE (catalog prebuilt instant serve). The shim is
         # deterministic given the resolved row + gpu, so its manifest hash is an
@@ -429,13 +490,20 @@ def _write_serve_shim(
     exo_class: str | None = None,
     exo_image: str | None = None,
     warm: int | None = None,
+    urun_wheel: str | None = None,
 ) -> tuple[Path, str]:
     """Write the bundled-app shim ``app.py`` pinned to ``row`` into a temp root."""
     project_root = Path(tempfile.mkdtemp(prefix="urun-serve-"))
     try:
         app_path = project_root / "app.py"
         app_path.write_text(
-            render_serve_shim_py(row, exo_class=exo_class, exo_image=exo_image, warm=warm),
+            render_serve_shim_py(
+                row,
+                exo_class=exo_class,
+                exo_image=exo_image,
+                warm=warm,
+                urun_wheel=urun_wheel,
+            ),
             encoding="utf-8",
         )
         # Function-engine map for the launcher's PRE-IMPORT topology decision
@@ -554,6 +622,7 @@ def render_serve_shim_py(
     exo_class: str | None = None,
     exo_image: str | None = None,
     warm: int | None = None,
+    urun_wheel: str | None = None,
 ) -> str:
     """Render the tiny shim that deploys the BUNDLED urun-python serve app.
 
@@ -575,6 +644,11 @@ def render_serve_shim_py(
         the bundled app's ``@app.function(warm=...)`` declares the idle replica
         floor (app_functions.warm_replicas) at import. Unset renders NOTHING —
         byte-identical shim, legacy always-on.
+      * When ``urun_wheel`` is not None, ``URUN_WHEEL_VERSION`` is set before the
+        import so the platform's wheel resolver pins THAT urun wheel. The pin is
+        CONTENT-BEARING: it changes the shim (hence the manifest hash), so a
+        wheel roll is a NEW RELEASE, never a re-register of the immutable one.
+        Unset renders NOTHING — byte-identical shim.
 
     Values are embedded as JSON (NOT interpolated Python) so a weird model string,
     gpu spec, or engine name can never break the module. The catalog row's
@@ -641,6 +715,7 @@ os.environ["URUN_SERVE_GPUS"] = %(gpus)s
 os.environ["URUN_SERVE_ENGINE"] = %(engine)s
 %(exo_env)s
 %(warm_env)s
+%(urun_wheel_env)s
 %(serve_deps_env)s
 
 from urun.serve.app import app  # noqa: E402  (bundled urun-python serve app)
@@ -663,10 +738,15 @@ __all__ = ["app"]
 '''
     exo_env = render_exo_pin_env(exo_class, exo_image)
     warm_env = (
-        'os.environ["URUN_SERVE_WARM"] = ' + json.dumps(int(warm)) + "\n"
+        'os.environ["URUN_SERVE_WARM"] = ' + json.dumps(str(int(warm))) + "\n"
         if warm is not None
         else ""
     )
+    urun_wheel_env = (
+        'os.environ["URUN_WHEEL_VERSION"] = ' + json.dumps(urun_wheel) + "\n"
+        if urun_wheel is not None
+        else ""
+    )
     return template % {
         "entrypoint": BUNDLED_SERVE_ENTRYPOINT,
         "model": model,
@@ -676,6 +756,7 @@ __all__ = ["app"]
         "serve_deps_env": serve_deps_env,
         "exo_env": exo_env,
         "warm_env": warm_env,
+        "urun_wheel_env": urun_wheel_env,
     }