feat(api): include error field in StatInstancePath response

Add error field to PathInfo schema in OpenAPI spec and update handler
to propagate error messages from the guest agent (e.g., permission denied).
This allows clients to distinguish between 'path does not exist' and
'cannot access path due to error'.

Author: rgarcia

cmd/api/api/instances.go

@@ -482,15 +482,20 @@ func (s *ApiService) StatInstancePath(ctx context.Context, request oapi.StatInst
 
 	// Convert types from protobuf to OAPI
 	mode := int(resp.Mode)
-	return oapi.StatInstancePath200JSONResponse{
+	response := oapi.StatInstancePath200JSONResponse{
 		Exists:     resp.Exists,
 		IsDir:      &resp.IsDir,
 		IsFile:     &resp.IsFile,
 		IsSymlink:  &resp.IsSymlink,
 		LinkTarget: &resp.LinkTarget,
 		Mode:       &mode,
 		Size:       &resp.Size,
-	}, nil
+	}
+	// Include error message if stat failed (e.g., permission denied)
+	if resp.Error != "" {
+		response.Error = &resp.Error
+	}
+	return response, nil
 }
 
 // AttachVolume attaches a volume to an instance (not yet implemented)

lib/oapi/oapi.go

@@ -289,6 +289,11 @@ components:
           format: int64
           description: File size in bytes
           example: 1024
+        error:
+          type: string
+          description: Error message if stat failed (e.g., permission denied). Only set when exists is false due to an error rather than the path not existing.
+          nullable: true
+          example: "permission denied"
 
     CreateImageRequest:
       type: object