plato-sdk-v2 2.0.50__py3-none-any.whl → 2.2.4__py3-none-any.whl

plato/v1/cli/sandbox.py

@@ -5,6 +5,7 @@ import io
 import json
 import logging
 import os
+import re
 import shutil
 import subprocess
 import tarfile
@@ -16,7 +17,6 @@ from urllib.parse import quote
 
 import typer
 import yaml
-from playwright.async_api import async_playwright
 from rich.logging import RichHandler
 
 from plato._generated.api.v1.gitea import (
@@ -25,7 +25,7 @@ from plato._generated.api.v1.gitea import (
     get_gitea_credentials,
     get_simulator_repository,
 )
-from plato._generated.api.v1.sandbox import setup_sandbox, start_worker
+from plato._generated.api.v1.sandbox import setup_root_access, setup_sandbox, start_worker
 from plato._generated.api.v2.jobs import get_flows as jobs_get_flows
 from plato._generated.api.v2.jobs import state as jobs_state
 from plato._generated.api.v2.sessions import (
@@ -47,13 +47,14 @@ from plato._generated.api.v2.sessions import (
     state as sessions_state,
 )
 from plato._generated.models import (
+    AppSchemasBuildModelsSetupSandboxRequest,
     AppSchemasBuildModelsSimConfigCompute,
     AppSchemasBuildModelsSimConfigDataset,
     AppSchemasBuildModelsSimConfigMetadata,
     CreateCheckpointRequest,
     ExecuteCommandRequest,
     Flow,
-    SetupSandboxRequest,
+    SetupRootPasswordRequest,
     VMManagementRequest,
 )
 from plato.v1.cli.ssh import setup_ssh_for_sandbox
@@ -69,11 +70,16 @@ from plato.v1.cli.utils import (
     require_sandbox_state,
     save_sandbox_state,
 )
+from plato.v1.cli.verify import sandbox_verify_app
 from plato.v2.async_.flow_executor import FlowExecutor
 from plato.v2.sync.client import Plato as PlatoV2
 from plato.v2.types import Env, SimConfigCompute
 
+# UUID pattern for detecting artifact IDs in colon notation
+UUID_PATTERN = re.compile(r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", re.IGNORECASE)
+
 sandbox_app = typer.Typer(help="Manage sandboxes for simulator development")
+sandbox_app.add_typer(sandbox_verify_app, name="verify")
 
 
 def format_public_url_with_router_target(public_url: str | None, service_name: str | None) -> str | None:
@@ -89,6 +95,10 @@ def format_public_url_with_router_target(public_url: str | None, service_name: s
     if not public_url or not service_name:
         return public_url
 
+    # Check if router target already exists (idempotent)
+    if "_plato_router_target=" in public_url:
+        return public_url
+
     target_param = f"_plato_router_target={service_name}.web.plato.so"
     if "?" in public_url:
         return f"{public_url}&{target_param}"
@@ -104,56 +114,85 @@ def sandbox_start(
         None,
         "--simulator",
         "-s",
-        help="Simulator name (e.g., espocrm, espocrm:staging)",
+        help="Simulator name. Supports: -s sim, -s sim:tag, -s sim:<artifact-uuid>",
     ),
-    artifact_id: str = typer.Option(None, "--artifact-id", "-a", help="Specific artifact ID"),
+    artifact_id: str = typer.Option(None, "--artifact-id", "-a", help="Specific artifact UUID"),
     blank: bool = typer.Option(False, "--blank", "-b", help="Create blank VM"),
     # Config mode options
     dataset: str = typer.Option(None, "--dataset", "-d", help="Dataset from config or simulator"),
     # Artifact mode options
-    tag: str = typer.Option("latest", "--tag", "-t", help="Artifact tag"),
+    tag: str = typer.Option("latest", "--tag", "-t", help="Artifact tag (used with -s)"),
     # Blank VM options
     service: str = typer.Option(None, "--service", help="Service name (required for blank VM)"),
     cpus: int = typer.Option(2, "--cpus", help="Number of CPUs (blank VM)"),
     memory: int = typer.Option(1024, "--memory", help="Memory in MB (blank VM)"),
     disk: int = typer.Option(10240, "--disk", help="Disk in MB (blank VM)"),
     # Common options
-    timeout: int = typer.Option(300, "--timeout", help="Timeout for VM ready (seconds)"),
+    timeout: int = typer.Option(1800, "--timeout", help="VM lifetime in seconds (default: 30 minutes)"),
     no_reset: bool = typer.Option(False, "--no-reset", help="Skip initial reset after ready"),
     json_output: bool = typer.Option(False, "--json", "-j", help="Output as JSON"),
 ):
     """
     Start a sandbox environment.
 
-    Three modes available:
+    THREE MODES (pick one):
+
+    1. FROM CONFIG (-c): Use plato-config.yml in current directory
+
+        plato sandbox start -c
+        plato sandbox start -c -d base
+
+    2. FROM SIMULATOR/ARTIFACT (-s or -a): Start from existing artifact
 
-    1. FROM CONFIG: Use plato-config.yml in current directory
-       plato sandbox start --from-config
-       plato sandbox start --from-config --dataset base
+        -s <simulator>                      Latest tag
+        -s <simulator>:<tag>                Specific tag
+        -s <simulator>:<artifact-uuid>      Specific artifact (UUID detected)
+        -s <simulator> -a <artifact-uuid>   Explicit artifact
+        -a <artifact-uuid>                  Artifact only (no simulator name)
 
-    2. FROM ARTIFACT: Use simulator name or artifact ID
-       plato sandbox start --simulator espocrm
-       plato sandbox start --simulator espocrm:staging
-       plato sandbox start --artifact-id art_abc123
+    3. BLANK VM (-b): Create fresh VM with custom specs
 
-    3. BLANK VM: Create fresh VM with custom specs
-       plato sandbox start --blank --service myapp
-       plato sandbox start --blank --service myapp --cpus 4 --memory 2048
+        plato sandbox start -b --service myapp
+        plato sandbox start -b --service myapp --cpus 4 --memory 2048
+
+    EXAMPLES:
+
+        plato sandbox start -c                                    # From config
+        plato sandbox start -s espocrm                            # Latest artifact
+        plato sandbox start -s espocrm:staging                    # Staging tag
+        plato sandbox start -s espocrm:e9c25ca5-1234-5678-...     # Specific artifact
+        plato sandbox start -a e9c25ca5-1234-5678-9abc-...        # Artifact only
     """
     api_key = require_api_key()
 
     # Validate mode selection - exactly one must be specified
     modes_selected = sum([from_config, simulator is not None, artifact_id is not None, blank])
     if modes_selected == 0:
-        console.print("[red]Must specify one mode: --from-config, --simulator, --artifact-id, or --blank[/red]")
+        console.print("[red]❌ No mode specified[/red]")
+        console.print()
+        console.print("[yellow]Usage (pick one):[/yellow]")
+        console.print("  plato sandbox start -c                           # From plato-config.yml")
+        console.print("  plato sandbox start -s <simulator>               # From simulator (latest)")
+        console.print("  plato sandbox start -s <simulator>:<artifact>    # From specific artifact")
+        console.print("  plato sandbox start -a <artifact-uuid>           # From artifact directly")
+        console.print("  plato sandbox start -b --service <name>          # Blank VM")
         raise typer.Exit(1)
     if modes_selected > 1:
-        console.print("[red]Only one mode can be specified[/red]")
+        console.print("[red]❌ Multiple modes specified - pick only one[/red]")
+        console.print()
+        console.print("[yellow]Use ONE of:[/yellow]")
+        console.print("  -c (--from-config)   # From plato-config.yml")
+        console.print("  -s (--simulator)     # From simulator name")
+        console.print("  -a (--artifact-id)   # From artifact UUID")
+        console.print("  -b (--blank)         # Blank VM")
         raise typer.Exit(1)
 
     # Validate mode-specific options
     if blank and not service:
-        console.print("[red]--service is required for blank VM mode[/red]")
+        console.print("[red]❌ --service is required for blank VM mode[/red]")
+        console.print()
+        console.print("[yellow]Usage:[/yellow]")
+        console.print("  plato sandbox start -b --service <name>")
         raise typer.Exit(1)
 
     # Build environment configuration
@@ -198,9 +237,13 @@ def sandbox_start(
         config_cpus = compute_config.get("cpus", 2)
         config_memory = compute_config.get("memory", 2048)
         config_disk = compute_config.get("disk", 10240)
+        config_app_port = compute_config.get("app_port", 80)
 
         # Create blank VM with specs from config
-        sim_config = SimConfigCompute(cpus=config_cpus, memory=config_memory, disk=config_disk)
+        config_messaging_port = compute_config.get("plato_messaging_port", 7000)
+        sim_config = SimConfigCompute(
+            cpus=config_cpus, memory=config_memory, disk=config_disk, app_port=config_app_port
+        )
         env_config = Env.resource(sim_name, sim_config)
         state_extras = {
             "plato_config_path": str(config_path),
@@ -209,6 +252,8 @@ def sandbox_start(
             "cpus": config_cpus,
             "memory": config_memory,
             "disk": config_disk,
+            "app_port": config_app_port,
+            "messaging_port": config_messaging_port,
         }
         if not json_output:
             console.print(f"[cyan]Using plato-config.yml: {config_path}[/cyan]")
@@ -216,16 +261,42 @@ def sandbox_start(
             console.print(f"[cyan]Specs: {config_cpus} CPUs, {config_memory}MB RAM, {config_disk}MB disk[/cyan]")
 
     elif simulator:
-        # MODE 2a: From simulator name
+        # MODE 2a: From simulator name (or simulator:artifact_id notation)
         mode = "artifact"
         # Default dataset to "base" if not provided
         effective_dataset = dataset or "base"
-        env_config = Env.simulator(simulator, tag=tag, dataset=effective_dataset)
-        # Extract sim_name from simulator (e.g., "docuseal:prod-latest" -> "docuseal")
-        sim_name = simulator.split(":")[0] if ":" in simulator else simulator
-        state_extras = {"simulator": simulator, "tag": tag, "dataset": effective_dataset, "service": sim_name}
-        if not json_output:
-            console.print(f"[cyan]Starting from simulator: {simulator}:{tag}[/cyan]")
+
+        # Extract sim_name and check if colon part is a UUID (artifact ID)
+        if ":" in simulator:
+            sim_name, colon_part = simulator.split(":", 1)
+            if UUID_PATTERN.match(colon_part):
+                # Colon part is a UUID -> treat as artifact ID
+                env_config = Env.artifact(colon_part)
+                state_extras = {
+                    "simulator": sim_name,
+                    "artifact_id": colon_part,
+                    "dataset": effective_dataset,
+                    "service": sim_name,
+                }
+                if not json_output:
+                    console.print(f"[cyan]Starting from artifact: {sim_name}:{colon_part}[/cyan]")
+            else:
+                # Colon part is a tag name
+                env_config = Env.simulator(simulator, tag=tag, dataset=effective_dataset)
+                state_extras = {
+                    "simulator": simulator,
+                    "tag": colon_part,
+                    "dataset": effective_dataset,
+                    "service": sim_name,
+                }
+                if not json_output:
+                    console.print(f"[cyan]Starting from simulator: {simulator}[/cyan]")
+        else:
+            sim_name = simulator
+            env_config = Env.simulator(simulator, tag=tag, dataset=effective_dataset)
+            state_extras = {"simulator": simulator, "tag": tag, "dataset": effective_dataset, "service": sim_name}
+            if not json_output:
+                console.print(f"[cyan]Starting from simulator: {simulator}:{tag}[/cyan]")
 
     elif artifact_id:
         # MODE 2b: From artifact ID
@@ -257,7 +328,9 @@ def sandbox_start(
 
     try:
         plato = PlatoV2(api_key=api_key)
-        session = plato.sessions.create(envs=[env_config] if env_config else None, timeout=timeout)
+        if not env_config:
+            raise ValueError("No environment configuration provided")
+        session = plato.sessions.create(envs=[env_config], timeout=timeout)
 
         # Get session info
         session_id = session.session_id
@@ -286,20 +359,25 @@ def sandbox_start(
                 console.print("[cyan]Resetting environment...[/cyan]")
             session.reset()
 
-        # Setup sandbox for --from-config mode (clone git repo, configure worker)
+        # Setup SSH for ALL modes (so you can SSH into any sandbox)
         ssh_host = None
         ssh_config_path = None
         ssh_private_key_path = None
-        if mode == "config" and full_dataset_config_dict and job_id:
+
+        if job_id:
             if not json_output:
-                console.print("[cyan]Setting up sandbox (SSH keys, git clone, worker config)...[/cyan]")
+                console.print("[cyan]Setting up SSH access...[/cyan]")
             try:
                 # Step 1: Generate SSH key pair and create SSH config (like Go hub does)
+                # For config mode: use "plato" user (setup_sandbox configures this)
+                # For artifact/simulator modes: use "root" user (setup_root_access configures this)
+                ssh_username = "plato" if (mode == "config" and full_dataset_config_dict) else "root"
+
                 if not json_output:
                     console.print("[cyan]  Generating SSH key pair...[/cyan]")
 
                 base_url = os.getenv("PLATO_BASE_URL", "https://plato.so")
-                ssh_info = setup_ssh_for_sandbox(base_url, job_id, username="plato")
+                ssh_info = setup_ssh_for_sandbox(base_url, job_id, username=ssh_username)
                 ssh_host = ssh_info["ssh_host"]
                 ssh_config_path = ssh_info["config_path"]
                 ssh_private_key_path = ssh_info["private_key_path"]
@@ -308,68 +386,81 @@ def sandbox_start(
                 if not json_output:
                     console.print(f"[cyan]  SSH config: {ssh_config_path}[/cyan]")
 
-                # Step 2: Build the full dataset config from plato-config.yml
-                compute_dict = full_dataset_config_dict.get("compute", {})
-                metadata_dict = full_dataset_config_dict.get("metadata", {})
-                services_dict = full_dataset_config_dict.get("services")
-                listeners_dict = full_dataset_config_dict.get("listeners")
-
-                # Build compute config
-                compute_obj = AppSchemasBuildModelsSimConfigCompute(
-                    cpus=compute_dict.get("cpus", 2),
-                    memory=compute_dict.get("memory", 2048),
-                    disk=compute_dict.get("disk", 10240),
-                    app_port=compute_dict.get("app_port", 80),
-                    plato_messaging_port=compute_dict.get("plato_messaging_port", 7000),
-                )
-
-                # Build metadata config
-                metadata_obj = AppSchemasBuildModelsSimConfigMetadata(
-                    name=metadata_dict.get("name", sim_name),
-                    description=metadata_dict.get("description", ""),
-                    source_code_url=metadata_dict.get("source_code_url"),
-                    start_url=metadata_dict.get("start_url", "blank"),
-                    license=metadata_dict.get("license"),
-                    variables=metadata_dict.get("variables"),
-                    flows_path=metadata_dict.get("flows_path"),
-                )
+                # Step 2: Upload SSH key to sandbox
+                # For --from-config mode: use setup_sandbox with full config
+                # For --simulator/--artifact-id modes: use setup_root_access (just SSH key, no config changes)
+                if not json_output:
+                    console.print("[cyan]  Uploading SSH key to sandbox...[/cyan]")
+
+                if mode == "config" and full_dataset_config_dict:
+                    # Full config from plato-config.yml - use setup_sandbox API
+                    compute_dict = full_dataset_config_dict.get("compute", {})
+                    metadata_dict = full_dataset_config_dict.get("metadata", {})
+                    services_dict = full_dataset_config_dict.get("services")
+                    listeners_dict = full_dataset_config_dict.get("listeners")
+
+                    compute_obj = AppSchemasBuildModelsSimConfigCompute(
+                        cpus=compute_dict.get("cpus", 2),
+                        memory=compute_dict.get("memory", 2048),
+                        disk=compute_dict.get("disk", 10240),
+                        app_port=compute_dict.get("app_port", 80),
+                        plato_messaging_port=compute_dict.get("plato_messaging_port", 7000),
+                    )
 
-                # Build the full dataset config object
-                dataset_config_obj = AppSchemasBuildModelsSimConfigDataset(
-                    compute=compute_obj,
-                    metadata=metadata_obj,
-                    services=services_dict,
-                    listeners=listeners_dict,
-                )
+                    metadata_obj = AppSchemasBuildModelsSimConfigMetadata(
+                        name=metadata_dict.get("name", sim_name or "sandbox"),
+                        description=metadata_dict.get("description", ""),
+                        source_code_url=metadata_dict.get("source_code_url"),
+                        start_url=metadata_dict.get("start_url", "blank"),
+                        license=metadata_dict.get("license"),
+                        variables=metadata_dict.get("variables"),
+                        flows_path=metadata_dict.get("flows_path"),
+                    )
 
-                # Step 3: Build setup request WITH SSH public key
-                setup_request = SetupSandboxRequest(
-                    service=sim_name,
-                    dataset=dataset_name or "",
-                    plato_dataset_config=dataset_config_obj,
-                    ssh_public_key=ssh_public_key,  # Pass the generated public key
-                )
+                    dataset_config_obj = AppSchemasBuildModelsSimConfigDataset(
+                        compute=compute_obj,
+                        metadata=metadata_obj,
+                        services=services_dict,
+                        listeners=listeners_dict,
+                    )
 
-                # Step 4: Call setup_sandbox API
-                if not json_output:
-                    console.print("[cyan]  Calling setup-sandbox API...[/cyan]")
+                    dataset_value = dataset_name or state_extras.get("dataset", "base")
+                    setup_request = AppSchemasBuildModelsSetupSandboxRequest(
+                        service=sim_name or "",
+                        dataset=str(dataset_value) if dataset_value else "",
+                        plato_dataset_config=dataset_config_obj,
+                        ssh_public_key=ssh_public_key,
+                    )
 
-                with get_http_client() as client:
-                    _setup_response = setup_sandbox.sync(
-                        client=client,
-                        public_id=job_id,
-                        body=setup_request,
-                        x_api_key=api_key,
+                    with get_http_client() as client:
+                        _setup_response = setup_sandbox.sync(
+                            client=client,
+                            public_id=job_id,
+                            body=setup_request,
+                            x_api_key=api_key,
+                        )
+                else:
+                    # Artifact/simulator modes - use setup_root_access API (just SSH key, preserves existing config)
+                    setup_root_request = SetupRootPasswordRequest(
+                        ssh_public_key=ssh_public_key,
                     )
 
+                    with get_http_client() as client:
+                        _setup_response = setup_root_access.sync(
+                            client=client,
+                            public_id=job_id,
+                            body=setup_root_request,
+                            x_api_key=api_key,
+                        )
+
                 if not json_output:
-                    console.print("[green]Sandbox setup complete![/green]")
+                    console.print("[green]SSH setup complete![/green]")
                     console.print(f"  [cyan]SSH:[/cyan] ssh -F {ssh_config_path} {ssh_host}")
 
             except Exception as e:
                 if not json_output:
-                    console.print(f"[yellow]Warning: Setup sandbox failed: {e}[/yellow]")
-                    console.print("[yellow]You may need to run 'plato sandbox start-worker' manually[/yellow]")
+                    console.print(f"[yellow]Warning: SSH setup failed: {e}[/yellow]")
+                    console.print("[yellow]You may not be able to SSH into this sandbox[/yellow]")
 
         # Start background heartbeat process to keep session alive
         heartbeat_pid = _start_heartbeat_process(session_id, api_key)
@@ -383,8 +474,7 @@ def sandbox_start(
         state = {
             "session_id": session_id,
             "job_id": job_id,
-            "public_url": public_url,
-            "url": display_url,  # Full URL with _plato_router_target for flow execution
+            "public_url": display_url,  # Full URL with _plato_router_target
             "mode": mode,
             "created_at": datetime.now(timezone.utc).isoformat(),
             **state_extras,
@@ -409,7 +499,7 @@ def sandbox_start(
             output = {
                 "session_id": session_id,
                 "job_id": job_id,
-                "public_url": public_url,
+                "public_url": display_url,  # Full URL with _plato_router_target
             }
             if ssh_host:
                 output["ssh_host"] = ssh_host
@@ -426,6 +516,7 @@ def sandbox_start(
                 console.print(f"  [cyan]Public URL:[/cyan]  {display_url}")
             if ssh_host and ssh_config_path:
                 console.print(f"  [cyan]SSH:[/cyan]         ssh -F {ssh_config_path} {ssh_host}")
+            console.print("  [cyan]Docker:[/cyan]      export DOCKER_HOST=unix:///var/run/docker-user.sock")
             console.print(f"\n[dim]State saved to {SANDBOX_FILE}[/dim]")
 
     except Exception as e:
@@ -439,27 +530,102 @@ def sandbox_start(
 @sandbox_app.command(name="snapshot")
 def sandbox_snapshot(
     json_output: bool = typer.Option(False, "--json", "-j", help="Output as JSON"),
+    include_config: bool = typer.Option(
+        None,
+        "--include-config",
+        "-c",
+        help="Include plato-config.yml and flows.yml in snapshot. Auto-enabled for sandboxes started from config.",
+    ),
+    app_port: int = typer.Option(None, "--app-port", help="Override internal app port"),
+    messaging_port: int = typer.Option(None, "--messaging-port", help="Override messaging port"),
+    target: str = typer.Option(None, "--target", help="Override target domain (e.g., myapp.web.plato.so)"),
 ):
     """
     Create a snapshot of the current sandbox state.
 
-    Examples:
-        plato sandbox snapshot
-        plato sandbox snapshot --json
+    Saves the artifact ID to .sandbox.yaml so it can be used by
+    'plato pm submit base' without needing to specify it manually.
+
+    CONFIG BEHAVIOR:
+
+        - Sandboxes started from config (-c): Automatically includes plato-config.yml,
+          flows.yml, app_port, and messaging_port in the snapshot.
+        - Sandboxes started from artifact: Inherits config from parent artifact.
+          Use --include-config to override with local config files.
+
+    USAGE:
+
+        plato sandbox snapshot           # Creates snapshot, saves artifact_id
+        plato sandbox snapshot --json    # JSON output
+        plato sandbox snapshot -c        # Force include local config files
+        plato sandbox snapshot --app-port 8080  # Override app port
+
+    NEXT STEPS:
+
+        After snapshot, you can submit for review:
+        plato pm submit base             # Reads artifact_id from .sandbox.yaml
     """
     api_key = require_api_key()
     state = require_sandbox_state()
     session_id = require_sandbox_field(state, "session_id")
+    mode = state.get("mode", "artifact")
+    service_name = state.get("service")
+
+    # Determine whether to include config
+    # Auto-enable for "config" mode sandboxes, unless explicitly disabled
+    should_include_config = include_config if include_config is not None else (mode == "config")
 
     if not json_output:
         console.print("[cyan]Creating snapshot...[/cyan]")
 
+    # Build the request with optional config fields
+    request_kwargs = {}
+
+    # Get port info from state or CLI overrides
+    if app_port is not None:
+        request_kwargs["internal_app_port"] = app_port
+    elif should_include_config and state.get("app_port"):
+        request_kwargs["internal_app_port"] = state.get("app_port")
+
+    if messaging_port is not None:
+        request_kwargs["messaging_port"] = messaging_port
+    elif should_include_config and state.get("messaging_port"):
+        request_kwargs["messaging_port"] = state.get("messaging_port")
+
+    # Set target domain
+    if target is not None:
+        request_kwargs["target"] = target
+    elif should_include_config and service_name:
+        request_kwargs["target"] = f"{service_name}.web.plato.so"
+
+    # Include config files if requested
+    if should_include_config:
+        plato_config_path = state.get("plato_config_path")
+        if plato_config_path:
+            config_file = Path(plato_config_path)
+            if config_file.exists():
+                request_kwargs["plato_config"] = config_file.read_text()
+                if not json_output:
+                    console.print(f"[dim]Including plato-config.yml from {plato_config_path}[/dim]")
+
+            # Also check for flows.yml in same directory
+            flows_file = config_file.parent / "flows.yml"
+            if not flows_file.exists():
+                flows_file = config_file.parent / "base" / "flows.yml"
+            if flows_file.exists():
+                request_kwargs["flows"] = flows_file.read_text()
+                if not json_output:
+                    console.print(f"[dim]Including flows.yml from {flows_file}[/dim]")
+
+    if not json_output and request_kwargs:
+        console.print(f"[dim]Snapshot config: {list(request_kwargs.keys())}[/dim]")
+
     try:
         with get_http_client() as client:
             response = sessions_snapshot.sync(
                 client=client,
                 session_id=session_id,
-                body=CreateCheckpointRequest(),
+                body=CreateCheckpointRequest(**request_kwargs),
                 x_api_key=api_key,
             )
 
@@ -470,11 +636,17 @@ def sandbox_snapshot(
                     artifact_id = result.artifact_id if hasattr(result, "artifact_id") else None
                     break
 
+            # Save artifact_id to sandbox state for pm submit base
+            if artifact_id:
+                state["artifact_id"] = artifact_id
+                save_sandbox_state(state)
+
             if json_output:
                 console.print(json.dumps({"artifact_id": artifact_id}))
             else:
                 console.print("\n[green]Snapshot created successfully![/green]")
                 console.print(f"  [cyan]Artifact ID:[/cyan] {artifact_id}")
+                console.print("  [dim]Saved to .sandbox.yaml for 'plato pm submit base'[/dim]")
 
     except Exception as e:
         if json_output:
@@ -487,10 +659,25 @@ def sandbox_snapshot(
 @sandbox_app.command(name="stop")
 def sandbox_stop():
     """
-    Stop and destroy the sandbox.
+    Stop and destroy the current sandbox.
+
+    Closes the session, cleans up SSH keys, and removes .sandbox.yaml.
+    Run this when you're done with the sandbox or want to start fresh.
+
+    REQUIRES:
+
+        .sandbox.yaml in current directory (created by 'plato sandbox start')
+
+    USAGE:
 
-    Examples:
         plato sandbox stop
+
+    WHAT IT DOES:
+
+        1. Stops the heartbeat process
+        2. Closes the remote session
+        3. Removes SSH config and keys
+        4. Deletes .sandbox.yaml
     """
     api_key = require_api_key()
     state = require_sandbox_state()
@@ -547,11 +734,27 @@ def sandbox_status(
     json_output: bool = typer.Option(False, "--json", "-j", help="Output as JSON"),
 ):
     """
-    Show current sandbox status and info.
+    Show current sandbox status and connection info.
+
+    Displays the public URL, SSH config, VM status, and other details
+    from .sandbox.yaml plus live status from the API.
 
-    Examples:
-        plato sandbox status
-        plato sandbox status --json
+    REQUIRES:
+
+        .sandbox.yaml in current directory (created by 'plato sandbox start')
+
+    USAGE:
+
+        plato sandbox status           # Human-readable output
+        plato sandbox status --json    # JSON output for scripts
+
+    OUTPUT INCLUDES:
+
+        - Public URL (for browser access)
+        - SSH config path (for 'ssh -F <config> sandbox-<id>')
+        - VM status (running/stopped/etc.)
+        - Session ID, Job ID
+        - Service name, dataset
     """
     state = require_sandbox_state()
 
@@ -607,6 +810,34 @@ def sandbox_status(
 
     if json_output:
         output = {**state, "vm_status": vm_status, "vm_status_reason": vm_status_reason, "vm_running": vm_running}
+
+        # Add heartbeat status to JSON output
+        if session_id:
+            try:
+                with get_http_client() as client:
+                    response = client.post(
+                        f"/api/v2/sessions/{session_id}/heartbeat",
+                        headers={"X-API-Key": api_key},
+                    )
+                    heartbeat_data = response.json()
+                    output["heartbeat"] = {
+                        "success": heartbeat_data.get("success", False),
+                        "timestamp": heartbeat_data.get("timestamp"),
+                        "jobs": {},
+                    }
+                    for job_id, job_result in heartbeat_data.get("results", {}).items():
+                        errors = job_result.get("errors", [])
+                        vm_ok = not any("registry_heartbeat_update" in e for e in errors)
+                        worker_ok = not any("vm_heartbeat_message" in e for e in errors)
+                        output["heartbeat"]["jobs"][job_id] = {
+                            "success": job_result.get("success", False),
+                            "vm_heartbeat_ok": vm_ok,
+                            "worker_heartbeat_ok": worker_ok,
+                            "errors": errors,
+                        }
+            except Exception as e:
+                output["heartbeat"] = {"error": str(e)}
+
         console.print(json.dumps(output))
     else:
         console.print("\n[bold]Sandbox Status[/bold]")
@@ -648,7 +879,7 @@ def sandbox_status(
         if ssh_host and ssh_config_path:
             console.print(f"  [cyan]SSH:[/cyan]         ssh -F {ssh_config_path} {ssh_host}")
 
-        # Display heartbeat status
+        # Display heartbeat process status
         heartbeat_pid = state.get("heartbeat_pid")
         if heartbeat_pid:
             # Check if process is still running
@@ -658,6 +889,30 @@ def sandbox_status(
             except ProcessLookupError:
                 console.print(f"  [cyan]Heartbeat:[/cyan]   [red]stopped[/red] (PID: {heartbeat_pid} not found)")
 
+        # Call heartbeat endpoint and show detailed status
+        if session_id:
+            console.print("\n[bold]Heartbeat[/bold]")
+            try:
+                with get_http_client() as client:
+                    response = client.post(
+                        f"/api/v2/sessions/{session_id}/heartbeat",
+                        headers={"X-API-Key": api_key},
+                    )
+                    hb = response.json()
+                    console.print(f"  success: {hb.get('success')}")
+                    for job_id, result in hb.get("results", {}).items():
+                        console.print(f"  job {job_id[:8]}: success={result.get('success')}")
+                        for err in result.get("errors") or []:
+                            # Simplify error - just show type
+                            if "502" in err:
+                                console.print("    worker: 502 (not running)")
+                            elif "registry" in err:
+                                console.print("    vm: registry update failed")
+                            else:
+                                console.print(f"    {err[:50]}")
+            except Exception as e:
+                console.print(f"  error: {e}")
+
 
 @sandbox_app.command(name="start-worker")
 def sandbox_start_worker(
@@ -665,24 +920,46 @@ def sandbox_start_worker(
         None,
         "--service",
         "-s",
-        help="Service name (uses sandbox service if not specified)",
+        help="Service name (defaults to value in .sandbox.yaml)",
     ),
     dataset: str = typer.Option("base", "--dataset", "-d", help="Dataset name"),
-    config_path: Path | None = typer.Option(None, "--config-path", help="Path to plato-config.yml (required)"),
+    config_path: Path | None = typer.Option(None, "--config-path", help="Path to plato-config.yml"),
+    wait: bool = typer.Option(False, "--wait", "-w", help="Wait for worker to be ready (polls state API)"),
+    wait_timeout: int = typer.Option(240, "--wait-timeout", help="Timeout in seconds for --wait (default: 240)"),
     json_output: bool = typer.Option(False, "--json", "-j", help="Output as JSON"),
 ):
     """
-    Start/configure the Plato worker in the sandbox (for blank VMs).
+    Start the Plato worker in the sandbox.
+
+    The worker handles flow execution and state tracking. Only start it
+    AFTER verifying login works (via 'plato sandbox flow' or browser testing).
+
+    REQUIRES:
 
-    This is needed after creating a blank VM to configure the worker
-    with the correct service and dataset settings.
+        .sandbox.yaml in current directory (created by 'plato sandbox start')
+        plato-config.yml in current directory (or specify with --config-path)
 
-    Requires a plato-config.yml file with dataset configuration.
+    USAGE:
 
-    Examples:
+        plato sandbox start-worker                    # Uses plato-config.yml in cwd
+        plato sandbox start-worker --wait             # Wait for worker to be ready
+        plato sandbox start-worker -d base            # Specify dataset
         plato sandbox start-worker --config-path ./plato-config.yml
-        plato sandbox start-worker --config-path ./plato-config.yml --dataset base
-        plato sandbox start-worker -s myapp -d base --config-path ./plato-config.yml
+
+    WORKFLOW POSITION:
+
+        1. plato sandbox start -c
+        2. plato sandbox start-services
+        3. plato sandbox flow             ← verify login works first!
+        4. plato sandbox start-worker --wait  ← you are here (wait ~2-3 min)
+        5. plato sandbox flow             ← run login again to verify with worker
+        6. plato sandbox state --verify-no-mutations  ← verify no mutations
+        7. plato sandbox snapshot
+
+    WARNING:
+
+        Starting the worker with broken login causes infinite error loops.
+        Always verify login works before starting the worker.
     """
     api_key = require_api_key()
     state = require_sandbox_state()
@@ -763,18 +1040,66 @@ def sandbox_start_worker(
                 x_api_key=api_key,
             )
 
-            if json_output:
-                console.print(
-                    json.dumps(
-                        {
-                            "status": response.status if hasattr(response, "status") else "ok",
-                            "correlation_id": response.correlation_id if hasattr(response, "correlation_id") else None,
-                        }
-                    )
-                )
-            else:
+            if not json_output:
                 console.print("[green]Worker started successfully![/green]")
 
+            # Wait for worker to be ready if --wait flag is set
+            if wait:
+                if not json_output:
+                    console.print(f"[cyan]Waiting for worker to be ready (timeout: {wait_timeout}s)...[/cyan]")
+
+                session_id = state.get("session_id")
+                if not session_id:
+                    console.print("[red]Session ID not found in .sandbox.yaml[/red]")
+                    raise typer.Exit(1)
+                start_time = time.time()
+                poll_interval = 10  # seconds between polls
+                worker_ready = False
+
+                while time.time() - start_time < wait_timeout:
+                    try:
+                        # Try to get state - if it works without error, worker is ready
+                        state_response = sessions_state.sync(
+                            client=client,
+                            session_id=session_id,
+                            x_api_key=api_key,
+                        )
+                        # Check if response has an error (like 502)
+                        if state_response and state_response.results:
+                            has_error = False
+                            for jid, result in state_response.results.items():
+                                result_dict = result.model_dump() if hasattr(result, "model_dump") else result
+                                if isinstance(result_dict, dict) and "error" in result_dict:
+                                    has_error = True
+                                    break
+                            if not has_error:
+                                worker_ready = True
+                                break
+                    except Exception:
+                        pass  # Worker not ready yet
+
+                    elapsed = int(time.time() - start_time)
+                    if not json_output:
+                        console.print(f"  [dim]Worker not ready yet... ({elapsed}s elapsed)[/dim]")
+                    time.sleep(poll_interval)
+
+                if worker_ready:
+                    if not json_output:
+                        elapsed = int(time.time() - start_time)
+                        console.print(f"[green]Worker ready after {elapsed}s![/green]")
+                else:
+                    if not json_output:
+                        console.print(f"[yellow]Warning: Worker not ready after {wait_timeout}s timeout[/yellow]")
+
+            if json_output:
+                result = {
+                    "status": response.status if hasattr(response, "status") else "ok",
+                    "correlation_id": response.correlation_id if hasattr(response, "correlation_id") else None,
+                }
+                if wait:
+                    result["worker_ready"] = worker_ready
+                console.print(json.dumps(result))
+
     except Exception as e:
         if json_output:
             console.print(json.dumps({"error": str(e)}))
@@ -796,15 +1121,35 @@ def sandbox_sync(
     json_output: bool = typer.Option(False, "--json", "-j", help="Output as JSON"),
 ):
     """
-    Sync local code to the sandbox (pure Python, no rsync needed).
+    Sync local files to the sandbox VM.
+
+    Uploads local files to the remote sandbox. Useful for updating
+    docker-compose.yml, flows.yml, or other config without restarting.
+
+    REQUIRES:
+
+        .sandbox.yaml in current directory (created by 'plato sandbox start')
+
+    USAGE:
+
+        plato sandbox sync                    # Sync current directory
+        plato sandbox sync ./base             # Sync specific directory
+        plato sandbox sync -r /custom/path    # Custom remote path
+
+    DEFAULT REMOTE PATH:
+
+        /home/plato/worktree/<service>/
+
+    WHAT IT SYNCS:
+
+        - Respects .gitignore patterns
+        - Excludes .git, __pycache__, node_modules, etc.
+        - Creates tar archive and extracts on remote
 
-    Creates a tar archive of the local directory, uploads it via the
-    execute API, and extracts it on the remote sandbox.
+    NOTE:
 
-    Examples:
-        plato sandbox sync
-        plato sandbox sync ./src
-        plato sandbox sync --remote-path /home/plato/custom/path
+        For most workflows, use 'plato sandbox start-services' instead,
+        which syncs files AND restarts containers.
     """
     api_key = require_api_key()
     state = require_sandbox_state()
@@ -1017,20 +1362,50 @@ _flow_logger = logging.getLogger("plato.flow")
 @sandbox_app.command(name="flow")
 def sandbox_flow(
     flow_name: str = typer.Option("login", "--flow-name", "-f", help="Name of the flow to execute"),
+    local: bool = typer.Option(False, "--local", "-l", help="Force using local flows.yml only"),
+    api: bool = typer.Option(False, "--api", "-a", help="Force fetching flows from API only"),
 ):
     """
-    Execute a test flow against a simulator environment.
+    Execute a test flow against the running sandbox.
 
-    Reads .sandbox.yaml to get the URL. Uses "login" as default flow name.
+    Runs a flow (like login) to verify it works before starting the worker.
+    Opens a browser and executes the flow steps automatically.
 
-    Flow source priority:
-    1. Local plato-config.yml (development workflow)
-    2. Flows from API based on artifact (artifact/simulator mode)
+    REQUIRES:
 
-    Example:
-        plato sandbox flow
-        plato sandbox flow --flow-name login
+        .sandbox.yaml in current directory (created by 'plato sandbox start')
+        Either:
+          - Local plato-config.yml with flows_path pointing to flows.yml
+          - Or sandbox started from artifact (flows fetched from API)
+
+    USAGE:
+
+        plato sandbox flow                    # Run "login" flow (default)
+        plato sandbox flow -f login           # Explicit flow name
+        plato sandbox flow -f incorrect_login # Test failed login flow
+        plato sandbox flow --local            # Force local flows.yml
+        plato sandbox flow --api              # Force API flows (from artifact)
+
+    WORKFLOW POSITION:
+
+        1. plato sandbox start -c
+        2. plato sandbox start-services
+        3. plato sandbox flow             ← you are here (verify login)
+        4. plato sandbox start-worker
+        5. plato sandbox snapshot
+
+    FLOW SOURCE (default priority):
+
+        1. Local flows.yml (from plato-config.yml metadata.flows_path)
+        2. API (fetched from artifact if started from simulator)
+
+        Use --local or --api to override this behavior.
     """
+    # Validate mutually exclusive flags
+    if local and api:
+        console.print("[red]❌ Cannot use both --local and --api[/red]")
+        raise typer.Exit(1)
+
     api_key = require_api_key()
     sandbox_data = require_sandbox_state()
     job_id = sandbox_data.get("job_id")
@@ -1043,16 +1418,16 @@ def sandbox_flow(
         if simulator:
             service_name = simulator.split(":")[0] if ":" in simulator else simulator
 
-    # Build proper URL with router target
-    public_url = sandbox_data.get("public_url") or sandbox_data.get("url")
-    if not public_url:
-        console.print("[red]❌ No URL found in .sandbox.yaml[/red]")
+    # Get URL from sandbox state
+    url = sandbox_data.get("public_url")
+    if not url:
+        console.print("[red]❌ No public_url found in .sandbox.yaml[/red]")
         raise typer.Exit(1)
 
-    # Always construct URL with router target for proper routing
-    url = format_public_url_with_router_target(public_url, service_name)
+    # Ensure URL has router target (in case of older .sandbox.yaml files)
+    url = format_public_url_with_router_target(url, service_name)
 
-    # Try to get flows from local plato-config.yml first
+    # Try to get flows from local plato-config.yml first (unless --api is set)
     flow_obj = None
     flow_file = None
     screenshots_dir = None
@@ -1061,11 +1436,12 @@ def sandbox_flow(
     plato_config_path = sandbox_data.get("plato_config_path")
     dataset = sandbox_data.get("dataset", "base")
 
-    # Try local config first (either from state or current directory)
+    # Try local config first (either from state or current directory) unless --api forces API
     local_config_paths = []
-    if plato_config_path:
-        local_config_paths.append(Path(plato_config_path))
-    local_config_paths.extend([Path.cwd() / "plato-config.yml", Path.cwd() / "plato-config.yaml"])
+    if not api:  # Skip local if --api flag is set
+        if plato_config_path:
+            local_config_paths.append(Path(plato_config_path))
+        local_config_paths.extend([Path.cwd() / "plato-config.yml", Path.cwd() / "plato-config.yaml"])
 
     for config_path in local_config_paths:
         if config_path.exists():
@@ -1098,11 +1474,19 @@ def sandbox_flow(
                                 screenshots_dir = Path(flow_file).parent / "screenshots"
                                 console.print(f"[cyan]Flow source: local ({flow_file})[/cyan]")
                                 break
-            except Exception:
+            except Exception as e:
+                console.print(f"[yellow]Warning: Failed to load flow from {config_path}: {e}[/yellow]")
                 pass  # Try next config or fall back to API
 
     # If no local flow found, fetch from API
+    # If no local flow found (or --api forced), fetch from API
     if not flow_obj:
+        # If --local was specified and we didn't find a local flow, error out
+        if local:
+            console.print("[red]❌ No local flow found and --local flag was specified[/red]")
+            console.print("[yellow]Ensure plato-config.yml exists with flows_path pointing to flows.yml[/yellow]")
+            raise typer.Exit(1)
+
         if not job_id:
             console.print("[red]❌ No local plato-config.yml found and no job_id in .sandbox.yaml[/red]")
             console.print("[yellow]Either create a local plato-config.yml or start sandbox from an artifact[/yellow]")
@@ -1151,17 +1535,31 @@ def sandbox_flow(
             console.print(f"[red]❌ Failed to fetch flows from API: {e}[/red]")
             raise typer.Exit(1) from e
 
+    # At this point, url and flow_obj must be set (validated above)
+    if not url:
+        console.print("[red]❌ URL is not set[/red]")
+        raise typer.Exit(1)
+    if not flow_obj:
+        console.print("[red]❌ Flow object could not be loaded[/red]")
+        raise typer.Exit(1)
+
     console.print(f"[cyan]URL: {url}[/cyan]")
     console.print(f"[cyan]Flow name: {flow_name}[/cyan]")
 
+    # Capture for closure (narrowed types)
+    _url: str = url
+    _flow_obj: Flow = flow_obj
+
     async def _run():
+        from playwright.async_api import async_playwright
+
         browser = None
         try:
             async with async_playwright() as p:
                 browser = await p.chromium.launch(headless=False)
                 page = await browser.new_page()
-                await page.goto(url)
-                executor = FlowExecutor(page, flow_obj, screenshots_dir, log=_flow_logger)
+                await page.goto(_url)
+                executor = FlowExecutor(page, _flow_obj, screenshots_dir, log=_flow_logger)
                 await executor.execute()
                 console.print("[green]✅ Flow executed successfully[/green]")
         except Exception as e:
@@ -1175,37 +1573,98 @@ def sandbox_flow(
 
 
 @sandbox_app.command(name="state")
-def sandbox_state_cmd():
-    """Get the current state of the simulator environment."""
-    state = require_sandbox_state()
+def sandbox_state_cmd(
+    verify_no_mutations: bool = typer.Option(
+        False, "--verify-no-mutations", "-v", help="Exit with code 1 if mutations are detected (for CI/automation)"
+    ),
+    json_output: bool = typer.Option(False, "--json", "-j", help="Output as JSON"),
+):
+    """
+    Get the database state/mutations from the simulator.
+
+    Shows what database changes have been detected since the last reset.
+    Useful during review to verify:
+      - No mutations after login (state should be empty)
+      - Mutations appear after making changes (audit is working)
+
+    REQUIRES:
+
+        .sandbox.yaml in current directory (created by 'plato sandbox start')
+
+    USAGE:
+
+        plato sandbox state                      # Show current state
+        plato sandbox state --verify-no-mutations  # Exit 1 if mutations found
+        plato sandbox state -v                   # Short form
+
+    USED DURING REVIEW:
+
+        1. Run login flow
+        2. plato sandbox state -v    ← should pass (no mutations)
+        3. Make a change in the app
+        4. plato sandbox state       ← should show mutations
+    """
+    sandbox_state = require_sandbox_state()
     api_key = require_api_key()
 
     # Try session_id first (v2 SDK), then job_id, then job_group_id (legacy)
-    session_id = state.get("session_id")
-    job_id = state.get("job_id")
-    job_group_id = state.get("job_group_id")
+    session_id = sandbox_state.get("session_id")
+    job_id = sandbox_state.get("job_id")
+    job_group_id = sandbox_state.get("job_group_id")
+
+    state_dict = None
+    has_mutations = False
+    has_error = False
+    error_message = None
+
+    def check_mutations(result_dict: dict) -> tuple[bool, bool, str | None]:
+        """Check if result has mutations or errors. Returns (has_mutations, has_error, error_msg)."""
+        if isinstance(result_dict, dict):
+            # Check for state
+            state = result_dict.get("state", {})
+            if isinstance(state, dict):
+                # Check for error wrapped in state (from API layer transformation)
+                if "error" in state:
+                    return False, True, state["error"]
+                # Check for db state
+                db_state = state.get("db", {})
+                if isinstance(db_state, dict):
+                    mutations = db_state.get("mutations", [])
+                    if mutations:
+                        return True, False, None
+                    # Also check audit_log_count
+                    audit_count = db_state.get("audit_log_count", 0)
+                    if audit_count > 0:
+                        return True, False, None
+            # Check top-level mutations as fallback
+            mutations = result_dict.get("mutations", [])
+            if mutations:
+                return True, False, None
+        return False, False, None
 
     if session_id:
-        console.print(f"[cyan]Getting state for session: {session_id}[/cyan]")
+        if not json_output:
+            console.print(f"[cyan]Getting state for session: {session_id}[/cyan]")
         with get_http_client() as client:
             response = sessions_state.sync(
                 client=client,
                 session_id=session_id,
                 x_api_key=api_key,
             )
-            # Convert response to dict for display
             if response and response.results:
                 state_dict = {
                     jid: result.model_dump() if hasattr(result, "model_dump") else result
                     for jid, result in response.results.items()
                 }
-                console.print("\n[bold]Environment State:[/bold]")
-                console.print(json.dumps(state_dict, indent=2, default=str))
-            else:
-                console.print("[yellow]No state returned[/yellow]")
+                for jid, result in state_dict.items():
+                    m, e, msg = check_mutations(result)
+                    has_mutations = has_mutations or m
+                    has_error = has_error or e
+                    if msg:
+                        error_message = msg
     elif job_id:
-        # Use job-level state API
-        console.print(f"[cyan]Getting state for job: {job_id}[/cyan]")
+        if not json_output:
+            console.print(f"[cyan]Getting state for job: {job_id}[/cyan]")
         with get_http_client() as client:
             response = jobs_state.sync(
                 client=client,
@@ -1214,13 +1673,13 @@ def sandbox_state_cmd():
             )
             if response:
                 state_dict = response.model_dump() if hasattr(response, "model_dump") else response
-                console.print("\n[bold]Environment State:[/bold]")
-                console.print(json.dumps(state_dict, indent=2, default=str))
-            else:
-                console.print("[yellow]No state returned[/yellow]")
+                m, e, msg = check_mutations(state_dict)
+                has_mutations = m
+                has_error = e
+                error_message = msg
     elif job_group_id:
-        # Legacy: Use job_group_id with session state API (it accepts job_group_id as session_id)
-        console.print(f"[cyan]Getting state for job_group: {job_group_id}[/cyan]")
+        if not json_output:
+            console.print(f"[cyan]Getting state for job_group: {job_group_id}[/cyan]")
         with get_http_client() as client:
             response = sessions_state.sync(
                 client=client,
@@ -1232,25 +1691,74 @@ def sandbox_state_cmd():
                     jid: result.model_dump() if hasattr(result, "model_dump") else result
                     for jid, result in response.results.items()
                 }
-                console.print("\n[bold]Environment State:[/bold]")
-                console.print(json.dumps(state_dict, indent=2, default=str))
-            else:
-                console.print("[yellow]No state returned[/yellow]")
+                for jid, result in state_dict.items():
+                    m, e, msg = check_mutations(result)
+                    has_mutations = has_mutations or m
+                    has_error = has_error or e
+                    if msg:
+                        error_message = msg
     else:
         console.print("[red]❌ .sandbox.yaml missing session_id, job_id, or job_group_id[/red]")
         raise typer.Exit(1)
 
+    # Output results
+    if json_output:
+        result = {
+            "state": state_dict,
+            "has_mutations": has_mutations,
+            "has_error": has_error,
+        }
+        if error_message:
+            result["error"] = error_message
+        console.print(json.dumps(result, indent=2, default=str))
+    else:
+        if has_error:
+            console.print(f"\n[red]Error getting state:[/red] {error_message}")
+        elif state_dict:
+            console.print("\n[bold]Environment State:[/bold]")
+            console.print(json.dumps(state_dict, indent=2, default=str))
+        else:
+            console.print("[yellow]No state returned[/yellow]")
+
+        # Summary for verify mode
+        if verify_no_mutations:
+            if has_error:
+                console.print("\n[red]❌ Error checking state - worker may not be ready[/red]")
+            elif has_mutations:
+                console.print("\n[red]❌ FAIL: Mutations detected after login![/red]")
+                console.print(
+                    "[yellow]Fix: Add affected tables/columns to audit_ignore_tables in plato-config.yml[/yellow]"
+                )
+            else:
+                console.print("\n[green]✅ PASS: No mutations detected[/green]")
+
+    # Exit with error code if verify mode and mutations/errors found
+    if verify_no_mutations and (has_mutations or has_error):
+        raise typer.Exit(1)
+
 
 @sandbox_app.command(name="audit-ui")
 def sandbox_audit_ui():
     """
-    Launch Streamlit UI for auditing database ignore rules.
+    Launch Streamlit UI for configuring database audit rules.
+
+    Opens a visual interface to help configure audit_ignore_tables
+    in plato-config.yml. Useful when you see unwanted mutations
+    during review (like session tables, timestamps, etc.).
+
+    REQUIRES:
+
+        streamlit installed: pip install streamlit psycopg2-binary pymysql
 
-    Note: Requires streamlit to be installed:
-        pip install streamlit psycopg2-binary pymysql
+    USAGE:
 
-    Examples:
         plato sandbox audit-ui
+
+    WHEN TO USE:
+
+        - Review shows mutations after login (sessions, timestamps)
+        - Need to figure out which tables/columns to ignore
+        - Want visual help building audit_ignore_tables config
     """
     # Check if streamlit is installed
     if not shutil.which("streamlit"):
@@ -1340,25 +1848,51 @@ def _start_heartbeat_process(session_id: str, api_key: str) -> int | None:
 
     Returns the PID of the background process, or None if failed.
     """
+    # Log file for heartbeat debugging
+    log_file = f"/tmp/plato_heartbeat_{session_id}.log"
+
     # Python script to run in background
     heartbeat_script = f'''
 import time
 import os
 import httpx
+from datetime import datetime
 
 session_id = "{session_id}"
 api_key = "{api_key}"
 base_url = os.getenv("PLATO_BASE_URL", "https://plato.so")
+log_file = "{log_file}"
 
+def log(msg):
+    timestamp = datetime.now().isoformat()
+    with open(log_file, "a") as f:
+        f.write(f"[{{timestamp}}] {{msg}}\\n")
+        f.flush()
+
+log(f"Heartbeat process started for session {{session_id}}")
+log(f"Base URL: {{base_url}}")
+
+heartbeat_count = 0
 while True:
+    heartbeat_count += 1
     try:
         with httpx.Client(base_url=base_url, timeout=30) as client:
-            client.post(
-                f"/api/v2/sessions/{{session_id}}/heartbeat",
+            # base_url already includes /api, so just use /v2/...
+            response = client.post(
+                f"/v2/sessions/{{session_id}}/heartbeat",
                 headers={{"X-API-Key": api_key}},
             )
-    except Exception:
-        pass
+            result = response.json()
+            success = result.get("success", False)
+            log(f"Heartbeat #{{heartbeat_count}}: status={{response.status_code}}, success={{success}}")
+            if not success:
+                results = result.get("results", {{}})
+                for job_id, job_result in results.items():
+                    errors = job_result.get("errors", [])
+                    if errors:
+                        log(f"  Job {{job_id}} errors: {{errors}}")
+    except Exception as e:
+        log(f"Heartbeat #{{heartbeat_count}} EXCEPTION: {{type(e).__name__}}: {{e}}")
     time.sleep(30)
 '''
 
@@ -1398,21 +1932,39 @@ def sandbox_start_services(
     json_output: bool = typer.Option(False, "--json", "-j", help="Output as JSON"),
 ):
     """
-    Push code to hub, clone on VM, and start docker compose services.
+    Deploy and start docker compose services on the sandbox.
+
+    Syncs your local code to the VM and starts the containers defined
+    in plato-config.yml. This is the main command for deploying your app.
+
+    REQUIRES:
+
+        .sandbox.yaml in current directory (created by 'plato sandbox start -c')
+        plato-config.yml with services defined
+
+    USAGE:
+
+        plato sandbox start-services           # Deploy and start containers
+        plato sandbox start-services --json    # JSON output
 
-    This command:
-    1. Pushes your local code to the Plato Hub (Gitea)
-    2. Clones the code on the VM via SSH
-    3. Starts docker compose services defined in plato-config.yml
+    WHAT IT DOES:
 
-    Requires:
-    - A running sandbox (from 'plato sandbox start --from-config')
-    - plato-config.yml with services defined
-    - SSH access configured
+        1. Pushes local code to Plato Hub (Gitea)
+        2. Clones code on VM via SSH
+        3. Runs 'docker compose up -d' on VM
+        4. Waits for containers to be healthy
 
-    Examples:
-        plato sandbox start-services
-        plato sandbox start-services --json
+    WORKFLOW POSITION:
+
+        1. plato sandbox start -c             ← creates VM
+        2. plato sandbox start-services       ← you are here (deploy app)
+        3. plato sandbox flow                 ← verify login
+        4. plato sandbox start-worker
+        5. plato sandbox snapshot
+
+    AFTER MAKING CHANGES:
+
+        Run this command again to re-sync and restart containers.
     """
     api_key = require_api_key()
     state = require_sandbox_state()
@@ -1486,6 +2038,10 @@ def sandbox_start_services(
             if not json_output:
                 console.print("[cyan]Step 3: Getting/creating repository...[/cyan]")
 
+            if sim_id is None:
+                console.print("[red]❌ Simulator ID not available[/red]")
+                raise typer.Exit(1)
+
             if has_repo:
                 repo = get_simulator_repository.sync(client=client, simulator_id=sim_id, x_api_key=api_key)
             else: