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

snowflake/sandbox/_upload_plan.py

@@ -0,0 +1,497 @@
+"""Deciding *what* a directory upload sends, and being able to say why.
+
+This is the selection engine behind `Sandbox.upload_dir` and the `from_local`
+bundle, and behind `snow sandbox run`'s TARGET handling. It lives here, in the SDK,
+because the SDK is where the primitives already were (`_bundle._is_credential_path`,
+`_globs`) and because two different walks had drifted apart: `_bundle._collect_tree`
+used `rglob` and reported nothing, while this one used `os.scandir` and recorded a
+reason per drop. One engine, so they cannot disagree again.
+
+The CLI keeps the half that is genuinely about argv — `resolve_targets` and its
+`TargetError`, whose messages name CLI flags — in `cli_sandbox._upload_plan`, and
+imports the engine from here.
+
+The module's job is to make every drop explainable. `UploadPlan.skipped` carries a
+reason per path, so a caller can report "3 credential-shaped, 91 vcs/build, 2
+symlinked directories" instead of silently sending fewer files than the user
+expected. Silent under-upload is the failure mode users cannot debug.
+
+Three deliberate choices worth knowing:
+
+* **`os.scandir` recursion, not `rglob`.** `rglob` swallows per-entry errors, so an
+  unreadable directory is indistinguishable from an empty one, and it never
+  recurses into a symlinked directory — which means a pnpm/bazel workspace whose
+  packages are symlinks uploads *nothing* from those trees, without a word. Explicit
+  recursion lets both be counted and reported.
+* **The credential test is fed the target-relative path, not the destination rel
+  and not a fixed-length tail.** `_is_credential_path` keys its directory rules on
+  everything but the last component, so the path it judges has to name every
+  directory between the tree root and the file — no more (a project that merely
+  lives under `~/.snowflake/` is not a credential) and no less (a truncated tail
+  hides `fixtures/.aws/sso/cache/token.json`). A single-file target has no tree to
+  be relative to, so there the absolute source path is judged instead.
+* **`include` is compiled as a trailing negation.** gitignore's last-match-wins
+  then gives "include beats exclude" for free, and the reason a file survived can
+  still name the rule that saved it.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Literal
+
+from snowflake.sandbox._bundle import _is_credential_path
+from snowflake.sandbox._globs import GlobRule, anchored_head, compile_rules, match_rules
+from snowflake.sandbox.exceptions import SandboxValidationError
+
+__all__ = [
+    "SKIP_DIRS",
+    "ResolvedTarget",
+    "Selected",
+    "Skipped",
+    "UploadPlan",
+    "build_plan",
+    "plan_directory",
+]
+
+# Build output / VCS / editor state, never worth uploading. Carried over from
+# `_run_command`; a `--include` can re-admit anything here, which is why the check
+# runs before user rules rather than short-circuiting them.
+SKIP_DIRS = frozenset(
+    {
+        ".git",
+        ".hg",
+        ".svn",
+        "__pycache__",
+        ".venv",
+        "venv",
+        "env",
+        "node_modules",
+        "target",
+        "dist",
+        "build",
+        ".mypy_cache",
+        ".pytest_cache",
+        ".ruff_cache",
+        ".tox",
+        ".idea",
+        ".vscode",
+        ".eggs",
+    }
+)
+
+# Why a path was not uploaded. 'default' and 'rule' are ordinary filtering; the rest
+# are conditions the user probably wants to know about.
+SkipReason = Literal[
+    "credential",
+    "default",
+    "empty-dir",
+    "rule",
+    "symlink-file",
+    "symlink-dir",
+    "not-regular",
+    "unreadable",
+    "bad-name",
+]
+
+
+@dataclass(frozen=True)
+class ResolvedTarget:
+    """One validated target: what the user typed, and where it lands."""
+
+    given: str
+    path: Path  # absolute, symlinks resolved
+    is_dir: bool
+    basename: str  # the single path component it occupies in the sandbox
+
+
+@dataclass(frozen=True)
+class Selected:
+    source: Path
+    rel: str  # posix, relative to the sandbox destination root
+    size: int
+
+
+@dataclass(frozen=True)
+class Skipped:
+    rel: str
+    reason: SkipReason
+    detail: str = ""  # the matching rule, or the OS error
+
+
+@dataclass(frozen=True)
+class UploadPlan:
+    targets: tuple[ResolvedTarget, ...]
+    selected: tuple[Selected, ...]
+    skipped: tuple[Skipped, ...]
+    total_bytes: int
+    cwd: str
+    oversized: tuple[Selected, ...] = field(default=())
+
+    @property
+    def file_count(self) -> int:
+        return len(self.selected)
+
+    def skipped_by_reason(self) -> dict[SkipReason, int]:
+        """Counts per reason, for the manifest's "why" line."""
+        out: dict[SkipReason, int] = {}
+        for item in self.skipped:
+            out[item.reason] = out.get(item.reason, 0) + 1
+        return out
+
+
+def _reject_unusable_name(name: str) -> str | None:
+    """Return a reason string when *name* cannot ride the upload path.
+
+    `make_directory` used to reject NUL and newline client-side, but `upload_file`
+    creates parents itself so those calls are gone — taking the only guard with
+    them. The check moves here, where it can also be reported rather than raised.
+    """
+    if "\x00" in name:
+        return "contains a NUL byte"
+    if "\n" in name or "\r" in name:
+        return "contains a newline"
+    return None
+
+
+def _compile(exclude: list[str] | None, include: list[str] | None) -> tuple[GlobRule, ...]:
+    """Excludes in order, then includes as trailing negations so include wins.
+
+    Two separate lists cannot express an interleaved order, so rather than pretend
+    otherwise the rule is stated plainly: every `include` is applied after every
+    `exclude`.
+    """
+    for pattern in (*(exclude or []), *(include or [])):
+        if pattern.startswith("!"):
+            raise SandboxValidationError(
+                f"{pattern!r}: '!' is not accepted here — pass the pattern to "
+                f"include= to re-admit paths instead of negating an exclude=."
+            )
+        # Validated in the caller's own spelling, before the `!` below is prepended:
+        # `compile_rules` quotes the pattern it was handed, and quoting `'![abc'`
+        # names a pattern the caller never typed. Prepending `!` cannot change
+        # validity -- `_translate` strips it first -- so this is the same check.
+        try:
+            compile_rules([pattern])
+        except ValueError as exc:
+            raise SandboxValidationError(str(exc)) from exc
+    return compile_rules([*(exclude or []), *(f"!{p}" for p in (include or []))])
+
+
+def _credential_rel(source: Path, mrel: str, *, explicit: bool) -> Path:
+    """The path `_is_credential_path` should judge.
+
+    Inside a walked tree that is *mrel*, the target-relative path. The denylist
+    inspects every component *but* the last, so it needs every directory between the
+    tree root and the file and nothing above it. A fixed-length tail gets this wrong
+    in both directions: `fixtures/.aws/sso/cache/token.json` hides `.aws` from a
+    three-component tail and ships a credential, while a tree that merely happens to
+    sit under `~/.snowflake/` has components *above* its own root judged and drops
+    its own source files as credentials — silently, since `credential` is not a
+    notable bundle skip.
+
+    A single named file is the one case with no tree to be relative to: *mrel* is a
+    bare basename, which hides the signal (`.ssh/config` tests True, `config`
+    False), so the absolute source path is judged. That direction only ever refuses
+    more, and `allow_credential_files=` is the escape hatch.
+    """
+    return source if explicit else Path(mrel)
+
+
+def build_plan(
+    targets: tuple[ResolvedTarget, ...],
+    *,
+    dest_root: str,
+    exclude: list[str] | None = None,
+    include: list[str] | None = None,
+    allow_credential_files: list[str] | None = None,
+    max_file_bytes: int | None = None,
+) -> UploadPlan:
+    """Walk *targets* and decide every file's fate, recording a reason for each."""
+    rules = _compile(exclude, include)
+    allowed = {Path(p).expanduser().resolve() for p in (allow_credential_files or [])}
+
+    selected: list[Selected] = []
+    skipped: list[Skipped] = []
+
+    for target in targets:
+        prefix = target.basename
+        if target.is_dir:
+            _walk_dir(target.path, prefix, rules, allowed, selected, skipped)
+        else:
+            # A lone file matches on its own name: `run proj/boot.py --exclude boot.py`.
+            _classify_file(
+                target.path,
+                prefix,
+                target.basename,
+                rules,
+                allowed,
+                selected,
+                skipped,
+                explicit=True,
+            )
+
+    oversized = tuple(s for s in selected if s.size > max_file_bytes) if max_file_bytes else ()
+    return UploadPlan(
+        targets=targets,
+        selected=tuple(selected),
+        skipped=tuple(skipped),
+        total_bytes=sum(s.size for s in selected),
+        cwd=_resolve_cwd(targets, dest_root),
+        oversized=oversized,
+    )
+
+
+def _resolve_cwd(targets: tuple[ResolvedTarget, ...], dest_root: str) -> str:
+    """Where the command runs.
+
+    A single directory target runs *inside* that directory, which is what makes
+    `run ./project --command "python -m app"` behave as typed. Everything else runs
+    at the root, so a relative command can still reach every target by basename —
+    with one dir target among several, a cwd inside it would hide the siblings.
+    """
+    if len(targets) == 1 and targets[0].is_dir:
+        return f"{dest_root}/{targets[0].basename}"
+    return dest_root
+
+
+def _walk_dir(
+    root: Path,
+    prefix: str,
+    rules: tuple[GlobRule, ...],
+    allowed: set[Path],
+    selected: list[Selected],
+    skipped: list[Skipped],
+) -> None:
+    """Recurse *root* with `os.scandir`, recording every exclusion with its reason.
+
+    Two paths are tracked per entry, and conflating them is a bug: *rel* is where the
+    file lands in the sandbox (prefixed with the target's basename) and is what the
+    manifest shows, while *mrel* is the path **relative to the target the user named**
+    and is what patterns match against. Users write `--exclude "src/**"` thinking in
+    terms of the directory they passed, exactly as `.gitignore` is relative to its own
+    directory; matching the prefixed path instead would make every *anchored* pattern
+    silently never match. It also keeps a target that happens to be named `build` or
+    `dist` from being mistaken for a default-skipped directory.
+    """
+    stack: list[tuple[Path, str, str]] = [(root, prefix, "")]
+    while stack:
+        current, rel_prefix, match_prefix = stack.pop()
+        try:
+            entries = sorted(os.scandir(current), key=lambda e: e.name)
+        except OSError as exc:
+            skipped.append(Skipped(rel_prefix, "unreadable", exc.strerror or str(exc)))
+            continue
+
+        if not entries:
+            # Reported rather than dropped: the destination gets no such directory
+            # (there is no file to create it under), and an app that expects
+            # `logs/` to exist otherwise gets neither the directory nor a word
+            # about it -- against this module's "every drop is explainable" premise.
+            skipped.append(Skipped(f"{rel_prefix}/", "empty-dir"))
+            continue
+
+        for entry in entries:
+            rel = f"{rel_prefix}/{entry.name}"
+            mrel = f"{match_prefix}/{entry.name}" if match_prefix else entry.name
+            if bad := _reject_unusable_name(entry.name):
+                skipped.append(Skipped(rel, "bad-name", bad))
+                continue
+            try:
+                is_symlink = entry.is_symlink()
+                is_dir = entry.is_dir(follow_symlinks=False)
+                is_file = entry.is_file(follow_symlinks=False)
+            except OSError as exc:
+                skipped.append(Skipped(rel, "unreadable", exc.strerror or str(exc)))
+                continue
+
+            if is_symlink:
+                # Never followed, in either direction. Reported separately because a
+                # symlinked *directory* can silently omit an entire vendored tree,
+                # while a symlinked file omits one file.
+                points_at_dir = False
+                try:
+                    points_at_dir = os.path.isdir(entry.path)
+                except OSError:
+                    pass
+                skipped.append(Skipped(rel, "symlink-dir" if points_at_dir else "symlink-file"))
+                continue
+
+            if is_dir:
+                # Pruning a default-skipped directory is cheap and lets the manifest
+                # report one line instead of thousands. But `--include` means "re-admit
+                # what matches", and a pattern like `dist/**` cannot match the bare
+                # directory path -- so a skipped tree an include could still reach into
+                # has to be descended, and per-file evaluation decides.
+                #
+                # Asked per directory rather than once for the whole walk: any include
+                # at all used to disable pruning everywhere, so `include=["dist/**"]`
+                # walked `.git`, `node_modules` and `.venv` in full and allocated a
+                # `Skipped` per file -- hundreds of thousands on a large repo, plus a
+                # spurious "not-regular" warning off sockets under `.venv`.
+                if entry.name in SKIP_DIRS and not _include_may_reach(mrel, rules):
+                    skipped.append(Skipped(rel + "/", "default", entry.name))
+                    continue
+                stack.append((Path(entry.path), rel, mrel))
+                continue
+
+            if not is_file:
+                skipped.append(Skipped(rel, "not-regular"))
+                continue
+
+            _classify_file(
+                Path(entry.path), rel, mrel, rules, allowed, selected, skipped, explicit=False
+            )
+
+
+def _classify_file(
+    source: Path,
+    rel: str,
+    mrel: str,
+    rules: tuple[GlobRule, ...],
+    allowed: set[Path],
+    selected: list[Selected],
+    skipped: list[Skipped],
+    *,
+    explicit: bool,
+) -> None:
+    """Decide one file. *explicit* marks a path the user named as a TARGET.
+
+    *rel* is the destination path (reported); *mrel* is target-relative (matched).
+    """
+    if bad := _reject_unusable_name(Path(rel).name):
+        skipped.append(Skipped(rel, "bad-name", bad))
+        return
+
+    hit = match_rules(mrel, rules)
+    if hit is not None and not hit.negated:
+        skipped.append(Skipped(rel, "rule", hit.source))
+        return
+    if hit is None and not explicit and _in_skipped_dir(mrel):
+        skipped.append(Skipped(rel, "default"))
+        return
+
+    # The credential filter runs last and is not overridable by a pattern: with
+    # negation available, a stray `--include "*"` would otherwise be one flag away
+    # from shipping ~/.aws/credentials. Only an exact --allow-credential-file PATH
+    # overrides, and naming a credential as a TARGET does not.
+    if (
+        _is_credential_path(_credential_rel(source, mrel, explicit=explicit))
+        and source not in allowed
+    ):
+        skipped.append(Skipped(rel, "credential", source.name))
+        return
+
+    try:
+        size = source.stat().st_size
+    except OSError as exc:
+        skipped.append(Skipped(rel, "unreadable", exc.strerror or str(exc)))
+        return
+    selected.append(Selected(source, rel, size))
+
+
+def _include_may_reach(mrel: str, rules: tuple[GlobRule, ...]) -> bool:
+    """True when some `include=` could still match a path inside skipped dir *mrel*.
+
+    An unanchored include (`*.pyc`) matches at any depth, so it could; an include
+    anchored to a literal first segment (`dist/**`) can only reach into a tree whose
+    own first component is that segment. Anything this cannot decide counts as "it
+    could", so the answer is never wrong in the direction that loses files.
+    """
+    first = mrel.split("/", 1)[0]
+    for rule in rules:
+        if not rule.negated:
+            continue
+        head = anchored_head(rule)
+        if head is None or head == first:
+            return True
+    return False
+
+
+def _in_skipped_dir(rel: str) -> bool:
+    """True when any parent component of *rel* is a default-skipped directory.
+
+    `_walk_dir` prunes these before descending, so this only catches the case where
+    a file is reached by another route.
+    """
+    return bool(SKIP_DIRS & set(Path(rel).parts[:-1]))
+
+
+def plan_directory(
+    local_dir: str | Path,
+    *,
+    dest_root: str,
+    exclude: list[str] | None = None,
+    include: list[str] | None = None,
+    allow_credential_files: list[str] | None = None,
+    max_file_bytes: int | None = None,
+    strip_root: bool = False,
+) -> UploadPlan:
+    """Plan the upload of one local directory, the shape both SDK callers need.
+
+    `build_plan` takes resolved *targets* because the CLI can be handed several at
+    once; the SDK's two callers each have exactly one directory, so this wraps the
+    single-target case and owns the two things that differ between them.
+
+    ``strip_root`` chooses whether the directory's own name becomes a path component
+    in the destination. `Sandbox.upload_dir` strips it -- ``upload_dir("./site",
+    "/app")`` puts ``site/index.html`` at ``/app/index.html``, which is what "upload
+    the contents of this folder there" means, and mirrors ``cp -r src/. dst``. The
+    `from_local` bundle also strips it, because the zip is extracted *as* the project
+    root. `snow sandbox run` keeps it, so several targets can sit side by side.
+
+    Raises `SandboxValidationError` if *local_dir* is not a directory, so a caller
+    that passes a file gets told which of the two verbs it wanted.
+    """
+    root = Path(local_dir).expanduser().resolve()
+    if not root.exists():
+        # Distinguished from the is-a-file case below: sending someone to
+        # `upload_file()` for a path that is not there is the same misdirection this
+        # message was introduced to remove from `upload_file`.
+        raise SandboxValidationError(f"{root} does not exist")
+    if not root.is_dir():
+        raise SandboxValidationError(
+            f"{root} is not a directory; use upload_file() for a single file"
+        )
+    target = ResolvedTarget(str(local_dir), root, is_dir=True, basename=root.name)
+    plan = build_plan(
+        (target,),
+        dest_root=dest_root,
+        exclude=exclude,
+        include=include,
+        allow_credential_files=allow_credential_files,
+        max_file_bytes=max_file_bytes,
+    )
+    if not strip_root:
+        return plan
+    # Re-root every path at dest_root by dropping the leading "<basename>/". Done
+    # here rather than by teaching `_walk_dir` a second prefix convention, so the
+    # walk keeps one rule and the rewrite stays visible in one place.
+    cut = len(target.basename) + 1
+    return UploadPlan(
+        targets=plan.targets,
+        selected=tuple(
+            Selected(s.source, s.rel[cut:], s.size)
+            if s.rel.startswith(target.basename + "/")
+            else s
+            for s in plan.selected
+        ),
+        skipped=tuple(
+            # `or "."`: the root itself is reported when it is empty, and stripping
+            # its own name off leaves nothing to name it by.
+            Skipped(k.rel[cut:] or ".", k.reason, k.detail)
+            if k.rel.startswith(target.basename + "/")
+            else k
+            for k in plan.skipped
+        ),
+        total_bytes=plan.total_bytes,
+        cwd=dest_root,
+        oversized=tuple(
+            Selected(s.source, s.rel[cut:], s.size)
+            if s.rel.startswith(target.basename + "/")
+            else s
+            for s in plan.oversized
+        ),
+    )

snowflake/sandbox/_version.py

@@ -0,0 +1,37 @@
+"""Single source of truth for the installed package version.
+
+Resolves via ``importlib.metadata`` against the installed distribution
+(the pinned wheel/sdist a caller ``pip install``s, or the dist-info an
+editable install registers) so a runtime import always reflects the actual
+installed build -- catching the "stale git checkout" class of incident this
+was written for, where a long-stale SDK checkout silently routed to a dead
+endpoint.
+
+There is no ``setuptools-scm`` wiring: shallow CI checkouts can't derive a
+version from git anyway. Instead this is a documented manual semver track:
+``_FALLBACK_VERSION`` below must be bumped in lockstep with
+``[project].version`` in ``pyproject.toml`` on every release, and the
+release tag (``vX.Y.Z``) must match -- ``Jenkinsfile.release`` fails the
+publish if the tag and ``pyproject.toml`` disagree. The fallback only
+matters when the package metadata can't be found at all (e.g. running from
+a raw source checkout with nothing installed).
+
+Kept import-cheap: only stdlib ``importlib.metadata``.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+
+__all__ = ["__version__"]
+
+_DIST_NAME = "snowflake-sandbox-python"
+
+# Keep in sync with [project].version in pyproject.toml.
+_FALLBACK_VERSION = "0.2.1a1"
+
+try:
+    __version__: str = _pkg_version(_DIST_NAME)
+except PackageNotFoundError:  # pragma: no cover - raw/uninstalled source checkout
+    __version__ = _FALLBACK_VERSION

snowflake/sandbox/_watch.py

@@ -0,0 +1,164 @@
+"""Filesystem change notifications for ``AsyncSandbox``, over ``inotify(7)``.
+
+One of the three separate mechanisms that reach a sandbox filesystem, split out of
+``files.py``. `files` keeps the ``/files`` byte route; `_fs_ops` the directory
+operations. Paths here follow the byte route rather than `_fs_ops`: ``watch``
+requires an absolute path, and calls `files._require_absolute` to say so.
+
+``watch`` streams filesystem-change events
+(`FileWatchEvent`) as they happen. It needs no server route: it runs a tiny
+``ctypes``-driven ``inotify(7)`` monitor in the container over the resumable
+``exec_stream`` (the same channel the directory ops use), which reattaches to the
+same exec session when the ingress drops a long-lived connection. Zero container
+dependency — inotify is a kernel facility reached through ``libc``, so it does
+not rely on an ``inotifywait`` binary (absent from the image) or any pip
+install. See `watch` for the recursion/indefinite-timeout caveats.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING
+
+from snowflake.sandbox._runtime._fs_helper import _watch_program
+from snowflake.sandbox._runtime._protocol import (
+    _IN_ACCESS,
+    _IN_CLOSE_WRITE,
+    _IN_CREATE,
+    _IN_DELETE,
+    _IN_MODIFY,
+    _IN_MOVED_FROM,
+    _IN_MOVED_TO,
+    _IN_OPEN,
+    _WATCH_SENTINEL,
+)
+from snowflake.sandbox._transport import Transport
+from snowflake.sandbox.files import _require_absolute
+from snowflake.sandbox.types import FileWatchEvent, FileWatchEventType
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator, Sequence
+
+    from snowflake.sandbox.client import AsyncSandbox
+
+__all__ = ["watch"]
+
+
+# ---- filesystem change notifications (Modal Sandbox.filesystem.watch) ------
+#
+# The monitor emits one sentinel-prefixed JSON line per raw inotify event; watch()
+# parses those, maps the mask onto FileWatchEventType, applies the caller's filter,
+# and yields FileWatchEvent. argv (path/recursive/timeout) is passed as separate
+# argv entries -- never shell-interpolated -- so a path with spaces/quotes is safe.
+# `inotify_init1` is always present on a Linux kernel, so the monitor needs no
+# container package; see the module docstring for the rest of the mechanism.
+
+# The single server-side exec budget a watch stream gets when no timeout is asked
+# for. exec_stream caps an untimed exec at _DEFAULT_EXEC_BUDGET_S (600s) server
+# side, so an "indefinite" watch is realised as a relaunch loop of bounded
+# windows (see watch()); this is that window.
+_WATCH_WINDOW_S = 3600.0
+
+
+def _mask_to_event_type(mask: int) -> FileWatchEventType:
+    """Collapse a raw inotify mask onto the coarse FileWatchEventType enum.
+
+    Order matters: a create/move-in is reported as Create even though the same
+    write often also carries MODIFY bits; delete/move-out wins similarly. This
+    matches Modal's granularity (it wraps the Rust ``notify`` crate, which makes
+    the same coarse distinctions).
+    """
+    if mask & (_IN_CREATE | _IN_MOVED_TO):
+        return FileWatchEventType.Create
+    if mask & (_IN_DELETE | _IN_MOVED_FROM):
+        return FileWatchEventType.Delete
+    if mask & (_IN_MODIFY | _IN_CLOSE_WRITE):
+        return FileWatchEventType.Modify
+    if mask & (_IN_ACCESS | _IN_OPEN):
+        return FileWatchEventType.Access
+    return FileWatchEventType.Unknown
+
+
+async def watch(
+    sandbox: AsyncSandbox,
+    path: str,
+    *,
+    filter: Sequence[FileWatchEventType] | None = None,
+    recursive: bool = False,
+    timeout: float | None = None,
+    transport: Transport | None = None,
+) -> AsyncIterator[FileWatchEvent]:
+    """Stream filesystem-change events under ``path`` (Modal
+    ``Sandbox.filesystem.watch``). Async generator — ``async for ev in
+    sb.watch(...)``.
+
+    ``path`` must be absolute. ``filter`` restricts the yielded
+    `FileWatchEventType`\\ s (``None`` = all). ``recursive`` also watches nested
+    subdirectories (and directories created later). ``timeout`` bounds the watch
+    in seconds; ``None`` watches until the caller stops iterating (or the sandbox
+    dies).
+
+    **How.** Runs a ctypes ``inotify(7)`` monitor in the container over the
+    resumable `exec_stream` — no server route, no container package. See the
+    module docstring.
+
+    **Caveats.**
+    * A single logical file save commonly yields a `Modify` (write) event; atomic
+      editors that save-by-rename surface as `Create`/`Delete` of a temp plus a
+      move — ordinary inotify granularity, matching Modal.
+    * A large ``recursive`` watch consumes one kernel watch descriptor per
+      directory (``fs.inotify.max_user_watches``); a very deep tree can exhaust it.
+    * ``timeout=None`` is realised as a relaunch loop of bounded exec windows
+      (the server caps an untimed exec at ~600s). Events that occur during the
+      sub-second relaunch gap between windows can be missed — a gap-free
+      indefinite watch would need a server-side ``/files/watch`` endpoint, which
+      does not exist yet. A bounded ``timeout`` runs as a single stream and has no
+      such gap.
+    """
+    p = _require_absolute(path)
+    allowed = frozenset(filter) if filter else None
+    prog = _watch_program()
+
+    async def _one_window(window_timeout: float | None) -> AsyncIterator[FileWatchEvent]:
+        argv = [
+            "python3",
+            "-c",
+            prog,
+            p,
+            "1" if recursive else "0",
+            "" if window_timeout is None else repr(window_timeout),
+        ]
+        # Client read budget must outlast the server exec budget so a live watch
+        # is never abandoned client-side; exec_stream adds its own grace on top.
+        stream = sandbox.exec_stream(argv, timeout=window_timeout)
+        async for line in stream:
+            if line.stream != "stdout":
+                continue
+            idx = line.data.find(_WATCH_SENTINEL)
+            if idx == -1:
+                continue
+            payload = line.data[idx + len(_WATCH_SENTINEL) :]
+            if payload.startswith("READY"):
+                continue
+            try:
+                obj = json.loads(payload)
+            except ValueError:
+                continue
+            etype = _mask_to_event_type(int(obj.get("mask", 0)))
+            if allowed is not None and etype not in allowed:
+                continue
+            yield FileWatchEvent(paths=[str(obj.get("path", p))], type=etype)
+
+    if timeout is not None:
+        # Bounded: a single stream (the resumable exec_stream keeps it alive
+        # across GOAWAYs up to the requested duration).
+        async for ev in _one_window(timeout):
+            yield ev
+        return
+
+    # Indefinite: relaunch bounded windows until the caller stops iterating.
+    # Breaking the async-for closes the generator, which closes the stream and
+    # kills the in-container monitor.
+    while True:
+        async for ev in _one_window(_WATCH_WINDOW_S):
+            yield ev