[sfroment]

Summary

sync(local, remote, *, direction="push", delete=False, exclude=(),
     checksum=False, dry_run=False)                         both fs twins
  list both sides   walk_local(local, exclude) vs NDJSON files_list(remote)
  plan              filter the remote listing through path_excluded
                    (own path or any directory prefix — the walker prunes
                    a matching dir whole, the plan must agree)
  diff              path/type/size/mtime, whole seconds; dirs skip size
                    (a filesystem artifact that never converges);
                    checksum=True adds sha256 stats for pairs that pass
  plan_batches      changed set -> ~50 MiB tar batches;
                    files over one batch -> upload_file/download_file
                    (multipart sessions on executors v0.0.24+)
  push              build_archive -> PUT /files/archive (creates the root)
  pull              GET /files/archive (server-side excludes + oversized
                    paths, so their bytes travel once) -> extract only the
                    changed set, replacing in-the-way files/links/dirs
                    without following symlinks out of the destination
  collision guard   oversized patterns that would also drop planned
                    members -> SandboxFilesystemError before any transfer
  delete=True       prune the destination via the legacy routes, sparing
                    excluded trees whole and tolerating paths a type flip
                    in this sync already replaced

DeclarativeSnapshot.copy() rides the same routes: a directory builds as one archive push (binary-safe, modes/mtimes/symlinks kept), a single file through upload_file; pre-v0.0.24 executors keep the per-file legacy walk, pinned unchanged.

A five-pass review loop (parallel per-file lanes + tools lens, then four focused verification passes) landed 24 red-first findings on top of the build: the exclude contract (push+delete no longer deletes what exclude promised to skip; pull no longer plans or counts prunable members), directory size convergence, Go-parity for escaped class members, extraction make-room, loud unreadable-subtree walks, async failure-arm pinning with multipart-capable fakes, the no-retry/build-seam/no-op tokens watched, and docs regenerated with the whole sync surface (koyeb.sandbox.sync added to the doc module list).

Evidence

• Before: files-multipart tip — 448 sandbox tests green; SandboxFilesystem has no sync surface and snapshot copy walks per-file as text.
  After: 607 sandbox tests green (uv run --no-sync pytest koyeb/sandbox/ -q → 607 passed in 9.77s): +112 build tests and +47 review tests, every review test red-first or an explicit coverage pin. Mutation runs scoped to the delta report zero survivors across every pass (crapper: all delta-touched functions under CRAP 10; the ancestor-blind path_excluded mutant is killed by all six of its tests).
• The exclude contract is pinned end to end: push with delete=True, exclude=("*.log",) leaves skip.log on the remote with deleted == 0; pull with exclude=("backup",) never plans x/backup/small.txt (0 downloads, no archive GET, local copy untouched); an oversized backup next to a changed x/backup/small.txt raises SandboxFilesystemError naming the member before any transfer.

Merge Danger

Door: two-way — additive surface on both fs twins; reverting the branch reverts the feature. No wire changes below the base.

Blast Radius: the sandbox filesystem sync/copy surface only. The archive/list routes and multipart rides require executor v0.0.24+ (has_files_routes() gates them); older executors keep the legacy walk for snapshot copy. delete=True prunes the destination — new capability, explicit opt-in. Stacked on #106 (base files-multipart); retarget to main when #106 merges.