urun-cli 0.7.0__tar.gz → 0.7.2__tar.gz

{urun_cli-0.7.0 → urun_cli-0.7.2}/CHANGELOG.md

@@ -1,3 +1,21 @@
+## 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
+  catalog's `warm` marker for platform-operated shared endpoints; absent =
+  the unchanged scale-to-zero default). Pins `URUN_SERVE_WARM` into the
+  generated shim so the bundled app's `@app.function(warm=...)` reads it.
+- `urun serve --exo-class / --exo-image` — pin a deploy's provider on the EXO rail.
+- Deploy Python and Rust functions in one app release.
+- Compat: bundle the proxy with the queued session identity; stop reporting
+  an unconverged roll as ready and stop dropping the server's error message.
+
 ## 0.6.3
 
 - Bump the vendored `urun-openai` binary pin to `@urun-sh/openai@0.5.0` — the

{urun_cli-0.7.0 → urun_cli-0.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: urun-cli
-Version: 0.7.0
+Version: 0.7.2
 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.0 → urun_cli-0.7.2}/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.0"
+version = "0.7.2"
 description = "End-user CLI for deploying apps to urun"
 readme = "README.md"
 requires-python = ">=3.11"

{urun_cli-0.7.0 → urun_cli-0.7.2}/src/urun/cli.py

@@ -2675,7 +2675,7 @@ def deploy_once(args: argparse.Namespace) -> DeployOutcome:
         # showing" and hides a broken build-log path (owner, 2026-07-17).
         if not tailer.emitted_any:
             print(f"{BUILD_LOG_PREFIX}{NO_BUILD_LOGS_NOTE}")
-        watch_rollout(
+        rollout = watch_rollout(
             client,
             app=app_name,
             manifest_hash=mh,
@@ -2683,6 +2683,27 @@ def deploy_once(args: argparse.Namespace) -> DeployOutcome:
             on_phase=lambda phase: print(f"  rollout: {phase}"),
         )
         mark_phase("roll-wait")
+        # A ROLL THAT DID NOT CONVERGE IS NOT A READY DEPLOYMENT. watch_rollout's
+        # verdict used to be discarded, so a `timeout` printed its own honest
+        # "still not converged" line and was then immediately contradicted by
+        # "Deployment ready" and exit 0 -- the one signal automation reads.
+        # Live receipt, dev-usw2 2026-09-09 `urun serve qwen3.6-27b:bf16`:
+        # `rollout: still not converged after 300s` followed by
+        # `Deployment ready`, exit 0, while the app sat at
+        # `no_ready_gpu_units`. A CI job gating on the exit code called that a
+        # successful deploy. `skipped` (no presence signal for this app at all)
+        # stays exit 0: nothing was observed, so nothing is contradicted.
+        if rollout == "timeout":
+            print(format_phase_timing(phases))
+            print(
+                "Deployment NOT confirmed ready: the build succeeded and the "
+                "roll continues server-side, but this command did not observe "
+                "the new release serving before its deadline. Re-check with "
+                "`urun app status`, or pass --no-wait to finalize without "
+                "waiting.",
+                file=sys.stderr,
+            )
+            return DeployOutcome(exit_code=1, manifest_hash=mh, deps=deps, status=status)
     print(format_phase_timing(phases))
     print_ready(status)
     return DeployOutcome(exit_code=0, manifest_hash=mh, deps=deps, status=status)
@@ -2944,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.0 → urun_cli-0.7.2}/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.0 → urun_cli-0.7.2}/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.0 → urun_cli-0.7.2}/src/urun/errors.py

@@ -31,6 +31,55 @@ MAX_ERROR_BODY_CHARS = 500
 ENDPOINT_HINT = "the endpoint may not be deployed on this server yet"
 
 
+# ── credential redaction ──────────────────────────────────────────────────────
+#
+# Server-supplied error text is echoed to terminals and CI logs (the exception
+# string itself, and urun.retry.describe_error's retry line). A PROXIED upstream
+# error can carry credential material verbatim -- a signed URL's query token, an
+# echoed Authorization header, a JWT. Whitespace normalisation and truncation do
+# not prevent it reaching a log, so redact before any of it is rendered.
+#
+# Patterns are TARGETED, never "anything long and hex": a build id is 64 hex
+# chars and is exactly the value an operator needs to keep reading. Redacting it
+# would trade a credential leak for an unusable diagnostic.
+_REDACTIONS: tuple[tuple[re.Pattern[str], str], ...] = (
+    # urun API keys, both shapes (cli.API_KEY_RE).
+    (re.compile(r"\burun_(?:[0-9a-f]{32}|sk_[A-Za-z0-9_-]{43})\b"), "urun_[redacted]"),
+    # Authorization headers echoed back by a proxy.
+    (
+        re.compile(r"\b(bearer|basic)\s+[A-Za-z0-9._~+/=-]{8,}", re.IGNORECASE),
+        r"\1 [redacted]",
+    ),
+    # JWTs (three base64url segments), wherever they appear.
+    (
+        re.compile(r"\beyJ[A-Za-z0-9_-]{4,}\.[A-Za-z0-9_-]{4,}\.[A-Za-z0-9_-]{4,}"),
+        "[redacted-jwt]",
+    ),
+    # Signed-URL and query-string secrets: ?token=, &sig=, &X-Amz-Signature=, ...
+    (
+        re.compile(
+            r"([?&](?:[A-Za-z0-9_-]*(?:token|signature|sig|secret|password|api[_-]?key|"
+            r"access[_-]?key|credential)[A-Za-z0-9_-]*)=)[^&\s\"']+",
+            re.IGNORECASE,
+        ),
+        r"\1[redacted]",
+    ),
+)
+
+
+def redact_credentials(text: str) -> str:
+    """Strip credential material from server-supplied text before it is logged.
+
+    Applied at :class:`ApiError` construction so EVERY render of a server
+    message -- the exception string, ``describe_error``'s retry line, anything
+    downstream -- is safe by construction rather than by each caller
+    remembering.
+    """
+    for pattern, replacement in _REDACTIONS:
+        text = pattern.sub(replacement, text)
+    return text
+
+
 def sanitize_error_text(text: str, limit: int = MAX_ERROR_BODY_CHARS) -> str:
     """Make server-supplied text safe to print: no ANSI/control chars, bounded.
 
@@ -74,6 +123,11 @@ class ApiError(UrunError):
         method: str | None = None,
         url: str | None = None,
     ):
+        # Redact FIRST: `message` (and a signed `url`) are server-supplied and
+        # end up in this exception's string, in retry lines, and in CI logs.
+        message = redact_credentials(message)
+        if url:
+            url = redact_credentials(url)
         detail = f"{status} {code}: {message}"
         if method and url:
             detail += f" ({method} {url})"

{urun_cli-0.7.0 → urun_cli-0.7.2}/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.0 → urun_cli-0.7.2}/src/urun/retry.py

@@ -157,9 +157,27 @@ def retry_call(
             sleep(wait)
 
 
+#: Cap for the server message echoed by :func:`describe_error`. Long enough for
+#: a real upstream diagnosis ("cube load failed: upstream status 503"), short
+#: enough that a retry line stays one line.
+_DESCRIBE_DETAIL_MAX = 160
+
+
 def describe_error(exc: BaseException) -> str:
     """Short, honest one-line description of a transient failure for logging."""
     if isinstance(exc, ApiError):
+        # The server's MESSAGE is the diagnosis; the code alone is only a label.
+        # Dropping it turned a 30-second read into an investigation: a `urun
+        # serve` on dev-usw2 2026-09-09 retried the build-log fetch 7 times
+        # showing `HTTP 502 logs_upstream_error` and gave up, while the very
+        # same response body said `cube load failed: upstream status 503` --
+        # i.e. the log backend had no healthy upstream at all. Bounded so a
+        # verbose server message cannot turn a retry line into a paragraph.
+        detail = " ".join((exc.message or "").split())
+        if detail:
+            if len(detail) > _DESCRIBE_DETAIL_MAX:
+                detail = detail[: _DESCRIBE_DETAIL_MAX - 1].rstrip() + "\u2026"
+            return f"HTTP {exc.status} {exc.code}: {detail}"
         return f"HTTP {exc.status} {exc.code}"
     if isinstance(exc, urllib.error.HTTPError):
         return f"HTTP {exc.code} {exc.reason}"

{urun_cli-0.7.0 → urun_cli-0.7.2}/src/urun/rust.py

@@ -909,11 +909,15 @@ def _resolve_symlink(logical: Path, ws_root: Path, rel: str) -> Path:
 def _dir_ignored(rel: str, name: str, patterns: list[str]) -> bool:
     if rel in _BUILTIN_EXCLUDED_DIRS or name in _BUILTIN_EXCLUDED_DIRS:
         return True
-    # gitignore-style directory patterns ("docs/") match the directory itself.
+    # gitignore-style directory patterns ("docs/") match the directory itself;
+    # a descendant pattern ("cache/**", "cache/*") ignores every entry under
+    # the directory, so the directory is skipped as a whole.
     for pat in patterns:
         base = pat.rstrip("/")
         if fnmatch.fnmatch(rel, base) or fnmatch.fnmatch(name, base):
             return True
+        if fnmatch.fnmatch(rel + "/", pat):
+            return True
     return False
 
 
@@ -938,6 +942,8 @@ def _collect_files(ws_root: Path, patterns: list[str]) -> dict[str, Path]:
                     f"{rel}: '.urun' is generated exclusively by the builder; "
                     "remove it from the project before deploying"
                 )
+            if _dir_ignored(rel, d, patterns):
+                continue  # an ignored tree never ships, symlinked or not
             if logical.is_symlink():
                 target = _resolve_symlink(logical, ws_root, rel)
                 raise UrunError(
@@ -945,8 +951,6 @@ def _collect_files(ws_root: Path, patterns: list[str]) -> dict[str, Path]:
                     f"(only file symlinks inside the workspace ship; {rel} resolves "
                     f"to {target})"
                 )
-            if _dir_ignored(rel, d, patterns):
-                continue
             keep.append(d)
         dirnames[:] = keep
         for f in sorted(filenames):

{urun_cli-0.7.0 → urun_cli-0.7.2}/src/urun/serve.py

@@ -120,6 +120,19 @@ def _add_serve_model_args(parser: argparse.ArgumentParser) -> None:
             "own this flag pins nothing and is refused)."
         ),
     )
+    parser.add_argument(
+        "--warm",
+        dest="warm",
+        type=int,
+        default=None,
+        metavar="N",
+        help=(
+            "Idle replica floor (app_functions.warm_replicas) for THIS deploy: "
+            "N idle replicas stay resident at zero live sessions. Omit = legacy "
+            "always-on (NULL). 0 = scale to zero when idle. Shared-endpoint "
+            "deploys pass the catalog row's warm (default 0)."
+        ),
+    )
     parser.add_argument(
         "--entrypoint",
         help=(
@@ -314,14 +327,30 @@ def _build_deploy_args(args: argparse.Namespace, row: CatalogRow) -> argparse.Na
     The shim does NOT bake the catalog row — it sets ``URUN_SERVE_MODEL`` (the
     ``<id:variant>`` string), ``URUN_SERVE_GPUS`` (the resolved gpu spec), and
     ``URUN_SERVE_ENGINE`` (the row's engine) in its own module body and re-exports
-    ``urun.serve.app:app``. 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.
+    ``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
+    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.
     """
     name = getattr(args, "name", None) or _default_app_name(row)
     exo_class, exo_image = _validated_exo_pin(args)
+    # --warm re-validation (argparse guarantees the int): a negative floor is a
+    # config contradiction the deployer must see here, never at app import in
+    # a build pod minutes later. Warm rides the shim env, so --entrypoint (the
+    # user's own app) + --warm cannot combine — validate against entrypoint too.
+    warm = getattr(args, "warm", None)
+    if warm is not None and warm < 0:
+        raise UrunError(f"--warm must be a non-negative integer, got {warm}")
+    if warm is not None and getattr(args, "entrypoint", None):
+        raise UrunError(
+            "--warm 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:
@@ -334,7 +363,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
+            row, exo_class=exo_class, exo_image=exo_image, warm=warm
         )
         # PLATFORM RELEASE SCOPE (catalog prebuilt instant serve). The shim is
         # deterministic given the resolved row + gpu, so its manifest hash is an
@@ -399,13 +428,14 @@ def _write_serve_shim(
     *,
     exo_class: str | None = None,
     exo_image: str | None = None,
+    warm: int | 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),
+            render_serve_shim_py(row, exo_class=exo_class, exo_image=exo_image, warm=warm),
             encoding="utf-8",
         )
         # Function-engine map for the launcher's PRE-IMPORT topology decision
@@ -523,6 +553,7 @@ def render_serve_shim_py(
     *,
     exo_class: str | None = None,
     exo_image: str | None = None,
+    warm: int | None = None,
 ) -> str:
     """Render the tiny shim that deploys the BUNDLED urun-python serve app.
 
@@ -540,6 +571,10 @@ def render_serve_shim_py(
         ``deps=_deploy_deps()`` selects this engine's dependency group — the build
         installs vllm / llama-cpp-python / ... into the per-serve deps venv (the
         engine the adapter lazily imports at load).
+      * When ``warm`` is not None, ``URUN_SERVE_WARM`` is set before the import so
+        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.
 
     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
@@ -605,6 +640,7 @@ os.environ["URUN_SERVE_MODEL"] = %(model)s
 os.environ["URUN_SERVE_GPUS"] = %(gpus)s
 os.environ["URUN_SERVE_ENGINE"] = %(engine)s
 %(exo_env)s
+%(warm_env)s
 %(serve_deps_env)s
 
 from urun.serve.app import app  # noqa: E402  (bundled urun-python serve app)
@@ -626,6 +662,11 @@ if False:  # AST-visible deps declaration; never runs.
 __all__ = ["app"]
 '''
     exo_env = render_exo_pin_env(exo_class, exo_image)
+    warm_env = (
+        'os.environ["URUN_SERVE_WARM"] = ' + json.dumps(str(int(warm))) + "\n"
+        if warm is not None
+        else ""
+    )
     return template % {
         "entrypoint": BUNDLED_SERVE_ENTRYPOINT,
         "model": model,
@@ -634,6 +675,7 @@ __all__ = ["app"]
         "deps_literal": deps_literal,
         "serve_deps_env": serve_deps_env,
         "exo_env": exo_env,
+        "warm_env": warm_env,
     }