snowflake-sandbox-python 0.2.1a1__py3-none-any.whl

snowflake/cli_sandbox/_run_command.py

@@ -0,0 +1,1091 @@
+"""``snow sandbox run`` — the one verb for running a workload in a sandbox.
+
+**TARGET is always a local path; images come only from ``--image``.** The shape of
+a local TARGET is auto-detected, but image-vs-local never is — an unresolvable
+TARGET is an error, not an image reference. Inferring it both ways would make the
+dangerous direction silent: a bare image name that collides with a local
+directory (``run myapp`` beside ``myapp/``) would upload that whole tree to
+Snowflake instead of running the image, while the reverse mistake merely fails
+loudly at pull. So:
+
+  * ``--image /repo/img:tag`` with **no TARGET** runs that image — with
+    ``--command``, or with ``--detach`` to run the image's own entrypoint;
+  * ``--image`` *with* a local TARGET instead names the **base image** that the
+    uploaded code runs on;
+  * **one or more local paths** (files, directories, or a mix) are pushed into a
+    fresh sandbox and run there. A lone ``.py``/``.sh`` file gets its interpreter
+    from its extension; anything else needs ``--command``;
+  * ``--app MODULE.py`` deploys an App via the SDK's authoring path (what
+    ``deploy`` used to do). It is **explicit**: a script is never treated as an App
+    because of what is inside it. The static AST check survives only as a *hint*,
+    and is gated on the file importing ``snowflake.sandbox`` — ``@app.function()``
+    is also Modal's API, so the decorator shape alone means nothing.
+
+What is uploaded is never guessed silently. Credential-shaped files are excluded by
+default (reusing the SDK's ``_is_credential_path``), ``$HOME`` and filesystem roots
+are refused outright, ``--include``/``--exclude`` take gitignore-syntax globs
+relative to each TARGET, and every run prints a manifest naming what was sent and
+what was dropped and why. An upload that is *anomalous* rather than merely large --
+over a fraction of the ``--memory`` tier, since ``/tmp`` is RAM-backed, or over a
+file count that would be slow -- is refused until ``--allow-large``.
+
+Lifecycle is a flag, not a verb. By default ``run`` is **run-to-completion**: it
+streams output, exits with the command's code, and tears the sandbox down.
+``--detach`` makes it **long-running** (detached; for an App this is the
+deploy-detached path). Auto-restart across platform interruptions is a separate,
+deferred feature (the create body has no restart policy yet).
+
+Local delivery for the inferred targets is a direct push
+(``PUT /containers/{id}/files``), not the stage bundle path — no stage, no zip,
+capped per-file. An App target uses the SDK's ``Bundle`` path as before.
+"""
+
+from __future__ import annotations
+
+import ast
+import asyncio
+import shlex
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+import typer
+
+from snowflake.cli_sandbox._common import (
+    _CONN_HELP,
+    _ENV_HELP,
+    _USE_SNOW_CONN_HELP,
+    _apply_connection,
+    _parse_env,
+)
+from snowflake.cli_sandbox._egress_flags import (
+    EAI_HELP,
+    NO_DEFAULT_EGRESS_HELP,
+    SECRET_HELP,
+    build_egress,
+)
+from snowflake.cli_sandbox._shell_command import (
+    _emit_status,
+    _exec_streaming,
+    _run_on_fresh_sandbox,
+)
+from snowflake.cli_sandbox._upload_plan import (
+    ResolvedTarget,
+    TargetError,
+    UploadPlan,
+    build_plan,
+    resolve_targets,
+)
+
+if TYPE_CHECKING:
+    from snowflake.sandbox._deploy_spec import DeploySpec
+    from snowflake.sandbox.client import AsyncSandbox
+
+# 24h is proven safe on the fleet (SnowBots runs with it); a --detach box with
+# no inbound traffic would otherwise be idle-reaped at CNG's shorter default.
+_DETACH_IDLE_SUSPEND = "24h"
+
+# Uploaded local code lands here; /tmp is world-writable on every base image. Note it
+# is also RAM-backed, which is why the upload thresholds below scale with --memory.
+_REMOTE_WORKDIR = "/tmp/sandbox-run"
+
+# Matches the SDK's own per-file ceiling (`sandbox.files.MAX_FILE_BYTES`), checked here
+# so an oversized file is refused before anything is created rather than aborting the
+# upload half-way and leaving a partially-populated sandbox.
+_MAX_FILE_BYTES = 25 * 1024 * 1024
+
+# `--memory` default, mirrored from `_run_on_fresh_sandbox`; the byte gate is a
+# fraction of it. Tuned to catch *anomalous*, not merely large: 20% of the default 4g
+# is ~820 MB, which a real project reaches only by accident. Both are one edit to
+# re-tune, and `--allow-large` overrides either.
+_DEFAULT_MEMORY_TIER = "4g"
+_UPLOAD_BYTE_FRACTION = 0.20
+_UPLOAD_FILE_LIMIT = 2000
+
+# A --detach local command is backgrounded (its process is not the container's
+# managed process, unlike an image's command), so its output has no managed-process
+# log capture — tee it to a file, which `logs --file` reads.
+_DETACH_LOG = "/tmp/sandbox-run.out"
+
+# Only runtimes present on the base image are auto-detected; anything else (a
+# compiled toolchain, node when the base lacks it, ...) must pass --command.
+_RUNNER_BY_SUFFIX = {".py": "python", ".sh": "bash", ".bash": "bash"}
+
+# @app.<these> decorators mark an App entry (see snowflake.sandbox.app).
+_APP_DECORATORS = frozenset({"function", "entrypoint", "session"})
+
+_RUN_HELP = """Run a workload in a sandbox: local code (TARGET) or an image (--image).
+
+TARGET is always a LOCAL PATH, repeatable -- never an image reference. Pass files,
+directories, or a mix. A lone .py/.sh file gets its interpreter from its extension
+(.py -> python, .sh -> bash); anything else needs --command.
+
+To run an IMAGE, name it with --image. An image is never inferred from TARGET: a
+bare image name can collide with a local directory, and guessing wrong would upload
+that directory to Snowflake. With local TARGETs, --image is the base image they run
+on. To deploy an App module, pass --app.
+
+Uploads are filtered and reported. Credential-shaped files (.env, *.pem, id_rsa,
+.ssh/, ...) are excluded by default; $HOME and filesystem roots are refused.
+--exclude/--include take gitignore-syntax globs relative to each TARGET, so
+`node_modules/` and `data/` work as written. Every run prints what it sent and what
+it dropped.
+
+By default this is run-to-completion: the output streams, the exit code is
+returned, and the sandbox is torn down. --detach leaves it running (detached);
+auto-restart across platform interruptions is a separate, deferred feature.
+--dry-run prints the resolved plan without creating anything.
+
+Example:
+    snow sandbox run agent.py                           # local script: stream, exit
+    snow sandbox run src/ config.yaml main.py           # several paths at once
+    snow sandbox run ./project --command "python -m app"
+    snow sandbox run ./project --exclude "data/" --exclude "*.log"
+    snow sandbox run main.py --image /repo/node:20 --command "node main.js"
+    snow sandbox run agent.py --detach                  # leave it running
+    snow sandbox run --image /repo/snowbots:8 --detach --command "node /boot.mjs"
+    snow sandbox run --image /repo/snowbots:8 --detach  # the image's own entrypoint
+    snow sandbox run --command "echo hi"                # ad-hoc, default image
+    snow sandbox run --app agent_app.py --function triage
+    snow sandbox run --app agent_app.py --dry-run
+"""
+
+
+def _imports_the_sdk(tree: ast.AST) -> bool:
+    """True when the module imports `snowflake.sandbox` in any spelling.
+
+    Gates the App hint. `@app.function()` and `App(...)` are *also* Modal's API
+    (`app = modal.App(...)`), and Textual exports an `App` too — so the decorator
+    shape alone false-positives on entirely unrelated code. Requiring an SDK import
+    keeps the hint from firing on a Modal script.
+    """
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import) and any(
+            a.name.startswith("snowflake.sandbox") for a in node.names
+        ):
+            return True
+        if isinstance(node, ast.ImportFrom) and (node.module or "").startswith("snowflake.sandbox"):
+            return True
+    return False
+
+
+def _looks_like_app(path: Path) -> bool:
+    """True if *path* statically looks like an SDK App module.
+
+    Requires **both** an SDK import and an ``App(...)`` call or an
+    ``@app.function``/``@app.entrypoint``/``@app.session`` decorator. Parses the AST
+    only -- it never imports or runs the file.
+
+    This no longer decides anything: `--app` selects the App path explicitly, and this
+    only powers a hint. That matters because the decorator shape is not ours alone --
+    Modal is `app = modal.App(...)` with `@app.function()` -- so without the import
+    gate the hint would fire on every Modal script in the world.
+    """
+    try:
+        tree = ast.parse(path.read_text(encoding="utf-8", errors="replace"))
+    except (OSError, SyntaxError, ValueError):
+        return False
+    if not _imports_the_sdk(tree):
+        return False
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Call):
+            fn = node.func
+            if (isinstance(fn, ast.Name) and fn.id == "App") or (
+                isinstance(fn, ast.Attribute) and fn.attr == "App"
+            ):
+                return True
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+            for dec in node.decorator_list:
+                target = dec.func if isinstance(dec, ast.Call) else dec
+                if isinstance(target, ast.Attribute) and target.attr in _APP_DECORATORS:
+                    return True
+    return False
+
+
+def _detect_file_command(path: Path) -> str | None:
+    """A shell command to run a single local file by extension, or None if unknown."""
+    runner = _RUNNER_BY_SUFFIX.get(path.suffix)
+    return f"{runner} {shlex.quote(path.name)}" if runner else None
+
+
+def _load_app_spec(
+    module_path: str | None, function: str | None, env_overrides: dict[str, str]
+) -> DeploySpec:
+    """Import a Python module by path and pull a DeploySpec out of its App.
+
+    The module defines the App, so importing it is how we discover what to run.
+    Reached only after `_looks_like_app` matched, so this is not run on an arbitrary
+    script.
+    """
+    import importlib.util
+
+    if module_path is None:
+        raise typer.BadParameter("provide MODULE (e.g. agent.py)")
+    src = Path(module_path).expanduser().resolve()
+    if src.is_dir():
+        raise typer.BadParameter(
+            f"{module_path} is a directory. sandbox.toml is retired — point at the "
+            f"Python module that defines your App, e.g. `snow sandbox run --app agent.py`."
+        )
+    if not src.is_file():
+        raise typer.BadParameter(f"module not found: {src}")
+
+    sys.path.insert(0, str(src.parent))
+    spec_obj = importlib.util.spec_from_file_location(src.stem, src)
+    if spec_obj is None or spec_obj.loader is None:
+        raise typer.BadParameter(f"cannot import {src}")
+    module = importlib.util.module_from_spec(spec_obj)
+    try:
+        spec_obj.loader.exec_module(module)
+    except Exception as exc:  # noqa: BLE001 - surface the user's import error
+        raise typer.BadParameter(f"failed to import {src}: {exc}") from exc
+
+    from snowflake.sandbox.app import App as _App
+
+    apps = [v for v in vars(module).values() if isinstance(v, _App)]
+    if not apps:
+        raise typer.BadParameter(
+            f'no App found in {src.name}. Define one: app = App("my-agent") '
+            f"with an @app.function(...)."
+        )
+    if len(apps) > 1:
+        raise typer.BadParameter(
+            f"{src.name} defines {len(apps)} Apps; a module should define one."
+        )
+    try:
+        spec = apps[0].resolve(function).deploy_spec(**env_overrides)
+    except ValueError as exc:
+        raise typer.BadParameter(str(exc)) from exc
+
+    # A relative bundle root means "next to the module", not the invoking cwd.
+    if spec.bundle is not None and not Path(spec.bundle.root).is_absolute():
+        from dataclasses import replace
+
+        from snowflake.sandbox._assemble import Bundle
+
+        rooted = (src.parent / spec.bundle.root).resolve()
+        spec = replace(
+            spec,
+            bundle=Bundle(
+                root=str(rooted), include=spec.bundle.include, exclude=spec.bundle.exclude
+            ),
+        )
+    return spec
+
+
+def _print_preflight_findings(result: Any) -> None:
+    """Echo the preflight problems; exit(2) if any are errors (nothing ran)."""
+    errors = [p for p in result.problems if p.severity == "error"]
+    for p in result.problems:
+        fix_note = f"  -> fix: {p.fix}" if p.fix else ""
+        typer.echo(f"[{p.severity}] {p.message}{fix_note}", err=(p.severity == "error"))
+    if errors:
+        typer.echo("preflight failed; nothing ran.", err=True)
+        raise typer.Exit(2)
+
+
+def _print_app_plan(result: Any) -> None:
+    """Print the resolved App deploy plan (``--dry-run``) and exit 0."""
+    pl = result.plan
+    typer.echo("target:     App module")
+    typer.echo(f"image:      {pl.image}")
+    typer.echo(f"memory:     {pl.memory}")
+    if pl.cpu is not None:
+        typer.echo(f"cpu:        {pl.cpu}")
+    typer.echo(f"entry:      {' '.join(pl.entry)}")
+    typer.echo(f"code_stage: {pl.code_stage or '(none)'}")
+    typer.echo(f"egress:     {pl.egress}")
+    typer.echo(f"env keys:   {', '.join(pl.env_keys) or '(none)'}")
+    typer.echo(f"bundle ({len(pl.bundle_files)} files):")
+    for f in pl.bundle_files:
+        typer.echo(f"  {f}")
+    raise typer.Exit(0)
+
+
+def _print_inferred_plan(plan: _RunPlan) -> None:
+    """Print the resolved plan for an image/file/dir target (``--dry-run``), exit 0.
+
+    Needs no live connection — nothing is created, so this is a client-side echo."""
+    typer.echo(f"target:     {'image (no TARGET)' if plan.kind == 'image' else plan.kind}")
+    typer.echo(f"image:      {plan.base_image or '(deployment default)'}")
+    typer.echo(f"command:    {plan.command or '(image default)'}")
+    if plan.egress is not None:
+        eais = getattr(plan.egress, "external_access_integrations", ())
+        closed = getattr(plan.egress, "allow_default_egress", None) is False
+        bits = [f"eai={','.join(eais)}" if eais else "", "default-egress=closed" if closed else ""]
+        if plan.secrets:
+            bits.append(f"secrets={len(plan.secrets)}")
+        typer.echo(f"egress:     {' '.join(b for b in bits if b)}")
+    if plan.upload is not None:
+        typer.echo(
+            f"upload:     {plan.upload.file_count} file(s), "
+            f"{_human(plan.upload.total_bytes)} -> {_REMOTE_WORKDIR}"
+        )
+        for item in plan.upload.selected:
+            typer.echo(f"  {item.rel}")
+        if why := _describe_exclusions(plan.upload):
+            typer.echo(f"excluded:   {why}")
+        typer.echo(f"cwd:        {plan.upload.cwd}")
+    typer.echo(f"detach: {plan.detach}")
+    if plan.idle_suspend:
+        typer.echo(f"idle_suspend: {plan.idle_suspend}")
+    typer.echo(f"env keys:   {', '.join(plan.env) or '(none)'}")
+    raise typer.Exit(0)
+
+
+@dataclass(frozen=True)
+class _RunPlan:
+    """The resolved ``run`` invocation, threaded to the async workers so they stay
+    module-level and independently testable rather than closures over the flags."""
+
+    kind: str  # 'image' (no TARGET) | 'local' (paths) | 'app' (--app)
+    app_path: Path | None  # --app module
+    upload: UploadPlan | None  # the settled selection; None unless kind == 'local'
+    command: str | None  # shell command; None for an App or a detached image (own entry)
+    base_image: str  # '' = the deployment's default runtime image (unused for 'app')
+    detach: bool
+    idle_suspend: str | None
+    memory: str | None
+    cpu: float | None
+    name: str | None
+    function: str | None  # App-module target only
+    env: dict[str, str]
+    egress: object | None  # Egress | None -- typed loosely to keep the SDK import lazy
+    secrets: tuple[object, ...]
+    quiet: bool
+
+
+def _reject_app_incompatible_flags(
+    *,
+    n_targets: int,
+    command: str | None,
+    name: str | None,
+    idle_suspend: str | None,
+    image: str | None,
+    selection_flags: dict[str, object],
+    eai: list[str] | None,
+    secret: list[str] | None,
+    nde: bool,
+) -> None:
+    """Everything an App module declares for itself, and so cannot be told from a flag.
+
+    Split from `_reject_inapplicable_flags` purely to keep each half under the
+    complexity limit; the App rules are a self-contained set.
+    """
+    if n_targets:
+        raise typer.BadParameter(
+            "--app takes the module itself; do not also pass a TARGET "
+            "(`run --app agent_app.py`, not `run --app agent_app.py extra.py`)."
+        )
+    if command is not None:
+        raise typer.BadParameter(
+            "--command does not apply to an App module; the App defines its own entry."
+        )
+    if name is not None:
+        raise typer.BadParameter("--name does not apply to an App module (assigned on deploy).")
+    if idle_suspend is not None:
+        raise typer.BadParameter("--idle-suspend applies only to an image or local-code run.")
+    if image is not None:
+        raise typer.BadParameter("--image does not apply to an App module (the App declares it).")
+    for flag, value in selection_flags.items():
+        if value:
+            raise typer.BadParameter(
+                f"{flag} applies only to local code; an App declares its own bundle."
+            )
+    for flag, value in (("--eai", eai), ("--secret", secret), ("--no-default-egress", nde)):
+        if value:
+            raise typer.BadParameter(
+                f"{flag} does not apply to an App module; an App declares its own egress "
+                f"and secrets in code (see @app.function(egress=..., secrets=...))."
+            )
+
+
+def _reject_inapplicable_flags(
+    *,
+    kind: str,
+    detach: bool,
+    function: str | None,
+    name: str | None,
+    idle_suspend: str | None,
+    command: str | None,
+    image: str | None,
+    n_targets: int,
+    selection_flags: dict[str, object],
+    eai: list[str] | None = None,
+    secret: list[str] | None = None,
+    nde: bool = False,
+) -> None:
+    """Reject flag combinations that cannot take effect, loudly rather than silently.
+
+    Everything here is a *shape* error the user can fix by retyping, so each message
+    names the flag at fault and, where it is not obvious, why it cannot apply.
+    """
+    if kind == "app":
+        _reject_app_incompatible_flags(
+            n_targets=n_targets,
+            command=command,
+            name=name,
+            idle_suspend=idle_suspend,
+            image=image,
+            selection_flags=selection_flags,
+            eai=eai,
+            secret=secret,
+            nde=nde,
+        )
+    elif function is not None:
+        raise typer.BadParameter("--function applies only to an App module (--app).")
+
+    if not n_targets:
+        for flag, value in selection_flags.items():
+            if value:
+                raise typer.BadParameter(f"{flag} applies only when uploading local code.")
+
+    if name is not None and not detach:
+        raise typer.BadParameter(
+            "--name only applies with --detach (a run-to-completion job is ephemeral)."
+        )
+    if idle_suspend is not None and not detach:
+        raise typer.BadParameter("--idle-suspend applies only to a --detach run.")
+
+
+def _memory_bytes(tier: str | None) -> int:
+    """The sandbox's RAM in bytes, from the `--memory` tier (default 4g)."""
+    text = (tier or _DEFAULT_MEMORY_TIER).strip().lower().rstrip("b")
+    try:
+        return int(float(text.rstrip("g")) * 1024**3) if text.endswith("g") else int(text)
+    except ValueError:  # an unparseable tier is the server's error to give, not ours
+        return int(float(_DEFAULT_MEMORY_TIER.rstrip("g")) * 1024**3)
+
+
+def _reject_oversized_upload(plan: UploadPlan, *, memory: str | None, allow_large: bool) -> None:
+    """Refuse an upload that is anomalous rather than merely large.
+
+    Two gates, whichever trips first. The byte gate is a fraction of the memory tier
+    because `_REMOTE_WORKDIR` is under `/tmp`, which is **RAM-backed** -- uploaded
+    bytes are taken out of the same budget the workload runs in, so "too big" is
+    relative to `--memory`, not absolute. The count gate is separate because a
+    few-thousand-file tree is a wall-clock problem, not a memory one: uploads are one
+    sequential request per file.
+
+    Refuses everywhere, with no interactive branch: a pipeline doing something this
+    unusual should stop, not prompt.
+    """
+    if allow_large:
+        return
+    budget = int(_UPLOAD_BYTE_FRACTION * _memory_bytes(memory))
+    if plan.total_bytes > budget:
+        raise typer.BadParameter(
+            f"would upload {_human(plan.total_bytes)} into /tmp on a "
+            f"{memory or _DEFAULT_MEMORY_TIER} sandbox, over the "
+            f"{_human(budget)} limit; /tmp is RAM-backed, so this competes with the "
+            f"workload. Narrow it with --include/--exclude, raise --memory, or pass "
+            f"--allow-large."
+        )
+    if plan.file_count > _UPLOAD_FILE_LIMIT:
+        raise typer.BadParameter(
+            f"would upload {plan.file_count} files, over the {_UPLOAD_FILE_LIMIT} "
+            f"limit (each is a separate request, so this would be slow). Narrow it "
+            f"with --include/--exclude, or pass --allow-large."
+        )
+
+
+def _human(size: int) -> str:
+    """Bytes as a short human string; the manifest and the refusals share it."""
+    value = float(size)
+    for unit in ("B", "KB", "MB", "GB"):
+        if value < 1024 or unit == "GB":
+            return f"{value:.0f} {unit}" if unit == "B" else f"{value:.1f} {unit}"
+        value /= 1024
+    return f"{value:.1f} GB"
+
+
+def _plan_from_args(
+    *,
+    targets: list[str] | None,
+    app: str | None,
+    command: str | None,
+    detach: bool,
+    envs: list[str] | None,
+    image: str | None,
+    memory: str | None,
+    cpu: float | None,
+    idle_suspend: str | None,
+    name: str | None,
+    function: str | None,
+    include: list[str] | None = None,
+    exclude: list[str] | None = None,
+    allow_credential_file: list[str] | None = None,
+    allow_large: bool = False,
+    eai: list[str] | None = None,
+    secret: list[str] | None = None,
+    no_default_egress: bool = False,
+    quiet: bool = False,
+) -> _RunPlan:
+    """Validate the flags and settle a `_RunPlan` (raising `typer.BadParameter`).
+
+    Three shapes, decided entirely by what the user typed -- never by inspecting the
+    filesystem or the contents of a file: `--app` is an App module, TARGETs are local
+    paths, and neither means the image (or the default image) is the workload.
+    """
+    given = list(targets or [])
+    kind = "app" if app else ("local" if given else "image")
+
+    selection_flags: dict[str, object] = {
+        "--include": include,
+        "--exclude": exclude,
+        "--allow-credential-file": allow_credential_file,
+        "--allow-large": allow_large,
+    }
+    _reject_inapplicable_flags(
+        kind=kind,
+        detach=detach,
+        function=function,
+        name=name,
+        idle_suspend=idle_suspend,
+        command=command,
+        image=image,
+        n_targets=len(given),
+        selection_flags=selection_flags,
+        eai=eai,
+        secret=secret,
+        nde=no_default_egress,
+    )
+
+    env_overrides: dict[str, str] = {}
+    for raw in envs or []:
+        k, v = _parse_env(raw)
+        env_overrides[k] = v
+
+    # An App declares its own egress and secrets in code, so the flags would be
+    # silently overridden rather than merged -- rejected above in
+    # `_reject_inapplicable_flags`, which is why this can run unconditionally.
+    egress_cfg, secret_objs = build_egress(
+        eai=eai, secret=secret, no_default_egress=no_default_egress
+    )
+
+    upload: UploadPlan | None = None
+    resolved = command
+    app_path: Path | None = None
+
+    if kind == "app":
+        app_path = Path(app).expanduser()  # type: ignore[arg-type]  # kind=='app' => app set
+        resolved = None  # the App declares its own entry
+    elif kind == "local":
+        try:
+            resolved_targets = resolve_targets(given)
+            upload = build_plan(
+                resolved_targets,
+                dest_root=_REMOTE_WORKDIR,
+                include=include,
+                exclude=exclude,
+                allow_credential_files=allow_credential_file,
+                max_file_bytes=_MAX_FILE_BYTES,
+            )
+        except TargetError as exc:
+            raise typer.BadParameter(str(exc)) from exc
+        if not upload.selected:
+            # Name the flag that actually applies: --include cannot resurrect a
+            # credential-shaped file by design, so pointing at it here would send the
+            # user in a circle.
+            reasons = upload.skipped_by_reason()
+            if reasons.get("credential") and len(reasons) == 1:
+                fix = "--allow-credential-file PATH names one of them explicitly"
+            elif reasons.get("rule"):
+                fix = "widen it with --include, or relax --exclude"
+            else:
+                fix = "point at different paths"
+            raise typer.BadParameter(
+                f"nothing to upload from {', '.join(repr(t) for t in given)} "
+                f"({_describe_exclusions(upload) or 'the paths hold no regular files'}): "
+                f"{fix}."
+            )
+        if upload.oversized:
+            worst = max(upload.oversized, key=lambda s: s.size)
+            raise typer.BadParameter(
+                f"{worst.rel} is {_human(worst.size)}, over the "
+                f"{_human(_MAX_FILE_BYTES)} per-file limit. Exclude it and mount a "
+                f"stage for large files."
+            )
+        _reject_oversized_upload(upload, memory=memory, allow_large=allow_large)
+        if resolved is None:
+            resolved = _detect_single_file_command(resolved_targets)
+            if resolved is None:
+                raise typer.BadParameter(
+                    f"could not determine how to run {', '.join(repr(t) for t in given)}: "
+                    f"pass --command. (A command is inferred only for a lone .py/.sh/.bash "
+                    f"file.)"
+                )
+    else:
+        # No TARGET and no --app: the image is the workload. Without --detach there is
+        # nothing to stream to completion (`_run_job` execs a command), so a command
+        # is required; with --detach the image's own entrypoint becomes the process.
+        if resolved is None and not detach:
+            raise typer.BadParameter(
+                "nothing to run: pass a TARGET (local path), --command, --app, or "
+                "--image with --detach to run the image's own entrypoint."
+            )
+
+    return _RunPlan(
+        kind=kind,
+        app_path=app_path,
+        upload=upload,
+        command=resolved,
+        base_image="" if kind == "app" else (image or ""),
+        detach=detach,
+        idle_suspend=(idle_suspend or _DETACH_IDLE_SUSPEND) if (detach and kind != "app") else None,
+        memory=memory,
+        cpu=cpu,
+        name=name,
+        function=function,
+        env=env_overrides,
+        egress=egress_cfg,
+        secrets=secret_objs,
+        quiet=quiet,
+    )
+
+
+def _detect_single_file_command(targets: tuple[ResolvedTarget, ...]) -> str | None:
+    """The command for a lone file target, by extension, or None.
+
+    Only a *single* file target gets one: with several targets there is no basis for
+    picking which to run. Detection deliberately still applies when `--image` was
+    given -- `.py` means `python` wherever it runs -- and if that image has no
+    interpreter the run fails loudly (see `_hint_missing_interpreter`).
+    """
+    if len(targets) != 1 or targets[0].is_dir:
+        return None
+    return _detect_file_command(Path(targets[0].basename))
+
+
+def _hint_app_module(plan: _RunPlan) -> None:
+    """Mention `--app` when a script-run target is statically an App module.
+
+    This is the whole remaining role of App detection: it *informs*, it never decides.
+    `run agent_app.py` runs the module as a script, which for an App file usually does
+    nothing visible -- so a nudge is worth printing, while silently switching to a
+    different execution path (what the old behaviour did) is not.
+    """
+    if plan.kind != "local" or plan.upload is None:
+        return
+    for item in plan.upload.selected:
+        if item.source.suffix == ".py" and _looks_like_app(item.source):
+            typer.echo(
+                f"note: {item.rel} declares an App; to deploy it use "
+                f"`--app {item.source.name}` (running it as a script may do nothing).",
+                err=True,
+            )
+            return
+
+
+def _describe_exclusions(plan: UploadPlan) -> str:
+    """ "3 credential-shaped, 2 vcs/build" -- the manifest's why-clause."""
+    labels = {
+        "credential": "credential-shaped",
+        "default": "vcs/build",
+        "rule": "excluded by a rule",
+        "symlink-file": "symlinked file",
+        "symlink-dir": "symlinked directory",
+        "not-regular": "not a regular file",
+        "unreadable": "unreadable",
+        "bad-name": "unusable name",
+    }
+    counts = plan.skipped_by_reason()
+    return ", ".join(f"{n} {labels.get(r, r)}" for r, n in sorted(counts.items()))
+
+
+def _print_manifest(plan: UploadPlan, *, quiet: bool) -> None:
+    """Say what is about to leave the machine, before it does.
+
+    Advisory, so it goes to stderr and `--quiet` silences it -- but refusals and
+    errors never are, so those still print. Top-level entries only: listing every
+    file would bury the counts that matter.
+    """
+    if quiet:
+        return
+    tops: dict[str, int] = {}
+    for item in plan.selected:
+        tops[item.rel.split("/")[0]] = tops.get(item.rel.split("/")[0], 0) + 1
+    shown = ", ".join(
+        f"{name} ({count})" if count > 1 else name for name, count in sorted(tops.items())
+    )
+    _emit_status(
+        f"upload: {plan.file_count} file(s), {_human(plan.total_bytes)} -> {_REMOTE_WORKDIR}",
+        quiet=quiet,
+    )
+    _emit_status(f"  {shown}", quiet=quiet)
+    if why := _describe_exclusions(plan):
+        _emit_status(f"  excluded: {why}", quiet=quiet)
+    # A symlinked directory contributes *no* files and is the one exclusion that
+    # silently loses a whole subtree, so it is named rather than only counted.
+    for dropped in plan.skipped:
+        if dropped.reason == "symlink-dir":
+            _emit_status(
+                f"  note: {dropped.rel} is a symlink; its contents were not sent", quiet=quiet
+            )
+
+
+async def _upload_target(sb: AsyncSandbox, plan: _RunPlan) -> str:
+    """Push the selected files into the box; return the cwd for the command.
+
+    No `make_directory` calls: `upload_file` creates parent directories itself, and
+    each `make_directory` is a `python3 -c` exec round trip rather than a file
+    operation -- so dropping them removes one request per directory.
+    """
+    upload = plan.upload
+    assert upload is not None
+    total = upload.file_count
+    # Progress every 10%, so a few-thousand-file tree does not look hung behind a
+    # single status line. Never for a handful of files, where it would be noise.
+    step = max(1, total // 10) if total > 25 else total + 1
+    for index, item in enumerate(upload.selected, start=1):
+        await sb.upload_file(str(item.source), f"{_REMOTE_WORKDIR}/{item.rel}")
+        if index % step == 0 and index != total:
+            _emit_status(f"uploading... {index}/{total}", quiet=plan.quiet)
+    return upload.cwd
+
+
+def _hint_missing_interpreter(plan: _RunPlan, code: int) -> None:
+    """After a 127, say the likely cause: the image has no such interpreter.
+
+    Extension detection applies even when `--image` names a custom image, so
+    `run main.py --image /repo/scratch:1` resolves to `python main.py` on an image
+    that may have no python. The exit code alone (`sh: python: not found`) does not
+    mention the flag that fixes it.
+    """
+    if code != 127 or plan.command is None:
+        return
+    runner = plan.command.split()[0]
+    where = plan.base_image or "the default image"
+    typer.echo(
+        f"hint: exit 127 usually means {runner!r} is not on {where}. "
+        f"Pass --command to run it another way, or use an image that has it.",
+        err=True,
+    )
+
+
+async def _run_job(plan: _RunPlan) -> int:
+    """Run-to-completion: create a fresh box, upload local code (if any), stream the
+    command, and tear the box down — via the shared `_run_on_fresh_sandbox` path."""
+
+    async def _use(sb: AsyncSandbox) -> int:
+        cwd: str | None = None
+        if plan.upload is not None:
+            _print_manifest(plan.upload, quiet=plan.quiet)
+            cwd = await _upload_target(sb, plan)
+        assert plan.command is not None  # a job always has a command (settled in _plan_from_args)
+        return await _exec_streaming(sb, plan.command, cwd, None)
+
+    return await _run_on_fresh_sandbox(
+        use=_use,
+        keep=False,
+        quiet=plan.quiet,
+        announce_ready=True,
+        image=plan.base_image,
+        memory=plan.memory,
+        cpu=plan.cpu,
+        env=plan.env or None,
+        egress=plan.egress,  # type: ignore[arg-type]  # Egress | None, lazily typed
+        secrets=plan.secrets,  # type: ignore[arg-type]
+    )
+
+
+async def _run_detached_image(plan: _RunPlan) -> None:
+    """Long-running image: create detached with the command as the managed process
+    (or the image's own entrypoint when no command), print the handle."""
+    command = ["sh", "-c", plan.command] if plan.command else None
+
+    async def _use(sb: AsyncSandbox) -> int:
+        typer.echo(f"running (detached): {sb.name or sb.id}")
+        typer.echo(f"logs: snow sandbox logs {sb.name or sb.id}", err=True)
+        return 0
+
+    await _run_on_fresh_sandbox(
+        use=_use,
+        keep=True,
+        quiet=plan.quiet,
+        image=plan.base_image,
+        memory=plan.memory,
+        cpu=plan.cpu,
+        env=plan.env or None,
+        egress=plan.egress,  # type: ignore[arg-type]  # Egress | None, lazily typed
+        secrets=plan.secrets,  # type: ignore[arg-type]
+        name=plan.name,
+        command=command,
+        idle_suspend=plan.idle_suspend,
+    )
+
+
+async def _run_detached_local(plan: _RunPlan) -> None:
+    """Long-running local code: create an idle box, upload, background the command,
+    and print the handle. The backgrounded process is not the managed process, so
+    its output is tee'd to a file rather than the managed-process log."""
+
+    async def _use(sb: AsyncSandbox) -> int:
+        assert plan.upload is not None and plan.command is not None
+        _print_manifest(plan.upload, quiet=plan.quiet)
+        cwd = await _upload_target(sb, plan)
+        bg = (
+            f"cd {shlex.quote(cwd)} && "
+            f"nohup {plan.command} >{shlex.quote(_DETACH_LOG)} 2>&1 & echo started"
+        )
+        await sb.exec(["sh", "-c", bg])
+        typer.echo(f"running (detached): {sb.name or sb.id}")
+        typer.echo(
+            f"logs: snow sandbox logs {sb.name or sb.id} --file {_DETACH_LOG}",
+            err=True,
+        )
+        return 0
+
+    await _run_on_fresh_sandbox(
+        use=_use,
+        keep=True,
+        quiet=plan.quiet,
+        image=plan.base_image,
+        memory=plan.memory,
+        cpu=plan.cpu,
+        env=plan.env or None,
+        egress=plan.egress,  # type: ignore[arg-type]  # Egress | None, lazily typed
+        secrets=plan.secrets,  # type: ignore[arg-type]
+        name=plan.name,
+        idle_suspend=plan.idle_suspend,
+    )
+
+
+async def _run_app(plan: _RunPlan, *, dry_run: bool) -> int:
+    """App-module target: the authoring path `deploy` used to drive. Bundles the
+    module's App via `deploy_spec` and streams it. `--detach` runs it detached."""
+    from snowflake.cli_sandbox._adapter import sdk_connection
+    from snowflake.sandbox.deploy import deploy_spec as _deploy_spec
+
+    assert plan.app_path is not None
+    spec = _load_app_spec(str(plan.app_path), plan.function, plan.env)
+
+    def _on_line(stream: str, data: str) -> None:
+        typer.echo(data, err=(stream == "stderr"), nl=False)
+
+    result = await _deploy_spec(
+        spec,
+        on_line=None if dry_run else _on_line,
+        dry_run=dry_run,
+        run_preflight=True,
+        detach=plan.detach,
+        connection=sdk_connection(),
+    )
+    _print_preflight_findings(result)
+    if dry_run:
+        _print_app_plan(result)  # raises Exit(0)
+    if plan.detach:
+        typer.echo(f"running (detached): {result.name or result.sandbox_id}")
+        return 0
+    if result.diagnosis:
+        typer.echo(f"diagnosis: {result.diagnosis}", err=True)
+    return result.exit_code or 0
+
+
+def _run_command(
+    targets: list[str] | None = typer.Argument(
+        None,
+        metavar="[TARGET]...",
+        help="Local paths to run: files and/or directories, repeatable. Never an "
+        "image reference -- pass images as --image. Omit to run --image (or the "
+        "default image) directly, or use --app for an App module.",
+    ),
+    app: str | None = typer.Option(
+        None,
+        "--app",
+        metavar="MODULE.py",
+        help="Deploy a .py module that declares an App, via the SDK authoring path. "
+        "Explicit: a plain script is never treated as an App because of its contents.",
+    ),
+    command: str | None = typer.Option(
+        None,
+        "--command",
+        "--cmd",
+        metavar="CMD",
+        help="Command to run after the code is in place (streamed, exits with its "
+        "code). Overrides extension detection; required for a directory, an "
+        "unrecognized file type, and for a TARGET-less run unless --detach runs the "
+        "image's own entrypoint. Not valid for an App module. `--cmd` is an accepted "
+        "alias (same flag on `shell`).",
+    ),
+    detach: bool = typer.Option(
+        False,
+        "--detach",
+        "-d",
+        help="Create the sandbox and leave it running instead of running to "
+        "completion: wait for it to spin up and the command to start, then print "
+        "the handle and return. (Supervised restart across platform interruptions "
+        "is a separate, not-yet-available feature.)",
+    ),
+    dry_run: bool = typer.Option(
+        False,
+        "--dry-run",
+        help="Print the resolved plan and exit without creating anything.",
+    ),
+    function: str | None = typer.Option(
+        None,
+        "--function",
+        "-f",
+        metavar="NAME",
+        help="For an App module: which @app.function to run (default: the first). "
+        "Errors on any other target.",
+    ),
+    envs: list[str] | None = typer.Option(
+        None,
+        "--env",
+        "-e",
+        metavar="KEY=VAL",
+        help=_ENV_HELP,
+    ),
+    image: str | None = typer.Option(
+        None,
+        "--image",
+        metavar="IMAGE",
+        help="The image to run. With no TARGET it IS the workload; with local "
+        "TARGETs it is the base image that code runs on. Default: the deployment's "
+        "default runtime image. Invalid with --app (the App declares it).",
+    ),
+    include: list[str] | None = typer.Option(
+        None,
+        "--include",
+        metavar="GLOB",
+        help="Re-admit paths an exclusion dropped; repeatable, applied after every "
+        "--exclude. gitignore syntax, relative to each TARGET. Cannot resurrect a "
+        "credential-shaped file.",
+    ),
+    exclude: list[str] | None = typer.Option(
+        None,
+        "--exclude",
+        metavar="GLOB",
+        help="Skip matching paths; repeatable. gitignore syntax relative to each "
+        "TARGET, so `node_modules/` and `data/` work as written.",
+    ),
+    allow_credential_file: list[str] | None = typer.Option(
+        None,
+        "--allow-credential-file",
+        metavar="PATH",
+        help="Upload one credential-shaped file (.env, *.pem, id_rsa, ...) that is "
+        "excluded by default. Exact path only, never a glob; repeatable.",
+    ),
+    eai: list[str] | None = typer.Option(
+        None,
+        "--eai",
+        metavar="NAME",
+        help=EAI_HELP,
+    ),
+    secret: list[str] | None = typer.Option(
+        None,
+        "--secret",
+        metavar="ENV_VAR=DB.SCHEMA.NAME",
+        help=SECRET_HELP,
+    ),
+    no_default_egress: bool = typer.Option(
+        False,
+        "--no-default-egress",
+        help=NO_DEFAULT_EGRESS_HELP,
+    ),
+    allow_large: bool = typer.Option(
+        False,
+        "--allow-large",
+        help="Proceed with an upload over the size or file-count limit. /tmp is "
+        "RAM-backed, so a large upload competes with the workload for --memory.",
+    ),
+    memory: str | None = typer.Option(
+        None,
+        "--memory",
+        metavar="TIER",
+        help="Memory tier: 1g/4g/8g/16g/32g/64g (default: 4g).",
+    ),
+    cpu: float | None = typer.Option(
+        None,
+        "--cpu",
+        metavar="CORES",
+        help="CPU cores (0.25-8.0).",
+    ),
+    idle_suspend: str | None = typer.Option(
+        None,
+        "--idle-suspend",
+        metavar="DURATION",
+        help="Idle-suspend timeout (e.g. 30m/2h) for a --detach image or "
+        "local-code run (default: 24h).",
+    ),
+    name: str | None = typer.Option(
+        None,
+        "--name",
+        metavar="NAME",
+        help="Name for a --detach image or local-code sandbox (unique per owner).",
+    ),
+    quiet: bool = typer.Option(
+        False,
+        "--quiet",
+        "-q",
+        help="Suppress the status lines on stderr; the command's own output is unaffected.",
+    ),
+    use_snow_connection: bool = typer.Option(
+        True,
+        "--use-snow-connection/--no-snow-connection",
+        help=_USE_SNOW_CONN_HELP,
+    ),
+    connection: str | None = typer.Option(
+        None,
+        "--connection",
+        "-c",
+        help=_CONN_HELP,
+    ),
+    **options: Any,
+) -> None:
+    from snowflake.sandbox.exceptions import SandboxError
+
+    plan = _plan_from_args(
+        targets=targets,
+        app=app,
+        command=command,
+        detach=detach,
+        envs=envs,
+        image=image,
+        memory=memory,
+        cpu=cpu,
+        idle_suspend=idle_suspend,
+        name=name,
+        function=function,
+        include=include,
+        exclude=exclude,
+        allow_credential_file=allow_credential_file,
+        allow_large=allow_large,
+        eai=eai,
+        secret=secret,
+        no_default_egress=no_default_egress,
+        quiet=quiet,
+    )
+    _hint_app_module(plan)
+
+    # An inferred dry-run creates nothing, so it needs no live connection.
+    if dry_run and plan.kind != "app":
+        _print_inferred_plan(plan)  # raises Exit(0)
+
+    # No dry run connects -- `_apply_connection` below is passed `not dry_run` -- so
+    # announcing a connection for one was simply untrue.
+    if use_snow_connection and not dry_run:
+        where = f" ({connection})" if connection else ""
+        _emit_status(f"Connecting to Snowflake{where}...", quiet=quiet)
+    # An App dry-run resolves the plan locally too; only a live run needs credentials.
+    _apply_connection(use_snow_connection and not dry_run, connection=connection)
+
+    try:
+        if plan.kind == "app":
+            code = asyncio.run(_run_app(plan, dry_run=dry_run))
+            raise typer.Exit(code)
+        if not plan.detach:
+            code = asyncio.run(_run_job(plan))
+            _hint_missing_interpreter(plan, code)
+            raise typer.Exit(code)
+        if plan.kind == "image":
+            asyncio.run(_run_detached_image(plan))
+        else:
+            asyncio.run(_run_detached_local(plan))
+    except KeyboardInterrupt:
+        raise typer.Exit(130) from None
+    except SandboxError as exc:
+        typer.echo(f"error: {exc}", err=True)
+        raise typer.Exit(1) from exc