@synsci/cli-darwin-x64 1.1.80 → 1.1.82

package/bin/skills/modal/SKILL.md

@@ -65,9 +65,44 @@ If Modal CLI isn't installed: `pip install modal` (no `modal setup` needed — e
 
 | Command | When to Use |
 |---------|-------------|
-| `modal run script.py` | One-off jobs: training, batch processing, data pipelines |
+| `modal run script.py` | Quick jobs that complete in minutes |
 | `modal serve script.py` | Development: live reload on code changes, test endpoints locally |
 | `modal deploy script.py` | Production: persistent endpoints, scheduled jobs, always-on services |
+| `modal deploy` + `Function.lookup().spawn()` | **Long-running training (disconnect-safe)** |
+
+### CRITICAL: Long-Running Training Must Be Disconnect-Safe
+
+**NEVER use `.spawn()` or `.remote()` from `@app.local_entrypoint()` for training runs that take more than a few minutes.** If the local process dies (laptop battery, closed terminal, SSH disconnect), Modal tears down the app context and kills the spawned function.
+
+**The disconnect-safe pattern:**
+
+```python
+# train.py — Step 1: Define your training function
+import modal
+
+app = modal.App("my-training")
+volume = modal.Volume.from_name("training-data", create_if_missing=True)
+image = modal.Image.debian_slim(python_version="3.11").uv_pip_install("torch", "transformers")
+
+@app.function(gpu="H100", image=image, volumes={"/data": volume}, timeout=86400)
+def train():
+    # Your training code here — runs entirely in Modal's cloud
+    ...
+    volume.commit()  # Save checkpoints
+```
+
+```bash
+# Step 2: Deploy the app (persists independently of your machine)
+modal deploy train.py
+
+# Step 3: Trigger training (fire-and-forget, survives local disconnect)
+python -c "import modal; modal.Function.lookup('my-training', 'train').spawn()"
+
+# Step 4: Monitor from anywhere (even a different machine)
+modal app logs my-training
+```
+
+This pattern ensures training runs are completely decoupled from your local machine. The function runs on Modal's infrastructure and persists even if you close your laptop, lose internet, or reboot.
 
 ## GPU Selection Guide
 
@@ -362,6 +397,7 @@ def my_function():
 
 | Issue | Fix |
 |-------|-----|
+| **Training dies when laptop closes** | **NEVER use `.spawn()`/`.remote()` from `local_entrypoint()` for long jobs. Use `modal deploy` + `Function.lookup().spawn()` pattern (see Execution Modes above)** |
 | Cold start slow | Use `@modal.enter()` for model loading, increase `container_idle_timeout`, use memory snapshots |
 | GPU OOM | Use larger GPU, enable gradient checkpointing, use mixed precision (bf16) |
 | Image build fails | Pin versions, use `uv_pip_install`, use multi-stage builds |

package/bin/skills/modal/references/advanced-patterns.md

@@ -1,6 +1,103 @@
 # Modal Advanced Patterns
 
-Advanced patterns for Modal including multi-node training, distributed primitives, sandbox workflows, memory snapshots, and integration with synsc/other skills.
+Advanced patterns for Modal including disconnect-safe training, multi-node training, distributed primitives, sandbox workflows, memory snapshots, and integration with synsc/other skills.
+
+## Disconnect-Safe Training (CRITICAL)
+
+**Problem:** When you launch training via `@app.local_entrypoint()` using `.spawn()` or `.remote()`, the training run is tied to your local process. If the local process dies — laptop battery, closed terminal, SSH disconnect, or coding agent crash — Modal tears down the app context and **kills the training function**, even if it was running in Modal's cloud.
+
+**This is the #1 cause of lost training runs.** Always use the disconnect-safe pattern for any job that takes more than a few minutes.
+
+### Anti-Pattern (DO NOT USE for long training)
+
+```python
+# BAD — training dies if local process dies
+@app.local_entrypoint()
+def main():
+    train.spawn()  # DANGER: tied to this process
+    # or: train.remote()  # DANGER: also tied
+```
+
+### Correct Pattern: Deploy + Lookup + Spawn
+
+```python
+# train.py — define training function (NO local_entrypoint needed)
+import modal
+
+app = modal.App("grpo-training")
+vol = modal.Volume.from_name("training-checkpoints", create_if_missing=True)
+image = modal.Image.debian_slim(python_version="3.11").uv_pip_install(
+    "torch", "transformers", "trl", "datasets"
+)
+
+@app.function(gpu="H100:4", image=image, volumes={"/checkpoints": vol}, timeout=86400)
+def train(config: dict = None):
+    """Training function — runs entirely in Modal cloud, no local dependency."""
+    config = config or {}
+    # ... training code ...
+    vol.commit()  # Save checkpoints
+    return {"status": "complete", "checkpoints": "/checkpoints/final"}
+```
+
+```bash
+# Step 1: Deploy the app (one-time, persists independently)
+modal deploy train.py
+
+# Step 2: Fire-and-forget launch (survives any local disconnect)
+python -c "
+import modal
+fn = modal.Function.lookup('grpo-training', 'train')
+handle = fn.spawn({'lr': 1e-5, 'epochs': 3})
+print(f'Launched! Function call ID: {handle.object_id}')
+"
+
+# Step 3: Monitor from anywhere (different terminal, different machine)
+modal app logs grpo-training
+
+# Step 4: Check results later
+python -c "
+import modal
+fn = modal.Function.lookup('grpo-training', 'train')
+# Get result from a specific call if you saved the ID
+# Or just check the Volume for checkpoints
+"
+```
+
+### Quick Helper Script
+
+For convenience, create a `launch.py` alongside your training script:
+
+```python
+# launch.py — fire-and-forget launcher
+import modal, sys, json
+
+app_name = sys.argv[1]  # e.g., "grpo-training"
+fn_name = sys.argv[2]   # e.g., "train"
+config = json.loads(sys.argv[3]) if len(sys.argv) > 3 else {}
+
+fn = modal.Function.lookup(app_name, fn_name)
+handle = fn.spawn(config)
+print(f"Training launched! ID: {handle.object_id}")
+print(f"Monitor: modal app logs {app_name}")
+print("Safe to close this terminal — training runs independently.")
+```
+
+```bash
+# Usage:
+modal deploy train.py
+python launch.py grpo-training train '{"lr": 1e-5}'
+# Now safe to close everything
+```
+
+### When to Use Each Pattern
+
+| Pattern | Safe to Disconnect? | Use For |
+|---------|---------------------|---------|
+| `modal run script.py` | NO | Quick tests (<5 min) |
+| `local_entrypoint()` + `.remote()` | NO | Interactive dev, short jobs |
+| `local_entrypoint()` + `.spawn()` | NO | **NEVER for training** |
+| `modal deploy` + `Function.lookup().spawn()` | **YES** | Training, batch jobs, anything >5 min |
+| `modal deploy` + REST API trigger | **YES** | CI/CD, automated pipelines |
 
 ## Multi-Node Training (Beta)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synsci/cli-darwin-x64",
-  "version": "1.1.80",
+  "version": "1.1.82",
   "os": [
     "darwin"
   ],