feat(sandbox): add shared build cache PVC to sandbox-env chart

[pedrofrxncx]

Summary

• Adds cache-pvc.yaml template to sandbox-env chart — creates a shared PersistentVolumeClaim (<name>-cache) in agent-sandbox-system
• Wires the PVC into the SandboxTemplate with env vars that redirect every package manager's cache to /mnt/cache (npm, pnpm, yarn, bun, deno, XDG)
• Off by default (cache.enabled: false); opt-in per environment via values
• values-kind.yaml enables it with standard/ReadWriteOnce/10Gi for local dev (single-node kind, no EFS needed)

How it works

Package managers have a two-level storage model: a content-addressed global cache (tarballs, keyed by name+version+hash) and the per-project node_modules/. The PVC holds the global cache layer. On a cold start the first bun install populates it; every subsequent sandbox that shares a dep at the same version skips the registry download and links from the local cache instead.

Production setup (EKS)

Requires the AWS EFS CSI driver and a provisioned EFS filesystem. Set:

cache:
  enabled: true
  storageClass: efs-sc   # EFS-backed StorageClass with ReadWriteMany
  accessMode: ReadWriteMany
  size: 50Gi

Test plan

• helm template with values-kind.yaml renders PVC + env vars + volumeMount in SandboxTemplate
• helm template with default values renders no cache resources
• Deploy to kind with cache.enabled: true — PVC binds on first sandbox pod, /mnt/cache is mounted, BUN_INSTALL_CACHE_DIR etc. are set
• Second sandbox install reuses cached tarballs (faster cold start, no registry traffic)

🤖 Generated with Claude Code

---

Summary by cubic

Adds an opt‑in shared build and source cache to the sandbox-env chart. Speeds up clone, install, and Next.js cold starts while cutting registry and Git traffic. Adds safer fallbacks when the cache PVC is unavailable or full.

• New Features

  • Shared <sandbox>-cache PVC in agent-sandbox-system, mounted at cache.mountPath (default /mnt/cache), kept across Helm upgrades.
  • Template passes CACHE_DIR; the daemon redirects npm/pnpm/yarn/bun/deno/XDG caches, adds lockfile‑keyed shared node_modules with flock + sentinel, and a per‑repo Next.js .next/cache via SANDBOX_CACHE_KEY. Installs use --prefer-offline/--frozen-lockfile to reduce network.
  • Git clones use shallow bare mirrors on the PVC wired as alternates; hourly TTL refresh touches HEAD. If the cache dir is unavailable, falls back to direct clone.
  • Nightly GC CronJob evicts stale node_modules slots and git mirrors; configure via cache.gc.* (enabled, schedule, ttlDays).
  • Helm validation blocks ReadWriteMany without cache.storageClass; README adds EFS setup guidance. Configure via cache.* (enabled, storageClass, accessMode, size, mountPath, gc.*). examples/values-kind.yaml enables local dev with standard/ReadWriteOnce/10Gi.
  • On install fallback, the daemon now removes the node_modules symlink to avoid writing into a bad PVC slot.

• Migration

  • EKS: install EFS CSI, create an RWX StorageClass (e.g. efs-sc), then set cache.enabled: true, cache.storageClass: efs-sc, cache.accessMode: ReadWriteMany, and size as needed. Optional: tune cache.gc.schedule and cache.gc.ttlDays.

^{Written for commit dd07d10. Summary will update on new commits. Review in cubic}